waffo-pancake 0.2.1 → 0.4.0

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

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)
@@ -100,13 +115,13 @@ module Waffo
             "expiresAt" => (Time.now + 2700).utc.iso8601 }
         end
 
-        def cancel_subscription(order_id)
-          record(:cancel_subscription, order_id)
+        def cancel_subscription(order_id, **params)
+          record(:cancel_subscription, order_id, *optional(params))
           change_status(order_id, "canceling")
         end
 
-        def reactivate_subscription(order_id)
-          record(:reactivate_subscription, order_id)
+        def reactivate_subscription(order_id, **params)
+          record(:reactivate_subscription, order_id, *optional(params))
           change_status(order_id, "active")
         end
 
@@ -115,19 +130,41 @@ module Waffo
           {}
         end
 
-        def action(path, params)
-          record(:action, path, params)
+        def action(path, params = {}, **named)
+          record(:action, path, params.merge(named))
           {}
         end
 
+        # Recorded, then answers as this same fake, so a test reads every call from one list.
+        def customer(token, **options)
+          record(:customer, token, *optional(options))
+          self
+        end
+
         def called?(name) = calls.any? { |call| call.first == name }
 
+        # Every other API method records its call and answers empty, so a new endpoint cannot be
+        # missing from the fake. Lists answer [], counts 0, reads nil, writes {}.
+        answers = API::Queries.empty_answers.merge(webhook_deliveries_count: 0)
+        api_methods = [API::CustomerActions, API::StoreActions, API::ProductActions, API::PromotionActions,
+                       API::Queries].flat_map(&:public_instance_methods)
+        client_only = %i[issue_session_token create_authenticated_plan_change webhook_deliveries_count
+                         create_onetime_order create_subscription_order]
+        (api_methods + client_only).uniq.reject { |name| method_defined?(name) }.each do |name|
+          define_method(name) do |*arguments, **params|
+            record(name, *arguments, *optional(params))
+            answers.fetch(name, {})
+          end
+        end
+
         private
           def record(name, *arguments)
             calls << [name, *arguments]
             raise fail_with if fail_with
           end
 
+          def optional(params) = params.empty? ? [] : [params]
+
           def change_status(order_id, status)
             @orders[order_id.to_s]&.merge!("status" => status)
             { "orderId" => order_id, "status" => status }

data/lib/waffo/pancake/version.rb

@@ -2,6 +2,6 @@
 
 module Waffo
   module Pancake
-    VERSION = "0.2.1"
+    VERSION = "0.4.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,10 @@ require_relative "pancake/version"
 require_relative "pancake/errors"
 require_relative "pancake/keys"
 require_relative "pancake/client"
+require_relative "pancake/store_checkout"
+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 +16,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.4.0
 platform: ruby
 authors:
 - Good First Issue
@@ -41,14 +41,26 @@ files:
 - lib/generators/waffo_pancake/install/templates/webhook_job.rb.tt
 - lib/generators/waffo_pancake/install/templates/webhooks_controller.rb.tt
 - lib/waffo/pancake.rb
+- lib/waffo/pancake/api/customer_actions.rb
+- lib/waffo/pancake/api/product_actions.rb
+- lib/waffo/pancake/api/promotion_actions.rb
+- lib/waffo/pancake/api/queries.rb
+- lib/waffo/pancake/api/store_actions.rb
 - lib/waffo/pancake/client.rb
 - lib/waffo/pancake/configuration.rb
+- lib/waffo/pancake/connection.rb
+- lib/waffo/pancake/customer_portal_controller.rb
+- lib/waffo/pancake/customer_session.rb
+- lib/waffo/pancake/deprecation.rb
 - lib/waffo/pancake/errors.rb
 - lib/waffo/pancake/keys.rb
 - lib/waffo/pancake/railtie.rb
+- lib/waffo/pancake/requests.rb
+- lib/waffo/pancake/store_checkout.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: