waffo-pancake 0.2.1 → 0.4.0

data/lib/waffo/pancake/client.rb

@@ -2,9 +2,17 @@
 
 require "base64"
 require "json"
-require "net/http"
 require "openssl"
-require "uri"
+require "time"
+
+require_relative "connection"
+require_relative "requests"
+require_relative "api/customer_actions"
+require_relative "api/store_actions"
+require_relative "api/product_actions"
+require_relative "api/promotion_actions"
+require_relative "api/queries"
+require_relative "customer_session"
 
 module Waffo
   module Pancake
@@ -16,14 +24,19 @@ module Waffo
     #   client.cancel_subscription("ORD_...") # => {"orderId" => "ORD_...", "status" => "canceling"}
     #
     # Parameters may be given in snake_case; top-level keys are sent in camelCase. Nested
-    # hashes (metadata, prices, billing details) are sent exactly as given.
+    # hashes (metadata, prices, billing details) are sent exactly as given. Every action takes
+    # `idempotency_key:`. Routes that do not take an API key are reached through #customer.
     class Client
+      include Requests
+      include API::CustomerActions
+      include API::StoreActions
+      include API::ProductActions
+      include API::PromotionActions
+      include API::Queries
+
       DEFAULT_BASE_URL = "https://api.waffo.ai"
       DEFAULT_TIMEOUT = 15
-
-      NETWORK_ERRORS = [
-        Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse
-      ].freeze
+      NETWORK_ERRORS = Connection::NETWORK_ERRORS
 
       SUBSCRIPTION_ORDER_QUERY = <<~GRAPHQL
         query ($id: String!) {
@@ -35,7 +48,11 @@ module Waffo
         }
       GRAPHQL
 
-      attr_reader :merchant_id, :base_url
+      WEBHOOK_DELIVERY_FIELDS = "id storeId eventType eventId payload webhookUrl status httpStatus responseBody " \
+                                "attemptCount lastAttemptedAt createdAt"
+      WEBHOOK_DELIVERY_STATUSES = %w[pending success failed].freeze
+
+      attr_reader :merchant_id, :base_url, :store_id, :environment
 
       # The canonical request the gateway checks `X-Signature` against: method, path,
       # timestamp (seconds) and the base64 SHA-256 of the body, one per line.
@@ -47,42 +64,50 @@ module Waffo
 
       # Every argument defaults to Waffo::Pancake.configuration (itself defaulting to the
       # WAFFO_* environment variables). `transport` replaces the HTTP call: it takes the URI,
-      # the headers and the JSON body and answers `[status, body]` (status nil when there was
-      # no answer). `logger` gets one info line per request and `instrumenter` one
-      # `request.waffo_pancake` event; neither ever sees the body or the key.
+      # the headers and the JSON body and answers `[status, body]` or `[status, body, headers]`
+      # (status nil when there was no answer). `logger` gets one info line per request and
+      # `instrumenter` one `request.waffo_pancake` event; neither ever sees the body or the key.
+      #
+      # The key's environment cannot be read from the key, so `environment` only tells #customer
+      # and create_authenticated_plan_change which one to use.
       def initialize(config: Pancake.configuration, merchant_id: config.merchant_id, private_key: config.private_key,
-                     base_url: config.base_url, timeout: config.timeout, logger: config.logger,
-                     instrumenter: config.instrumenter, transport: nil)
+                     store_id: config.store_id, environment: config.environment, base_url: config.base_url,
+                     timeout: config.timeout, logger: config.logger, instrumenter: config.instrumenter, transport: nil)
         raise ConfigurationError, "Missing merchant_id (WAFFO_MERCHANT_ID)" if blank?(merchant_id)
         raise ConfigurationError, "Missing private_key (WAFFO_PRIVATE_KEY)" if blank?(private_key)
 
         @merchant_id = merchant_id
+        @store_id = blank?(store_id) ? nil : store_id
+        @environment = blank?(environment) ? nil : Requests.environment!(environment)
         @private_key = Keys.private_key(private_key)
         @base_url = base_url.to_s.chomp("/")
