@waffo/pancake-ts 0.1.5 → 0.1.9

package/dist/index.d.ts

@@ -1,14 +1,22 @@
 interface WaffoPancakeConfig {
-    /** Merchant ID (X-Merchant-Id header) */
+    /** Merchant ID in `MER_{base62}` format (sent as X-Merchant-Id header) */
     merchantId: string;
     /** RSA private key in PEM format for request signing */
     privateKey: string;
-    /** Base URL override (default: https://waffo-pancake-auth-service.vercel.app) */
+    /** Base URL override (default: https://api.waffo.ai) */
     baseUrl?: string;
     /** Custom fetch implementation (default: global fetch) */
     fetch?: typeof fetch;
-    /** Custom RSA public key (PEM) for webhook signature verification. When set, overrides the built-in Waffo public keys. */
-    webhookPublicKey?: string;
+    /**
+     * Custom RSA public key(s) for webhook signature verification.
+     *
+     * - `string` — single key used for both test and prod environments
+     * - `{ test?, prod? }` — per-environment keys
+     *
+     * Resolution order per environment: config key → env var → built-in key.
+     * @see {@link VerifyWebhookOptions} for per-call overrides
+     */
+    webhookPublicKey?: WebhookPublicKeys;
 }
 /**
  * Single error object within the `errors` array.
@@ -107,10 +115,11 @@ declare enum OnetimeOrderStatus {
  * Subscription order status.
  *
  * State machine:
- * - pending -> active, canceled
+ * - pending -> active, canceled, closed (PSP CLOSE from never-activated)
  * - active -> canceling, past_due, canceled, expired
  * - canceling -> active, canceled
  * - past_due -> active, canceled
+ * - closed -> terminal (never-activated subscription closed by PSP)
  * - canceled -> terminal
  * - expired -> terminal
  *
@@ -120,8 +129,9 @@ declare enum SubscriptionOrderStatus {
     Pending = "pending",
     Active = "active",
     Canceling = "canceling",
-    Canceled = "canceled",
     PastDue = "past_due",
+    Closed = "closed",
+    Canceled = "canceled",
     Expired = "expired"
 }
 /**
@@ -177,8 +187,10 @@ declare enum ErrorLayer {
     Store = "store",
     Product = "product",
     Order = "order",
+    Ticket = "ticket",
     GraphQL = "graphql",
     Resource = "resource",
+    /** SDK-specific layer for email delivery errors (not part of the service-side error layers). */
     Email = "email"
 }
 /**
@@ -281,11 +293,21 @@ interface CreateStoreParams {
 interface UpdateStoreParams {
     /** Store ID */
     id: string;
+    /** Store display name */
     name?: string;
+    /** Store status */
     status?: EntityStatus;
+    /** Store logo URL (set to `null` to remove) */
     logo?: string | null;
+    /** Support email address (set to `null` to remove) */
+    supportEmail?: string | null;
+    /** Store website URL (set to `null` to remove) */
+    website?: string | null;
+    /** Webhook configuration for test and production environments (set to `null` to remove) */
     webhookSettings?: WebhookSettings | null;
+    /** Notification preferences (set to `null` to remove) */
     notificationSettings?: NotificationSettings | null;
+    /** Checkout page theme configuration (set to `null` to remove) */
     checkoutSettings?: CheckoutSettings | null;
 }
 /** Parameters for deleting (soft-delete) a store. */
