ruby_shopify_app 1.0.0

data/docs/shopify_app/session-repository.md

@@ -0,0 +1,88 @@
+# Session repository
+
+#### Table of contents
+
+[`ShopifyApp::SessionRepository`](#shopifyappsessionrepository)
+  * [Shop-based token storage](#shop-based-token-storage)
+  * [User-based token storage](#user-based-token-storage)
+
+[Access scopes](#access-scopes)
+  * [`ShopifyApp::ShopSessionStorageWithScopes`](#shopifyappshopsessionstoragewithscopes)
+  * [``ShopifyApp::UserSessionStorageWithScopes``](#shopifyappusersessionstoragewithscopes)
+
+[Migrating from shop-based to user-based token strategy](#migrating-from-shop-based-to-user-based-token-strategy)
+
+## ShopifyApp::SessionRepository
+
+`ShopifyApp::SessionRepository` allows you as a developer to define how your sessions are stored and retrieved for shops. The `SessionRepository` is configured in the `config/initializers/shopify_app.rb` file and can be set to any object that implements `self.store(auth_session, *args)` which stores the session and returns a unique identifier and `self.retrieve(id)` which returns a `ShopifyAPI::Session` for the passed id. These methods are already implemented as part of the `ShopifyApp::SessionStorage` concern but can be overridden for custom implementation.
+
+### Shop-based token storage
+
+Storing tokens on the store model means that any user login associated with the store will have equal access levels to whatever the original user granted the app.
+```sh
+$ rails generate shopify_app:shop_model
+```
+This will generate a shop model which will be the storage for the tokens necessary for authentication.
+
+### User-based token storage
+
+A more granular control over the level of access per user on an app might be necessary, to which the shop-based token strategy is not sufficient. Shopify supports a user-based token storage strategy where a unique token to each user can be managed. Shop tokens must still be maintained if you are running background jobs so that you can make use of them when necessary.
+```sh
+$ rails generate shopify_app:shop_model
+$ rails generate shopify_app:user_model
+```
+This will generate a shop model and user model, which will be the storage for the tokens necessary for authentication.
+
+The current Shopify user will be stored in the rails session at `session[:shopify_user]`
+
+Read more about Online vs. Offline access [here](https://help.shopify.com/api/getting-started/authentication/oauth).
+
+## Access scopes
+
+If you want to customize how access scopes are stored for shops and users, you can implement the `access_scopes` getters and setters in the models that include `ShopifyApp::ShopSessionStorageWithScopes` and `ShopifyApp::UserSessionStorageWithScopes` as shown:
+
+### `ShopifyApp::ShopSessionStorageWithScopes`
+```ruby
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorageWithScopes
+
+  def access_scopes=(scopes)
+    # Store access scopes
+  end
+  def access_scopes
+    # Find access scopes
+  end
+end
+```
+
+### `ShopifyApp::UserSessionStorageWithScopes`
+```ruby
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorageWithScopes
+
+  def access_scopes=(scopes)
+    # Store access scopes
+  end
+  def access_scopes
+    # Find access scopes
+  end
+end
+```
+## Migrating from shop-based to user-based token strategy
+
+1. Run the `user_model` generator as mentioned above.
+2. Ensure that both your `Shop` model and `User` model includes the necessary concerns `ShopifyApp::ShopSessionStorage` and `ShopifyApp::UserSessionStorage`.
+3. Make changes to 2 initializer files as shown below:
+```ruby
+# In the `omniauth.rb` initializer:
+provider :shopify,
+  ...
+  setup: lambda { |env|
+    configuration = ShopifyApp::OmniAuthConfiguration.new(env['omniauth.strategy'], Rack::Request.new(env))
+    configuration.build_options
+  }
+
+# In the `shopify_app.rb` initializer:
+config.shop_session_repository = {YOUR_SHOP_MODEL_CLASS}
+config.user_session_repository = {YOUR_USER_MODEL_CLASS}
+```

data/docs/shopify_app/testing.md

@@ -0,0 +1,38 @@
+# Testing
+
+#### Table of contents
+
+[Using test helpers inside your application](#using-test-helpers-inside-your-application)
+
+[Testing an embedded app outside the Shopify admin](#testing-an-embedded-app-outside-the-shopify-admin)
+
+## Using test helpers inside your application
+
+A test helper that will allow you to test `ShopifyApp::WebhookVerification` in the controller from your app, to use this test, you need to `require` it directly inside your app `test/controllers/webhook_verification_test.rb`.
+
+```ruby
+    require 'test_helper'
+    require 'action_controller'
+    require 'action_controller/base'
+    require 'shopify_app/test_helpers/webhook_verification_helper'
+```
+
+Or you can require in your `test/test_helper.rb`.
+
+```ruby
+  ENV['RAILS_ENV'] ||= 'test'
+  require_relative '../config/environment'
+  require 'rails/test_help'
+  require 'byebug'
+  require 'shopify_app/test_helpers/all'
+```
+
+With `lib/shopify_app/test_helpers/all'` more tests can be added and will only need to be required in once in your library.
+
+## Testing an embedded app outside the Shopify admin
+
+By default, loading your embedded app will redirect to the Shopify admin, with the app view loaded in an `iframe`. If you need to load your app outside of the Shopify admin (e.g., for performance testing), you can change `forceRedirect: true` to `false` in `ShopifyApp.init` block in the `embedded_app` view. To keep the redirect on in production but off in your `development` and `test` environments, you can use:
+
+```javascript
+forceRedirect: <%= Rails.env.development? || Rails.env.test? ? 'false' : 'true' %>
+```

data/docs/shopify_app/webhooks.md

@@ -0,0 +1,72 @@
+# Webhooks
+
+#### Table of contents
+
+[Manage webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager)
+
+## Manage webhooks using `ShopifyApp::WebhooksManager`
+
+See [`ShopifyApp::WebhooksManager`](/lib/shopify_app/managers/webhooks_manager.rb)
+ShopifyApp can manage your app's webhooks for you if you set which webhooks you require in the initializer:
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {topic: 'carts/update', address: 'https://example.com/webhooks/carts_update'}
+  ]
+end
+```
+
+When the [OAuth callback](/docs/shopify_app/authentication.md#oauth-callback) is completed successfully, ShopifyApp will queue a background job which will ensure all the specified webhooks exist for that shop. Because this runs on every OAuth callback, it means your app will always have the webhooks it needs even if the user uninstalls and re-installs the app.
+
+ShopifyApp also provides a [WebhooksController](/app/controllers/shopify_app/webhooks_controller.rb) that receives webhooks and queues a job based on the received topic. For example, if you register the webhook from above, then all you need to do is create a job called `CartsUpdateJob`. The job will be queued with 2 params: `shop_domain` and `webhook` (which is the webhook body).
+
+If you would like to namespace your jobs, you may set `webhook_jobs_namespace` in the config. For example, if your app handles webhooks from other ecommerce applications as well, and you want Shopify cart update webhooks to be processed by a job living in `jobs/shopify/webhooks/carts_update_job.rb` rather than `jobs/carts_update_job.rb`):
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhook_jobs_namespace = 'shopify/webhooks'
+end
+```
+
+If you are only interested in particular fields, you can optionally filter the data sent by Shopify by specifying the `fields` parameter in `config/webhooks`. Note that you will still receive a webhook request from Shopify every time the resource is updated, but only the specified fields will be sent.
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {topic: 'products/update', address: 'https://example.com/webhooks/products_update', fields: ['title', 'vendor']}
+  ]
+end
+```
+
+If you'd rather implement your own controller then you'll want to use the [`ShopifyApp::WebhookVerification`](/lib/shopify_app/controller_concerns/webhook_verification.rb) module to verify your webhooks, example:
+
+```ruby
+class CustomWebhooksController < ApplicationController
+  include ShopifyApp::WebhookVerification
+
+  def carts_update
+    params.permit!
+    SomeJob.perform_later(shop_domain: shop_domain, webhook: webhook_params.to_h)
+    head :no_content
+  end
+
+  private
+
+  def webhook_params
+    params.except(:controller, :action, :type)
+  end
+end
+```
+
+The module skips the `verify_authenticity_token` before_action and adds an action to verify that the webhook came from Shopify. You can now add a post route to your application, pointing to the controller and action to accept the webhook data from Shopify.
+
+The WebhooksManager uses ActiveJob. If ActiveJob is not configured then by default Rails will run the jobs inline. However, it is highly recommended to configure a proper background processing queue like Sidekiq or Resque in production.
+
+ShopifyApp can create webhooks for you using the `add_webhook` generator. This will add the new webhook to your config and create the required job class for you.
+
+```
+rails g shopify_app:add_webhook -t carts/update -a https://example.com/webhooks/carts_update
+```
+
+Where `-t` is the topic and `-a` is the address the webhook should be sent to.

data/karma.conf.js

@@ -0,0 +1,44 @@
+const karmaReporters = ['mocha-clean'];
+
+function isDebug(argument) {
+  return argument === '--debug';
+}
+
+module.exports = function(config) {
+  config.set({
+    mode: 'development',
+    basePath: '',
+    frameworks: ['mocha', 'chai-sinon'],
+    files: [
+      'app/assets/javascripts/**/*.js',
+      'test/javascripts/**/*test.js',
+    ],
+    exclude: [
+      // Exclude JS files that create 'DOMContentLoaded' event listeners
+      'app/assets/javascripts/**/redirect.js',
+      'app/assets/javascripts/**/storage_access_redirect.js',
+      'app/assets/javascripts/**/top_level_interaction.js',
+      'app/assets/javascripts/**/partition_cookies.js',
+    ],
+    mochaReporter: {
+      output: 'autowatch',
+    },
+    preprocessors: {
+      'test/javascripts/**/*test.js': ['webpack'],
+    },
+    webpack: {},
+    reporters: karmaReporters,
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_WARN,
+    autoWatch: false,
+    browsers: ['ChromeHeadless'],
+    singleRun: true,
+    client: {
+      mocha: {
+        ui: 'tdd',
+        grep: config.grep,
+      },
+    },
+  });
+};

data/lib/generators/shopify_app/add_after_authenticate_job/add_after_authenticate_job_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class AddAfterAuthenticateJobGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      hook_for :test_framework, as: :job, in: :rails do |instance, generator|
+        instance.invoke(generator, [instance.send(:job_file_name)])
+      end
+
+      def init_after_authenticate_config
+        initializer = load_initializer
+
+        after_authenticate_job_config =
+          "  config.after_authenticate_job = "\
+          "{ job: \"Shopify::AfterAuthenticateJob\", inline: false }\n"
+
+        inject_into_file(
+          'config/initializers/shopify_app.rb',
+          after_authenticate_job_config,
+          before: 'end'
+        )
+
+        unless initializer.include?(after_authenticate_job_config)
+          shell.say("Error adding after_authenticate_job to config. Add this line manually: "\
+                    "#{after_authenticate_job_config}", :red)
+        end
+      end
+
+      def add_after_authenticate_job
+        template('after_authenticate_job.rb', "app/jobs/#{job_file_name}_job.rb")
+      end
+
+      private
+
+      def load_initializer
+        File.read(File.join(destination_root, 'config/initializers/shopify_app.rb'))
+      end
+
+      def job_file_name
+        'shopify/after_authenticate'
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module Shopify
+  class AfterAuthenticateJob < ActiveJob::Base
+    def perform(shop_domain:)
+      shop = Shop.find_by(shopify_domain: shop_domain)
+
+      shop.with_shopify_session do
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/add_marketing_activity_extension/add_marketing_activity_extension_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class AddMarketingActivityExtensionGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def generate_app_extension
+        template("marketing_activities_controller.rb", "app/controllers/marketing_activities_controller.rb")
+        generate_routes
+      end
+
+      private
+
+      def generate_routes
+        inject_into_file(
+          'config/routes.rb',
+          optimize_indentation(routes, 2),
+          after: "root :to => 'home#index'\n"
+        )
+      end
+
+      def routes
+        <<~EOS
+
+          resource :marketing_activities, only: [:create, :update] do
+            patch :resume
+            patch :pause
+            patch :delete
+            post :republish
+            post :preload_form_data
+            post :preview
+            post :errors
+          end
+        EOS
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/add_marketing_activity_extension/templates/marketing_activities_controller.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class MarketingActivitiesController < ShopifyApp::ExtensionVerificationController
+  def preload_form_data
+    preload_data = {
+      "form_data": {},
+    }
+    render(json: preload_data, status: :ok)
+  end
+
+  def update
+    render(json: {}, status: :accepted)
+  end
+
+  def pause
+    render(json: {}, status: :accepted)
+  end
+
+  def resume
+    render(json: {}, status: :accepted)
+  end
+
+  def delete
+    render(json: {}, status: :accepted)
+  end
+
+  def preview
+    placeholder_img = "https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-image_small.png"
+    preview_response = {
+      "desktop": {
+        "preview_url": placeholder_img,
+        "content_type": "text/html",
+        "width": 360,
+        "height": 200,
+      },
+      "mobile": {
+        "preview_url": placeholder_img,
+        "content_type": "text/html",
+        "width": 360,
+        "height": 200,
+      },
+    }
+    render(json: preview_response, status: :ok)
+  end
+
+  def create
+    render(json: {}, status: :ok)
+  end
+
+  def republish
+    render(json: {}, status: :accepted)
+  end
+
+  def errors
+    request_id = params[:request_id]
+    message = params[:message]
+
+    Rails.logger.info("[Marketing Activity App Error Feedback] Request id: #{request_id}, message: #{message}")
+
+    render(json: {}, status: :ok)
+  end
+end

data/lib/generators/shopify_app/add_webhook/add_webhook_generator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class AddWebhookGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+      class_option :topic, type: :string, aliases: "-t", required: true
+      class_option :address, type: :string, aliases: "-a", required: true
+
+      hook_for :test_framework, as: :job, in: :rails do |instance, generator|
+        instance.invoke(generator, [instance.send(:job_file_name)])
+      end
+
+      def init_webhook_config
+        initializer = load_initializer
+        return if initializer.include?("config.webhooks")
+
+        inject_into_file(
+          'config/initializers/shopify_app.rb',
+          "  config.webhooks = [\n  ]\n",
+          before: 'end'
+        )
+      end
+
+      def inject_webhook_to_shopify_app_initializer
+        inject_into_file(
+          'config/initializers/shopify_app.rb',
+          webhook_config,
+          after: "config.webhooks = ["
+        )
+
+        initializer = load_initializer
+
+        unless initializer.include?(webhook_config)
+          shell.say("Error adding webhook to config. Add this line manually: #{webhook_config}", :red)
+        end
+      end
+
+      def add_webhook_job
+        @job_file_name = job_file_name + '_job'
+        @job_class_name = @job_file_name.classify
+        template('webhook_job.rb', "app/jobs/#{@job_file_name}.rb")
+      end
+
+      private
+
+      def job_file_name
+        address.split('/').last
+      end
+
+      def load_initializer
+        File.read(File.join(destination_root, 'config/initializers/shopify_app.rb'))
+      end
+
+      def webhook_config
+        "\n    {topic: '#{topic}', address: '#{address}', format: 'json'},"
+      end
+
+      def topic
+        options['topic']
+      end
+
+      def address
+        options['address']
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/add_webhook/templates/webhook_job.rb.tt

@@ -0,0 +1,13 @@
+class <%= @job_class_name %> < ActiveJob::Base
+  def perform(shop_domain:, webhook:)
+    shop = Shop.find_by(shopify_domain: shop_domain)
+
+    if shop.nil?
+      logger.error("#{self.class} failed: cannot find shop with domain '#{shop_domain}'")
+      return
+    end
+
+    shop.with_shopify_session do
+    end
+  end
+end

data/lib/generators/shopify_app/app_proxy_controller/app_proxy_controller_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class AppProxyControllerGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_app_proxy_controller
+        template('app_proxy_controller.rb', 'app/controllers/app_proxy_controller.rb')
+      end
+
+      def create_app_proxy_index_view
+        copy_file('index.html.erb', 'app/views/app_proxy/index.html.erb')
+      end
+
+      def add_app_proxy_route
+        inject_into_file(
+          'config/routes.rb',
+          File.read(File.expand_path(find_in_source_paths('app_proxy_route.rb'))),
+          after: "mount ShopifyApp::Engine, at: '/'\n"
+        )
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/app_proxy_controller/templates/app_proxy_controller.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+class AppProxyController < ApplicationController
+  include ShopifyApp::AppProxyVerification
+
+  def index
+    render(layout: false, content_type: 'application/liquid')
+  end
+end

data/lib/generators/shopify_app/app_proxy_controller/templates/app_proxy_route.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+namespace :app_proxy do
+  root action: 'index'
+  # simple routes without a specified controller will go to AppProxyController
+
+  # more complex routes will go to controllers in the AppProxy namespace
+  #   resources :reviews
+  # GET /app_proxy/reviews will now be routed to
+  # AppProxy::ReviewsController#index, for example
+end

data/lib/generators/shopify_app/app_proxy_controller/templates/index.html.erb

@@ -0,0 +1,19 @@
+<h2>App Proxy Page</h2>
+
+<p>Congratulations! You have successfully configured App Proxy for your shopify application.</p>
+<p>Any valid liquid code included in this page will be parsed and rendered by Shopify.</p>
+
+<br>
+
+<pre>
+Your Shop Details:
+<hr>
+	Shop Name 			: {{ shop.name }}
+	myshopify name 			: {{ shop.permanent_domain }}
+	Primary Domain of Shop 		: {{ shop.domain }}
+	Shop URL 			: {{ shop.url }}
+	Shop Currency 			: {{ shop.currency }}
+	No. of products in this shop 	: {{ shop.products_count }}
+<br>
+<hr>
+</pre>

data/lib/generators/shopify_app/authenticated_controller/authenticated_controller_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class AuthenticatedControllerGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_authenticated_controller
+        template('authenticated_controller.rb', 'app/controllers/authenticated_controller.rb')
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/authenticated_controller/templates/authenticated_controller.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class AuthenticatedController < ApplicationController
+  include ShopifyApp::Authenticated
+end

data/lib/generators/shopify_app/controllers/controllers_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class ControllersGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../../..", __FILE__)
+
+      def create_controllers
+        controllers.each do |controller|
+          copy_file(controller)
+        end
+      end
+
+      private
+
+      def controllers
+        files_within_root('.', 'app/controllers/shopify_app/*.*')
+      end
+
+      def files_within_root(prefix, glob)
+        root = "#{self.class.source_root}/#{prefix}"
+
+        Dir["#{root}/#{glob}"].sort.map do |full_path|
+          full_path.sub(root, '.').gsub('/./', '/')
+        end
+      end
+    end
+  end
+end

data/lib/generators/shopify_app/home_controller/home_controller_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+require 'rails/generators/base'
+
+module ShopifyApp
+  module Generators
+    class HomeControllerGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      class_option :with_cookie_authentication, type: :boolean, default: false
+      class_option :embedded, type: :string, default: 'true'
+
+      def create_home_controller
+        template(home_controller_template, 'app/controllers/home_controller.rb')
+      end
+
+      def create_products_controller
+        generate("shopify_app:products_controller") unless with_cookie_authentication?
+      end
+
+      def create_home_index_view
+        template('index.html.erb', 'app/views/home/index.html.erb')
+      end
+
+      def add_home_index_route
+        route("root :to => 'home#index'")
+      end
+
+      private
+
+      def embedded?
+        options['embedded'] == 'true'
+      end
+
+      def embedded_app?
+        ShopifyApp.configuration.embedded_app?
+      end
+
+      def with_cookie_authentication?
+        options['with_cookie_authentication']
+      end
+
+      def home_controller_template
+        return 'unauthenticated_home_controller.rb' unless authenticated_home_controller_required?
+
+        'home_controller.rb'
+      end
+
+      def authenticated_home_controller_required?
+        with_cookie_authentication? || !embedded? || !embedded_app?
+      end
+    end
+  end
+end