-        @timeout = timeout
-        @logger = logger
-        @instrumenter = instrumenter
-        @transport = transport || method(:http_post)
+        @connection = Connection.new(base_url: @base_url, timeout: timeout, logger: logger, instrumenter: instrumenter,
+                                     transport: transport)
+      end
+
+      def inspect = "#<#{self.class} merchant_id=#{@merchant_id.inspect} environment=#{@environment.inspect}>"
+
+      # The same connection, authenticated as a customer with a token from issue_session_token.
+      def customer(token, environment: @environment)
+        CustomerSession.new(token: token, environment: environment, connection: @connection)
       end
 
       # --- Checkout ----------------------------------------------------------------------
 
-      def issue_session_token(buyer_identity:, store_id: nil, product_id: nil)
+      # `purpose: "portal"` signs the customer into the store's customer portal instead; see
+      # create_customer_portal_link.
+      def issue_session_token(buyer_identity:, store_id: nil, product_id: nil, purpose: nil, idempotency_key: nil)
         raise ArgumentError, "store_id or product_id is required" if store_id.nil? && product_id.nil?
 
-        action("/v1/actions/auth/issue-session-token",
-               { buyer_identity: buyer_identity, store_id: store_id, product_id: product_id })
-      end
-
-      # Anonymous checkout: the buyer fills everything in on the page.
-      # Returns {"sessionId", "checkoutUrl", "expiresAt"}.
-      def create_checkout_session(product_id:, currency:, **params)
-        action("/v1/actions/checkout/create-session", { product_id: product_id, currency: currency, **params })
+        action("/v1/actions/auth/issue-session-token", buyer_identity: buyer_identity, store_id: store_id,
+                                                       product_id: product_id, purpose: purpose,
+                                                       idempotency_key: idempotency_key)
       end
 
       # Authenticated checkout: `buyer_identity` (your stable id for the customer) goes into a
       # session token, which Waffo uses for trial eligibility and the customer portal. The
-      # token is appended to the checkout URL as a fragment (`#token=...`).
+      # token is appended to the checkout URL as a fragment (`#token=...`). `idempotency_key`
+      # applies to the session only: a token is short-lived and cheap to issue again.
       def create_authenticated_checkout(product_id:, currency:, buyer_identity:, **params)
         token = issue_session_token(buyer_identity: buyer_identity, product_id: product_id)
         session = create_checkout_session(product_id: product_id, currency: currency, **params)
@@ -93,23 +118,50 @@ module Waffo
         )
       end
 
-      # --- Orders ------------------------------------------------------------------------
-
-      # pending → canceled at once; active, trialing and past_due → canceling, ending with the
-      # paid period. The terminal `canceled` arrives later as a webhook.
-      def cancel_subscription(order_id)
-        action("/v1/actions/subscription-order/cancel-order", { order_id: order_id })
+      # A plan change the customer confirms on Waffo's page. The URL is a bearer credential, like
+      # the one from create_customer_portal_link. Needs a known environment, because a test
+      # session needs `?test=true` before the fragment, and prod must not have it.
+      def create_authenticated_plan_change(origin_order_id:, product_id:, currency:, buyer_identity:, **params)
+        environment = Requests.environment!(@environment)
+        token = issue_session_token(buyer_identity: buyer_identity, product_id: product_id)
+        session = create_plan_change_session(origin_order_id: origin_order_id, product_id: product_id,
+                                             currency: currency, **params)
+        url = session.fetch("checkoutUrl")
+        url = "#{url}#{url.include?("?") ? "&" : "?"}test=true" if environment == "test"
+        session.merge(
+          "checkoutUrl" => "#{url}#token=#{token.fetch("token")}",
+          "token" => token["token"],
+          "tokenExpiresAt" => token["expiresAt"]
+        )
       end
 
