waffo-pancake 0.3.0 → 0.4.0

data/lib/waffo/pancake/client.rb

@@ -2,10 +2,17 @@
 
 require "base64"
 require "json"
-require "net/http"
 require "openssl"
 require "time"
-require "uri"
+
+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
@@ -17,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!) {
@@ -40,7 +52,7 @@ module Waffo
                                 "attemptCount lastAttemptedAt createdAt"
       WEBHOOK_DELIVERY_STATUSES = %w[pending success failed].freeze
 
-      attr_reader :merchant_id, :base_url, :store_id
+      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.
@@ -52,45 +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,
-                     store_id: config.store_id, 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 ----------------------------------------------------------------------
 
       # `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)
+      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, purpose: purpose })
-      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)
@@ -101,6 +118,23 @@ module Waffo
         )
       end
 
+      # 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
+
       # --- Customer portal ----------------------------------------------------------------
 
       # Signs a customer who is signed in on your site into the store's customer portal, with no
@@ -128,21 +162,6 @@ module Waffo
 
       # --- 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 })
-      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
-
-      def cancel_onetime_order(order_id)
-        action("/v1/actions/onetime-order/cancel-order", { order_id: order_id })
-      end
-
       # 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)
@@ -150,37 +169,7 @@ module Waffo
         order && order.merge("productId" => order.dig("subscriptionProduct", "id"))
       end
 
-      # --- Products ----------------------------------------------------------------------
-
-      # 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 })
-      end
-
-      def update_subscription_product(id:, **params)
-        action("/v1/actions/subscription-product/update-product", { id: id, **params })
-      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
-
-      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
+      # --- Webhook deliveries ------------------------------------------------------------
 
       # Delivery records, newest first, for the API key's environment: id, eventType, eventId,
       # payload, webhookUrl, status (pending / success / failed), httpStatus, responseBody,
@@ -205,25 +194,6 @@ module Waffo
         graphql(query, storeId: require_store_id(store_id))&.fetch("webhookDeliveriesCount", nil)
       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"] || {}
-      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
@@ -243,6 +213,18 @@ module Waffo
       end
 
       private
+        attr_reader :connection
+
+        def auth_headers(path, json)
+          timestamp = Time.now.to_i.to_s
+          {
+            "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)
+          }
+        end
+
         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(", ")}"
@@ -259,79 +241,6 @@ module Waffo
 
           store_id
         end
-
-        def request(path, params)
-          json = JSON.generate(params)
-          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)
-          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
-        end
-
-        def camelize(params)
-          params.each_with_object({}) do |(key, value), out|
-            next if value.nil?
-
-            out[key.to_s.gsub(/_([a-z\d])/) { Regexp.last_match(1).upcase }] = value
-          end
-        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/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_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/errors.rb

@@ -3,14 +3,16 @@
 module Waffo
   module Pancake
     # Base class. `status` is the HTTP status (nil when the request never got an answer) and
-    # `errors` the envelope's `errors` array, as Waffo sent it.
+    # `errors` the envelope's `errors` array, as Waffo sent it. `retry_after` is the seconds from
+    # the Retry-After header, nil when Waffo sent none.
     class Error < StandardError
-      attr_reader :status, :errors
+      attr_reader :status, :errors, :retry_after
 
-      def initialize(message = nil, status: nil, errors: [])
+      def initialize(message = nil, status: nil, errors: [], retry_after: nil)
         super(message)
         @status = status
         @errors = errors
+        @retry_after = retry_after
       end
     end
 

data/lib/waffo/pancake/requests.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Waffo
+  module Pancake
+    # Sends an explicit JSON null in an update, which clears the field. A plain nil is dropped,
+    # so a variable that happens to be nil can never erase data at Waffo.
+    NULL = Object.new
+    class << NULL
+      def to_json(*) = "null"
+      def inspect = "Waffo::Pancake::NULL"
+    end
+    NULL.freeze
+
+    # The request logic shared by Client, CustomerSession and StoreCheckout. An includer defines
+    # `auth_headers(path, json)` and `connection`.
+    #
+    # Waffo refuses a request that carries two authentication methods, so an includer sends the
+    # headers of one method only.
+    module Requests
+      IDEMPOTENCY_KEY = /\A[A-Za-z0-9_-]{1,256}\z/
+
+      # Any action endpoint. Returns the envelope's `data`, plus a "warnings" key when Waffo sent
+      # any. Raises Rejected or Unavailable on `errors` or a non-2xx status.
+      #
+      # Top-level keys are sent in camelCase and nil values are dropped; use NULL to clear a field.
+      # `idempotency_key:` is sent as X-Idempotency-Key. Waffo keeps the answer for 24 hours.
+      def action(path, params = {}, **named)
+        params = params.merge(named)
+        key = params.delete(:idempotency_key)
+        response = post(path, camelize(params), idempotency_headers(key))
+        succeeded = !present?(response.envelope["errors"]) && (200..299).cover?(response.status)
+        connection.fail_with(path, response) unless succeeded
+
+        with_warnings(response.envelope)
+      end
+
+      # Returns `data`. Raises when the response carries `errors` and no data, or on a non-2xx
+      # status. Partial data comes back as is, because the fields Waffo did answer are still valid.
+      def graphql(query, variables = {})
+        path = "/v1/graphql"
+        response = post(path, { "query" => query, "variables" => variables })
+        envelope = response.envelope
+        failed = (present?(envelope["errors"]) && envelope["data"].nil?) || !(200..299).cover?(response.status)
+        connection.fail_with(path, response) if failed
+
+        envelope["data"]
+      end
+
+      def self.environment!(value)
+        value = value.to_s.strip.downcase
+        return value if Configuration::ENVIRONMENTS.include?(value)
+
+        raise ConfigurationError, "environment must be test or prod, got #{value.inspect}"
+      end
+
+      private
+        def post(path, params, extra_headers = {})
+          json = JSON.generate(params)
+          headers = { "Content-Type" => "application/json" }.merge(auth_headers(path, json)).merge(extra_headers)
+          connection.post(path, headers, json)
+        end
+
+        def idempotency_headers(key)
+          return {} if key.nil?
+          return { "X-Idempotency-Key" => key } if key.is_a?(String) && key.match?(IDEMPOTENCY_KEY)
+
+          raise ArgumentError, "idempotency_key must be 1 to 256 characters from A-Z a-z 0-9 _ -"
+        end
+
+        def with_warnings(envelope)
+          data = envelope["data"] || {}
+          warnings = envelope["warnings"]
+          data.is_a?(Hash) && present?(warnings) ? data.merge("warnings" => warnings) : data
+        end
+
+        def camelize(params)
+          params.each_with_object({}) do |(key, value), out|
+            next if value.nil?
+
+            out[key.to_s.gsub(/_([a-z\d])/) { Regexp.last_match(1).upcase }] = value.equal?(NULL) ? nil : value
+          end
+        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/store_checkout.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "requests"
+require_relative "connection"
+
+module Waffo
+  module Pancake
+    # Anonymous storefront access, authenticated with only the store's public slug. It holds no
+    # secret, so it suits code that cannot keep an API key.
+    #
+    #   storefront = Waffo::Pancake::StoreCheckout.new(store_slug: "my-store", environment: "test")
+    #   storefront.create_checkout_session(product_id: "PROD_...", currency: "USD")
+    class StoreCheckout
+      include Requests
+
+      attr_reader :store_slug, :environment
+
+      def initialize(store_slug:, config: Pancake.configuration, environment: config.environment,
+                     base_url: config.base_url, timeout: config.timeout, logger: config.logger,
+                     instrumenter: config.instrumenter, transport: nil)
+        raise ConfigurationError, "Missing store_slug" if store_slug.to_s.strip.empty?
+
+        @store_slug = store_slug
+        @environment = Requests.environment!(environment)
+        @connection = Connection.new(base_url: base_url, timeout: timeout, logger: logger, instrumenter: instrumenter,
+                                     transport: transport)
+      end
+
+      def create_checkout_session(product_id:, currency:, **params)
+        action("/v1/actions/checkout/create-session", product_id: product_id, currency: currency, **params)
+      end
+
+      private
+        attr_reader :connection
+
+        def auth_headers(_path, _json)
+          { "X-Store-Slug" => @store_slug, "X-Environment" => @environment }
+        end
+    end
+  end
+end