@waffo/pancake-ts 0.17.0 → 0.18.0

package/dist/index.d.cts

@@ -7,6 +7,21 @@ interface WaffoPancakeConfig {
     baseUrl?: string;
     /** Custom fetch implementation (default: global fetch) */
     fetch?: typeof fetch;
+    /**
+     * Environment that customer sessions operate in (sent as the `X-Environment`
+     * header alongside the session token's Bearer credential).
+     *
+     * API Key requests do not need this — the gateway derives their environment
+     * from the key itself. Session tokens carry no environment, so the gateway
+     * requires the header and rejects the request with HTTP 400 without it.
+     *
+     * There is no default: a wrong guess would route the call to the other
+     * environment. Supply it here, or per session via
+     * {@link CustomerSessionOptions.environment}.
+     *
+     * @see {@link WaffoPancake.customer}
+     */
+    environment?: `${Environment}`;
     /**
      * Custom RSA public key(s) for webhook signature verification.
      *
@@ -18,6 +33,16 @@ interface WaffoPancakeConfig {
      */
     webhookPublicKey?: WebhookPublicKeys;
 }
+/** Options for {@link WaffoPancake.customer}. */
+interface CustomerSessionOptions {
+    /**
+     * Environment this session operates in, overriding
+     * {@link WaffoPancakeConfig.environment} for a single session.
+     *
+     * Required when the client config omits `environment`.
+     */
+    environment?: `${Environment}`;
+}
 /**
  * Options for {@link HttpClient.post}.
  * Not exported publicly — used by resource classes.
@@ -1127,11 +1152,27 @@ interface VerifyWebhookOptions {
      */
     environment?: `${Environment}`;
     /**
-     * Timestamp tolerance window in milliseconds for replay protection.
-     * Set to 0 to skip timestamp checking.
-     * @default 300000 (5 minutes)
+     * How far in the past a signature timestamp may be, in milliseconds.
+     * Set to 0 to skip timestamp checking entirely (this also skips
+     * {@link futureToleranceMs}).
+     *
+     * The default covers the full delivery retry schedule: the timestamp is
+     * stamped before the first attempt and retries reuse it, so the last retry
+     * arrives with a timestamp as old as the schedule itself.
+     *
+     * @default 2700000 (45 minutes)
      */
     toleranceMs?: number;
