# AppManager

Welcome to the new gem of Hulkapps.com ! An API wrapper of Hulkapps.com's AppManager portal.

* [Installation](#step1)
* [Configuration](#step2)
* [Usage](#step3)
* [Extras](#step4)


<a name="step1"></a>
### Installation

* Add following line to your application's Gemfile:

```ruby
gem 'app_manager'
```

* Execute following in terminal:

```
    bundle install
```
```
    rails g app_manager:install
```

 this install command will mount routes in your rails route and will create a config file at ```config/initializers/app_manager.rb```

```
    rails db:migrate
```


<a name="step2"></a>
### Configuration

* Set Shopify API version to 2022-04 as app_manager is best compatible with this version.


* Please map new fields (which added by app manager migration) in 'config.field_names' in below initializer file which is generated by install command. Please note: this is important step.


* Please update blank fields in initializer file. Please copy 'uuid' from this [file](https://docs.google.com/spreadsheets/d/1cw2nSKxAHTGn4Cfa98RNdtfHT3zdtwu9bQD7s7hErXc/edit#gid=0) and paste in the following file and make sure that is unique per feature. After copying put your 'app name' next to 'uuid' column in this [file](https://docs.google.com/spreadsheets/d/1cw2nSKxAHTGn4Cfa98RNdtfHT3zdtwu9bQD7s7hErXc/edit#gid=0).


```
AppManager.configure do |config|
  config.enable_caching = false  # Optional, True to enable app-manager api response caching, default is enabled from gem
  config.expires_in = 1.days  # Optional, Example: 30.seconds, 5.minutes or 2.days  Default caching is for 1.days from gem 
  config.app_url = '' # App URL like https://volumediscount.hulkapps.dev/ or #https://5044-2409-4052-209a-69da-9d7-925a-9418-a9c3.ngrok.io
  config.shopify_api_key = '' # Shopify api key of app
  config.shopify_api_version = ''  # Must be 2022-04 or latest
  config.shopify_table_name = 'shops'  #  Table name which is generated by shopify mostly it is 'shops'
  config.shopify_domain_field = 'shopify_domain' #shopify domain field
  config.plan_id_or_name_field = 'plan_id'
  config.shopify_app_slug = '' #Add your app slug here
  config.plan_page_route = '' #Add your app's plan page route here without first slash. Ex. "payment" 
  config.field_names = {
        'name' => 'shopify_domain', # demo-rahul-tiwari.myshopify.com
        'shopify_email' => 'email', # rahul.t@hulkapps.com
        'shopify_token' => 'shopify_token',
        'shopify_plan' => 'shopify_plan', # partner_test
        'plan_id' => 'plan_id', # 1. t
        'created_at' => 'created_at', # 2022-04-15 10:43:05
        'trial_activated_at' => 'trial_activated_at', # field name that stores trial start/activated date
        'grandfathered' => 'grandfathered',
        'total_trial_days' => '' #optional, put a trial days field from your shops table otherwise leave it blank
    }
  config.plan_features =  [
    {
	  	"uuid" => "b48a3a6c-c1fb-11ec-9d64-0242ac120002",
	  	"name" => "Features 1",
	  	"slug" => "feature-1",
	  	"description" => "Feature Description",
	  	"value_type" => "integer",
	  	"format" => "count",
	  	"display_order" => 1,
		"hidden_feature" => false,
		"group_order" => "1",
		"group" => "Group Name",
	},
	{
		"uuid" => "9f18f95a-bfaf-11ec-9d64-0242ac120002",
		"name" => "Features 2",
		"slug" => "feature-2",
		"description" => "Feature Description",
		"value_type" => "boolean",
		"format" => "percentage",
	  	"display_order" => 2,
		"hidden_feature" => false,
		"group_order" => "1",
		"group" => "Group Name",
	},
	{
		"uuid" => "9f190a26-bfaf-11ec-9d64-0242ac120002",
		"name" => "Features 3",
		"slug" => "feature-3",
		"description" => "Feature Description",
		"value_type" => "string",
	  	"format" => "string",
	  	"display_order" => 3,
		"hidden_feature" => false,
		"group_order" => "1",
		"group" => "Group Name",
	},
	{
		"uuid" => "9f191340-bfaf-11ec-9d64-0242ac12000",
		"name" => "Features 4",
		"slug" => "feature-4",
		"description" => "Feature Description",
		"value_type" => "array",
		"values" => [
			"val-1" => "val 1",
			"val-2" => "val 2",
			"val-3" => "val 3",
		],
	  	"format" => "string",
	  	"display_order" => 4,
		"hidden_feature" => false,
		"group_order" => "1",
		"group" => "Group Name",
	}
]  
end
#Required, Values type : integer, boolean, string, array #
#Format: percentage, count, string
```


  
* You must have to set ENV variable with key 'APP_MANAGER_ACCESS_TOKEN' in your application.yml or .env file like this:

```
    APP_MANAGER_ACCESS_TOKEN: 'XXXXXXXXXXXXXXXXXXX'
    APP_MANAGER_API_URL: 'https://XXXXXXXX.com'
```

* App Manager provides a rake task that must needs to include in your existing app cron for every 10 minutes. Like if you are using [whenever](https://github.com/javan/whenever) gem then you MUST need to include following rake take in your 'schedule.rb' (created by whenever gem)

```
every 10.minutes do
  rake 'sync:local_app_manager'
end
```


<a name="step3"></a>
### Usage


* App Manager provides a helper module which needs to include in your 'shop' model something like below

```
class Shop < ActiveRecord::Base
  include AppManager::Model
end
```

and then you can use follwing methods with your shop objects.

```
@shop.has_plan # return true or false

@shop.plan_features # return array of plan features of your shop's plan 

@shop.has_feature('feature-1') # provide slug of feature which you set in your 'config.plan_features' in config/initializers/app_manager.rb
#return true/false

@shop.get_feature('feature-3') #  provide slug of feature and this returns value of feature which is set in portal. 

@shop.get_remaining_days # return integer based on trial activated date.

@shop.get_plan # return current plan hash

	if you pass @shop.get_plan(plan_id) it will return that particular plan hash like @shop.get_plan(311)

@shop.get_charge # return current charge hash from app manager with 'active_charge' & 'cancelled_charge' keys, it will return nil if current plan is free

@shop.cancel_charge # it will cancel charge in app manager and will return success to true if done from app manager

@shop.set_default_plan(plan_id=nil)  #if plan id is passed nil, then it will set the free(public and $0 price) plan_id in database and if passed it will set that plan_id in database.

@shop.get_plans_by_features(feature_slugs)  # pass feature_slugs as an array even if one slug and it will return plans array which have that slug found. Example: 
	
	@shop.get_plans_by_features(['quantity-based-discount'])
	@shop.get_plans_by_features(['quantity-based-discount','multiple-discount-types'])


	you can pass string argument 'exclude_current_plan' which will return all plans that matching features except current plan

	@shop.get_plans_by_features(['quantity-based-discount'],'exclude_current_plan')
	@shop.get_plans_by_features(['quantity-based-discount','multiple-discount-types'],'exclude_current_plan')


@shop.get_all_plans # return all app plans array

@shop.get_active_charge_app_manager # return active charge hash from app manager otherwise nil

@shop.update_app_manager_charge # return true if shop has shopify recurring charge but app manager doesn't then it update to app manager and return true otherwise nil. This method also accepts current shopify charge id, so you can pass it if you already. This will reduce the extra call like this @shop.update_app_manager_charge("xx23432434")

@shop.update_app_manager_charge_with_plan_id # same as update_app_manager_charge method, the only difference is that, it will not check the plan_id in the shop table is valid from app manager. This method also accepts two parameters, first is current shopify charge id and second is plan_id .It shop table doesn't have plan_id saved then you can pass in second parameter. @shop.update_app_manager_charge_with_plan_id("xx23432434",23)

@shop.get_current_shopify_charge # return active charge hash from shopify https://shopify.dev/docs/api/admin-graphql/2022-10/queries/currentAppInstallation otherwise nil

@shop.active_shopify_charge_id # return active shopify charge id if shop has any current shopify reccurring charge otherwise nil

@shop.cancel_current_shopify_charge # It will cancel charge in shopify if there is any, if success then it will cancel charge in app manager as well using (@shop.cancel_charge ) and will make plan_id and grandfathered field to false. It will clear cache as well.

@shop.active_shopfiy_charge_full #It will give shopify recurring charge graphql object with discounted price details

@shop.usage_charge_call(amount,description,shopify_charge_id #optional) #It will call usage charge API. Amount parameter must be present and should be float value. You can skip shopify_charge_id if you want to pass active shopify charge id. This method will automatically pull that, otherwise you can pass it. You have to pass descriptions as a second parameter.
```

<a name="step4"></a>
### Discount Link Integration

* Update app manager vue package in Rails+Vue apps & for for non-vue apps, update css or js from npm package, minimum version should be 2.4.4

* Update app manager gem in your project's Gemfile

```ruby
gem 'app_manager', '2.2.3'
```
* In Rails project, in application.rb, add following line after require "rails/all" line 

```ruby
require 'app_manager/set_local_storage'
```

* In route.rb file, add following route with constraints
```ruby
condition = ->(request) { request.path_info.include?('/discount/') }
plan_url = "https://admin.shopify.com/admin/apps/#{ENV['SHOPIFY_APP_SLUG']}/home/plan"
constraints(condition) do
get '/discount/*any', to: AppManager::SetLocalStorage.new(Rails.application, condition, plan_url)
end
```
* If updating gem from 1.6.1, then run these commands on rails root.

Note: In this command, Please do not overwrite app_manager.rb file so press n
```ruby
rails g app_manager:install
```
This will add a new migration file in your db/app_manager directory

```ruby
rails db:migrate
```


<a name="step5"></a>
### Extras

* To view the app_manager ruby gem is working in your rails app you can use rails console and initialize app_manager instance like with App Manager Portal access:

```ruby
ob = AppManager::Client.new(ENV['APP_MANAGER_ACCESS_TOKEN'])
```

To get banners use this command:
```ruby
ob.get_banners
```


* For Vue UI Library in Rails Project:

Please make sure you have following line in your route file otherwise add this manually. 

mount AppManager::Engine, at: "/"



## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/app_manager. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/app_manager/blob/master/CODE_OF_CONDUCT.md).

## Code of Conduct

Everyone interacting in the AppManager project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/app_manager/blob/master/CODE_OF_CONDUCT.md).