@waffo/pancake-ts 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `@waffo/pancake-ts` will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.0] - 2026-08-18
+
+Subscription products can now charge for the trial period.
+
+### Added
+
+- **`PriceInfo.trialAmount`** — trial period price as a display string, subscription products only. Omit it for a free trial. It requires `metadata.trialDays` on the product and must be lower than `amount`; the API rejects either violation with a 400.
+- **`PriceSnapshot`** — the type `CreateCheckoutSessionParams.priceSnapshot` accepts. Same shape as `PriceInfo` without `trialAmount`.
+
+### Changed
+
+- **`CreateCheckoutSessionParams.priceSnapshot` is typed `PriceSnapshot` rather than `PriceInfo`.** A session-level override replaces the regular period price; the trial price comes from the product version locked into the session, so a `trialAmount` passed here would be dropped server-side. Existing calls compile unchanged — the fields `PriceSnapshot` declares are exactly the two `PriceInfo` had before `trialAmount` was added.
+
+## [0.18.0] - 2026-08-08
+
+Customer sessions never reached the API, and webhook retries were rejected as replays.
+
+### Fixed
+
+- **Customer session requests now send `X-Environment`.** A session token carries no environment of its own, so the gateway requires the header next to the Bearer credential and rejects the request with a 400 without it. The header was missing, which made every `client.customer(...)` method unusable: `cancelSubscription`, `cancelOnetimeOrder`, `reactivateSubscription`, `createRefundTicket`, `resubmitRefundTicket`, and `graphql.query`. API Key requests were never affected — the gateway derives their environment from the key.
+- **Webhook verification no longer rejects legitimate retries.** The signature timestamp is stamped once, before the first delivery attempt, and retries reuse the original header — so the last retry of a schedule arrives with a timestamp as old as the schedule itself (observed above 31 minutes). Against the old 5-minute window every late retry failed verification as a suspected replay. `verifyWebhook` now allows timestamps up to **45 minutes** old.
+
+### Added
+
+- **`WaffoPancakeConfig.environment`** — `"test"` or `"prod"`, the environment customer sessions operate in.
+- **`CustomerSessionOptions`** — second argument to `client.customer(token, options)`, overriding the config for a single session.
+- **`VerifyWebhookOptions.futureToleranceMs`** — how far in the future a signature timestamp may be, default `60000` (1 minute). Raise it for a receiving server with known clock skew.
+
+### Changed
+
+- **`client.customer(token)` requires an environment** from either the config or the per-session options, and throws `WaffoPancakeError` (400, `layer: "sdk"`) when neither supplies one. There is no default — guessing would route the call to the other environment. This turns a request that always failed at the gateway into a local error; no working call changes behavior. Migration: add `environment` to your client config, or pass `client.customer(token, { environment: "test" })`.
+- `client.buyer(token, options)` (deprecated) accepts and forwards the same options.
+- **`VerifyWebhookOptions.toleranceMs` default raised from `300000` to `2700000`, and the window is now asymmetric** — matching the gateway's API Key check, which pairs a wide past-facing window with a tight future-facing one. `toleranceMs` now means "how far in the past"; the future direction is `futureToleranceMs`. `toleranceMs: 0` still disables the check entirely. A captured request stays replayable for longer under the wider window, so keep your handler idempotent on the event `id` — that, not the window, is the real defense.
+
+
 ## [0.17.0] - 2026-08-03
 
 `supportEmail` and `website` were never applied by the update-store endpoint — passing them was silently ignored.

package/README.md

@@ -40,13 +40,14 @@ res.json({ checkoutUrl: result.checkoutUrl });
 
 ## Configuration
 
-| Parameter          | Type                         | Required | Description                                                                        |
-| ------------------ | ---------------------------- | -------- | ---------------------------------------------------------------------------------- |
-| `merchantId`       | `string`                     | Yes      | Merchant ID in `MER_{base62}` format                                               |
-| `privateKey`       | `string`                     | Yes      | RSA private key in PEM format (auto-normalized, see [docs](docs/api-reference.md)) |
-| `baseUrl`          | `string`                     | No       | API base URL override                                                              |
-| `fetch`            | `typeof fetch`               | No       | Custom fetch implementation                                                        |
-| `webhookPublicKey` | `string \| { test?, prod? }` | No       | Custom webhook public key(s)                                                       |
+| Parameter          | Type                         | Required              | Description                                                                                               |
+| ------------------ | ---------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `merchantId`       | `string`                     | Yes                   | Merchant ID in `MER_{base62}` format                                                                      |
+| `privateKey`       | `string`                     | Yes                   | RSA private key in PEM format (auto-normalized, see [docs](docs/api-reference.md))                        |
+| `baseUrl`          | `string`                     | No                    | API base URL override                                                                                     |
+| `environment`      | `"test" \| "prod"`           | For customer sessions | Sent as `X-Environment`. No default — override per session with `client.customer(token, { environment })` |
+| `fetch`            | `typeof fetch`               | No                    | Custom fetch implementation                                                                               |
+| `webhookPublicKey` | `string \| { test?, prod? }` | No                    | Custom webhook public key(s)                                                                              |
 
 The SDK auto-normalizes key formats: standard PEM, PKCS#1, literal `\n` from env vars, raw base64, and Windows line endings are all accepted.
 
@@ -73,7 +74,7 @@ Waffo supports two checkout modes based on whether the merchant knows the custom
 
 Both modes support **dynamic pricing** and **trial control** at checkout time:
 
-- `priceSnapshot` — override the product's stored price with a custom amount (e.g., coupon, volume discount)
+- `priceSnapshot` — override the product's stored price with a custom amount (e.g., coupon, volume discount); for subscription products this replaces the regular period price only
 - `withTrial` — explicitly enable or disable the trial period for subscriptions (`true` = force trial, `false` = skip trial, omit = use default rules)
 
 ### Authenticated Checkout (Recommended)
@@ -232,7 +233,7 @@ See [Webhook Guide](docs/webhook-guide.md) for event types, `WebhookEventData` f
 
 Beyond checkout, you can let customers manage their own orders and subscriptions — for example, embedding a "Cancel Subscription" or "Request Refund" button in your site.
 
-Issue a session token, then use `client.customer(token)` to get a session with self-service methods:
+Issue a session token, then use `client.customer(token, options?)` to get a session with self-service methods:
 
 ```typescript
 // Your backend — issue a session token for the customer
@@ -241,8 +242,9 @@ const { token } = await client.auth.issueSessionToken({
   buyerIdentity: req.user.email,
 });
 
-// Create a customer session
-const customer = client.customer(token);
+// Create a customer session — environment is required here (or on the client config),
+// because a session token carries none of its own
+const customer = client.customer(token, { environment: "test" });
 
 // Cancel a subscription
 const { orderId, status } = await customer.cancelSubscription({ orderId: "ORD_xxx" });
@@ -545,7 +547,7 @@ try {
 | `client.checkout.authenticated`    | `create()`                                                                                                               | Authenticated checkout (recommended)    |
 | `client.checkout.anonymous`        | `create()`                                                                                                               | Anonymous checkout                      |
 | `client.checkout`                  | `createSession()`                                                                                                        | Low-level checkout session              |
-| `client.customer(token)`           | `cancelSubscription()` `cancelOnetimeOrder()` `reactivateSubscription()` `createRefundTicket()` `resubmitRefundTicket()` | Customer self-service                   |
+| `client.customer(token, opts?)`    | `cancelSubscription()` `cancelOnetimeOrder()` `reactivateSubscription()` `createRefundTicket()` `resubmitRefundTicket()` | Customer self-service                   |
 | `client.customer(token).graphql`   | `query<T>()`                                                                                                             | Customer-scoped GraphQL queries         |
 | `client.webhooks`                  | `verify<T>()` `add()` `update()` `remove()`                                                                              | Webhook config + signature verification |
 | `client.graphql`                   | `query<T>()`                                                                                                             | Merchant GraphQL queries                |

package/dist/index.cjs

@@ -62,16 +62,21 @@ var WaffoPancakeError = class extends Error {
 var DEFAULT_BASE_URL = "https://api.waffo.ai";
 var CustomerHttpClient = class {
   token;
+  environment;
   baseUrl;
   _fetch;
-  constructor(token, config) {
+  constructor(token, environment, config) {
     this.token = token;
+    this.environment = environment;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
   }
   /**
    * Send a Bearer-authenticated POST and return the full envelope plus HTTP status.
    *
+   * Sends `Authorization: Bearer <token>` and `X-Environment` — the gateway
+   * requires both to accept a session token.
+   *
    * Does NOT throw on `errors[]` or non-2xx status — caller inspects the result.
    * Throws {@link WaffoPancakeError} only when the response body is not valid JSON.
    */
@@ -80,7 +85,8 @@ var CustomerHttpClient = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${this.token}`
+        Authorization: `Bearer ${this.token}`,
+        "X-Environment": this.environment
       },
       body: JSON.stringify(body)
     });
