waffo-pancake 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87fe6008dd468bd2fe340702f5b8a6b5f4ce9141a7b49b9c069cf37062aaca3f
-  data.tar.gz: f9d37be2f832780519fdcd3319eb1ac3a96e073c588c153bea72477c4518cd61
+  metadata.gz: 53bc96e6da7f2a84f2ad08a962fe1bb1f7041d630a74446f933c78a475384dfa
+  data.tar.gz: 8ff4d5eabce81147a7bdeafe43d744cb82782ef047116d5d62a38208b2857d87
 SHA512:
-  metadata.gz: 77f17baee5d56461088b0b3ecc8b948d2d341d35b373ae6845593e5504632a17f995fbcc63d889821341267305edc70c1bbb21088ce6870927ca4a154043d72c
-  data.tar.gz: 9e0cb6aae549bc3fd02978fd432252d7d5eefe4018505360284374548158fd62b5c5ea10d59f3c8769a3748a08eca053d3e75ed8c25e5a615bfc739a6d15c635
+  metadata.gz: a567f41bee5bbedd913786a18623285f45303f2b7f45e13c0a60171bead24ab70b65e51f9231043f857128e30e5229688fa553a07a3799b768fc89b799654881
+  data.tar.gz: 53b910c7287fe30d1c2ef9f0796f9e4de5e868a058db982f3e421efb0d2494b03683ed3202d814e5431a1f8902493a3a09d1023d280665cd8fc38b4b18df53d3

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.4.0
+
+- Every endpoint in Waffo's API reference now has a method:
+  - Stores: `create_store`, `update_store`, `delete_store`.
+  - Store members: `add_store_merchant`, `remove_store_merchant`, `update_store_merchant_role`.
+  - Webhooks: `update_webhook`.
+  - Notification recipients: `add_notification_recipient`, `update_notification_recipient`,
+    `remove_notification_recipient`.
+  - Products: `update_onetime_product`, `publish_onetime_product`,
+    `update_onetime_product_status`, `update_subscription_product_status`.
+  - Product groups: `create_subscription_product_group`, `update_…`, `delete_…`, `publish_…`.
+  - Promotions: `create_coupon`, `update_coupon`, `deactivate_coupon`, `create_promotion_code`,
+    `generate_promotion_codes`, `deactivate_promotion_code`.
+  - Refund tickets: `create_refund_ticket`, `resubmit_refund_ticket`.
+  - Plan changes: `create_plan_change_session`, `create_authenticated_plan_change`.
+  - Content safety: `scan_prompt`.
+- `Client#customer(token, environment:)` returns a `CustomerSession`, authenticated with a session
+  token, with the customer actions plus `create_onetime_order` and `create_subscription_order`.
+- `StoreCheckout.new(store_slug:, environment:)` for anonymous checkout with only the store slug.
+- GraphQL readers, generated from the schema that introspection reports: lists, `*_count` and
+  single-record methods, `*_aggregate` methods and analytics methods. Filters travel as typed
+  variables.
+- `idempotency_key:` on every action, sent as `X-Idempotency-Key`.
+- `Waffo::Pancake::NULL` sends an explicit JSON null, which clears a field. A nil is still dropped.
+- `Error#retry_after`, from the `Retry-After` header.
+- An action's result has a `"warnings"` key when Waffo sent warnings.
+- `Client.new(environment:)`, defaulting to the configured environment.
+- `TestHelpers::FakeClient` has every API method, generated, so a new endpoint cannot be missing.
+- Changed: `graphql` now raises on a non-2xx status without `errors`. It used to return nil.
+- Known: with an API key, `reactivate_subscription` and `cancel_onetime_order` get a 401 from
+  Waffo's gateway. Call them through `client.customer(token)`.
+- `rake test:live` runs the real API with a test-mode key. It is not part of `rake test`.
+
 ## 0.3.0
 
 - Webhook amount fields (Waffo, 2026-09-20 to 2026-09-22):

data/README.md

@@ -100,13 +100,15 @@ settings: the portal's return button links only there.
 
 ```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.
 
+Waffo's gateway refuses an API key on `reactivate_subscription` and `cancel_onetime_order` with
+a 401. Call them as the customer; see [Customer sessions](#customer-sessions).
+
 ## Products
 
 ```ruby
