commerce7-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54a31ca6f73ce04f8fe8c32d673e781f53f34a6bab48220a907d57d0d9500a95
-  data.tar.gz: afb4810f89069ce03865b4fdb683c7b4d6778f1028dc49e8a7122db063755ea0
+  metadata.gz: '094411b4f2757ca97c279f68504a9a76b3c2aad6a8db04ae2176cc82c9868430'
+  data.tar.gz: 24b9fdb82f090f504c900ef2fe10bad35a709cb4c4b622bc0595b9a4c00f3bce
 SHA512:
-  metadata.gz: 347fb156c387dc45af3bffff70be82bb3c25f4e67ad5cce37de1fc6203be66dbe834b3d780931986296457601158dba77f0bdb3cab867555e5ba228f8ec9e858
-  data.tar.gz: e2424555f6b6948f79fdd8f72cdee26a8997c10d2c93dafc51eac65226c6eac06122fd03d93a90f53ecb62a00f57ef6c487480158e364532f1eafffc2cd26e69
+  metadata.gz: ba304ffc1ab7da1e5b2a3d9a9c1cc295402b3135c0803301765d7aec47fad3a7789d82ff16c0d0313835bbe4065608d55c74148a70a3e5799450dc2e8bd378c7
+  data.tar.gz: bfcfca822c4438ae7d09d90f6c8cb2fb3512a72f60784295ca46b824ed42b76f2cf4181463821360e69259a00e34340e059984e42358ca49e0c063dd3154dff7

data/README.md

@@ -92,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:
@@ -156,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
@@ -165,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.
 
@@ -176,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/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.3.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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Roberts