@@ -334,22 +356,22 @@ interface UpdateRoleResult {
 /**
  * Price for a single currency.
  *
- * Amounts are stored in the smallest currency unit (e.g. cents, yen)
- * to avoid floating-point precision issues.
+ * Amounts are represented as display strings (e.g., "9.99" for USD, "1000" for JPY).
+ * The server handles conversion to/from smallest currency units internally.
  *
  * @see waffo-pancake-product-service/app/lib/resources/types.ts
  *
  * @example
  * // USD $9.99
- * { amount: 999, taxCategory: "saas" }
+ * { amount: "9.99", taxCategory: "saas" }
  *
  * @example
  * // JPY ¥1000
  * { amount: 1000, taxCategory: "software" }
  */
 interface PriceInfo {
-    /** Price amount in smallest currency unit */
-    amount: number;
+    /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
+    amount: string;
     /** Tax category */
     taxCategory: TaxCategory;
 }
@@ -360,7 +382,7 @@ interface PriceInfo {
  *
  * @example
  * {
- *   "USD": { amount: 999, taxCategory: "saas" },
+ *   "USD": { amount: "9.99", taxCategory: "saas" },
  *   "EUR": { amount: 899, taxCategory: "saas" }
  * }
  */
@@ -620,6 +642,104 @@ interface CheckoutSessionResult {
     /** Session expiration time (ISO 8601 UTC) */
     expiresAt: string;
 }
+/**
+ * Parameters for anonymous checkout (visitor → shopper).
+ *
+ * The buyer enters the checkout page without a session token and fills in
+ * billing details manually. No identity is provided upfront.
+ *
+ * @example
+ * const result = await client.checkout.anonymous.create({
+ *   storeId: "STO_xxx",
+ *   productId: "PROD_xxx",
+ *   productType: "onetime",
+ *   currency: "USD",
+ * });
+ * // Redirect to result.checkoutUrl
+ */
+interface AnonymousCheckoutParams {
+    /** Store ID */
+    storeId: string;
+    /** Product ID */
+    productId: string;
+    /** Product type */
+    productType: `${CheckoutSessionProductType}`;
+    /** Currency code (ISO 4217) */
+    currency: string;
+    /** Optional price snapshot override (reads from DB if omitted) */
+    priceSnapshot?: PriceInfo;
+    /** Trial toggle override (subscription only) */
+    withTrial?: boolean;
+    /** Redirect URL after successful payment */
+    successUrl?: string;
+    /** Session expiration in seconds (default: 45 minutes) */
+    expiresInSeconds?: number;
+    /** Dark mode override (true=dark, false=light, omit=use store default) */
+    darkMode?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Parameters for authenticated checkout (customer).
+ *
+ * The merchant provides a buyer identity; the SDK issues a session token
+ * and appends it to the checkout URL as a URL fragment.
+ *
+ * @example
+ * const result = await client.checkout.authenticated.create({
+ *   storeId: "STO_xxx",
+ *   productId: "PROD_xxx",
+ *   productType: "onetime",
+ *   currency: "USD",
+ *   buyerIdentity: "customer@example.com",
+ * });
+ * // Redirect to result.checkoutUrl (includes #token=...)
+ */
+interface AuthenticatedCheckoutParams {
+    /** Store ID */
+    storeId: string;
+    /** Product ID */
+    productId: string;
+    /** Product type */
+    productType: `${CheckoutSessionProductType}`;
+    /** Currency code (ISO 4217) */
+    currency: string;
+    /** Buyer identity (email or merchant-provided identifier) */
+    buyerIdentity: string;
+    /** Pre-filled buyer email (defaults to `buyerIdentity` when omitted) */
+    buyerEmail?: string;
+    /** Pre-filled billing details */
+    billingDetail?: BillingDetail;
+    /** Optional price snapshot override (reads from DB if omitted) */
+    priceSnapshot?: PriceInfo;
+    /** Trial toggle override (subscription only) */
+    withTrial?: boolean;
+    /** Redirect URL after successful payment */
+    successUrl?: string;
+    /** Session expiration in seconds (default: 45 minutes) */
+    expiresInSeconds?: number;
+    /** Dark mode override (true=dark, false=light, omit=use store default) */
+    darkMode?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Result of an authenticated checkout creation.
+ *
+ * Extends the base session result with the issued token details.
+ */
+interface AuthenticatedCheckoutResult {
+    /** Session ID */
+    sessionId: string;
+    /** Checkout URL with session token appended as URL fragment (`#token=...`) */
+    checkoutUrl: string;
+    /** Session expiration time (ISO 8601 UTC) */
+    expiresAt: string;
+    /** Issued JWT token */
+    token: string;
+    /** Token expiration time (ISO 8601 UTC) */
+    tokenExpiresAt: string;
+}
 /** Parameters for a GraphQL query. */
 interface GraphQLParams {
     /** GraphQL query string */
@@ -673,10 +793,10 @@ interface WebhookEventData {
     orderId: string;
     buyerEmail: string;
     currency: string;
-    /** Amount in smallest currency unit */
-    amount: number;
-    /** Tax amount in smallest currency unit */
-    taxAmount: number;
+    /** Amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
+    amount: string;
+    /** Tax amount as display string (e.g., "0.91" for USD) */
+    taxAmount: string;
     productName: string;
 }
 /**
@@ -689,8 +809,8 @@ interface WebhookEventData {
  *   id: "550e8400-...",
  *   timestamp: "2026-03-10T08:30:00.000Z",
  *   eventType: "order.completed",
- *   eventId: "pay_660e8400-...",
- *   storeId: "770e8400-...",
+ *   eventId: "PAY_5xK9mRtYvWnPqLsJ3hBfDe",
+ *   storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  *   mode: "prod",
  *   data: { orderId: "...", buyerEmail: "...", currency: "USD", amount: 2900, taxAmount: 290, productName: "Pro Plan" }
  * }
@@ -711,6 +831,16 @@ interface WebhookEvent<T = WebhookEventData> {
     /** Event data */
     data: T;
 }
+/**
+ * Webhook public key configuration.
+ *
+ * - `string` — single key used for both test and prod environments
+ * - `{ test?, prod? }` — per-environment keys
+ */
+type WebhookPublicKeys = string | {
+    test?: string;
+    prod?: string;
+};
 /** Options for {@link verifyWebhook}. */
 interface VerifyWebhookOptions {
     /**
@@ -726,15 +856,31 @@ interface VerifyWebhookOptions {
      */
     toleranceMs?: number;
     /**
-     * Custom RSA public key (PEM) for signature verification.
-     * When provided, overrides both built-in keys and the `environment` option.
+     * Per-call public key override (highest priority).
+     * When provided, skips all other key resolution (config, env vars, built-in).
      */
     publicKey?: string;
+    /**
+     * Config-level public key(s) for the resolution chain.
+     * When using `client.webhooks.verify()`, this is set automatically from `WaffoPancakeConfig.webhookPublicKey`.
+     * When using the standalone `verifyWebhook()`, you can pass this directly for config-level key injection.
+     *
+     * Resolution order per environment:
+     * 1. `publicKey` (per-call override)
+     * 2. `publicKeys[env]` or `publicKeys` (config)
+     * 3. `WAFFO_WEBHOOK_{TEST|PROD}_PUBLIC_KEY` (env var)
+     * 4. `WAFFO_WEBHOOK_PUBLIC_KEY` (env var)
+     * 5. Built-in hardcoded key
+     */
+    publicKeys?: WebhookPublicKeys;
 }
 
 /**
  * Internal HTTP client that auto-signs requests and attaches idempotency keys.
  *
+ * The `X-Merchant-Id` header is sent in `MER_{base62}` format as provided by the user.
+ * The gateway decodes it to a raw UUID before forwarding to downstream services.
+ *
  * Not exported publicly — used by resource classes via {@link WaffoPancake}.
  */
 declare class HttpClient {
@@ -771,27 +917,124 @@ declare class AuthResource {
      *
      * @example
      * const { token, expiresAt } = await client.auth.issueSessionToken({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   buyerIdentity: "customer@example.com",
      * });
      */
     issueSessionToken(params: IssueSessionTokenParams): Promise<SessionToken>;
 }
 
-/** Checkout resource — create checkout sessions for payments. */
+/**
+ * Anonymous checkout — visitor enters without a session token.
+ *
+ * The buyer fills in billing details manually on the checkout page.
+ * Internally creates a checkout session and returns the redirect URL.
+ */
+declare class CheckoutAnonymousResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create an anonymous checkout session.
+     *
+     * @param params - Checkout parameters (no buyer identity required)
+     * @returns Session ID, checkout URL, and expiration
+     *
+     * @example
+     * const result = await client.checkout.anonymous.create({
+     *   storeId: "STO_xxx",
+     *   productId: "PROD_xxx",
+     *   productType: "onetime",
+     *   currency: "USD",
+     * });
+     * // Redirect to result.checkoutUrl
+     */
+    create(params: AnonymousCheckoutParams): Promise<CheckoutSessionResult>;
+}
+
+/**
+ * Authenticated checkout — merchant provides buyer identity.
+ *
+ * Issues a session token, creates a checkout session, and returns a
+ * checkout URL with the token appended as a URL fragment (`#token=...`).
+ * The checkout page reads the fragment to pre-fill buyer information.
+ */
+declare class CheckoutAuthenticatedResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create an authenticated checkout session.
+     *
+     * Behavior:
+     * - Issues a session token via `issue-session-token`
+     * - Creates a checkout session via `create-session`
+     * - Appends the token to the checkout URL as a URL fragment
+     * - Defaults `buyerEmail` to `buyerIdentity` when omitted
+     *
+     * @param params - Checkout parameters including buyer identity
+     * @returns Session details with token-appended checkout URL
+     *
+     * @example
+     * const result = await client.checkout.authenticated.create({
+     *   storeId: "STO_xxx",
+     *   productId: "PROD_xxx",
+     *   productType: "onetime",
+     *   currency: "USD",
+     *   buyerIdentity: "customer@example.com",
+     * });
+     * // Redirect to result.checkoutUrl (includes #token=...)
+     */
+    create(params: AuthenticatedCheckoutParams): Promise<AuthenticatedCheckoutResult>;
+}
+
+/**
+ * Checkout resource — create checkout sessions for payments.
+ *
+ * Provides two convenience sub-resources for the common checkout flows:
+ * - `anonymous` — visitor enters without identity (empty form)
+ * - `authenticated` — merchant provides buyer identity (pre-filled form + token)
+ *
+ * The low-level `createSession()` method is still available for full control.
+ *
+ * @example
+ * // Anonymous checkout (visitor → shopper)
+ * const result = await client.checkout.anonymous.create({
+ *   storeId: "STO_xxx",
+ *   productId: "PROD_xxx",
+ *   productType: "onetime",
+ *   currency: "USD",
+ * });
+ *
+ * @example
+ * // Authenticated checkout (customer)
+ * const result = await client.checkout.authenticated.create({
+ *   storeId: "STO_xxx",
+ *   productId: "PROD_xxx",
+ *   productType: "onetime",
+ *   currency: "USD",
+ *   buyerIdentity: "customer@example.com",
+ * });
+ * // result.checkoutUrl includes #token=...
+ */
 declare class CheckoutResource {
     private readonly http;
+    /** Anonymous checkout — visitor enters without a session token. */
+    readonly anonymous: CheckoutAnonymousResource;
+    /** Authenticated checkout — merchant provides buyer identity. */
+    readonly authenticated: CheckoutAuthenticatedResource;
     constructor(http: HttpClient);
     /**
-     * Create a checkout session. Returns a URL to redirect the customer to.
+     * Create a checkout session (low-level). Returns a URL to redirect the customer to.
+     *
+     * For most use cases, prefer `checkout.anonymous.create()` or
+     * `checkout.authenticated.create()` which handle the full flow automatically.
      *
      * @param params - Checkout session parameters
      * @returns Session ID, checkout URL, and expiration
      *
      * @example
      * const session = await client.checkout.createSession({
-     *   storeId: "store_xxx",
-     *   productId: "prod_xxx",
+     *   storeId: "STO_xxx",
+     *   productId: "PROD_xxx",
      *   productType: "onetime",
      *   currency: "USD",
      *   buyerEmail: "customer@example.com",
@@ -820,7 +1063,7 @@ declare class GraphQLResource {
      * @example
      * const result = await client.graphql.query({
      *   query: `query ($id: ID!) { onetimeProduct(id: $id) { id name prices } }`,
-     *   variables: { id: "prod_xxx" },
+     *   variables: { id: "PROD_xxx" },
      * });
      */
     query<T = Record<string, unknown>>(params: GraphQLParams): Promise<GraphQLResponse<T>>;
@@ -838,9 +1081,9 @@ declare class OnetimeProductsResource {
      *
      * @example
      * const { product } = await client.onetimeProducts.create({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   name: "E-Book",
-     *   prices: { USD: { amount: 2900, taxCategory: "digital_goods" } },
+     *   prices: { USD: { amount: "29.00", taxCategory: "digital_goods" } },
      * });
      */
     create(params: CreateOnetimeProductParams): Promise<{
@@ -854,9 +1097,9 @@ declare class OnetimeProductsResource {
      *
      * @example
      * const { product } = await client.onetimeProducts.update({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   name: "E-Book v2",
-     *   prices: { USD: { amount: 3900, taxCategory: "digital_goods" } },
+     *   prices: { USD: { amount: "39.00", taxCategory: "digital_goods" } },
      * });
      */
     update(params: UpdateOnetimeProductParams): Promise<{
@@ -869,7 +1112,7 @@ declare class OnetimeProductsResource {
      * @returns Published product detail
      *
      * @example
-     * const { product } = await client.onetimeProducts.publish({ id: "prod_xxx" });
+     * const { product } = await client.onetimeProducts.publish({ id: "PROD_xxx" });
      */
     publish(params: PublishOnetimeProductParams): Promise<{
         product: OnetimeProductDetail;
@@ -882,7 +1125,7 @@ declare class OnetimeProductsResource {
      *
      * @example
      * const { product } = await client.onetimeProducts.updateStatus({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   status: ProductVersionStatus.Inactive,
      * });
      */
@@ -906,7 +1149,7 @@ declare class OrdersResource {
      *
      * @example
      * const { orderId, status } = await client.orders.cancelSubscription({
-     *   orderId: "order_xxx",
+     *   orderId: "ORD_xxx",
      * });
      * // status: "canceled" or "canceling"
      */
@@ -925,7 +1168,7 @@ declare class StoreMerchantsResource {
      *
      * @example
      * const result = await client.storeMerchants.add({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   email: "member@example.com",
      *   role: "admin",
      * });
@@ -939,8 +1182,8 @@ declare class StoreMerchantsResource {
      *
      * @example
      * const result = await client.storeMerchants.remove({
-     *   storeId: "store_xxx",
-     *   merchantId: "merchant_xxx",
+     *   storeId: "STO_xxx",
+     *   merchantId: "MER_xxx",
      * });
      */
     remove(params: RemoveMerchantParams): Promise<RemoveMerchantResult>;
@@ -952,8 +1195,8 @@ declare class StoreMerchantsResource {
      *
      * @example
      * const result = await client.storeMerchants.updateRole({
-     *   storeId: "store_xxx",
-     *   merchantId: "merchant_xxx",
+     *   storeId: "STO_xxx",
+     *   merchantId: "MER_xxx",
      *   role: "member",
      * });
      */
@@ -984,7 +1227,7 @@ declare class StoresResource {
      *
      * @example
      * const { store } = await client.stores.update({
-     *   id: "store_xxx",
+     *   id: "STO_xxx",
      *   name: "Updated Name",
      * });
      */
@@ -998,7 +1241,7 @@ declare class StoresResource {
      * @returns Deleted store entity (with `deletedAt` set)
      *
      * @example
-     * const { store } = await client.stores.delete({ id: "store_xxx" });
+     * const { store } = await client.stores.delete({ id: "STO_xxx" });
      */
     delete(params: DeleteStoreParams): Promise<{
         store: Store;
@@ -1017,10 +1260,10 @@ declare class SubscriptionProductGroupsResource {
      *
      * @example
      * const { group } = await client.subscriptionProductGroups.create({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   name: "Pro Plans",
      *   rules: { sharedTrial: true },
-     *   productIds: ["prod_aaa", "prod_bbb"],
+     *   productIds: ["PROD_aaa", "PROD_bbb"],
      * });
      */
     create(params: CreateSubscriptionProductGroupParams): Promise<{
@@ -1034,8 +1277,8 @@ declare class SubscriptionProductGroupsResource {
      *
      * @example
      * const { group } = await client.subscriptionProductGroups.update({
-     *   id: "group_xxx",
-     *   productIds: ["prod_aaa", "prod_bbb", "prod_ccc"],
+     *   id: "GRP_xxx",
+     *   productIds: ["PROD_aaa", "PROD_bbb", "PROD_ccc"],
      * });
      */
     update(params: UpdateSubscriptionProductGroupParams): Promise<{
@@ -1048,7 +1291,7 @@ declare class SubscriptionProductGroupsResource {
      * @returns Deleted group entity
      *
      * @example
-     * const { group } = await client.subscriptionProductGroups.delete({ id: "group_xxx" });
+     * const { group } = await client.subscriptionProductGroups.delete({ id: "GRP_xxx" });
      */
     delete(params: DeleteSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
@@ -1060,7 +1303,7 @@ declare class SubscriptionProductGroupsResource {
      * @returns Published group entity
      *
      * @example
-     * const { group } = await client.subscriptionProductGroups.publish({ id: "group_xxx" });
+     * const { group } = await client.subscriptionProductGroups.publish({ id: "GRP_xxx" });
      */
     publish(params: PublishSubscriptionProductGroupParams): Promise<{
         group: SubscriptionProductGroup;
@@ -1079,10 +1322,10 @@ declare class SubscriptionProductsResource {
      *
      * @example
      * const { product } = await client.subscriptionProducts.create({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   name: "Pro Plan",
      *   billingPeriod: "monthly",
-     *   prices: { USD: { amount: 999, taxCategory: "saas" } },
+     *   prices: { USD: { amount: "9.99", taxCategory: "saas" } },
      * });
      */
     create(params: CreateSubscriptionProductParams): Promise<{
@@ -1096,10 +1339,10 @@ declare class SubscriptionProductsResource {
      *
      * @example
      * const { product } = await client.subscriptionProducts.update({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   name: "Pro Plan v2",
      *   billingPeriod: "monthly",
-     *   prices: { USD: { amount: 1499, taxCategory: "saas" } },
+     *   prices: { USD: { amount: "14.99", taxCategory: "saas" } },
      * });
      */
     update(params: UpdateSubscriptionProductParams): Promise<{
@@ -1112,7 +1355,7 @@ declare class SubscriptionProductsResource {
      * @returns Published product detail
      *
      * @example
-     * const { product } = await client.subscriptionProducts.publish({ id: "prod_xxx" });
+     * const { product } = await client.subscriptionProducts.publish({ id: "PROD_xxx" });
      */
     publish(params: PublishSubscriptionProductParams): Promise<{
         product: SubscriptionProductDetail;
@@ -1125,7 +1368,7 @@ declare class SubscriptionProductsResource {
      *
      * @example
      * const { product } = await client.subscriptionProducts.updateStatus({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   status: ProductVersionStatus.Active,
      * });
      */
@@ -1134,16 +1377,25 @@ declare class SubscriptionProductsResource {
     }>;
 }
 
-/** Webhook signature verification resource. */
+/**
+ * Webhook signature verification resource.
+ *
+ * Unlike other resources, this does not use HttpClient — webhook verification
+ * is a local cryptographic operation that does not require API calls.
+ */
 declare class WebhooksResource {
-    private readonly publicKey;
-    /** @param publicKey - Optional custom RSA public key (PEM or raw base64) */
-    constructor(publicKey: string | undefined);
+    private readonly publicKeys;
+    /** @param publicKeys - Optional config-level public key(s) from WaffoPancakeConfig */
+    constructor(publicKeys: WebhookPublicKeys | undefined);
     /**
      * Verify and parse an incoming webhook event.
      *
-     * When the client was created with a `webhookPublicKey`, that key is used
-     * automatically. You can still override per-call via `options.publicKey`.
+     * Key resolution order:
+     * 1. `options.publicKey` — per-call override (highest priority)
+     * 2. `config.webhookPublicKey[env]` or `config.webhookPublicKey` (string)
+     * 3. `WAFFO_WEBHOOK_{TEST|PROD}_PUBLIC_KEY` environment variable
+     * 4. `WAFFO_WEBHOOK_PUBLIC_KEY` environment variable
+     * 5. Built-in hardcoded key
      *
      * @param payload - Raw request body string (must be unparsed)
      * @param signatureHeader - Value of the `X-Waffo-Signature` header
@@ -1155,8 +1407,12 @@ declare class WebhooksResource {
      * const event = client.webhooks.verify(rawBody, signatureHeader);
      *
      * @example
-     * // Override tolerance per call
-     * const event = client.webhooks.verify(rawBody, sig, { toleranceMs: 0 });
+     * // Specify environment
+     * const event = client.webhooks.verify(rawBody, sig, { environment: "test" });
+     *
+     * @example
+     * // Per-call key override
+     * const event = client.webhooks.verify(rawBody, sig, { publicKey: oneOffKey });
      */
     verify<T = Record<string, unknown>>(payload: string, signatureHeader: string | undefined | null, options?: VerifyWebhookOptions): WebhookEvent<T>;
 }
@@ -1171,19 +1427,21 @@ declare class WebhooksResource {
  * import { WaffoPancake } from "@waffo/pancake-ts";
  *
  * const client = new WaffoPancake({
- *   merchantId: process.env.WAFFO_MERCHANT_ID!,
+ *   merchantId: "MER_2D5F8G3H1K4M6N9P0Q7R8S", // MER_{base62} format
  *   privateKey: process.env.WAFFO_PRIVATE_KEY!,
  * });
  *
- * // Create a store
+ * // Create a store — IDs are returned in {prefix}_{base62} format
  * const { store } = await client.stores.create({ name: "My Store" });
+ * // => store.id = "STO_..."
  *
  * // Create a product
  * const { product } = await client.onetimeProducts.create({
- *   storeId: store.id,
+ *   storeId: store.id, // "STO_..."
  *   name: "E-Book",
  *   prices: { USD: { amount: 2900, taxCategory: "digital_goods" } },
  * });
+ * // => product.id = "PROD_..."
  *
  * // Create a checkout session
  * const session = await client.checkout.createSession({
@@ -1200,11 +1458,14 @@ declare class WebhooksResource {
  * });
  *
  * @example
- * // Use a custom public key for webhook verification
+ * // Per-environment webhook public keys
  * const client = new WaffoPancake({
  *   merchantId: "...",
  *   privateKey: "...",
- *   webhookPublicKey: myCustomPublicKeyPem,
+ *   webhookPublicKey: {
+ *     test: process.env.WAFFO_TEST_PUB_KEY!,
+ *     prod: process.env.WAFFO_PROD_PUB_KEY!,
+ *   },
  * });
  * const event = client.webhooks.verify(rawBody, signatureHeader);
  */
@@ -1245,8 +1506,12 @@ declare class WaffoPancakeError extends Error {
 /**
  * Verify and parse an incoming Waffo Pancake webhook event.
  *
- * Uses built-in Waffo public keys (RSA-SHA256) for signature verification.
- * Test and production environments use different key pairs; both are embedded in the SDK.
+ * Public key resolution (per environment):
+ * 1. `options.publicKey` — per-call override (highest priority, skips all other resolution)
+ * 2. `options.publicKeys[env]` or `options.publicKeys` (string) — config-level
+ * 3. `WAFFO_WEBHOOK_{TEST|PROD}_PUBLIC_KEY` environment variable
+ * 4. `WAFFO_WEBHOOK_PUBLIC_KEY` environment variable
+ * 5. Built-in hardcoded key
  *
  * Behavior:
  * - Parses the `X-Waffo-Signature` header (`t=<timestamp>,v1=<base64sig>`)
@@ -1295,4 +1560,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 ApiError, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type BillingDetail, BillingPeriod, type CancelSubscriptionParams, type CancelSubscriptionResult, CheckoutSessionProductType, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, PaymentStatus, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, RefundStatus, RefundTicketStatus, type RemoveMerchantParams, type RemoveMerchantResult, type SessionToken, type Store, StoreRole, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookSettings, verifyWebhook };
+export { type AddMerchantParams, type AddMerchantResult, type AnonymousCheckoutParams, type ApiError, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AuthenticatedCheckoutParams, type AuthenticatedCheckoutResult, type BillingDetail, BillingPeriod, type CancelSubscriptionParams, type CancelSubscriptionResult, CheckoutSessionProductType, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateStoreParams, type CreateSubscriptionProductGroupParams, type CreateSubscriptionProductParams, type DeleteStoreParams, type DeleteSubscriptionProductGroupParams, EntityStatus, Environment, ErrorLayer, type GraphQLParams, type GraphQLResponse, type GroupRules, type IssueSessionTokenParams, type MediaItem, MediaType, type NotificationSettings, OnetimeOrderStatus, type OnetimeProductDetail, PaymentStatus, type PriceInfo, type Prices, ProductVersionStatus, type PublishOnetimeProductParams, type PublishSubscriptionProductGroupParams, type PublishSubscriptionProductParams, RefundStatus, RefundTicketStatus, type RemoveMerchantParams, type RemoveMerchantResult, type SessionToken, type Store, StoreRole, SubscriptionOrderStatus, type SubscriptionProductDetail, type SubscriptionProductGroup, TaxCategory, type UpdateOnetimeProductParams, type UpdateOnetimeStatusParams, type UpdateRoleParams, type UpdateRoleResult, type UpdateStoreParams, type UpdateSubscriptionProductGroupParams, type UpdateSubscriptionProductParams, type UpdateSubscriptionStatusParams, type VerifyWebhookOptions, WaffoPancake, type WaffoPancakeConfig, WaffoPancakeError, type WebhookEvent, type WebhookEventData, WebhookEventType, type WebhookPublicKeys, type WebhookSettings, verifyWebhook };