@@ -119,11 +121,102 @@ client.publish_subscription_product(id: "PROD_...")  # test → prod, first publ
 
 Amounts are display strings (`"9.99"`), not cents.
 
-## GraphQL and other endpoints
+## Stores, coupons and refunds
 
 ```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: "..." })
+client.create_store(name: "My Store")
+client.update_store(id: "STO_...", logo: Waffo::Pancake::NULL)   # NULL clears a field; nil is dropped
+
+client.update_onetime_product_status(id: "PROD_...", status: "inactive")
+client.create_subscription_product_group(store_id: "STO_...", name: "Plans", product_ids: ["PROD_..."])
+
+client.update_webhook(id: webhook["id"], url: "https://example.com/hooks/waffo")
+client.add_notification_recipient(store_id: "STO_...", email: "ops@example.com")
+client.add_store_merchant(store_id: "STO_...", email: "ada@example.com", role: "member")
+
+coupon = client.create_coupon(store_id: "STO_...", name: "Launch", discount: { type: "percentage", percentOff: 20 })
+client.generate_promotion_codes(coupon_id: "CPN_...", count: 100, prefix: "LAUNCH")
+
+client.create_refund_ticket(payment_id: "PAY_...", reason: "Duplicate charge",
+                            requested_amount: { amount: "9.99", currency: "USD" })
+client.scan_prompt(prompt: "...")
+```
+
+Every action takes `idempotency_key:` (1 to 256 characters of `A-Z a-z 0-9 _ -`). It is sent as
+`X-Idempotency-Key`, and Waffo keeps the answer for 24 hours. Nothing is sent unless you pass one:
+
+```ruby
+client.create_refund_ticket(..., idempotency_key: "refund-#{order.id}")
+```
+
+When Waffo sends warnings with a successful answer, the result has a `"warnings"` key.
+
+## Customer sessions
+
+Some routes act as one customer and take a session token instead of an API key. A token does not
+carry an environment, so the session needs one, from `environment:` or the configuration.
+
+```ruby
+token = client.issue_session_token(buyer_identity: "user-42", store_id: "STO_...")["token"]
+customer = client.customer(token, environment: "test")
+
+customer.reactivate_subscription("ORD_...")
+customer.cancel_onetime_order("ORD_...")
+customer.create_onetime_order(checkout_session_id: "cs_...", billing_detail: { country: "US", ... },
+                              language: "en", buyer_email: "ada@example.com")
+# create_subscription_order takes the same arguments. buyer_email: is required unless the checkout
+# session already has one.
+customer.graphql("{ onetimeOrders { id status } }")
+```
+
+`inspect` hides the token. A plan change the customer confirms on Waffo's page:
+
+```ruby
+link = client.create_authenticated_plan_change(origin_order_id: "ORD_...", product_id: "PROD_...",
+                                               currency: "USD", buyer_identity: "user-42")
+redirect_to link["checkoutUrl"], allow_other_host: true   # a bearer credential: never log it
+```
+
+Anonymous checkout with only the public store slug, which needs no secret:
+
+```ruby
+storefront = Waffo::Pancake::StoreCheckout.new(store_slug: "my-store", environment: "test")
+storefront.create_checkout_session(product_id: "PROD_...", currency: "USD")
+```
+
+## Reading data
+
+```ruby
+client.onetime_products(limit: 20)                     # store_id: defaults to WAFFO_STORE_ID
+client.onetime_products(store_slug: "my-store")
+client.onetime_products_count
+client.onetime_product("PROD_...")                     # nil when unknown
+client.payments(filter: { status: { eq: "succeeded" } }, order_by: :created_at_desc, offset: 20)
+client.promotion_codes(coupon_id: "CPN_...")
+client.subscription_product_versions("PROD_...")
+client.me
+```
+
+There are readers for stores, merchants, store merchants, products, product groups, orders,
+payments, refunds, refund tickets, chargebacks, customers, coupons, promotion codes, discount
+applications, email deliveries, cancel reasons, webhooks and notification recipients.
+`Waffo::Pancake::API::Queries::LISTS` is the full table. `fields:` replaces the default selection.
+It is written into the query, so it must come from your code and never from a request. Filters
+travel as GraphQL variables, so they are safe for any value.
+
+Analytics return the fields you ask for, and aggregates can group by a dimension:
+
+```ruby
+client.order_statistics(fields: "totalCount buyerMetrics { totalBuyers }",
+                        start_date: 1.month.ago, end_date: Time.now, currency: "USD")
+client.payments_aggregate(group_by: :status, granularity: :month, filter: { currency: { eq: "USD" } })
+```
+
+Anything else goes through the low-level calls:
+
+```ruby
+client.graphql("query ($id: String!) { payoutTicket(id: $id) { id status } }", id: "...")
+client.action("/v1/actions/some-group/some-action", { some_param: "..." })
 ```
 
 ## Webhooks