-      # Undoes a cancellation while the order is still `canceling`.
-      def reactivate_subscription(order_id)
-        action("/v1/actions/subscription-order/reactivate-order", { order_id: order_id })
-      end
+      # --- Customer portal ----------------------------------------------------------------
+
+      # Signs a customer who is signed in on your site into the store's customer portal, with no
+      # email code. Returns {"portalUrl" => "https://...#token=...", "expiresAt" => ISO 8601}.
+      #
+      # `buyer_identity` is the one given at authenticated checkout, taken from your own session,
+      # never from the request; `store_id` defaults to the configured store. The portal opens on
+      # the API key's environment. The URL is a bearer credential: make one per click, answer
+      # it with a 302 (Cache-Control: no-store, Referrer-Policy: no-referrer), and never log,
+      # cache or send it. Waffo::Pancake::CustomerPortalController does that in Rails.
+      def create_customer_portal_link(buyer_identity:, store_id: @store_id)
+        raise ArgumentError, "store_id is required (WAFFO_STORE_ID)" if blank?(store_id)
+        raise ArgumentError, "buyer_identity is required" if blank?(buyer_identity)
+
+        path = "/v1/actions/auth/issue-session-token"
+        data = issue_session_token(buyer_identity: buyer_identity.to_s, store_id: store_id, purpose: "portal")
+        %w[portalUrl token].each do |key|
+          next unless blank?(data[key])
+
+          raise Rejected.new("Waffo #{path}: response has no #{key} for purpose portal", status: 200)
+        end
 
-      def cancel_onetime_order(order_id)
-        action("/v1/actions/onetime-order/cancel-order", { order_id: order_id })
+        { "portalUrl" => "#{data["portalUrl"]}#token=#{data["token"]}", "expiresAt" => data["expiresAt"] }
       end
 
+      # --- Orders ------------------------------------------------------------------------
+
       # Nil when Waffo knows no such order. `productId` is the order's current product, so a plan
       # change to another product can be told apart.
       def subscription_order(order_id)
@@ -117,130 +169,78 @@ module Waffo
         order && order.merge("productId" => order.dig("subscriptionProduct", "id"))
       end
 
-      # --- Products ----------------------------------------------------------------------
+      # --- Webhook deliveries ------------------------------------------------------------
 
-      # prices: { "USD" => { amount: "9.99", taxCategory: "saas" } }
-      def create_subscription_product(store_id:, name:, billing_period:, prices:, **params)
-        action("/v1/actions/subscription-product/create-product",
-               { store_id: store_id, name: name, billing_period: billing_period, prices: prices, **params })
+      # Delivery records, newest first, for the API key's environment: id, eventType, eventId,
+      # payload, webhookUrl, status (pending / success / failed), httpStatus, responseBody,
+      # attemptCount, lastAttemptedAt and createdAt.
+      #
+      # Waffo has no redelivery: a delivery that failed every retry stays failed. To process it
+      # again, hand Waffo::Pancake::Webhook::Event.wrap(delivery["payload"]) to your handler.
+      #
+      # `filter` takes Waffo's GraphQL filter fields, e.g. { eventType: { eq: "refund.succeeded" } };
+      # `status` and `event_type` are shortcuts for an `eq` on those fields.
+      def webhook_deliveries(store_id: @store_id, status: nil, event_type: nil, filter: nil, limit: 20, offset: 0)
+        filter = delivery_filter(status, event_type, filter)
+        query = "query ($storeId: String!, $limit: Int, $offset: Int) { webhookDeliveries(storeId: $storeId, " \
+                "limit: $limit, offset: $offset#{filter}) { #{WEBHOOK_DELIVERY_FIELDS} } }"
+        graphql(query, storeId: require_store_id(store_id), limit: Integer(limit), offset: Integer(offset))
+          &.fetch("webhookDeliveries", nil) || []
       end
 
-      def update_subscription_product(id:, **params)
-        action("/v1/actions/subscription-product/update-product", { id: id, **params })
+      def webhook_deliveries_count(store_id: @store_id, status: nil, event_type: nil, filter: nil)
+        filter = delivery_filter(status, event_type, filter)
+        query = "query ($storeId: String!) { webhookDeliveriesCount(storeId: $storeId#{filter}) }"
+        graphql(query, storeId: require_store_id(store_id))&.fetch("webhookDeliveriesCount", nil)
       end
 
