waffo-pancake 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b498f6ef1ac1fbdec66122b1a9d4758ebd6ea917840563c8f296c9e020c03bdd
-  data.tar.gz: c34ede893f8f1a84c2d6f7e71968dddfed09ce1a20e43140156805cf2bf93e39
+  metadata.gz: 87fe6008dd468bd2fe340702f5b8a6b5f4ce9141a7b49b9c069cf37062aaca3f
+  data.tar.gz: f9d37be2f832780519fdcd3319eb1ac3a96e073c588c153bea72477c4518cd61
 SHA512:
-  metadata.gz: bee472c21659562c0a68275d615eb5af3f21d95ec1937f2aed7fab7a5570b1f968e6b27f3ff4bbd7fa82598eef3e30407b35afbf8503759cca44490aa9e3bb85
-  data.tar.gz: f96b92d6942e7a94e298153a02c1f9a5b480afb1c399ba420da5044964bbe7f946ca6d02f09c54086d256f2881485ff250c166536223d7493122fc01b8577926
+  metadata.gz: 77f17baee5d56461088b0b3ecc8b948d2d341d35b373ae6845593e5504632a17f995fbcc63d889821341267305edc70c1bbb21088ce6870927ca4a154043d72c
+  data.tar.gz: 9e0cb6aae549bc3fd02978fd432252d7d5eefe4018505360284374548158fd62b5c5ea10d59f3c8769a3748a08eca053d3e75ed8c25e5a615bfc739a6d15c635

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.0
+
+- Webhook amount fields (Waffo, 2026-09-20 to 2026-09-22):
+  - `Webhook.verify` and `Waffo::Pancake.verify_webhook` return a `Webhook::Event`, a Hash
+    subclass, so code that reads it as a Hash keeps working. `Webhook::Event.wrap` makes one from
+    a stored payload (Hash or JSON).
+  - `event.data` readers for the new fields: `charged_amount`, `refunded_amount`,
+    `original_charged_amount`, `list_price`, `original_payment`, `plan_price`, `price`,
+    `period_number`, `first_period?`, `renewal?`.
+  - Reading a deprecated field (`amount`, `total`, `subtotal`, `taxAmount`, `taxRate`, `taxName`)
+    with `[]`, `fetch` or `dig` reports a deprecation warning naming its replacement for that
+    event type. `config.deprecator` chooses where it goes: a once-per-message `Kernel#warn` by
+    default, `Rails.application.deprecators[:waffo_pancake]` in Rails, nil for none.
+  - `Webhook::DEPRECATED_FIELDS`, `PAYMENT_EVENT_TYPES`, `REFUND_EVENT_TYPES` and
+    `Webhook.family`.
+- Customer portal sign-in without an email code: `Client#create_customer_portal_link`
+  (`issue-session-token` with `purpose: "portal"`), `issue_session_token(purpose:)`, and the
+  `Waffo::Pancake::CustomerPortalController` Rails concern, which answers with a 302 and
+  `Cache-Control: no-store` / `Referrer-Policy: no-referrer`. The Railtie adds `#token=` to
+  `filter_redirect`, so these URLs stay out of the request log.
+- Webhook delivery records: `Client#webhook_deliveries` and `#webhook_deliveries_count`, with
+  `status:`, `event_type:`, `filter:`, `limit:` and `offset:`. Waffo has no redelivery API;
+  run your handler on `Webhook::Event.wrap(delivery["payload"])` instead.
+- `Client.new(store_id:)`, defaulting to the configured store, for the calls above.
+- `TestHelpers::FakeClient#create_customer_portal_link` and `#webhook_deliveries`.
+- The generated `WaffoWebhookEvent#data` and `#waffo_event` wrap the stored payload; the
+  generated job reads the new amount fields.
+
 ## 0.2.1
 
 - `Client#subscription_order` also returns the order's current product as `productId`, read

data/README.md

@@ -68,6 +68,34 @@ 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.
 