@@ -1120,7 +1126,8 @@ var SubscriptionProductsResource = class {
 
 // src/webhooks.ts
 var import_node_crypto3 = require("crypto");
-var DEFAULT_TOLERANCE_MS = 5 * 60 * 1e3;
+var DEFAULT_TOLERANCE_MS = 45 * 60 * 1e3;
+var DEFAULT_FUTURE_TOLERANCE_MS = 60 * 1e3;
 var TEST_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxnmRY6yMMA3lVqmAU6ZG
 b1sjL/+r/z6E+ZjkXaDAKiqOhk9rpazni0bNsGXwmftTPk9jy2wn+j6JHODD/WH/
@@ -1188,7 +1195,9 @@ function verifyWebhook(payload, signatureHeader, options) {
     if (Number.isNaN(timestampMs)) {
       throw new Error("Invalid timestamp in X-Waffo-Signature header");
     }
-    if (Math.abs(Date.now() - timestampMs) > toleranceMs) {
+    const futureToleranceMs = options?.futureToleranceMs ?? DEFAULT_FUTURE_TOLERANCE_MS;
+    const ageMs = Date.now() - timestampMs;
+    if (ageMs > toleranceMs || ageMs < -futureToleranceMs) {
       throw new Error("Webhook timestamp outside tolerance window (possible replay attack)");
     }
   }
@@ -1381,19 +1390,40 @@ var WaffoPancake = class {
    * methods for order cancellation, subscription management, refund tickets,
    * and scoped GraphQL queries.
    *
+   * Session tokens expire 5 minutes after issuance, so issue one right before
+   * use rather than caching it.
+   *
    * @param token - Session token from `client.auth.issueSessionToken()`
+   * @param options - Per-session overrides
    * @returns A customer session with self-service methods
+   * @throws {WaffoPancakeError} When no environment is available from either
+   *   `options.environment` or `WaffoPancakeConfig.environment`
    *
    * @example
    * const { token } = await client.auth.issueSessionToken({
    *   storeId: "STO_xxx",
    *   buyerIdentity: "customer@example.com",
    * });
-   * const customer = client.customer(token);
+   * const customer = client.customer(token, { environment: "test" });
    * await customer.cancelSubscription({ orderId: "ORD_xxx" });
+   *
+   * @example
+   * // Set the environment once on the client instead
+   * const client = new WaffoPancake({ merchantId, privateKey, environment: "test" });
+   * const customer = client.customer(token);
    */
-  customer(token) {
-    const customerHttp = new CustomerHttpClient(token, {
+  customer(token, options) {
+    const environment = options?.environment ?? this.config.environment;
+    if (environment === void 0) {
+      throw new WaffoPancakeError(400, [
+        {
+          message: "Missing required field: environment \u2014 set it on the client config or pass client.customer(token, { environment: 'test' | 'prod' })",
+          layer: "sdk"
+        }
+      ]);
+    }
+    validateEnum("environment", environment, ["test", "prod"]);
+    const customerHttp = new CustomerHttpClient(token, environment, {
       baseUrl: this.config.baseUrl,
       fetch: this.config.fetch
     });
@@ -1403,6 +1433,7 @@ var WaffoPancake = class {
    * Create a customer session for self-service operations.
    *
    * @param token - Session token from `client.auth.issueSessionToken()`
+   * @param options - Per-session overrides
    * @returns A customer session with self-service methods
    *
    * @example
@@ -1412,8 +1443,8 @@ var WaffoPancake = class {
    *
    * @deprecated Use {@link WaffoPancake.customer} instead.
    */
-  buyer(token) {
-    return this.customer(token);
+  buyer(token, options) {
+    return this.customer(token, options);
   }
 };