waffo-pancake 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5283cad4a209984c83a1416a5b8a56ba039935e1d7c4ed3879349f5eeb6e5f7
+  data.tar.gz: 76a97790c5458a0ce01f9edc5c88f54bada6b04d29abd2904f768b35b06d4213
+SHA512:
+  metadata.gz: 9f96eae8643cd2f8bc76c8ad36c4b48f991b0df654a1c696bf5cb53c5bbe0a48f9fa291809e3a3370aed504d3b7aeeda34b959ad91312cc62f1d21c0c0c95569
+  data.tar.gz: 21cc4f957a948cce53f880578094f8fece93ce4cc58f73500d1d82b0f8f3ef62d41f3ac012d4df92a42e017b99e53c85a269475445277b397938376714bebc4c

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- `Waffo::Pancake::Client`: signed merchant API requests (RSA-SHA256, `X-Merchant-Id` /
+  `X-Timestamp` / `X-Signature`), checkout sessions (anonymous and authenticated), subscription
+  cancel and reactivate, one-time order cancel, subscription and one-time products, webhook
+  endpoints, GraphQL and `subscription_order`.
+- `Waffo::Pancake::Webhook.verify`: `X-Waffo-Signature` verification with the built-in test and
+  prod platform keys, environment-variable overrides and replay tolerance.
+- Private and public keys accepted as PEM, PEM with literal `\n`, or bare base64.

data/LICENSE

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

data/README.md