+## Customer portal
+
+A customer who is signed in on your site can enter the store's customer portal without an email
+code. Use the `buyer_identity` you gave at authenticated checkout, taken from your own session.
+
+```ruby
+link = client.create_customer_portal_link(buyer_identity: current_user.id)  # store_id: defaults to WAFFO_STORE_ID
+# => {"portalUrl" => "https://pancake.waffo.ai/consumer/portal/store/STO_...#token=...", "expiresAt" => "..."}
+```
+
+The URL is a bearer credential: make a new one on each click, answer with a 302 and
+`Cache-Control: no-store` / `Referrer-Policy: no-referrer`, and never log, cache or email it.
+The portal opens on the API key's environment. In Rails, the concern does all of that:
+
+```ruby
+class WaffoPortalController < ApplicationController
+  include Waffo::Pancake::CustomerPortalController
+  before_action :authenticate_user!
+
+  def show
+    redirect_to_waffo_customer_portal(buyer_identity: current_user.id)  # 502 if Waffo fails
+  end
+end
+```
+
+Link to that route with a plain `<a>`, so nothing prefetches it. Set a Website in the store
+settings: the portal's return button links only there.
+
 ## Subscriptions
 
 ```ruby
@@ -112,9 +140,10 @@ class WaffoWebhooksController < ActionController::Base
       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
+    # Deduplicate on event.id: a retry redelivers the same id.
+    case event.event_type
+    when "order.completed" then                                 # record event.data.charged_amount
+    when "subscription.activated", "subscription.renewed" then # grant access until data["currentPeriodEnd"]
     when "subscription.canceled" then                           # revoke access
     end
     head :ok
@@ -131,12 +160,68 @@ both), or pass `public_key:`. Timestamps may be up to 45 minutes old and 1 minut
 
 `Waffo::Pancake::Webhook::EVENT_TYPES` lists the event types.
 
+### Amount fields
+
+`verify` returns a `Waffo::Pancake::Webhook::Event`, a Hash with readers. Its `data` reads
+the amount fields by what they describe:
+
+| Reader | Field | Events |
+|---|---|---|
+| `charged_amount` | `chargedAmount` | Payment (`order.completed`, `subscription.payment_succeeded`): what the buyer was actually charged, after prorated credits, trials and zero-amount card checks |
+| `list_price` | `listPrice` | Payment: the list price behind the charge (`total`, `subtotal`, `taxAmount`, `taxRate`, `taxName`) |
+| `refunded_amount` | `refundedAmount` | `refund.*`: what this refund returned |
+| `original_charged_amount` | `originalChargedAmount` | `refund.*`: what the refunded payment actually collected, the most a refund can reach |
+| `original_payment` | `originalPayment` | `refund.*`: the refunded payment's list price |
+| `plan_price` | `planPrice` | Other `subscription.*` events: the plan's price for the current period |
+| `period_number`, `first_period?`, `renewal?` | `periodNumber` | Subscription events, `subscription.payment_succeeded` and subscription refunds: 1 for the first period, N for the Nth renewal |
+
+`chargedAmount`, `refundedAmount` and `originalChargedAmount` are absent (nil) when the payment
+channel reported no amount. `periodNumber` counts failed charges too, is `0` before a scheduled
+plan change takes effect, and is not a deduplication key.
+
+`amount`, `total`, `subtotal`, `taxAmount`, `taxRate` and `taxName` are deprecated: one name meant
+a different amount per event family. Waffo sends them until its next major API version, not
+before 2027-09-20. Since 2026-09-21, `amount` on payment events is the charged amount, so a check
+such as `amount == total` fails there. Reading one of them with `[]`, `fetch` or `dig` still
+returns the value, and reports the field to read instead for that event type:
+
+```
+DEPRECATION WARNING: Waffo webhook data["amount"] is deprecated on refund.succeeded; read data["refundedAmount"] instead. ...
+```
+
+Outside Rails each message is printed once per process with `Kernel#warn`. In Rails it goes to
+`Rails.application.deprecators[:waffo_pancake]`, so `config.active_support.deprecation` applies
+(`:raise` in tests finds every place to change). Set `config.deprecator` to any object answering
+`warn(message, callstack)`, or to nil to turn the warnings off. A stored payload (or one that went
+through a job) is a plain Hash again: `Waffo::Pancake::Webhook::Event.wrap(payload)` brings the
+readers and warnings back.
+
+### Delivery records
+
+```ruby
+client.webhook_deliveries(status: :failed, limit: 20)  # store_id: defaults to WAFFO_STORE_ID
+# => [{"id" => ..., "eventType" => ..., "status" => "failed", "httpStatus" => 500, "attemptCount" => 4,
+#      "payload" => ..., "responseBody" => ..., "lastAttemptedAt" => ..., ...}]
+client.webhook_deliveries_count(status: :failed)
+client.webhook_deliveries(event_type: "refund.succeeded", filter: { createdAt: { gte: 1.week.ago } }, offset: 20)
+```
+
+Waffo retries a delivery 3 times and has no manual redelivery. To process a failed one again,
+run your own handler on its payload:
+
+```ruby
+client.webhook_deliveries(status: :failed).each do |delivery|
+  HandleWaffoEventJob.perform_later(Waffo::Pancake::Webhook::Event.wrap(delivery["payload"]))
+end
+```
+
 ## Rails
 
 Inside a Rails app the gem configures itself. Settings are read in this order, the last one
 winning: `WAFFO_*` environment variables, `credentials.waffo`, `config.waffo_pancake`, then