-      # Copies the test version to production (first publish only).
-      def publish_subscription_product(id:)
-        action("/v1/actions/subscription-product/publish-product", { id: id })
-      end
+      # A Ruby value as a GraphQL input literal: hashes as input objects, symbols and times as strings.
+      def self.graphql_literal(value)
+        case value
+        when Hash
+          fields = value.map do |key, field|
+            raise ArgumentError, "invalid GraphQL field name #{key.inspect}" unless key.to_s.match?(/\A[_A-Za-z]\w*\z/)
 
-      def create_onetime_product(store_id:, name:, prices:, **params)
-        action("/v1/actions/onetime-product/create-product", { store_id: store_id, name: name, prices: prices, **params })
-      end
-
-      # --- Webhook endpoints -------------------------------------------------------------
-
-      def add_webhook(store_id:, url:, events:, test_mode:, channel: "http", **params)
-        action("/v1/actions/store/add-webhook",
-               { store_id: store_id, channel: channel, url: url, events: events, test_mode: test_mode, **params })
-      end
-
-      def remove_webhook(id:)
-        action("/v1/actions/store/remove-webhook", { id: id })
-      end
-
-      # --- Low level ---------------------------------------------------------------------
-
-      # Returns `data`. Raises when the response carries `errors` and no data.
-      def graphql(query, variables = {})
-        status, envelope = request("/v1/graphql", { "query" => query, "variables" => variables })
-        raise_for(status, envelope, "/v1/graphql") if present?(envelope["errors"]) && envelope["data"].nil?
-
-        envelope["data"]
-      end
-
-      # Any action endpoint. Returns the envelope's `data`; raises Rejected or Unavailable on
-      # `errors` or a non-2xx status.
-      def action(path, params)
-        status, envelope = request(path, camelize(params))
-        raise_for(status, envelope, path) if present?(envelope["errors"]) || !(200..299).cover?(status)
-
-        envelope["data"] || {}
+            "#{key}: #{graphql_literal(field)}"
+          end
+          "{ #{fields.join(", ")} }"
+        when Array then "[#{value.map { |item| graphql_literal(item) }.join(", ")}]"
+        when Symbol then graphql_literal(value.to_s)
+        when Time then JSON.generate(value.utc.iso8601(3))
+        when String, Integer, Float, true, false, nil then JSON.generate(value)
+        else raise ArgumentError, "cannot send #{value.class} in a GraphQL filter"
+        end
       end
 
       private
-        def request(path, params)
-          json = JSON.generate(params)
+        attr_reader :connection
+
+        def auth_headers(path, json)
           timestamp = Time.now.to_i.to_s
-          headers = {
-            "Content-Type" => "application/json",
+          {
             "X-Merchant-Id" => @merchant_id,
             "X-Timestamp" => timestamp,
             "X-Signature" => self.class.sign(method: "POST", path: path, timestamp: timestamp, body: json,
                                              private_key: @private_key)
           }
-
-          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          status, body = instrument("request.waffo_pancake", method: "POST", path: path) do |payload|
-            call_transport(URI("#{@base_url}#{path}"), headers, json).tap { |answer| payload[:status] = answer.first }
-          end
-          elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(2)
-          @logger&.info("[Waffo] POST #{path} status=#{status.inspect} in #{elapsed}s")
-
-          raise Unavailable.new("Waffo #{path} unreachable: #{body}", status: nil) if status.nil?
-
-          envelope = parse(body)
-          raise_for(status, {}, path, "non-JSON response") unless envelope.is_a?(Hash)
-
-          [status, envelope]
-        end
-
-        def instrument(name, payload, &block)
-          return yield(payload) unless @instrumenter
-
-          @instrumenter.instrument(name, payload, &block)
-        end
-
-        def call_transport(uri, headers, json)
-          @transport.call(uri, headers, json)
-        rescue *NETWORK_ERRORS => e
-          [nil, "#{e.class}: #{e.message}"]
         end
 
-        def http_post(uri, headers, json)
-          request = Net::HTTP::Post.new(uri, headers)
-          request.body = json
-          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
-                                     read_timeout: @timeout, write_timeout: @timeout) do |http|
-            http.request(request)
+        def delivery_filter(status, event_type, filter)
+          if status && !WEBHOOK_DELIVERY_STATUSES.include?(status.to_s)
+            raise ArgumentError, "status must be one of #{WEBHOOK_DELIVERY_STATUSES.join(", ")}"
           end
