commerce7-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d17bdff3aaa4490b2fda29996b277c0947c5dcb6539d4bc02b8d81a63cb50fd0
-  data.tar.gz: b16fc3cdc51a00bf3e8563283db63fbaf2bc14d5508831038cb26c155ca3ad6e
+  metadata.gz: '094411b4f2757ca97c279f68504a9a76b3c2aad6a8db04ae2176cc82c9868430'
+  data.tar.gz: 24b9fdb82f090f504c900ef2fe10bad35a709cb4c4b622bc0595b9a4c00f3bce
 SHA512:
-  metadata.gz: 52f6b435f3044adf60b7210a78b1d0b69ccfaa018d126f89432a764875d55a4a370d50c87928a7f7e4024314b3c857a863e6ecc8512ce221c0f281065190ccd6
-  data.tar.gz: b7160af777302983bc93d39308bcf63a9f4058c177d5e1ddf5b37be021522fcb69dc5d109cbaf12db86550a45e006c52e18d67c98c8e92cbd18df6e56a4f5b94
+  metadata.gz: ba304ffc1ab7da1e5b2a3d9a9c1cc295402b3135c0803301765d7aec47fad3a7789d82ff16c0d0313835bbe4065608d55c74148a70a3e5799450dc2e8bd378c7
+  data.tar.gz: bfcfca822c4438ae7d09d90f6c8cb2fb3512a72f60784295ca46b824ed42b76f2cf4181463821360e69259a00e34340e059984e42358ca49e0c063dd3154dff7

data/README.md

@@ -4,11 +4,34 @@ Rails building blocks for building a [Commerce7](https://www.commerce7.com/) App
 
 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.
 
+## Requirements
+
+- Rails 8.1.4 or later
+- Faraday 2.14.4 or later
+
+Both floors date from v0.3.0. Earlier versions allowed Rails 7.1+ and any Faraday 2.x.
+
+**Why:** `json` 3.0 changed the signature of `JSON.parse`, and older Rails and Faraday releases call it in ways it no longer accepts. Nothing in your app has to request `json` 3 for this to happen. It arrives as a transitive dependency (rubocop 1.91 pulls it in, for one), and neither Rails nor Faraday caps `json` below 3, so Bundler will happily resolve a combination that breaks at runtime. The floors rule those combinations out.
+
+- **Faraday 2.14.3 and earlier:** the JSON response middleware breaks, so every Commerce7 REST client response raises `Faraday::ParsingError: wrong number of arguments (given 2, expected 1)`.
+- **Rails before 8.1.4:** `ActiveSupport::JSON.decode` breaks, so every `json`/`jsonb` column read raises. That includes the `raw_activation_payload` column the install generator creates. How it fails depends on the Rails line:
+
+  | Rails | With `json` 3 |
+  |---|---|
+  | 7.1.x, 8.0.x | `ArgumentError: unknown keyword: quirks_mode` |
+  | 7.2.x | JSON decoding works |
+  | 8.1.0 to 8.1.3.x | `ArgumentError: wrong number of arguments (given 2, expected 1)` |
+  | 8.1.4 and later | Works |
+
+  A gemspec can't say "7.2.x or 8.1.4 and later", so the floor is 8.1.4.
+
+If you're stuck on an older Rails, stay on v0.2.1 and pin `json` below 3 in your app's Gemfile (`gem "json", "~> 2.21"`).
+
 ## Install
 
 ```ruby
 # Gemfile
-gem "commerce7-rails", github: "ERCubed/commerce7-rails", tag: "v0.2.0"
+gem "commerce7-rails", github: "ERCubed/commerce7-rails", tag: "v0.3.0"
 ```
 
 ```
@@ -69,6 +92,19 @@ class Current < ActiveSupport::CurrentAttributes
 end
 ```
 
+### Limiting which resources the client can read
+
+Set `allowed_resources` to the Commerce7 resources your app reads. `Commerce7::Client` then refuses any other resource before sending a request, through the generic methods and the named helpers alike:
+
+```ruby
+Commerce7.configure do |c|
+  # ...
+  c.allowed_resources = %w[club-membership order customer]
+end
+```
+
+A resource is the first segment of an API path (`order` in `order/123`), so sub-paths of a listed resource are allowed. Keep the list matching the scopes registered for your app in Commerce7's Developer Center: Commerce7 enforces those scopes too, and this list is the app's own declaration of them, in code. Left unset (`nil`), every resource is allowed. The install generator starts new apps at `[]`, so each resource is added deliberately. Entries are checked when set, so a typo fails at boot.
+
 ## 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:
@@ -133,7 +169,30 @@ production:
 
 ```ruby
 client = Commerce7::Client.new(tenant)
-client.each_club_membership { |membership| ... }  # paginates automatically
+```
+
+### Any endpoint
+
+The generic methods reach every read endpoint in Commerce7's API, with pagination, rate-limit retries, and the tenant header handled for you:
+
+```ruby
+client.each("club-membership") { |membership| ... }          # paginates automatically
+client.each("customer", lastName: "Smith") { |customer| ... } # filters pass through as query params
+client.each("customer").first(10)                              # without a block, returns an Enumerator
+client.fetch("customer", customer_id)                          # one record: GET customer/{id}
+client.get("customer/#{customer_id}/address")                  # any other GET, returns the parsed body
+```
+
+`each` reads records from the response key Commerce7 names after the resource: the path's last segment, pluralized and camelCased (`"club-membership"` reads `clubMemberships`). If an endpoint uses a different key, pass `key: "theKey"`. A response without the expected key raises `ApiError` rather than quietly yielding nothing. Filters can be keywords or a hash; `key` is reserved for this method, so pass a filter literally named `key` in the hash.
+
+Paths must be relative (`"customer"`, `"order/123"`): segments of letters, digits, `-` and `_`. Anything else (a full URL, `..`, percent-encoding) raises `Commerce7::Client::InvalidRequestError` before a request is made, because a full URL would otherwise make Faraday send the request, App ID and Secret included, to that host. `fetch` applies the same rule to the id, which often comes from a URL param or webhook. `InvalidRequestError` is a `Client::Error`, so code that already rescues those treats a tampered id like any failed lookup. A resource outside `allowed_resources` (see [Configure](#limiting-which-resources-the-client-can-read)) raises it too.
+
+### Named helpers
+
+These wrap `each`/`fetch` for the resources the apps built on this gem use, with notes on what each record carries:
+
+```ruby
+client.each_club_membership { |membership| ... }  # embeds the customer and club
 client.each_customer { |customer| ... }
 client.each_order { |order| ... }
 client.each_order(orderPaidDate: "gte:2026-01-01") { |order| ... }  # params pass through as filters
@@ -142,7 +201,11 @@ 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.
+### Read only
+
+The client only sends GET requests. There's deliberately no POST/PUT/DELETE: an app that writes to Commerce7 needs broader API permissions, changes its answer on Commerce7's security review, and needs care around retries and audit logging. Writes will be added when an app actually needs them.
+
+Every call handles 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.
 
@@ -153,6 +216,7 @@ This gem exists so every app built on it starts from a "Yes" on Commerce7's App
 - **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.
+- **Least-privilege API access**: the client is read only (no POST/PUT/DELETE), refuses any resource outside `allowed_resources`, and rejects anything but a plain relative path or id before sending, so a tampered id or a full URL can never send your App ID and Secret anywhere but Commerce7.
 - **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.

data/app/controllers/commerce7/extension_controller.rb

@@ -18,15 +18,19 @@ module Commerce7
     # 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") }
+    #
+    # A before_action, declared ahead of authenticate_staff!, rather than an
+    # after_action: when auth fails, authenticate_staff! renders the error
+    # page and halts the chain, and after_actions never run — which left
+    # exactly the page staff most need to see blocked inside the iframe.
+    before_action { response.headers.delete("X-Frame-Options") }
+    before_action :authenticate_staff!
 
     rescue_from ActionController::ParameterMissing do |error|
       render plain: error.message, status: :bad_request

data/app/services/commerce7/client.rb

@@ -15,6 +15,10 @@ module Commerce7
     class AuthenticationError < Error; end
     class RateLimitedError < Error; end
     class ApiError < Error; end
+    # A path or id that isn't safe to send. A Client::Error, so callers that
+    # already rescue those (e.g. around a lookup by an id from a URL) handle a
+    # tampered value like any other failed lookup.
+    class InvalidRequestError < 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
@@ -22,6 +26,14 @@ module Commerce7
     BASE_URL = "https://api.commerce7.com/v1/"
     PAGE_SIZE = 50
     MAX_RETRIES = 3
+    # A relative API path: segments of letters, digits, - and _, joined by
+    # single slashes. Never a full URL (Faraday would send the request, App
+    # ID/Secret included, to that host instead), never "." or ".." segments,
+    # and no "%", so nothing percent-encoded (e.g. %2e%2e for "..") can be
+    # decoded into a different path by the server.
+    PATH_FORMAT = %r{\A[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*\z}
+    # A record id, which becomes one path segment. Commerce7 ids are UUIDs.
+    ID_FORMAT = /\A[A-Za-z0-9_-]+\z/
 
     def initialize(tenant, base_url: BASE_URL, sleeper: ->(seconds) { sleep(seconds) })
       @app_id, @app_secret_key = Commerce7.configuration.app_credentials.call
@@ -76,18 +88,68 @@ module Commerce7
     # 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}", {})
+      fetch("order", order_id)
+    end
+
+    # Generic read access to any Commerce7 list endpoint, with the same
+    # pagination and rate-limit handling as the named methods above:
+    #
+    #   client.each("club-membership") { |membership| ... }
+    #   client.each("customer", lastName: "Smith") { |customer| ... }
+    #   client.each("some-endpoint", key: "unusualKey") { |record| ... }
+    #
+    # Records are read from the response key Commerce7 names after the
+    # resource: the path's last segment, pluralized and camelCased
+    # ("club-membership" => "clubMemberships"). Pass `key:` when an endpoint
+    # differs. A response without that key raises ApiError rather than
+    # quietly yielding nothing. Filters can be keywords (as above) or a hash;
+    # `key` is the one name reserved for this method, so pass a filter that
+    # happens to be called "key" in the params hash.
+    def each(path, params = {}, key: nil, **filters, &block)
+      return enum_for(:each, path, params, key: key, **filters) unless block_given?
+
+      each_record(path, key || response_key_for(path), params.merge(filters), require_key: true, &block)
+    end
+
+    # A single record by id from any endpoint: fetch("customer", id) is
+    # GET customer/{id}. The id often comes from outside (a URL param, a
+    # webhook), so anything but a plain identifier raises InvalidRequestError
+    # rather than being sent.
+    def fetch(path, id)
+      id = id.to_s
+      raise InvalidRequestError, "Commerce7 record id must be a plain identifier, got #{id.inspect}" unless id.match?(ID_FORMAT)
+
+      get("#{path}/#{id}")
+    end
+
+    # Any GET, for endpoints that don't fit `each`/`fetch`. Returns the parsed
+    # response body. Read-only on purpose: this client has no POST/PUT/DELETE.
+    def get(path, params = {})
+      path = path.to_s # validate and send the same string
+      raise InvalidRequestError, "Commerce7 API path must be relative, like \"customer\" or \"order/123\", got #{path.inspect}" unless path.match?(PATH_FORMAT)
+      resource = path.split("/").first
+      unless Commerce7.configuration.resource_allowed?(resource)
+        raise InvalidRequestError, "Commerce7 resource #{resource.inspect} is not in Commerce7.configuration.allowed_resources (#{Commerce7.configuration.allowed_resources.join(', ')})"
+      end
+
+      response = with_rate_limit_retry { connection.get(path, params) }
+      handle_response(response)
     end
 
     private
 
     attr_reader :tenant, :base_url, :sleeper
 
-    def each_record(path, response_key, params = {})
+    def each_record(path, response_key, params = {}, require_key: false)
       page = 1
 
       loop do
-        records = get(path, params.merge(page: page, limit: PAGE_SIZE))[response_key] || []
+        body = get(path, params.merge(page: page, limit: PAGE_SIZE))
+        if require_key && !body.key?(response_key)
+          raise ApiError, "Commerce7 response for #{path.inspect} has no #{response_key.inspect} key (keys: #{body.keys.join(', ')}); pass key: to Client#each"
+        end
+
+        records = body[response_key] || []
         records.each { |record| yield record }
 
         break if records.size < PAGE_SIZE
@@ -96,9 +158,8 @@ module Commerce7
       end
     end
 
-    def get(path, params)
-      response = with_rate_limit_retry { connection.get(path, params) }
-      handle_response(response)
+    def response_key_for(path)
+      path.split("/").last.tr("-", "_").pluralize.camelize(:lower)
     end
 
     def with_rate_limit_retry

data/lib/commerce7/configuration.rb

@@ -28,6 +28,30 @@ module Commerce7
     # land in the same trail as the rest of the app's.
     attr_accessor :audit
 
+    # The Commerce7 API resources this app may read, e.g.
+    # %w[club-membership order customer]: the first segment of an API path
+    # ("order" in "order/123"). Commerce7::Client refuses any other resource
+    # before sending a request, so an app can only reach what it declares,
+    # and this list should match the scopes registered for the app in
+    # Commerce7's Developer Center. nil (the default) allows every resource;
+    # [] allows none.
+    attr_reader :allowed_resources
+
+    def allowed_resources=(resources)
+      @allowed_resources = resources.nil? ? nil : Array(resources).map do |resource|
+        resource = resource.to_s
+        unless resource.match?(/\A[A-Za-z0-9_-]+\z/)
+          raise ArgumentError, "Commerce7 allowed_resources entries are bare resource names like \"order\", got #{resource.inspect}"
+        end
+
+        resource
+      end.freeze
+    end
+
+    def resource_allowed?(resource)
+      allowed_resources.nil? || allowed_resources.include?(resource.to_s)
+    end
+
     def initialize
       @tenant_class_name = "Tenant"
       @webhook_credentials = -> { raise_unconfigured!(:webhook_credentials) }

data/lib/commerce7/version.rb

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

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

@@ -19,6 +19,12 @@ Commerce7.configure do |c|
   # 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) }
+
+  # The Commerce7 API resources this app reads, e.g. %w[club-membership order].
+  # Commerce7::Client refuses anything else. Keep it matching the scopes
+  # registered for this app in the Developer Center. Starts empty, so add
+  # each resource deliberately as the app starts using it.
+  c.allowed_resources = []
 end
 
 # Runs once, after a tenant activates (first install or a reinstall) —

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: commerce7-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Roberts
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: 8.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: 8.1.4
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.14.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.14.4
 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.