@@ -302,14 +395,15 @@ end
 
 `FakeClient` answers `subscription_order` from the orders it was given, moves an order to
 `canceling` / `active` on cancel / reactivate, records every call in `calls`, and raises
-`fail_with` when set.
+`fail_with` when set. It has every API method: lists answer `[]`, counts `0`, reads `nil` and
+writes `{}`. `customer(token)` answers with the same fake.
 
 ## 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::Unavailable` | Network failure, timeout, 429 or 5xx. Worth retrying later, after `retry_after` seconds when it is set. |
 | `Waffo::Pancake::ConfigurationError` | Missing merchant id, or a key that does not parse. |
 | `Waffo::Pancake::InvalidSignature` | A webhook that does not verify. |
 
@@ -318,7 +412,7 @@ 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]`.
+the headers and the JSON body and returns `[status, body]` or `[status, body, headers]`.
 
 ```ruby
 transport = ->(uri, headers, json) { [200, '{"data":{"orderId":"ORD_1","status":"canceling"}}'] }
@@ -334,6 +428,17 @@ bundle install
 bundle exec rake test        # test:core (no Rails loaded) and test:rails
 ```
 
+`rake test:live` calls the real API. It needs a **test-mode** key and refuses to run otherwise:
+
+```sh
+WAFFO_LIVE=1 WAFFO_ENVIRONMENT=test WAFFO_MERCHANT_ID=... WAFFO_PRIVATE_KEY=... WAFFO_STORE_ID=... \
+  bundle exec rake test:live
+```
+
+`WAFFO_STORE_ID` is only read. Writes go to a temporary store that the run creates and deletes.
+The `Live API` workflow runs this on pushes to `main` and by hand, from the `WAFFO_*` Actions
+secrets. It never runs for pull requests, so a fork cannot reach the key.
+
 Releases are published to RubyGems by the `Release` workflow when a `v*` tag is pushed (see
 [RELEASING.md](RELEASING.md)). It uses
 [trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no API key is stored.

data/lib/waffo/pancake/api/customer_actions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Waffo
+  module Pancake
+    module API
+      # Actions that act for one customer, so both Client and CustomerSession have them.
+      #
+      # The gateway decides which credential a route takes, and the two groups below differ:
+      # with an API key, reactivate-order and onetime-order/cancel-order answer 401 "API Key
+      # authentication not supported for this route" (tested on 2026-11-04). They stay here so
+      # the 0.x Client API keeps its shape, and because Waffo can open these routes later.
+      module CustomerActions
+        def create_checkout_session(product_id:, currency:, **params)
+          action("/v1/actions/checkout/create-session", product_id: product_id, currency: currency, **params)
+        end
+
+        # A checkout session that changes the plan of `origin_order_id`. Without a coupon of its
+        # own, the session follows the rules of the origin order's product group.
+        def create_plan_change_session(origin_order_id:, product_id:, currency:, **params)
+          action("/v1/actions/checkout/create-session", origin_order_id: origin_order_id, product_id: product_id,
+                                                        currency: currency, **params)
+        end
+
+        # pending → canceled at once; active, trialing and past_due → canceling, ending with the
+        # paid period. The terminal `canceled` arrives later as a webhook. Optional: cancel_reason,
+        # cancel_comment.
+        def cancel_subscription(order_id, **params)
+          action("/v1/actions/subscription-order/cancel-order", order_id: order_id, **params)
+        end
+
+        # Undoes a cancellation while the order is still `canceling`. Session token only; see the
+        # module comment.
+        def reactivate_subscription(order_id, **params)
+          action("/v1/actions/subscription-order/reactivate-order", order_id: order_id, **params)
+        end
+
+        # Session token only; see the module comment.
+        def cancel_onetime_order(order_id, **params)
+          action("/v1/actions/onetime-order/cancel-order", order_id: order_id, **params)
+        end
+
+        # requested_amount: { amount: "9.99", currency: "USD" }
+        def create_refund_ticket(payment_id:, reason:, requested_amount:, **params)
+          action("/v1/actions/refund-ticket/create-ticket", payment_id: payment_id, reason: reason,
+                                                            requested_amount: requested_amount, **params)
+        end
+
+        def resubmit_refund_ticket(ticket_id:, reason:, requested_amount:, **params)
+          action("/v1/actions/refund-ticket/resubmit-ticket", ticket_id: ticket_id, reason: reason,
+                                                              requested_amount: requested_amount, **params)
+        end
+      end
+    end
+  end
+end

data/lib/waffo/pancake/api/product_actions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Waffo
+  module Pancake
+    module API
+      # Products and subscription product groups. Merchant API key.
+      module ProductActions
+        # 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:, **params)
+          action("/v1/actions/subscription-product/publish-product", id: id, **params)
+        end
+
+        # status: "active" or "inactive"
+        def update_subscription_product_status(id:, status:, **params)
+          action("/v1/actions/subscription-product/update-status", id: id, status: status, **params)
+        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
+
+        def update_onetime_product(id:, **params)
+          action("/v1/actions/onetime-product/update-product", id: id, **params)
+        end
+
+        # Copies the test version to production.
+        def publish_onetime_product(id:, **params)
+          action("/v1/actions/onetime-product/publish-product", id: id, **params)
+        end
+
+        # status: "active" or "inactive"
+        def update_onetime_product_status(id:, status:, **params)
+          action("/v1/actions/onetime-product/update-status", id: id, status: status, **params)
+        end
+
+        def create_subscription_product_group(store_id:, name:, **params)
+          action("/v1/actions/subscription-product-group/create-group", store_id: store_id, name: name, **params)
+        end
+
+        def update_subscription_product_group(id:, **params)
+          action("/v1/actions/subscription-product-group/update-group", id: id, **params)
+        end
+
+        def delete_subscription_product_group(id:, **params)
+          action("/v1/actions/subscription-product-group/delete-group", id: id, **params)
+        end
+
+        def publish_subscription_product_group(id:, **params)
+          action("/v1/actions/subscription-product-group/publish-group", id: id, **params)
+        end
+      end
+    end
+  end
+end

data/lib/waffo/pancake/api/promotion_actions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Waffo
+  module Pancake
+    module API
+      # Coupons, promotion codes and the prompt scan. Merchant API key.
+      module PromotionActions
+        # discount: { type: "percentage", percentOff: 20 }
+        def create_coupon(store_id:, name:, discount:, **params)
+          action("/v1/actions/coupon/create-coupon", store_id: store_id, name: name, discount: discount, **params)
+        end
+
+        def update_coupon(id:, name:, **params)
+          action("/v1/actions/coupon/update-coupon", id: id, name: name, **params)
+        end
+
+        def deactivate_coupon(id:, **params)
+          action("/v1/actions/coupon/deactivate-coupon", id: id, **params)
+        end
+
+        def create_promotion_code(coupon_id:, **params)
+          action("/v1/actions/promotion-code/create-promotion-code", coupon_id: coupon_id, **params)
+        end
+
+        def generate_promotion_codes(coupon_id:, count:, **params)
+          action("/v1/actions/promotion-code/generate-promotion-codes", coupon_id: coupon_id, count: count, **params)
+        end
+
+        def deactivate_promotion_code(id:, **params)
+          action("/v1/actions/promotion-code/deactivate-promotion-code", id: id, **params)
+        end
+
+        def scan_prompt(prompt:, **params)
+          action("/v1/actions/verification/scan-prompt", prompt: prompt, **params)
+        end
+      end
+    end
+  end
+end