-          [response.code.to_i, response.body]
-        end
-
-        def raise_for(status, envelope, path, fallback = "request failed")
-          errors = Array(envelope["errors"])
-          message = errors.map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact.first || fallback
-          error = status.nil? || status == 429 || status >= 500 ? Unavailable : Rejected
-          raise error.new("Waffo #{path} status=#{status}: #{message}", status: status, errors: errors)
-        end
 
-        def parse(body)
-          JSON.parse(body.to_s)
-        rescue JSON::ParserError
-          nil
+          filter = (filter || {}).to_h.transform_keys(&:to_s)
+          filter["status"] = { "eq" => status.to_s } if status
+          filter["eventType"] = { "eq" => event_type.to_s } if event_type
+          filter.empty? ? "" : ", filter: #{self.class.graphql_literal(filter)}"
         end
 
-        def camelize(params)
-          params.each_with_object({}) do |(key, value), out|
-            next if value.nil?
+        def require_store_id(store_id)
+          raise ArgumentError, "store_id is required (WAFFO_STORE_ID)" if blank?(store_id)
 
-            out[key.to_s.gsub(/_([a-z\d])/) { Regexp.last_match(1).upcase }] = value
-          end
+          store_id
         end
-
-        def blank?(value) = value.nil? || value.to_s.strip.empty?
-
-        def present?(value) = !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
     end
   end
 end

data/lib/waffo/pancake/configuration.rb

@@ -18,6 +18,10 @@ module Waffo
       # Anything answering `instrument(name, payload) { |payload| ... }`. Defaults to
       # ActiveSupport::Notifications when it is loaded; nil turns instrumentation off.
       attr_writer :instrumenter
+      # Anything answering `warn(message, callstack)` hears about deprecated fields being read:
+      # Waffo::Pancake::Deprecation.default (a once-per-message Kernel#warn) unless set, the
+      # gem's ActiveSupport::Deprecation inside Rails; nil stays silent.
+      attr_writer :deprecator
 
       # "test" or "prod": which platform key verifies webhooks, and which deliveries the Rails
       # webhook concern accepts. nil tries prod, then test, and accepts both.
@@ -39,6 +43,7 @@ module Waffo
         @webhook_tolerance = Webhook::DEFAULT_TOLERANCE
         @webhook_future_tolerance = Webhook::DEFAULT_FUTURE_TOLERANCE
         @instrumenter = :default
+        @deprecator = :default
       end
 
       def environment=(value)
@@ -57,6 +62,10 @@ module Waffo
         defined?(::ActiveSupport::Notifications) ? ::ActiveSupport::Notifications : nil
       end
 
+      def deprecator
+        @deprecator == :default ? Deprecation.default : @deprecator
+      end
+
       # What a client needs; a store id is only checked by the webhook concern.
       def configured?
         !blank?(merchant_id) && !blank?(private_key)

data/lib/waffo/pancake/connection.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module Waffo
+  module Pancake
+    # One POST to Waffo: HTTP, instrumentation, the log line and envelope parsing. It knows
+    # nothing about authentication, so all three entry points share it.
+    #
+    # Invariant: the body and the headers are never logged or instrumented, because they hold
+    # credentials and buyer data.
+    class Connection
+      NETWORK_ERRORS = [
+        Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse
+      ].freeze
+
+      Response = Struct.new(:status, :envelope, :headers)
+
+      # `transport` takes the URI, the headers and the JSON body and answers `[status, body]` or
+      # `[status, body, headers]`.
+      def initialize(base_url:, timeout:, logger: nil, instrumenter: nil, transport: nil)
+        @base_url = base_url.to_s.chomp("/")
+        @timeout = timeout
+        @logger = logger
+        @instrumenter = instrumenter
+        @transport = transport || method(:http_post)
+      end
+
+      attr_reader :base_url
+
+      def post(path, headers, json)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        status, body, response_headers = instrument("request.waffo_pancake", method: "POST", path: path) do |payload|
+          call_transport(URI("#{@base_url}#{path}"), headers, json).tap { |answer| payload[:status] = answer.first }
+        end
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(2)
+        @logger&.info("[Waffo] POST #{path} status=#{status.inspect} in #{elapsed}s")
+
+        raise Unavailable.new("Waffo #{path} unreachable: #{body}", status: nil) if status.nil?
+
+        envelope = parse(body)
+        response = Response.new(status, envelope.is_a?(Hash) ? envelope : {}, response_headers || {})
+        fail_with(path, response, "non-JSON response") unless envelope.is_a?(Hash)
+
+        warn_about(path, response)
+        response
+      end
+
+      def fail_with(path, response, fallback = "request failed")
+        errors = Array(response.envelope["errors"])
+        message = errors.map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact.first || fallback
+        status = response.status
+        error = status == 429 || status >= 500 ? Unavailable : Rejected
+        raise error.new("Waffo #{path} status=#{status}: #{message}", status: status, errors: errors,
+                                                                       retry_after: retry_after(response.headers))
+      end
+
+      private
+        def warn_about(path, response)
+          warnings = response.envelope["warnings"]
+          return if warnings.nil? || warnings.empty?
+
+          @logger&.warn("[Waffo] POST #{path} warnings=#{warnings.size}")
+        end
+
+        # Seconds to wait, from delay-seconds or an HTTP-date. Nil when the header is missing or
+        # unusable, so a caller falls back to its own backoff instead of retrying at once.
+        def retry_after(headers)
+          _, value = headers.find { |name, _| name.to_s.casecmp?("retry-after") }
+          value = value.first if value.is_a?(Array)
+          value = value.to_s.strip
+          return if value.empty?
+          return value.to_i if value.match?(/\A\d+\z/)
+
+          [(Time.httpdate(value) - Time.now).ceil, 0].max
+        rescue ArgumentError
+          nil
+        end
+
+        def instrument(name, payload, &block)
+          return yield(payload) unless @instrumenter
+
+          @instrumenter.instrument(name, payload, &block)
+        end
+
+        def call_transport(uri, headers, json)
+          @transport.call(uri, headers, json)
+        rescue *NETWORK_ERRORS => e
+          [nil, "#{e.class}: #{e.message}"]
+        end
+
+        def http_post(uri, headers, json)
+          request = Net::HTTP::Post.new(uri, headers)
+          request.body = json
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
+                                     read_timeout: @timeout, write_timeout: @timeout) do |http|
+            http.request(request)
+          end
+          [response.code.to_i, response.body, response.to_hash]
+        end
+
+        def parse(body)
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError
+          nil
+        end
+    end
+  end
+end

data/lib/waffo/pancake/customer_portal_controller.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Waffo
+  module Pancake
+    # Sends a customer who is signed in on your site into the store's Waffo customer portal,
+    # with no email code:
+    #
+    #   class WaffoPortalController < ApplicationController
+    #     include Waffo::Pancake::CustomerPortalController
+    #     before_action :authenticate_user!            # your own sign-in
+    #
+    #     def show
+    #       redirect_to_waffo_customer_portal(buyer_identity: current_user.id)
+    #     end
+    #   end
+    #
+    # Link to the route with a plain link (a prefetch would make links nobody clicked). Each
+    # request gets a new portal link, answered with a 302, `Cache-Control: no-store` and
+    # `Referrer-Policy: no-referrer`; the Railtie keeps the URL out of the request log. When
+    # Waffo cannot make a link, the answer is a 502 and the error is logged without the URL.
+    module CustomerPortalController
+      extend ActiveSupport::Concern
+
+      NO_STORE_HEADERS = { "Cache-Control" => "no-store", "Referrer-Policy" => "no-referrer" }.freeze
+
+      private
+        # `buyer_identity` is the one given at authenticated checkout and must come from your
+        # session, never from params. `store_id` defaults to the configured store.
+        def redirect_to_waffo_customer_portal(buyer_identity:, store_id: nil, client: nil)
+          response.headers.merge!(NO_STORE_HEADERS)
+          store_id ||= Waffo::Pancake.configuration.store_id
+          link = (client || Waffo::Pancake.client).create_customer_portal_link(buyer_identity: buyer_identity,
+                                                                               store_id: store_id)
+          redirect_to link.fetch("portalUrl"), allow_other_host: true, status: :found
+        rescue Waffo::Pancake::Error => e
+          (Waffo::Pancake.configuration.logger || logger)&.error("[Waffo] customer portal link failed: #{e.message}")
+          head :bad_gateway
+        end
+    end
+  end
+end