@@ -0,0 +1,153 @@
+# waffo-pancake
+
+Ruby client for the [Waffo Pancake](https://docs.waffo.ai) merchant API. It signs requests with
+your API key, creates checkout sessions, manages subscriptions and products, runs GraphQL
+queries, and verifies webhook signatures. It is a Ruby port of the official TypeScript SDK,
+[`@waffo/pancake-ts`](https://www.npmjs.com/package/@waffo/pancake-ts), built on the standard
+library (`net/http`, `openssl`, `json`) plus the `base64` gem.
+
+## Install
+
+```ruby
+gem "waffo-pancake"
+```
+
+## Configure
+
+Create an API key in the Dashboard (**API & Development**). A key is bound to test or prod
+when it is created, so the key decides the environment.
+
+```ruby
+require "waffo/pancake"
+
+client = Waffo::Pancake::Client.new(
+  merchant_id: ENV["WAFFO_MERCHANT_ID"],  # MER_...
+  private_key: ENV["WAFFO_PRIVATE_KEY"],  # PEM, PEM with literal \n, or bare base64
+  logger: Rails.logger                    # optional: one line per request, never the body
+)
+```
+
+Both arguments default to those environment variables. Keep the private key on the server.
+
+## Checkout
+
+```ruby
+# Authenticated checkout (recommended): buyer_identity is your stable id for the customer.
+# Waffo uses it for trial eligibility and the customer portal.
+session = client.create_authenticated_checkout(
+  product_id: "PROD_...",
+  currency: "USD",
+  buyer_identity: "user-42",
+  buyer_email: "ada@example.com",
+  success_url: "https://example.com/settings?checkout=success",
+  order_merchant_external_id: "user-42",   # comes back on every webhook for the order
+  metadata: { "user_id" => "42" }
+)
+redirect_to session["checkoutUrl"], allow_other_host: true   # ends in #token=...
+
+# Anonymous checkout: the buyer fills everything in on the page.
+client.create_checkout_session(product_id: "PROD_...", currency: "USD")
+```
+
+Top-level keyword arguments may be snake_case and are sent as camelCase. Nested hashes
+(`metadata`, `prices`, `billing_detail`'s fields) are sent exactly as given.
+
+## Subscriptions
+
+```ruby
+client.cancel_subscription("ORD_...")      # => {"orderId" => "ORD_...", "status" => "canceling"}
+client.reactivate_subscription("ORD_...")  # while still canceling
+client.subscription_order("ORD_...")       # GraphQL; nil when unknown
+# => {"status" => "active", "currentPeriodEnd" => "2027-10-08T...", "merchantProvidedBuyerIdentity" => "user-42", ...}
+```
+
+`canceling` keeps access until `currentPeriodEnd`. The terminal `canceled` arrives as a webhook.
+
+## Products
+
+```ruby
+client.create_subscription_product(
+  store_id: "STO_...", name: "Pro", billing_period: "yearly",
+  prices: { "USD" => { amount: "9.99", taxCategory: "saas" } }
+)
+client.publish_subscription_product(id: "PROD_...")  # test → prod, first publish only
+```
+
+Amounts are display strings (`"9.99"`), not cents.
+
+## GraphQL and other endpoints
+
+```ruby
+client.graphql("query ($id: String!) { onetimeOrder(id: $id) { id status } }", id: "ORD_...")
+client.action("/v1/actions/refund-ticket/create-ticket", { payment_id: "PAY_...", reason: "..." })
+```
+
+## Webhooks
+
+Pass the raw body; a body that was parsed and re-serialized will not verify.
+
+```ruby
+class WaffoWebhooksController < ActionController::Base
+  skip_forgery_protection
+
+  def create
+    event = Waffo::Pancake::Webhook.verify(
+      request.raw_post,
+      request.headers["X-Waffo-Signature"],
+      environment: "prod"            # or "test"; omit to try prod, then test
+    )
+    # Deduplicate on event["id"]: a retry redelivers the same id.
+    case event["eventType"]
+    when "subscription.activated", "subscription.renewed" then # grant access until data.currentPeriodEnd
+    when "subscription.canceled" then                           # revoke access
+    end
+    head :ok
+  rescue Waffo::Pancake::InvalidSignature
+    head :unauthorized
+  end
+end
+```
+
+The platform's public keys are built in. When Waffo rotates them, set
+`WAFFO_WEBHOOK_PROD_PUBLIC_KEY` / `WAFFO_WEBHOOK_TEST_PUBLIC_KEY` (or `WAFFO_WEBHOOK_PUBLIC_KEY` for
+both), or pass `public_key:`. Timestamps may be up to 45 minutes old and 1 minute ahead by default
+(`tolerance:`, `future_tolerance:`, in seconds; `tolerance: 0` turns the check off).
+
+`Waffo::Pancake::Webhook::EVENT_TYPES` lists the event types.
+
+## Errors
+
+| Class | When |
+|---|---|
+| `Waffo::Pancake::Rejected` | Waffo refused the request (4xx other than 429). `status` and `errors` carry the details. |
+| `Waffo::Pancake::Unavailable` | Network failure, timeout, 429 or 5xx. Worth retrying later. |
+| `Waffo::Pancake::ConfigurationError` | Missing merchant id, or a key that does not parse. |
+| `Waffo::Pancake::InvalidSignature` | A webhook that does not verify. |
+
+All inherit from `Waffo::Pancake::Error`.
+
+## Testing your code
+
+`Client.new` takes a `transport:` callable that replaces the HTTP call. It receives the URI,
+the headers and the JSON body and returns `[status, body]`.
+
+```ruby
+transport = ->(uri, headers, json) { [200, '{"data":{"orderId":"ORD_1","status":"canceling"}}'] }
+client = Waffo::Pancake::Client.new(merchant_id: "MER_x", private_key: key, transport: transport)
+```
+
+Test cards: `4576 7500 0000 0110` succeeds and `4576 7500 0000 0220` is declined.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Releases are published to RubyGems by the `Release` workflow when a `v*` tag is pushed. It uses
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no API key is stored.
+
+## License
+
+MIT

data/lib/waffo/pancake/client.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Waffo
+  module Pancake
+    # The merchant API, authenticated with an API key: every request is a POST signed with the
+    # key's RSA private key. An API key is bound to test or prod when it is created, so no
+    # environment header is sent.
+    #
+    #   client = Waffo::Pancake::Client.new(merchant_id: "MER_...", private_key: ENV["WAFFO_PRIVATE_KEY"])
+    #   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.
+    class Client
+      DEFAULT_BASE_URL = "https://api.waffo.ai"
+      DEFAULT_TIMEOUT = 15
+
+      NETWORK_ERRORS = [
+        Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse
+      ].freeze
+
+      SUBSCRIPTION_ORDER_QUERY = <<~GRAPHQL
+        query ($id: String!) {
+          subscriptionOrder(id: $id) {
+            id storeId status testMode buyerEmail merchantProvidedBuyerIdentity orderMerchantExternalId
+            billingPeriod currentPeriodStart currentPeriodEnd canceledAt
+          }
+        }
+      GRAPHQL
+
+      attr_reader :merchant_id, :base_url
+
+      # The canonical request the gateway checks `X-Signature` against: method, path,
+      # timestamp (seconds) and the base64 SHA-256 of the body, one per line.
+      def self.sign(method:, path:, timestamp:, body:, private_key:)
+        body_hash = Base64.strict_encode64(OpenSSL::Digest::SHA256.digest(body))
+        canonical = "#{method}\n#{path}\n#{timestamp}\n#{body_hash}"
+        Base64.strict_encode64(private_key.sign(OpenSSL::Digest::SHA256.new, canonical))
+      end
+
+      # `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; neither the body nor the key is ever logged.
+      def initialize(merchant_id: ENV["WAFFO_MERCHANT_ID"], private_key: ENV["WAFFO_PRIVATE_KEY"],
+                     base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, logger: nil, 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
+        @private_key = Keys.private_key(private_key)
+        @base_url = base_url.to_s.chomp("/")
+        @timeout = timeout
+        @logger = logger
+        @transport = transport || method(:http_post)
+      end
+
+      # --- Checkout ----------------------------------------------------------------------
+
+      def issue_session_token(buyer_identity:, store_id: nil, product_id: 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 })
+      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=...`).
+      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)
+        session.merge(
+          "checkoutUrl" => "#{session.fetch("checkoutUrl")}#token=#{token.fetch("token")}",
+          "token" => token["token"],
+          "tokenExpiresAt" => token["expiresAt"]
+        )
+      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 })
+      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.
+      def subscription_order(order_id)
+        graphql(SUBSCRIPTION_ORDER_QUERY, id: order_id)&.dig("subscriptionOrder")
+      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
+
+      # --- 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
+
+      private
+        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 = call_transport(URI("#{@base_url}#{path}"), headers, json)
+          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 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/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+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.
+    class Error < StandardError
+      attr_reader :status, :errors
+
+      def initialize(message = nil, status: nil, errors: [])
+        super(message)
+        @status = status
+        @errors = errors
+      end
+    end
+
+    # The key, merchant id or other setting is missing or unusable.
+    class ConfigurationError < Error; end
+
+    # Worth another try later: a network failure, a timeout, a 429 or a 5xx.
+    class Unavailable < Error; end
+
+    # Not worth another try as is: Waffo refused the request (validation, state, auth).
+    class Rejected < Error; end
+
+    # A webhook whose signature, header or timestamp does not check out.
+    class InvalidSignature < Error; end
+  end
+end

data/lib/waffo/pancake/keys.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Waffo
+  module Pancake
+    # Turns the shapes keys arrive in (PEM, PEM with literal "\n" from an env file, CRLF,
+    # a one-line body, bare base64) into OpenSSL keys, as @waffo/pancake-ts does.
+    module Keys
+      module_function
+
+      def private_key(raw)
+        return raw if raw.is_a?(OpenSSL::PKey::RSA)
+
+        pem = clean(raw, "private")
+        kind = pem.include?("BEGIN RSA PRIVATE KEY") ? "RSA PRIVATE KEY" : "PRIVATE KEY"
+        OpenSSL::PKey::RSA.new(wrap(body_of(pem, "PRIVATE"), kind))
+      rescue OpenSSL::PKey::PKeyError, ArgumentError
+        raise ConfigurationError, "The private key is not a valid RSA private key (PKCS#8 or PKCS#1)"
+      end
+
+      def public_key(raw)
+        return raw if raw.is_a?(OpenSSL::PKey::RSA)
+
+        pem = clean(raw, "public")
+        kind = pem.include?("BEGIN RSA PUBLIC KEY") ? "RSA PUBLIC KEY" : "PUBLIC KEY"
+        OpenSSL::PKey::RSA.new(wrap(body_of(pem, "PUBLIC"), kind))
+      rescue OpenSSL::PKey::PKeyError, ArgumentError
+        raise ConfigurationError, "The public key is not a valid RSA public key (SPKI or PKCS#1)"
+      end
+
+      def clean(raw, label)
+        pem = raw.to_s.gsub("\\n", "\n").gsub("\r\n", "\n").strip
+        raise ConfigurationError, "The #{label} key is empty" if pem.empty?
+
+        pem
+      end
+
+      def body_of(pem, label)
+        body = pem.gsub(/-----(BEGIN|END) (RSA )?#{label} KEY-----/, "").gsub(/\s+/, "")
+        raise ArgumentError, "no key data" unless body.match?(%r{\A[A-Za-z0-9+/]+=*\z})
+
+        body
+      end
+
+      def wrap(body, kind)
+        "-----BEGIN #{kind}-----\n#{body.scan(/.{1,64}/).join("\n")}\n-----END #{kind}-----\n"
+      end
+    end
+  end
+end

data/lib/waffo/pancake/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Waffo
+  module Pancake
+    VERSION = "0.1.0"
+  end
+end

data/lib/waffo/pancake/webhook.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Waffo
+  module Pancake
+    # Verifies a delivery the way @waffo/pancake-ts's verifyWebhook does.
+    #
+    #   event = Waffo::Pancake::Webhook.verify(request.raw_post, request.headers["X-Waffo-Signature"],
+    #                                          environment: "prod")
+    #   event["eventType"] # => "subscription.activated"
+    #
+    # The header is `t=<unix ms>,v1=<base64>`: an RSA-SHA256 signature over "<t>.<raw body>".
+    # Pass the body exactly as received; a re-serialized JSON will not verify.
+    module Webhook
+      SIGNATURE_HEADER = "X-Waffo-Signature"
+
+      # Retries reuse the first attempt's header, so the past-facing window covers a whole
+      # retry schedule. Deduplicate on the event's `id`; the window only bounds replays.
+      DEFAULT_TOLERANCE = 45 * 60
+      DEFAULT_FUTURE_TOLERANCE = 60
+
+      ENVIRONMENTS = %w[test prod].freeze
+
+      # Waffo's platform keys, as embedded in @waffo/pancake-ts 0.25.0.
+      PUBLIC_KEYS = {
+        "test" => <<~PEM,
+          -----BEGIN PUBLIC KEY-----
+          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxnmRY6yMMA3lVqmAU6ZG
+          b1sjL/+r/z6E+ZjkXaDAKiqOhk9rpazni0bNsGXwmftTPk9jy2wn+j6JHODD/WH/
+          SCnSfvKkLIjy4Hk7BuCgB174C0ydan7J+KgXLkOwgCAxxB68t2tezldwo74ZpXgn
+          F49opzMvQ9prEwIAWOE+kV9iK6gx/AckSMtHIHpUesoPDkldpmFHlB2qpf1vsFTZ
+          5kD6DmGl+2GIVK01aChy2lk8pLv0yUMu18v44sLkO5M44TkGPJD9qG09wrvVG2wp
+          OTVCn1n5pP8P+HRLcgzbUB3OlZVfdFurn6EZwtyL4ZD9kdkQ4EZE/9inKcp3c1h4
+          xwIDAQAB
+          -----END PUBLIC KEY-----
+        PEM
+        "prod" => <<~PEM
+          -----BEGIN PUBLIC KEY-----
+          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAz+xApdTIb4ua+DgZKQ54
+          iBsD82ybyhGCLRETONW4Jgbb3A8DUM1LqBk6r/CmTOCHqLalTQHNigvP3R5zkDNX
+          iRJz6gA4MJ/+8K0+mnEE2RISQzN+Qu65TNd6svb+INm/kMaftY4uIXr6y6kchtTJ
+          dwnQhcKdAL2v7h7IFnkVelQsKxDdb2PqX8xX/qwd01iXvMcpCCaXovUwZsxH2QN5
+          ZKBTseJivbhUeyJCco4fdUyxOMHe2ybCVhyvim2uxAl1nkvL5L8RCWMCAV55LLo0
+          9OhmLahz/DYNu13YLVP6dvIT09ZFBYU6Owj1NxdinTynlJCFS9VYwBgmftosSE1U
+          dwIDAQAB
+          -----END PUBLIC KEY-----
+        PEM
+      }.freeze
+
+      EVENT_TYPES = %w[
+        order.completed
+        subscription.activated subscription.payment_succeeded subscription.renewed subscription.recovered
+        subscription.plan_changed subscription.plan_change_scheduled subscription.plan_change_failed
+        subscription.canceling subscription.uncanceled subscription.canceled subscription.past_due
+        refund.succeeded refund.failed
+      ].freeze
+
+      module_function
+
+      # Returns the parsed event. Raises InvalidSignature.
+      #
+      # environment: "test" or "prod" uses that environment's key; nil tries prod, then test.
+      # public_key:  a key to use instead (skips the lookup and `environment`).
+      # tolerance:   seconds a timestamp may lie in the past; 0 skips the timestamp check.
+      def verify(payload, signature_header, environment: nil, public_key: nil, tolerance: DEFAULT_TOLERANCE,
+                 future_tolerance: DEFAULT_FUTURE_TOLERANCE, now: Time.now)
+        timestamp, signature = parse_header(signature_header)
+        check_timestamp!(timestamp, now, tolerance, future_tolerance) if tolerance.positive?
+
+        input = "#{timestamp}.#{payload}"
+        keys = public_key ? [Keys.public_key(public_key)] : keys_for(environment)
+        raise InvalidSignature, "Invalid webhook signature" unless keys.any? { |key| valid?(key, signature, input) }
+
+        JSON.parse(payload.to_s)
+      rescue JSON::ParserError
+        raise InvalidSignature, "Webhook body is not JSON"
+      end
+
+      # The key for an environment: WAFFO_WEBHOOK_{TEST,PROD}_PUBLIC_KEY, then
+      # WAFFO_WEBHOOK_PUBLIC_KEY, then the built-in platform key.
+      def public_key_for(environment)
+        environment = environment.to_s
+        raise ArgumentError, "environment must be test or prod" unless ENVIRONMENTS.include?(environment)
+
+        custom = ENV["WAFFO_WEBHOOK_#{environment.upcase}_PUBLIC_KEY"] || ENV["WAFFO_WEBHOOK_PUBLIC_KEY"]
+        Keys.public_key(custom.to_s.strip.empty? ? PUBLIC_KEYS.fetch(environment) : custom)
+      end
+
+      def keys_for(environment)
+        environment ? [public_key_for(environment)] : [public_key_for("prod"), public_key_for("test")]
+      end
+
+      def parse_header(header)
+        raise InvalidSignature, "Missing #{SIGNATURE_HEADER} header" if header.nil? || header.to_s.strip.empty?
+
+        parts = header.to_s.split(",").each_with_object({}) do |pair, out|
+          key, value = pair.split("=", 2)
+          out[key.strip] = value.strip if value
+        end
+        timestamp, signature = parts["t"], parts["v1"]
+        if timestamp.to_s.empty? || signature.to_s.empty?
+          raise InvalidSignature, "Malformed #{SIGNATURE_HEADER} header: missing t or v1"
+        end
+
+        [timestamp, signature]
+      end
+
+      def check_timestamp!(timestamp, now, tolerance, future_tolerance)
+        raise InvalidSignature, "Invalid timestamp in #{SIGNATURE_HEADER} header" unless timestamp.match?(/\A\d+\z/)
+
+        age = now.to_f - (timestamp.to_i / 1000.0)
+        return if age <= tolerance && age >= -future_tolerance
+
+        raise InvalidSignature, "Webhook timestamp outside tolerance window (possible replay attack)"
+      end
+
+      def valid?(key, signature, input)
+        key.verify(OpenSSL::Digest::SHA256.new, Base64.strict_decode64(signature), input)
+      rescue ArgumentError, OpenSSL::PKey::PKeyError
+        false
+      end
+    end
+  end
+end

data/lib/waffo/pancake.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "pancake/version"
+require_relative "pancake/errors"
+require_relative "pancake/keys"
+require_relative "pancake/client"
+require_relative "pancake/webhook"
+
+module Waffo
+  # Ruby client for the Waffo Pancake merchant API (https://docs.waffo.ai).
+  module Pancake
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: waffo-pancake
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Good First Issue
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Signed requests to the Waffo Pancake merchant API (checkout, subscriptions,
+  products, GraphQL) and webhook signature verification. A Ruby port of @waffo/pancake-ts.
+email:
+- hi@goodfirstissue.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/waffo/pancake.rb
+- lib/waffo/pancake/client.rb
+- lib/waffo/pancake/errors.rb
+- lib/waffo/pancake/keys.rb
+- lib/waffo/pancake/version.rb
+- lib/waffo/pancake/webhook.rb
+homepage: https://github.com/goodfirstissueorg/waffo-pancake-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/goodfirstissueorg/waffo-pancake-ruby
+  source_code_uri: https://github.com/goodfirstissueorg/waffo-pancake-ruby/tree/main
+  changelog_uri: https://github.com/goodfirstissueorg/waffo-pancake-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/goodfirstissueorg/waffo-pancake-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby client for the Waffo Pancake merchant API
+test_files: []