-`Waffo::Pancake.configure` in an initializer. The logger is `Rails.logger`, and `private_key`
-is added to `filter_parameters`.
+`Waffo::Pancake.configure` in an initializer. The logger is `Rails.logger`, `private_key`
+is added to `filter_parameters`, and redirects to a URL with `#token=` (authenticated checkout,
+customer portal) to `filter_redirect`.
 
 ```yaml
 # bin/rails credentials:edit
@@ -165,7 +250,7 @@ class WaffoWebhooksController < ActionController::Base
   include Waffo::Pancake::WebhookController
 
   def create
-    HandleWaffoEventJob.perform_later(waffo_event)   # verified, parsed delivery
+    HandleWaffoEventJob.perform_later(waffo_event)   # verified Webhook::Event; wrap it again in the job
     head :ok
   end
 end

data/lib/generators/waffo_pancake/install/templates/webhook_event.rb.tt

@@ -13,5 +13,9 @@ class WaffoWebhookEvent < ApplicationRecord
     [ find_by!(delivery_id: event["id"].to_s), false ]
   end
 
-  def data = payload.fetch("data", {})
+  # The stored payload as Waffo::Pancake::Webhook::Event: readers for the amount fields, and a
+  # deprecation warning when a field Waffo has deprecated is read.
+  def waffo_event = Waffo::Pancake::Webhook::Event.wrap(payload)
+
+  def data = waffo_event.data
 end

data/lib/generators/waffo_pancake/install/templates/webhook_job.rb.tt

@@ -6,7 +6,13 @@ class WaffoWebhookJob < ApplicationJob
   def perform(event)
     return if event.processed_at
 
+    # Amounts: event.data.charged_amount on payment events (what the buyer was actually charged,
+    # after credits and trials), event.data.refunded_amount on refunds, event.data.plan_price on
+    # subscription events. data["amount"] / ["total"] / ["tax*"] are deprecated.
     case event.event_type
+    when "order.completed", "subscription.payment_succeeded"
+      # Record the receipt: event.data.charged_amount. event.data.first_period? tells the first
+      # charge of a subscription from a renewal (event.data.period_number).
     when "subscription.activated", "subscription.renewed", "subscription.recovered", "subscription.uncanceled"
       # Grant access until event.data["currentPeriodEnd"]. To read the order as Waffo has it
       # now, regardless of delivery order: Waffo::Pancake.client.subscription_order(event.order_id)
@@ -17,7 +23,7 @@ class WaffoWebhookJob < ApplicationJob
     when "subscription.past_due"
       # The renewal failed; the payment channel retries once, usually the next day.
     when "refund.succeeded"
-      # Compare event.data["refundedAmount"] with event.data["originalChargedAmount"].
+      # event.data.refunded_amount, out of event.data.original_charged_amount actually collected.
     end
 
     event.update!(processed_at: Time.current)

data/lib/waffo/pancake/client.rb

@@ -4,6 +4,7 @@ require "base64"
 require "json"
 require "net/http"
 require "openssl"
+require "time"
 require "uri"
 
 module Waffo
@@ -35,7 +36,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
 
       # The canonical request the gateway checks `X-Signature` against: method, path,
       # timestamp (seconds) and the base64 SHA-256 of the body, one per line.
@@ -51,12 +56,13 @@ module Waffo
       # no answer). `logger` gets one info line per request and `instrumenter` one
       # `request.waffo_pancake` event; neither ever sees the body or the key.
       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,
+                     store_id: config.store_id, 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
         @private_key = Keys.private_key(private_key)
         @base_url = base_url.to_s.chomp("/")
         @timeout = timeout
@@ -67,11 +73,13 @@ module Waffo
 
       # --- 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)
         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 })
+               { 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.
@@ -93,6 +101,31 @@ module Waffo
         )
       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
+
+        { "portalUrl" => "#{data["portalUrl"]}#token=#{data["token"]}", "expiresAt" => data["expiresAt"] }
+      end
+
       # --- Orders ------------------------------------------------------------------------
 
       # pending → canceled at once; active, trialing and past_due → canceling, ending with the
@@ -149,6 +182,29 @@ module Waffo
         action("/v1/actions/store/remove-webhook", { id: id })
       end
 
+      # 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 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
+
       # --- Low level ---------------------------------------------------------------------
 
       # Returns `data`. Raises when the response carries `errors` and no data.
@@ -168,7 +224,42 @@ module Waffo
         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
+        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/)
+
+            "#{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 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
+
+          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 require_store_id(store_id)
+          raise ArgumentError, "store_id is required (WAFFO_STORE_ID)" if blank?(store_id)
+
+          store_id
+        end
+
         def request(path, params)
           json = JSON.generate(params)
           timestamp = Time.now.to_i.to_s

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/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/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

data/lib/waffo/pancake/railtie.rb

@@ -11,14 +11,28 @@ module Waffo
     #   3. config.waffo_pancake.* in config/application.rb or an environment file
     #   4. Waffo::Pancake.configure in config/initializers
     #
-    # The logger defaults to Rails.logger, and `private_key` is filtered from logs.
+    # The logger defaults to Rails.logger, `private_key` is filtered from logs, and so is a
+    # redirect to a URL carrying a session token (`#token=`, authenticated checkout and the
+    # customer portal). Deprecated webhook fields are reported through `Railtie.deprecator`,
+    # registered as `Rails.application.deprecators[:waffo_pancake]`.
     class Railtie < ::Rails::Railtie
       CREDENTIAL_KEYS = %i[merchant_id private_key store_id environment webhook_public_key].freeze
 