data/lib/waffo/pancake/customer_session.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "requests"
+require_relative "api/customer_actions"
+
+module Waffo
+  module Pancake
+    # The API as one customer, authenticated with a session token from
+    # Client#issue_session_token. Use Client#customer to build one.
+    #
+    # A token is a bearer credential and is not bound to an environment, so X-Environment is
+    # required. `inspect` hides the token, so it cannot reach a log through an error report.
+    class CustomerSession
+      include Requests
+      include API::CustomerActions
+
+      attr_reader :environment
+
+      def initialize(token:, environment:, connection:)
+        raise ConfigurationError, "Missing session token" if token.to_s.strip.empty?
+
+        @token = token
+        @environment = Requests.environment!(environment)
+        @connection = connection
+      end
+
+      # `language` is required: without it Waffo answers 400 "Invalid input" and does not name
+      # the field. buyer_email: is required unless the checkout session already has one. Optional:
+      # user_terminal ("web" or "app").
+      def create_onetime_order(checkout_session_id:, billing_detail:, language:, **params)
+        create_order("/v1/actions/onetime-order/create-order", checkout_session_id, billing_detail, language, params)
+      end
+
+      def create_subscription_order(checkout_session_id:, billing_detail:, language:, **params)
+        create_order("/v1/actions/subscription-order/create-order", checkout_session_id, billing_detail, language, params)
+      end
+
+      def inspect = "#<#{self.class} environment=#{@environment.inspect}>"
+
+      private
+        attr_reader :connection
+
+        def create_order(path, checkout_session_id, billing_detail, language, params)
+          raise ArgumentError, "language is required" if blank?(language)
+
+          action(path, checkout_session_id: checkout_session_id, billing_detail: billing_detail, language: language,
+                       **params)
+        end
+
+        def auth_headers(_path, _json)
+          { "Authorization" => "Bearer #{@token}", "X-Environment" => @environment }
+        end
+    end
+  end
+end

data/lib/waffo/pancake/deprecation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Waffo
+  module Pancake
+    # Reports the use of fields Waffo has deprecated. The reporter is `configuration.deprecator`:
+    # anything answering `warn(message, callstack)`, such as ActiveSupport::Deprecation (the
+    # Railtie sets one up) or the Warner below, the default outside Rails. Set it to nil to stay
+    # silent.
+    module Deprecation
+      # Writes each distinct message once per process to $stderr through Kernel#warn, with the
+      # line that read the field.
+      class Warner
+        def initialize
+          @seen = Set.new
+          @mutex = Mutex.new
+        end
+
+        def warn(message, callstack = nil)
+          return unless @mutex.synchronize { @seen.add?(message) }
+
+          location = Array(callstack).first
+          Kernel.warn("DEPRECATION WARNING: #{message}#{" (called from #{location})" if location} [waffo-pancake]")
+        end
+      end
+
+      @default = Warner.new
+
+      class << self
+        # The Warner shared by the process, so a message is not repeated per configuration.
+        attr_reader :default
+
+        def warn(message, callstack = caller_locations(1))
+          Pancake.configuration.deprecator&.warn(message, callstack)
+        end
+      end
+    end
+  end
+end