commerce7-rails 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d17bdff3aaa4490b2fda29996b277c0947c5dcb6539d4bc02b8d81a63cb50fd0
+  data.tar.gz: b16fc3cdc51a00bf3e8563283db63fbaf2bc14d5508831038cb26c155ca3ad6e
+SHA512:
+  metadata.gz: 52f6b435f3044adf60b7210a78b1d0b69ccfaa018d126f89432a764875d55a4a370d50c87928a7f7e4024314b3c857a863e6ecc8512ce221c0f281065190ccd6
+  data.tar.gz: b7160af777302983bc93d39308bcf63a9f4058c177d5e1ddf5b37be021522fcb69dc5d109cbaf12db86550a45e006c52e18d67c98c8e92cbd18df6e56a4f5b94

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Roberts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# commerce7-rails
+
+Rails building blocks for building a [Commerce7](https://www.commerce7.com/) App Store integration: activation/deactivation lifecycle, App Extension staff-JWT auth, safe webhook dispatch, the Commerce7 REST client, and the post-uninstall data purge Commerce7's App Store security review requires.
+
+This gem owns the Commerce7-protocol plumbing. Your app owns the business logic: your tenant model's own fields, what a webhook handler actually does, what your App Extension pages render.
+
+## Install
+
+```ruby
+# Gemfile
+gem "commerce7-rails", github: "ERCubed/commerce7-rails", tag: "v0.2.0"
+```
+
+```
+bundle install
+bin/rails generate commerce7:install
+bin/rails db:migrate
+```
+
+The generator creates `db/migrate/*_create_tenants.rb` (skip/adapt it if your app already has a `tenants` table) and `config/initializers/commerce7.rb`.
+
+## Configure
+
+```ruby
+# config/initializers/commerce7.rb
+Commerce7.configure do |c|
+  c.tenant_class_name = "Tenant"
+
+  # -> { [username, password] } — the Basic Auth pair you configured in
+  # Commerce7's Developer Center for the Install/Uninstall URLs and the
+  # app-level Web Hook.
+  c.webhook_credentials = -> {
+    [
+      Rails.application.credentials.dig(:commerce7, :webhook_username),
+      Rails.application.credentials.dig(:commerce7, :webhook_password)
+    ]
+  }
+
+  # -> { [app_id, app_secret_key] } — the single app-wide Commerce7 API
+  # credential pair (not per-tenant).
+  c.app_credentials = -> {
+    [
+      Rails.application.credentials.dig(:commerce7, :app_id),
+      Rails.application.credentials.dig(:commerce7, :app_secret_key)
+    ]
+  }
+
+  # ->(event_type:, success:, **kwargs) { ... } — point this at your own
+  # audit-log write path so Commerce7-driven events land in the same trail
+  # as the rest of your app's.
+  c.audit = ->(**kwargs) { AuditEvent.record!(**kwargs) }
+end
+```
+
+Your tenant model includes the lifecycle concern and, since Commerce7's activation POST carries the installing staff member's name/email, encrypts it:
+
+```ruby
+class Tenant < ApplicationRecord
+  include Commerce7::TenantConcern
+  encrypts :raw_activation_payload
+end
+```
+
+Your app also needs a top-level `Current`, the standard Rails per-request-state convention — `Commerce7::ExtensionController` and `Commerce7::PurgeDeactivatedTenantsJob` both use it:
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :tenant, :staff_user
+end
+```
+
+## Routes
+
+This gem mounts nothing — you declare routes exactly as you would for any in-app controller, just pointing at the gem's classes, so the URLs already registered in Commerce7's Developer Center (Install/Uninstall URLs, an App Extension's iframe src) stay stable and under your control:
+
+```ruby
+namespace :commerce7 do
+  post "activate", to: "activations#create", as: :activate
+  post "deactivate", to: "deactivations#create", as: :deactivate
+  post "webhooks", to: "webhooks#create", as: :webhooks
+
+  # Your own App Extension pages, subclassing Commerce7::ExtensionController:
+  get "dashboard", to: "dashboard#show", as: :dashboard
+end
+```
+
+## Webhook dispatch
+
+`Commerce7::WebhooksController` handles the parsing, Basic Auth, tenant lookup, and audit write. You register what your app actually does for each `(object, action)` pair Commerce7 might send — anything unregistered is a silent no-op, matching Commerce7's own retry-tolerant expectations:
+
+```ruby
+Commerce7::Webhooks.on("Club Membership", "Create", "Update") do |tenant, payload, actor|
+  SyncJob.perform_later(tenant)
+end
+
+Commerce7::Webhooks.on("Customer", "Delete") do |tenant, payload, actor|
+  Current.tenant = tenant
+  ClubMember.find_by(commerce7_customer_id: payload["customerId"])&.destroy
+  Current.tenant = nil
+end
+```
+
+Handlers must be **idempotent by construction** (upsert / find-and-destroy) — Commerce7 doesn't expose a delivery/event id to dedupe a redelivery against.
+
+## Activation/deactivation hooks
+
+```ruby
+# Runs once, after a tenant activates (first install or reinstall) — typically
+# a one-time backfill sync, since Web Hooks only fire on future changes.
+Commerce7.on_activate do |tenant, payload|
+  SyncJob.perform_later(tenant)
+end
+
+Commerce7.on_deactivate do |tenant|
+  # optional
+end
+```
+
+## The 30-day post-uninstall purge
+
+Commerce7's security review requires customer data deleted within 30 days of app termination. `Commerce7::TenantConcern` soft-deactivates on uninstall (never hard-deletes, so a reinstall within the window keeps the tenant's data) and exposes a `pending_deletion` scope; `Commerce7::PurgeDeactivatedTenantsJob` hard-deletes anything past that window. Schedule it as a recurring job:
+
+```yaml
+# config/recurring.yml (Solid Queue)
+production:
+  commerce7_purge_deactivated_tenants:
+    class: Commerce7::PurgeDeactivatedTenantsJob
+    queue: default
+    schedule: every day at 3am
+```
+
+## The REST client
+
+```ruby
+client = Commerce7::Client.new(tenant)
+client.each_club_membership { |membership| ... }  # paginates automatically
+client.each_customer { |customer| ... }
+client.each_order { |order| ... }
+client.each_order(orderPaidDate: "gte:2026-01-01") { |order| ... }  # params pass through as filters
+client.each_product { |product| ... }              # variants + per-location inventory inline
+client.each_inventory_location { |location| ... }
+client.fetch_order(order_id)
+```
+
+Handles pagination, the 100 req/min rate limit (retries on 429 using `Retry-After` when present, exponential backoff otherwise), and raises `Commerce7::Client::AuthenticationError` / `RateLimitedError` / `ApiError` as appropriate.
+
+`Commerce7::AccountClient` validates the staff JWT Commerce7 passes into an App Extension iframe — used internally by `Commerce7::ExtensionController`, but available directly if you need it.
+
+## Security posture
+
+This gem exists so every app built on it starts from a "Yes" on Commerce7's App Store security questionnaire, not a retrofit:
+
+- **Server-to-server auth**: `Commerce7::BaseController` requires HTTP Basic Auth (your `webhook_credentials`) on every activation/deactivation/webhook POST, and audits both successful and failed attempts.
+- **App Extension auth**: `Commerce7::ExtensionController` validates the staff JWT Commerce7 passes into every iframe load against Commerce7's own `/account/user` endpoint — a real error page on failure, never a bare status code.
+- **PII**: `raw_activation_payload` (the installing staff member's name/email) is your model's column to encrypt — see Install above.
+- **Data deletion**: built in — soft-deactivate on uninstall, hard-delete after 30 days (`Commerce7::PurgeDeactivatedTenantsJob`).
+- **Webhook auth + idempotency**: Basic Auth on every delivery; handlers are expected to be idempotent by construction, since Commerce7 exposes no delivery id to dedupe against.
+- **Audit trail**: every security-relevant event (server auth success/failure, activation/deactivation, staff extension auth, webhook-driven dispatch, the post-uninstall purge) flows through your configured `audit` hook — user identity, event type, timestamp, success/failure, and origin.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec brakeman
+bundle exec bundler-audit --update
+```
+
+Tests run against a minimal dummy Rails app (via [combustion](https://github.com/pat/combustion)) at `spec/dummy`.

data/app/controllers/commerce7/activations_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Receives Commerce7's activation POST on app install. Per Commerce7's
+  # docs, this sends `tenantId` plus the installer's first name, last name,
+  # and email — NOT API credentials. That's expected: the App ID/Secret Key
+  # is a single app-wide pair (see Commerce7.configuration.app_credentials),
+  # not something issued per tenant.
+  class ActivationsController < BaseController
+    def create
+      tenant = Commerce7.configuration.tenant_class.activate!(
+        commerce7_tenant_id: params.require(:tenantId),
+        payload: activation_payload
+      )
+
+      # See Commerce7.on_activate — typically used to kick off a one-time
+      # backfill sync, since Commerce7's Web Hooks only fire on future
+      # changes, not a newly (re)installed tenant's pre-existing data.
+      Commerce7.run_activate_hooks(tenant, activation_payload)
+
+      Commerce7.audit!(event_type: "tenant_activated", success: true, commerce7_tenant_id: tenant.commerce7_tenant_id, origin_ip: request.remote_ip)
+
+      head :ok
+    end
+
+    private
+
+    def activation_payload
+      params.except(:controller, :action).to_unsafe_h
+    end
+  end
+end

data/app/controllers/commerce7/base_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Base for Commerce7 server-to-server POSTs: the app-wide Install/Uninstall
+  # URLs (activation, deactivation) and the app-level Web Hooks feature. Not
+  # browser requests, so this skips the CSRF check and doesn't inherit a
+  # host app's ApplicationController (e.g. its allow_browser restriction).
+  #
+  # Auth is HTTP Basic in both cases, per Commerce7's docs: Install/Uninstall
+  # URLs support an optional username/password configured in their
+  # dashboard's "Advanced" section, and a Web Hook registered in the same
+  # Developer Center app version supports the same "Advanced Authentication"
+  # — both are a single app-wide credential pair set once, not something
+  # each tenant configures (see Commerce7.configuration.webhook_credentials).
+  class BaseController < ActionController::Base
+    # Explicit rather than relying on a host app's `default_protect_from_forgery`
+    # config default — this gem shouldn't depend on that being set for its
+    # own controllers' safety. Immediately skipped below since these are
+    # server-to-server requests with no session/cookie to forge against.
+    protect_from_forgery with: :exception
+    skip_before_action :verify_authenticity_token, raise: false
+
+    before_action :authenticate_commerce7!
+
+    rescue_from ActionController::ParameterMissing do |error|
+      render json: { error: error.message }, status: :bad_request
+    end
+
+    private
+
+    # Deliberately not authenticate_or_request_with_http_basic: that method's
+    # return value is truthy even on failure (it's a bare
+    # `response_body = message` assignment under the hood — see
+    # ActionController::HttpAuthentication::Basic::ProtectedMethods#authentication_request),
+    # so it can't be used as a success/failure signal for auditing. Calling
+    # authenticate_with_http_basic directly and handling the 401 ourselves
+    # gives an unambiguous boolean instead.
+    def authenticate_commerce7!
+      return if authenticate_with_http_basic { |username, password| valid_commerce7_credentials?(username, password) }
+
+      Commerce7.audit!(
+        event_type: "commerce7_server_auth",
+        success: false,
+        commerce7_tenant_id: params[:tenantId],
+        origin_ip: request.remote_ip,
+        metadata: { path: request.path }
+      )
+      request_http_basic_authentication
+    end
+
+    def valid_commerce7_credentials?(username, password)
+      expected_username, expected_password = Commerce7.configuration.webhook_credentials.call
+
+      expected_username.present? && expected_password.present? &&
+        ActiveSupport::SecurityUtils.secure_compare(username, expected_username) &&
+        ActiveSupport::SecurityUtils.secure_compare(password, expected_password)
+    end
+  end
+end

data/app/controllers/commerce7/deactivations_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Receives Commerce7's deactivation POST on app uninstall. Soft-deactivates
+  # the tenant (never hard-deletes) so a reinstall can reactivate the same
+  # record — see Commerce7::TenantConcern#activate! and
+  # Commerce7::PurgeDeactivatedTenantsJob, which enforces the actual
+  # post-uninstall deletion after a retention window. A tenantId this app
+  # doesn't recognize is a no-op, not an error, since webhook/POST retries
+  # are common and shouldn't fail loudly.
+  class DeactivationsController < BaseController
+    def create
+      tenant = Commerce7.configuration.tenant_class.find_by(commerce7_tenant_id: params.require(:tenantId))
+      if tenant
+        tenant.deactivate!
+        Commerce7.run_deactivate_hooks(tenant)
+        Commerce7.audit!(event_type: "tenant_deactivated", success: true, commerce7_tenant_id: tenant.commerce7_tenant_id, origin_ip: request.remote_ip)
+      end
+
+      head :ok
+    end
+  end
+end

data/app/controllers/commerce7/extension_controller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Base for pages embedded as a Commerce7 App Extension (iframe). Commerce7
+  # appends `tenantId` and `account` (a staff JWT) to the iframe src URL;
+  # this validates that JWT against Commerce7's API and resolves
+  # Current.tenant/Current.staff_user before any subclass action runs. A
+  # host app is expected to define a top-level `Current < ActiveSupport::
+  # CurrentAttributes` with `tenant` and `staff_user` attributes — the same
+  # convention Rails apps already reach for to scope per-request state.
+  class ExtensionController < ActionController::Base
+    # Explicit rather than relying on a host app's `default_protect_from_forgery`
+    # config default — this gem shouldn't depend on that being set for its
+    # own controllers' safety. A subclass that adds a mutating, browser-
+    # submitted action inherits this; Commerce7's staff-JWT re-validation on
+    # every request (see authenticate_staff! below) is a second, independent
+    # boundary a subclass can lean on if it needs to skip this one (e.g. for
+    # a cross-site iframe POST where the session cookie may not travel).
+    protect_from_forgery with: :exception
+
+    before_action :authenticate_staff!
+
+    # Rails sends X-Frame-Options: SAMEORIGIN by default, which blocks
+    # Commerce7's admin panel (a different origin) from framing this page at
+    # all. Commerce7 doesn't publish a stable admin origin to scope a
+    # replacement CSP frame-ancestors to, so this just drops the blanket
+    # deny; a host app that wants a tighter CSP can add its own
+    # frame-ancestors directive once that origin is confirmed.
+    after_action { response.headers.delete("X-Frame-Options") }
+
+    rescue_from ActionController::ParameterMissing do |error|
+      render plain: error.message, status: :bad_request
+    end
+
+    private
+
+    def authenticate_staff!
+      tenant_id = params.require(:tenantId)
+      tenant = Commerce7.configuration.tenant_class.active.find_by(commerce7_tenant_id: tenant_id)
+      unless tenant
+        audit_auth!(success: false, tenant_id: tenant_id, reason: "unknown_or_deactivated_tenant")
+        # Same real error page as a rejected staff token (see below), not a
+        # bare status code — an uninstalled-then-still-open tab is the
+        # common way staff land here.
+        return render "commerce7/extension/unauthorized", status: :forbidden
+      end
+
+      Current.staff_user = Commerce7::AccountClient.new.fetch_user(tenant_id: tenant_id, token: params.require(:account))
+      Current.tenant = tenant
+      audit_auth!(success: true, tenant_id: tenant_id, actor: Current.staff_user["email"])
+    rescue Commerce7::AccountClient::AuthenticationError
+      audit_auth!(success: false, tenant_id: tenant_id, reason: "invalid_staff_token")
+      # A host app can override this view (same path, its own app/views) to
+      # match its own styling; this gem ships a plain-text fallback so
+      # staff always see a real error page here, never a bare 401.
+      render "commerce7/extension/unauthorized", status: :unauthorized
+    end
+
+    def audit_auth!(success:, tenant_id:, actor: nil, reason: nil)
+      Commerce7.audit!(
+        event_type: "staff_extension_auth",
+        success: success,
+        actor: actor,
+        commerce7_tenant_id: tenant_id,
+        origin_ip: request.remote_ip,
+        metadata: reason ? { reason: reason } : {}
+      )
+    end
+  end
+end

data/app/controllers/commerce7/webhooks_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Receives Commerce7's Web Hooks — configured once, app-wide, in the
+  # Developer Center's app version under "Step 1. APIs & Webhooks", NOT
+  # per-tenant. Per Commerce7's docs (developer.commerce7.com/docs/
+  # app-apis-webhooks), a webhook registered there applies automatically to
+  # every tenant that installs the app, no per-winery setup required — this
+  # is a different, app-level mechanism from a store's own independent
+  # "Developer > Web Hooks" admin page, which is for a winery's own
+  # integrations, unrelated to marketplace apps like this one.
+  #
+  # Per Commerce7's docs (developer.commerce7.com/docs/webhooks), the body
+  # is {object, action, payload, user, tenantId}; object/action cover far
+  # more than any one app acts on, so this only parses and dispatches —
+  # see Commerce7::Webhooks for how a host app registers what it cares
+  # about. Anything with no registered handler is silently a no-op rather
+  # than an error.
+  class WebhooksController < BaseController
+    # `action` is also the name Rails reserves for the controller action
+    # itself (routing sets params[:action] = "create" on every request
+    # regardless of body content) — reading it via `params` would silently
+    # return "create" no matter what Commerce7 actually sent, matching no
+    # registered handler and turning every webhook into a silent no-op.
+    # Parsing the raw JSON body instead sidesteps that collision entirely.
+    def create
+      body = JSON.parse(request.body.read)
+      return head :bad_request unless body["tenantId"].present? && body["object"].present? && body["action"].present?
+
+      tenant = Commerce7.configuration.tenant_class.active.find_by(commerce7_tenant_id: body["tenantId"])
+      handle(tenant, object: body["object"], action: body["action"], payload: body["payload"] || {}, actor: body["user"]) if tenant
+
+      head :ok
+    rescue JSON::ParserError
+      head :bad_request
+    end
+
+    private
+
+    def handle(tenant, object:, action:, payload:, actor:)
+      handled = Commerce7::Webhooks.dispatch(object: object, action: action, tenant: tenant, payload: payload, actor: actor)
+      return unless handled
+
+      Commerce7.audit!(
+        event_type: "webhook_#{object.parameterize(separator: '_')}_#{action.downcase}",
+        success: true,
+        actor: actor,
+        commerce7_tenant_id: tenant.commerce7_tenant_id,
+        origin_ip: request.remote_ip
+      )
+    end
+  end
+end

data/app/jobs/commerce7/purge_deactivated_tenants_job.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Schedule this as a recurring job (e.g. Solid Queue's config/recurring.yml,
+  # `schedule: every day at 3am`) to enforce Commerce7's app security policy:
+  # customer data deleted within 30 days of app termination. Hard-deletes
+  # any tenant still deactivated past Commerce7::TenantConcern::
+  # DATA_RETENTION_DAYS — cascading to whatever `dependent: :destroy`
+  # associations the host's tenant model declares.
+  class PurgeDeactivatedTenantsJob < ::ActiveJob::Base
+    queue_as :default
+
+    def perform
+      Commerce7.configuration.tenant_class.pending_deletion.find_each { |tenant| purge(tenant) }
+    end
+
+    private
+
+    # Many tenant-scoped hosts (see the app's TenantScoped-style pattern)
+    # resolve their default_scope through Current.tenant, which
+    # `dependent: :destroy` associations rely on to find what to cascade —
+    # skipping this can leave dependent rows behind, or make the tenant
+    # DELETE itself fail outright against a real FK constraint. Setting
+    # Current.tenant here mirrors what Commerce7::ExtensionController and
+    # Commerce7::WebhooksController already do per-request.
+    def purge(tenant)
+      commerce7_tenant_id = tenant.commerce7_tenant_id
+      Current.tenant = tenant
+      tenant.destroy!
+      Commerce7.audit!(event_type: "tenant_data_purged", success: true, commerce7_tenant_id: commerce7_tenant_id)
+    ensure
+      Current.tenant = nil
+    end
+  end
+end

data/app/models/concerns/commerce7/tenant_concern.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Include in the host app's own tenant model (see
+  # Commerce7.configuration.tenant_class_name) to get the activate/
+  # deactivate lifecycle Commerce7::ActivationsController,
+  # DeactivationsController, ExtensionController, and WebhooksController all
+  # depend on. Expects the model to have commerce7_tenant_id,
+  # activated_at, deactivated_at, and raw_activation_payload columns — see
+  # Commerce7::Generators::InstallGenerator for a migration that adds them.
+  #
+  # raw_activation_payload carries PII (the installing staff member's name/
+  # email, per Commerce7's activation docs) — add `encrypts
+  # :raw_activation_payload` in the including model.
+  module TenantConcern
+    extend ActiveSupport::Concern
+
+    # Commerce7's app security policy requires customer data deleted within
+    # 30 days of app termination — see Commerce7::PurgeDeactivatedTenantsJob,
+    # which hard-deletes any tenant still deactivated after this window.
+    # Kept short of 30 days deliberately: a tenant reactivated via
+    # .activate! before this elapses keeps all its data.
+    DATA_RETENTION_DAYS = 30
+
+    included do
+      validates :commerce7_tenant_id, presence: true, uniqueness: true
+
+      scope :active, -> { where(deactivated_at: nil) }
+      scope :pending_deletion, -> { where.not(deactivated_at: nil).where(deactivated_at: ..DATA_RETENTION_DAYS.days.ago) }
+    end
+
+    class_methods do
+      # Handles both first install and a reinstall of a previously
+      # deactivated tenant (find_or_initialize_by, not create!) —
+      # activation always clears deactivated_at, matching Commerce7
+      # sending an activation POST either way.
+      def activate!(commerce7_tenant_id:, payload:)
+        tenant = find_or_initialize_by(commerce7_tenant_id: commerce7_tenant_id)
+        tenant.update!(activated_at: Time.current, deactivated_at: nil, raw_activation_payload: payload)
+        tenant
+      end
+    end
+
+    def active?
+      deactivated_at.nil?
+    end
+
+    # Soft-deactivates, never deletes — an uninstall may be followed by a
+    # reinstall (see .activate!), and this app's synced data shouldn't
+    # vanish just because the app was temporarily removed.
+    def deactivate!
+      update!(deactivated_at: Time.current)
+    end
+  end
+end

data/app/services/commerce7/account_client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Validates the staff JWT Commerce7 passes into an App Extension iframe
+  # (the `account` URL param) via GET /account/user. Confirmed against
+  # Commerce7's docs: Authorization header carries the raw token (no
+  # "Bearer" prefix), `tenant` header carries the tenantId URL param.
+  #
+  # Distinct from Commerce7::Client: that one authenticates as the app
+  # (Basic Auth with App ID/Secret Key) for server-to-server calls; this
+  # authenticates as the staff member currently viewing the iframe, and
+  # needs no app credentials of its own.
+  class AccountClient
+    class Error < StandardError; end
+    class AuthenticationError < Error; end
+    class ApiError < Error; end
+
+    BASE_URL = Commerce7::Client::BASE_URL
+
+    def initialize(base_url: BASE_URL)
+      @base_url = base_url
+    end
+
+    def fetch_user(tenant_id:, token:)
+      response = connection.get("account/user") do |req|
+        req.headers["Authorization"] = token
+        req.headers["tenant"] = tenant_id
+      end
+
+      handle_response(response)
+    end
+
+    private
+
+    attr_reader :base_url
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401
+        raise AuthenticationError, "Commerce7 rejected the staff token"
+      else
+        raise ApiError, "Commerce7 API error (#{response.status}): #{response.body}"
+      end
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |f|
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/app/services/commerce7/client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # HTTP client for Commerce7's REST API. Confirmed against Commerce7's public
+  # docs: base URL, Basic Auth (App ID/App Secret Key as user/pass), endpoint
+  # paths, page/limit pagination (max 50/page, matches PAGE_SIZE), response
+  # envelope keys, and the 100 req/min rate limit.
+  #
+  # The App ID/App Secret Key pair is a single pair for the app as a whole,
+  # not one per tenant (see Commerce7.configuration.app_credentials) — so the
+  # `tenant` header is the only thing that scopes a request to a specific
+  # winery's data.
+  class Client
+    class Error < StandardError; end
+    class AuthenticationError < Error; end
+    class RateLimitedError < Error; end
+    class ApiError < Error; end
+
+    # Trailing slash matters: Faraday/URI joins a relative path onto this by
+    # RFC 3986 merge rules, so without it "v1" gets treated as a filename and
+    # dropped (e.g. base ".../v1" + "customer" => ".../customer", not ".../v1/customer").
+    BASE_URL = "https://api.commerce7.com/v1/"
+    PAGE_SIZE = 50
+    MAX_RETRIES = 3
+
+    def initialize(tenant, base_url: BASE_URL, sleeper: ->(seconds) { sleep(seconds) })
+      @app_id, @app_secret_key = Commerce7.configuration.app_credentials.call
+      if @app_id.blank? || @app_secret_key.blank?
+        raise ArgumentError, "Commerce7.configuration.app_credentials returned a blank app_id/app_secret_key"
+      end
+
+      @tenant = tenant
+      @base_url = base_url
+      @sleeper = sleeper
+    end
+
+    def each_customer(&block)
+      return enum_for(:each_customer) unless block_given?
+
+      each_record("customer", "customers", &block)
+    end
+
+    def each_club_membership(&block)
+      return enum_for(:each_club_membership) unless block_given?
+
+      each_record("club-membership", "clubMemberships", &block)
+    end
+
+    # `params` pass straight through as Commerce7 query filters (e.g.
+    # `orderPaidDate: "gte:2026-01-01"`), so a caller can bound a listing
+    # instead of paging through a tenant's entire order history.
+    def each_order(params = {}, &block)
+      return enum_for(:each_order, params) unless block_given?
+
+      each_record("order", "orders", params, &block)
+    end
+
+    # Products carry their variants inline, and each variant carries its
+    # per-location inventory counts (variants[].inventory[], keyed by
+    # inventoryLocationId) plus the winery's custom fields (metaData) —
+    # enough for a full inventory snapshot without a separate call per SKU.
+    def each_product(params = {}, &block)
+      return enum_for(:each_product, params) unless block_given?
+
+      each_record("product", "products", params, &block)
+    end
+
+    def each_inventory_location(params = {}, &block)
+      return enum_for(:each_inventory_location, params) unless block_given?
+
+      each_record("inventory-location", "inventoryLocations", params, &block)
+    end
+
+    # Single-order lookup (as opposed to each_order's bulk listing) — some
+    # App Extension placements (e.g. an Order Detail tab) only get an
+    # orderId from Commerce7. Returns the order hash, which carries a
+    # top-level customerId same as club-membership's.
+    def fetch_order(order_id)
+      get("order/#{order_id}", {})
+    end
+
+    private
+
+    attr_reader :tenant, :base_url, :sleeper
+
+    def each_record(path, response_key, params = {})
+      page = 1
+
+      loop do
+        records = get(path, params.merge(page: page, limit: PAGE_SIZE))[response_key] || []
+        records.each { |record| yield record }
+
+        break if records.size < PAGE_SIZE
+
+        page += 1
+      end
+    end
+
+    def get(path, params)
+      response = with_rate_limit_retry { connection.get(path, params) }
+      handle_response(response)
+    end
+
+    def with_rate_limit_retry
+      attempt = 0
+
+      loop do
+        response = yield
+        return response unless response.status == 429
+
+        attempt += 1
+        raise RateLimitedError, "Commerce7 rate limit exceeded after #{MAX_RETRIES} retries" if attempt > MAX_RETRIES
+
+        sleeper.call(retry_delay(response, attempt))
+      end
+    end
+
+    def retry_delay(response, attempt)
+      retry_after = response.headers["retry-after"].to_s.to_i
+      retry_after.positive? ? retry_after : 2**attempt
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401
+        raise AuthenticationError, "Commerce7 rejected the tenant's credentials"
+      else
+        raise ApiError, "Commerce7 API error (#{response.status}): #{response.body}"
+      end
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |f|
+        f.request :authorization, :basic, @app_id, @app_secret_key
+        f.headers["tenant"] = tenant.commerce7_tenant_id
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/app/views/commerce7/extension/unauthorized.html.erb

@@ -0,0 +1,2 @@
+<h1>Unauthorized</h1>
+<p>Commerce7 could not validate your staff session for this page. Please reload it from the Commerce7 admin panel.</p>

data/lib/commerce7/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Everything a host app wires up once, in config/initializers/commerce7.rb
+  # (see Commerce7::Generators::InstallGenerator for a starting template).
+  # There's no default tenant/webhook/app credential source deliberately —
+  # this gem never assumes Rails encrypted credentials over any other
+  # secrets store, so a missing config surfaces as a clear error rather than
+  # silently falling back to something the host never configured.
+  class Configuration
+    # The ActiveRecord class that includes Commerce7::TenantConcern.
+    attr_accessor :tenant_class_name
+
+    # -> { [webhook_username, webhook_password] } — HTTP Basic credentials
+    # Commerce7 was configured (in its Developer Center) to send on the
+    # Install/Uninstall URLs and the app-level Web Hook.
+    attr_accessor :webhook_credentials
+
+    # -> { [app_id, app_secret_key] } — the single app-wide Commerce7 API
+    # credential pair (not per-tenant) used by Commerce7::Client.
+    attr_accessor :app_credentials
+
+    # ->(event_type:, success:, **kwargs) { ... } — called for every
+    # security-relevant event this gem's controllers/jobs produce (auth
+    # success/failure, activation/deactivation, webhook-driven mutation,
+    # purge). Point this at your app's own audit-log write path (e.g.
+    # `->(**kw) { AuditEvent.record!(**kw) }`) so Commerce7-driven events
+    # land in the same trail as the rest of the app's.
+    attr_accessor :audit
+
+    def initialize
+      @tenant_class_name = "Tenant"
+      @webhook_credentials = -> { raise_unconfigured!(:webhook_credentials) }
+      @app_credentials = -> { raise_unconfigured!(:app_credentials) }
+      @audit = ->(**) { }
+    end
+
+    def tenant_class
+      tenant_class_name.constantize
+    end
+
+    private
+
+    def raise_unconfigured!(setting)
+      raise Commerce7::Error,
+        "Commerce7.configuration.#{setting} is not set — configure it in config/initializers/commerce7.rb"
+    end
+  end
+end

data/lib/commerce7/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Adds this gem's app/{controllers,models/concerns,jobs,services,views}
+  # to the host app's autoload/eager-load and view paths — the standard
+  # Rails::Engine subclassing convention. Deliberately not isolated
+  # (no `isolate_namespace`) and mounts no routes of its own: a host app
+  # keeps declaring its own config/routes.rb entries exactly as it would
+  # for any in-app controller, just pointing at these gem-provided classes
+  # (e.g. `post "activate", to: "commerce7/activations#create"`). That keeps
+  # the URLs Commerce7's Developer Center has registered (Install/Uninstall
+  # URLs, the App Extension iframe src) stable and host-controlled.
+  class Engine < ::Rails::Engine
+    engine_name "commerce7"
+  end
+end

data/lib/commerce7/rails.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "commerce7/version"
+require "commerce7/configuration"
+require "commerce7/webhooks"
+require "commerce7/engine" if defined?(Rails::Engine)
+
+module Commerce7
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # Runs after Commerce7::ActivationsController activates (or
+    # reactivates) a tenant — typically used to kick off a one-time backfill
+    # sync, since Commerce7's Web Hooks only fire on future changes, not a
+    # newly (re)installed tenant's pre-existing data.
+    def on_activate(&block)
+      activate_hooks << block
+    end
+
+    # Runs after Commerce7::DeactivationsController soft-deactivates a
+    # tenant. Optional — Commerce7::PurgeDeactivatedTenantsJob independently
+    # enforces the 30-day post-uninstall deletion requirement regardless of
+    # whether a host registers this hook.
+    def on_deactivate(&block)
+      deactivate_hooks << block
+    end
+
+    def run_activate_hooks(tenant, payload)
+      activate_hooks.each { |hook| hook.call(tenant, payload) }
+    end
+
+    def run_deactivate_hooks(tenant)
+      deactivate_hooks.each { |hook| hook.call(tenant) }
+    end
+
+    # Auditing must never be why the thing it's observing fails — a bad
+    # configured audit hook shouldn't 500 a webhook delivery or a staff
+    # member's page load. Logged loudly on failure so a real bug in the
+    # host's audit hook still surfaces instead of vanishing.
+    def audit!(**kwargs)
+      configuration.audit.call(**kwargs)
+    rescue StandardError => e
+      Rails.logger.error("Commerce7.audit! hook raised: #{e.class}: #{e.message}") if defined?(Rails)
+    end
+
+    # Test helper: resets configuration, lifecycle hooks, and webhook
+    # registrations. Call from a spec suite's global before/after hook so
+    # one example's Commerce7.configure doesn't leak into the next.
+    def reset!
+      @configuration = nil
+      @activate_hooks = []
+      @deactivate_hooks = []
+      Commerce7::Webhooks.reset!
+    end
+
+    private
+
+    def activate_hooks
+      @activate_hooks ||= []
+    end
+
+    def deactivate_hooks
+      @deactivate_hooks ||= []
+    end
+  end
+end

data/lib/commerce7/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Commerce7
+  VERSION = "0.2.0"
+end

data/lib/commerce7/webhooks.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Commerce7
+  # Registry for Commerce7::WebhooksController to dispatch into. Commerce7's
+  # Web Hooks feature (registered once, app-wide, in the Developer Center's
+  # "APIs & Webhooks" step) delivers a body of {object, action, payload,
+  # user, tenantId} covering far more object/action pairs than any one app
+  # acts on — object/action this app doesn't register a handler for are a
+  # silent no-op, not an error, matching Commerce7's own retry-tolerant
+  # expectations.
+  #
+  # Register handlers from a host app initializer:
+  #
+  #   Commerce7::Webhooks.on("Club Membership", "Create", "Update") do |tenant, payload, actor|
+  #     SyncJob.perform_later(tenant)
+  #   end
+  #
+  # A handler block receives the tenant (an instance of the configured
+  # tenant class), the raw payload hash, and the actor string Commerce7
+  # attached to the delivery (its "user" field, if any). Handlers are
+  # expected to be idempotent by construction (upsert / find-and-destroy) —
+  # Commerce7 doesn't expose a delivery/event id to dedupe against, so a
+  # redelivered webhook must land at the same end state, not double-apply.
+  module Webhooks
+    Handler = Struct.new(:object, :actions, :block)
+    private_constant :Handler
+
+    class << self
+      def on(object, *actions, &block)
+        handlers << Handler.new(object, actions, block)
+      end
+
+      # Runs every handler registered for this (object, action) pair.
+      # Returns true if at least one handler ran, so the caller knows
+      # whether this was a recognized event worth auditing.
+      def dispatch(object:, action:, tenant:, payload:, actor:)
+        matched = handlers.select { |handler| handler.object == object && handler.actions.include?(action) }
+        matched.each { |handler| handler.block.call(tenant, payload, actor) }
+        matched.any?
+      end
+
+      # Test helper: clears registrations between specs so one example's
+      # Commerce7::Webhooks.on doesn't leak into the next.
+      def reset!
+        @handlers = []
+      end
+
+      private
+
+      def handlers
+        @handlers ||= []
+      end
+    end
+  end
+end

data/lib/generators/commerce7/install/install_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Commerce7
+  module Generators
+    # `rails generate commerce7:install` — scaffolds the migration and
+    # initializer a fresh host app needs to start using this gem. Doesn't
+    # touch an existing `tenants` table if the host already has one; review
+    # and adapt the generated migration in that case instead of running it
+    # as-is.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "create_tenants.rb.erb", "db/migrate/create_tenants.rb"
+      end
+
+      def create_initializer
+        template "commerce7.rb", "config/initializers/commerce7.rb"
+      end
+
+      def show_readme
+        readme "POST_INSTALL.md" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/commerce7/install/templates/POST_INSTALL.md

@@ -0,0 +1,17 @@
+
+==============================================================================
+
+commerce7-rails installed. Next steps:
+
+  1. Run the generated migration: bin/rails db:migrate
+  2. Add `include Commerce7::TenantConcern` and
+     `encrypts :raw_activation_payload` to your Tenant model.
+  3. Fill in config/initializers/commerce7.rb — credentials sources, your
+     audit hook, and any on_activate/webhook handlers.
+  4. Add routes (see the README's "Routes" section) pointing at
+     commerce7/activations, commerce7/deactivations, commerce7/webhooks,
+     and any Commerce7::ExtensionController subclasses you write.
+  5. Schedule Commerce7::PurgeDeactivatedTenantsJob as a recurring job —
+     required for Commerce7's 30-day post-uninstall deletion policy.
+
+==============================================================================

data/lib/generators/commerce7/install/templates/commerce7.rb

@@ -0,0 +1,34 @@
+Commerce7.configure do |c|
+  c.tenant_class_name = "Tenant"
+
+  c.webhook_credentials = -> {
+    [
+      Rails.application.credentials.dig(:commerce7, :webhook_username),
+      Rails.application.credentials.dig(:commerce7, :webhook_password)
+    ]
+  }
+  c.app_credentials = -> {
+    [
+      Rails.application.credentials.dig(:commerce7, :app_id),
+      Rails.application.credentials.dig(:commerce7, :app_secret_key)
+    ]
+  }
+
+  # Point this at your app's own audit-log write path so Commerce7-driven
+  # events (server auth, activation/deactivation, staff extension auth,
+  # webhook-driven mutations, the post-uninstall purge) land in the same
+  # trail as the rest of the app's. See the README's "Audit trail" section.
+  c.audit = ->(**kwargs) { AuditEvent.record!(**kwargs) }
+end
+
+# Runs once, after a tenant activates (first install or a reinstall) —
+# typically a one-time backfill sync, since Commerce7's Web Hooks only fire
+# on future changes.
+# Commerce7.on_activate do |tenant, payload|
+# end
+
+# Register a handler per (object, action) pair your app cares about — see
+# Commerce7::Webhooks for the full contract, including the idempotency
+# expectation.
+# Commerce7::Webhooks.on("Club Membership", "Create", "Update") do |tenant, payload, actor|
+# end

data/lib/generators/commerce7/install/templates/create_tenants.rb.erb

@@ -0,0 +1,17 @@
+class CreateTenants < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :tenants do |t|
+      t.string :commerce7_tenant_id, null: false
+      t.datetime :activated_at
+      t.datetime :deactivated_at
+      # PII (installing staff member's name/email, per Commerce7's
+      # activation docs) — add `encrypts :raw_activation_payload` on the
+      # Tenant model.
+      t.jsonb :raw_activation_payload, default: {}, null: false
+
+      t.timestamps
+    end
+
+    add_index :tenants, :commerce7_tenant_id, unique: true
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: commerce7-rails
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Eric Roberts
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Activation/deactivation lifecycle, webhook dispatch, App Extension staff-JWT
+  auth, the Commerce7 REST client, and the post-uninstall data purge Commerce7's security
+  review requires — configured once, reused across every Commerce7 app.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/controllers/commerce7/activations_controller.rb
+- app/controllers/commerce7/base_controller.rb
+- app/controllers/commerce7/deactivations_controller.rb
+- app/controllers/commerce7/extension_controller.rb
+- app/controllers/commerce7/webhooks_controller.rb
+- app/jobs/commerce7/purge_deactivated_tenants_job.rb
+- app/models/concerns/commerce7/tenant_concern.rb
+- app/services/commerce7/account_client.rb
+- app/services/commerce7/client.rb
+- app/views/commerce7/extension/unauthorized.html.erb
+- lib/commerce7/configuration.rb
+- lib/commerce7/engine.rb
+- lib/commerce7/rails.rb
+- lib/commerce7/version.rb
+- lib/commerce7/webhooks.rb
+- lib/generators/commerce7/install/install_generator.rb
+- lib/generators/commerce7/install/templates/POST_INSTALL.md
+- lib/generators/commerce7/install/templates/commerce7.rb
+- lib/generators/commerce7/install/templates/create_tenants.rb.erb
+homepage: https://github.com/ERCubed/commerce7-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ERCubed/commerce7-rails
+  source_code_uri: https://github.com/ERCubed/commerce7-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails building blocks for Commerce7 App Store integrations
+test_files: []