+      TOKEN_FRAGMENT = "#token="
+
       config.waffo_pancake = ActiveSupport::OrderedOptions.new
 
+      def self.deprecator
+        @deprecator ||= ActiveSupport::Deprecation.new("1.0", "waffo-pancake")
+      end
+
       initializer "waffo_pancake.filter_parameters" do |app|
         app.config.filter_parameters |= [:private_key]
+        app.config.filter_redirect |= [TOKEN_FRAGMENT] if app.config.respond_to?(:filter_redirect)
+      end
+
+      initializer "waffo_pancake.deprecator" do |app|
+        app.deprecators[:waffo_pancake] = Railtie.deprecator if app.respond_to?(:deprecators)
       end
 
       initializer "waffo_pancake.configuration" do |app|
@@ -31,6 +45,7 @@ module Waffo
 
           app.config.waffo_pancake.each { |key, value| config.public_send(:"#{key}=", value) }
           config.logger ||= ::Rails.logger
+          config.deprecator = Railtie.deprecator unless app.config.waffo_pancake.key?(:deprecator)
         end
       end
     end

data/lib/waffo/pancake/test_helpers.rb

@@ -46,7 +46,8 @@ module Waffo
         { "CONTENT_TYPE" => "application/json", Webhook::SIGNATURE_HEADER => waffo_webhook_signature(body, **options) }
       end
 