+    /**
+     * How far in the future a signature timestamp may be, in milliseconds.
+     * Only clock skew on the receiving server puts a timestamp ahead of now, so
+     * this stays tight — it matches the gateway's API Key check.
+     *
+     * Ignored when `toleranceMs` is 0.
+     *
+     * @default 60000 (1 minute)
+     */
+    futureToleranceMs?: number;
     /**
      * Per-call public key override (highest priority).
      * When provided, skips all other key resolution (config, env vars, built-in).
@@ -1462,16 +1503,24 @@ declare class ContentSafetyResource {
  * never sends an idempotency key (customer session actions are not protected by
  * gateway idempotency in the current architecture).
  *
+ * Session tokens carry no environment of their own, so every request also sends
+ * `X-Environment`. The gateway treats a Bearer credential without it as an
+ * incomplete JWT header set and answers HTTP 400.
+ *
  * Not exported publicly — used internally by {@link CustomerSession}.
  */
 declare class CustomerHttpClient {
     private readonly token;
+    private readonly environment;
     private readonly baseUrl;
     private readonly _fetch;
-    constructor(token: string, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
+    constructor(token: string, environment: `${Environment}`, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
     /**
      * 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.
      */
@@ -2174,22 +2223,34 @@ declare class WaffoPancake {
      * 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: string): CustomerSession;
+    customer(token: string, options?: CustomerSessionOptions): CustomerSession;
     /**
      * 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
@@ -2199,7 +2260,7 @@ declare class WaffoPancake {
      *
      * @deprecated Use {@link WaffoPancake.customer} instead.
      */
-    buyer(token: string): CustomerSession;
+    buyer(token: string, options?: CustomerSessionOptions): CustomerSession;
 }
 
 /**
@@ -2278,4 +2339,4 @@ declare class WaffoPancakeError extends Error {
  */
 declare function verifyWebhook<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 
-export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };

package/dist/index.d.ts

@@ -7,6 +7,21 @@ interface WaffoPancakeConfig {
     baseUrl?: string;
     /** Custom fetch implementation (default: global fetch) */
     fetch?: typeof fetch;
+    /**
+     * Environment that customer sessions operate in (sent as the `X-Environment`
+     * header alongside the session token's Bearer credential).
+     *
+     * API Key requests do not need this — the gateway derives their environment
+     * from the key itself. Session tokens carry no environment, so the gateway
+     * requires the header and rejects the request with HTTP 400 without it.
+     *
+     * There is no default: a wrong guess would route the call to the other
+     * environment. Supply it here, or per session via
+     * {@link CustomerSessionOptions.environment}.
+     *
+     * @see {@link WaffoPancake.customer}
+     */
+    environment?: `${Environment}`;
     /**
      * Custom RSA public key(s) for webhook signature verification.
      *
@@ -18,6 +33,16 @@ interface WaffoPancakeConfig {
      */
     webhookPublicKey?: WebhookPublicKeys;
 }
+/** Options for {@link WaffoPancake.customer}. */
+interface CustomerSessionOptions {
+    /**
+     * Environment this session operates in, overriding
+     * {@link WaffoPancakeConfig.environment} for a single session.
+     *
+     * Required when the client config omits `environment`.
+     */
+    environment?: `${Environment}`;
+}
 /**
  * Options for {@link HttpClient.post}.
  * Not exported publicly — used by resource classes.
@@ -1127,11 +1152,27 @@ interface VerifyWebhookOptions {
      */
     environment?: `${Environment}`;
     /**
-     * Timestamp tolerance window in milliseconds for replay protection.
-     * Set to 0 to skip timestamp checking.
-     * @default 300000 (5 minutes)
+     * How far in the past a signature timestamp may be, in milliseconds.
+     * Set to 0 to skip timestamp checking entirely (this also skips
+     * {@link futureToleranceMs}).
+     *
+     * The default covers the full delivery retry schedule: the timestamp is
+     * stamped before the first attempt and retries reuse it, so the last retry
+     * arrives with a timestamp as old as the schedule itself.
+     *
+     * @default 2700000 (45 minutes)
      */
     toleranceMs?: number;
+    /**
+     * How far in the future a signature timestamp may be, in milliseconds.
+     * Only clock skew on the receiving server puts a timestamp ahead of now, so
+     * this stays tight — it matches the gateway's API Key check.
+     *
+     * Ignored when `toleranceMs` is 0.
+     *
+     * @default 60000 (1 minute)
+     */
+    futureToleranceMs?: number;
     /**
      * Per-call public key override (highest priority).
      * When provided, skips all other key resolution (config, env vars, built-in).
@@ -1462,16 +1503,24 @@ declare class ContentSafetyResource {
  * never sends an idempotency key (customer session actions are not protected by
  * gateway idempotency in the current architecture).
  *
+ * Session tokens carry no environment of their own, so every request also sends
+ * `X-Environment`. The gateway treats a Bearer credential without it as an
+ * incomplete JWT header set and answers HTTP 400.
+ *
  * Not exported publicly — used internally by {@link CustomerSession}.
  */
 declare class CustomerHttpClient {
     private readonly token;
+    private readonly environment;
     private readonly baseUrl;
     private readonly _fetch;
-    constructor(token: string, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
+    constructor(token: string, environment: `${Environment}`, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
     /**
      * 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.
      */
@@ -2174,22 +2223,34 @@ declare class WaffoPancake {
      * 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: string): CustomerSession;
+    customer(token: string, options?: CustomerSessionOptions): CustomerSession;
     /**
      * 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
@@ -2199,7 +2260,7 @@ declare class WaffoPancake {
      *
      * @deprecated Use {@link WaffoPancake.customer} instead.
      */
-    buyer(token: string): CustomerSession;
+    buyer(token: string, options?: CustomerSessionOptions): CustomerSession;
 }
 
 /**
@@ -2278,4 +2339,4 @@ declare class WaffoPancakeError extends Error {
  */
 declare function verifyWebhook<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 
-export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AddWebhookParams, type AnonymousCheckoutParams, type ApiError, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, type CashierLanguage, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type CustomerSessionOptions, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, type Envelope, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type MerchantWritableNotificationSettings, type Notice, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, type PaymentMethod, PaymentStatus, type PostResult, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RefundTicketVersionData, type RemoveMerchantParams, type RemoveMerchantResult, type RemoveWebhookParams, type RequestedAmount, type ResubmitRefundTicketParams, ScanAction, ScanPolicyCategory, type ScanPromptParams, ScanReasonCode, type ScanResult, ScanSemanticMode, ScanSemanticStatus, type SessionToken, type Store, StoreRole, type StoreWebhook, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type UpdateWebhookParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookChannel, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, verifyWebhook };

package/dist/index.js

@@ -15,16 +15,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.
    */
@@ -33,7 +38,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)
     });
@@ -1073,7 +1079,8 @@ var SubscriptionProductsResource = class {
 
 // src/webhooks.ts
 import { createVerify } from "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/
@@ -1141,7 +1148,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)");
     }
   }
@@ -1334,19 +1343,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
     });
@@ -1356,6 +1386,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
@@ -1365,8 +1396,8 @@ var WaffoPancake = class {
    *
    * @deprecated Use {@link WaffoPancake.customer} instead.
    */
-  buyer(token) {
-    return this.customer(token);
+  buyer(token, options) {
+    return this.customer(token, options);
   }
 };