-      # A webhook envelope in Waffo's shape. `mode` and `store_id` default to the configuration.
+      # A webhook envelope in Waffo's shape, as a plain Hash to JSON.generate and sign.
+      # `mode` and `store_id` default to the configuration.
       def waffo_webhook_event(event_type, data: {}, id: SecureRandom.uuid, mode: nil, store_id: nil)
         config = Waffo::Pancake.configuration
         {
@@ -70,17 +71,31 @@ module Waffo
         Waffo::Pancake.client = previous
       end
 
-      # Stands in for Waffo::Pancake::Client. Answers subscription_order from `orders`, moves
-      # an order's status on cancel / reactivate the way Waffo does, and records every call
-      # in `calls` as [method, arguments]. Set `fail_with` to an error to make calls raise it.
+      # Stands in for Waffo::Pancake::Client. Answers subscription_order from `orders` and
+      # webhook_deliveries from `deliveries`, moves an order's status on cancel / reactivate the
+      # way Waffo does, and records every call in `calls` as [method, arguments]. Set
+      # `fail_with` to an error to make calls raise it.
       class FakeClient
         attr_reader :orders, :calls
-        attr_accessor :fail_with, :checkout_url
+        attr_accessor :fail_with, :checkout_url, :portal_url, :deliveries
 
         def initialize(orders = {})
           @orders = orders.transform_keys(&:to_s)
           @calls = []
           @checkout_url = "https://pancake.waffo.ai/store/test/checkout/cs_test"
+          @portal_url = "https://pancake.waffo.ai/consumer/portal/store/STO_test"
+          @deliveries = []
+        end
+
+        def create_customer_portal_link(**params)
+          record(:create_customer_portal_link, params)
+          { "portalUrl" => "#{portal_url}#token=test_token", "expiresAt" => (Time.now + 900).utc.iso8601 }
+        end
+
+        def webhook_deliveries(**params)
+          record(:webhook_deliveries, params)
+          status = params[:status]&.to_s
+          status ? deliveries.select { |delivery| delivery["status"] == status } : deliveries.dup
         end
 
         def subscription_order(order_id)

data/lib/waffo/pancake/version.rb

@@ -2,6 +2,6 @@
 
 module Waffo
   module Pancake
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/waffo/pancake/webhook/event.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Waffo
+  module Pancake
+    module Webhook
+      PAYMENT_EVENT_TYPES = %w[order.completed subscription.payment_succeeded].freeze
+      REFUND_EVENT_TYPES = %w[refund.succeeded refund.failed].freeze
+
+      # The six `data` fields whose name meant a different thing per event family, with the field
+      # that replaces each on payment, refund and subscription events. Waffo keeps sending them
+      # until the next major API version, not before DEPRECATED_FIELDS_REMOVAL.
+      DEPRECATED_FIELDS = {
+        "amount" => { payment: "chargedAmount", refund: "refundedAmount", subscription: "planPrice.total" },
+        "total" => { payment: "listPrice.total", refund: "originalPayment.total", subscription: "planPrice.total" },
+        "subtotal" => { payment: "listPrice.subtotal", refund: "originalPayment.subtotal",
+                        subscription: "planPrice.subtotal" },
+        "taxAmount" => { payment: "listPrice.taxAmount", refund: "originalPayment.taxAmount",
+                         subscription: "planPrice.taxAmount" },
+        "taxRate" => { payment: "listPrice.taxRate", refund: "originalPayment.taxRate",
+                       subscription: "planPrice.taxRate" },
+        "taxName" => { payment: "listPrice.taxName", refund: "originalPayment.taxName",
+                       subscription: "planPrice.taxName" }
+      }.freeze
+      DEPRECATED_FIELDS_REMOVAL = "2027-09-20"
+
+      module_function
+
+      # :payment (one charge), :refund, :subscription (a subscription's status), or nil.
+      def family(event_type)
+        event_type = event_type.to_s
+        return :payment if PAYMENT_EVENT_TYPES.include?(event_type)
+        return :refund if REFUND_EVENT_TYPES.include?(event_type)
+
+        :subscription if event_type.start_with?("subscription.")
+      end
+
+      # A delivery as a Hash, with readers for the envelope. `data` is an EventData, which warns
+      # through Waffo::Pancake::Deprecation when a deprecated field is read.
+      #
+      #   event = Waffo::Pancake::Webhook::Event.wrap(stored_payload)  # Hash or JSON String
+      #   event.data.charged_amount                                     # => "9.00"
+      class Event < Hash
+        # `payload` is a Hash (string or symbol keys) or its JSON. Use it on a delivery you stored
+        # or read back with Client#webhook_deliveries; it does not check a signature.
+        def self.wrap(payload)
+          return payload if payload.is_a?(Event)
+
+          payload = JSON.parse(payload) if payload.is_a?(String)
+          raise ArgumentError, "webhook event must be a Hash, got #{payload.class}" unless payload.respond_to?(:to_hash)
+
+          event = new.replace(payload.to_hash.transform_keys(&:to_s))
+          event["data"] = EventData.new(event["data"], event["eventType"]) if event["data"].respond_to?(:to_hash)
+          event
+        end
+
+        # The delivery id: the same on every retry, so deduplicate on it.
+        def id = self["id"]
+        def event_type = self["eventType"]
+        def event_id = self["eventId"]
+        def store_id = self["storeId"]
+        def mode = self["mode"]
+        def test? = mode == "test"
+        def timestamp = self["timestamp"]
+        def data = self["data"] || EventData.new({}, event_type)
+        def family = Webhook.family(event_type)
+        def payment? = family == :payment
+        def refund? = family == :refund
+        def subscription? = family == :subscription
+      end
+
+      # The `data` of a delivery. Reading `amount`, `total`, `subtotal`, `taxAmount`, `taxRate` or
+      # `taxName` with [], fetch or dig still answers the value, and reports the field to read
+      # instead. Iterating, serializing and `key?` report nothing.
+      class EventData < Hash
+        attr_reader :event_type
+
+        def initialize(fields = {}, event_type = nil)
+          super()
+          replace(fields.to_hash.transform_keys(&:to_s))
+          @event_type = event_type
+        end
+
+        def [](key)
+          deprecated_read(key)
+          super
+        end
+
+        def fetch(key, *default, &block)
+          deprecated_read(key)
+          super
+        end
+
+        def dig(key, *keys)
+          deprecated_read(key)
+          super
+        end
+
+        def order_id = self["orderId"]
+        def currency = self["currency"]
+
+        # What this charge actually took, after prorated credits, trials and zero-amount card
+        # checks. Payment events only; nil when the payment channel reported no amount.
+        def charged_amount = self["chargedAmount"]
+
+        # What this refund returned. Refund events only; nil when the channel reported no amount.
+        def refunded_amount = self["refundedAmount"]
+
+        # What the refunded payment actually collected: the most a refund can reach. Refund
+        # events only; nil when the channel reported no amount for that payment.
+        def original_charged_amount = self["originalChargedAmount"]
+
+        # Breakdowns (total, subtotal, taxAmount, taxRate, taxName), each on one event family.
+        def list_price = self["listPrice"]
+        def original_payment = self["originalPayment"]
+        def plan_price = self["planPrice"]
+
+        # The breakdown this event's figures refer to, whatever its family.
+        def price = list_price || original_payment || plan_price
+
+        # The payment channel's billing period: 1 for the first, N for the Nth renewal. A failed
+        # charge uses a period too; 0 is authorized but not charged yet. On refunds, the period of
+        # the refunded charge. Nil on one-time orders and on older subscriptions. Not unique per
+        # event: deduplicate on the event id.
+        def period_number = self["periodNumber"]
+        def first_period? = period_number == 1
+        def renewal? = period_number.is_a?(Integer) && period_number > 1
+
+        private
+          def deprecated_read(key)
+            replacements = DEPRECATED_FIELDS[key.to_s]
+            return unless replacements
+
+            Deprecation.warn(deprecation_message(key.to_s, replacements), caller_locations(2))
+          end
+
+          def deprecation_message(key, replacements)
+            family = Webhook.family(event_type)
+            instead = if family
+                        reader(replacements.fetch(family))
+                      else
+                        replacements.map { |name, field| "#{reader(field)} on #{name} events" }.join(", ")
+                      end
+            "Waffo webhook data[#{key.inspect}] is deprecated#{" on #{event_type}" if family}; read #{instead} " \
+              "instead. Waffo removes it in its next major API version, not before #{DEPRECATED_FIELDS_REMOVAL}."
+          end
+
+          def reader(field)
+            parts = field.split(".")
+            parts.one? ? "data[#{field.inspect}]" : "data.dig(#{parts.map(&:inspect).join(", ")})"
+          end
+      end
+    end
+  end
+end

data/lib/waffo/pancake/webhook.rb

@@ -10,7 +10,8 @@ module Waffo
     #
     #   event = Waffo::Pancake::Webhook.verify(request.raw_post, request.headers["X-Waffo-Signature"],
     #                                          environment: "prod")
-    #   event["eventType"] # => "subscription.activated"
+    #   event["eventType"]        # => "subscription.activated"
+    #   event.data.period_number  # => 1
     #
     # 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.
@@ -24,7 +25,7 @@ module Waffo
 
       ENVIRONMENTS = %w[test prod].freeze
 
-      # Waffo's platform keys, as embedded in @waffo/pancake-ts 0.25.0.
+      # Waffo's platform keys, as embedded in @waffo/pancake-ts 0.26.0.
       PUBLIC_KEYS = {
         "test" => <<~PEM,
           -----BEGIN PUBLIC KEY-----
@@ -60,7 +61,7 @@ module Waffo
 
       module_function
 
-      # Returns the parsed event. Raises InvalidSignature.
+      # Returns the parsed event, a Webhook::Event (a Hash). 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`).
@@ -74,7 +75,8 @@ module Waffo
         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)
+        event = JSON.parse(payload.to_s)
+        event.is_a?(Hash) ? Event.wrap(event) : event
       rescue JSON::ParserError
         raise InvalidSignature, "Webhook body is not JSON"
       end

data/lib/waffo/pancake.rb

@@ -4,7 +4,9 @@ require_relative "pancake/version"
 require_relative "pancake/errors"
 require_relative "pancake/keys"
 require_relative "pancake/client"
+require_relative "pancake/deprecation"
 require_relative "pancake/webhook"
+require_relative "pancake/webhook/event"
 require_relative "pancake/configuration"
 require_relative "pancake/railtie" if defined?(Rails::Railtie)
 
@@ -13,6 +15,7 @@ module Waffo
   module Pancake
     # Need ActiveSupport / Action Pack; loaded on first use.
     autoload :WebhookController, "waffo/pancake/webhook_controller"
+    autoload :CustomerPortalController, "waffo/pancake/customer_portal_controller"
     autoload :TestHelpers, "waffo/pancake/test_helpers"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waffo-pancake
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Good First Issue
@@ -43,12 +43,15 @@ files:
 - lib/waffo/pancake.rb
 - lib/waffo/pancake/client.rb
 - lib/waffo/pancake/configuration.rb
+- lib/waffo/pancake/customer_portal_controller.rb
+- lib/waffo/pancake/deprecation.rb
 - lib/waffo/pancake/errors.rb
 - lib/waffo/pancake/keys.rb
 - lib/waffo/pancake/railtie.rb
 - lib/waffo/pancake/test_helpers.rb
 - lib/waffo/pancake/version.rb
 - lib/waffo/pancake/webhook.rb
+- lib/waffo/pancake/webhook/event.rb
 - lib/waffo/pancake/webhook_controller.rb
 homepage: https://github.com/goodfirstissueorg/waffo-pancake-ruby
 licenses: