@waffo/pancake-ts 0.1.7 → 0.2.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 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;
@@ -115,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
  *
@@ -128,8 +129,9 @@ declare enum SubscriptionOrderStatus {
     Pending = "pending",
     Active = "active",
     Canceling = "canceling",
-    Canceled = "canceled",
     PastDue = "past_due",
+    Closed = "closed",
+    Canceled = "canceled",
     Expired = "expired"
 }
 /**
@@ -185,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"
 }
 /**
@@ -289,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. */
@@ -342,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;
 }
@@ -368,7 +382,7 @@ interface PriceInfo {
  *
  * @example
  * {
- *   "USD": { amount: 999, taxCategory: "saas" },
+ *   "USD": { amount: "9.99", taxCategory: "saas" },
  *   "EUR": { amount: 899, taxCategory: "saas" }
  * }
  */
@@ -628,6 +642,190 @@ interface CheckoutSessionResult {
     /** Session expiration time (ISO 8601 UTC) */
     expiresAt: string;
 }
+/** Parameters for canceling a one-time order (buyer-side). */
+interface CancelOnetimeOrderParams {
+    /** Order ID */
+    orderId: string;
+}
+/** Result of canceling a one-time order. */
+interface CancelOnetimeOrderResult {
+    /** Order ID */
+    orderId: string;
+    /** Resulting status (`"canceled"`) */
+    status: string;
+}
+/** Parameters for reactivating a subscription (buyer-side). */
+interface ReactivateSubscriptionParams {
+    /** Subscription order ID */
+    orderId: string;
+}
+/** Result of reactivating a subscription. */
+interface ReactivateSubscriptionResult {
+    /** Order ID */
+    orderId: string;
+    /** Resulting status (`"active"`) */
+    status: string;
+}
+/** Requested refund amount. */
+interface RequestedAmount {
+    /** Refund amount in display format (e.g., `"29.00"`) */
+    amount: string;
+    /** Currency code (ISO 4217) */
+    currency: string;
+}
+/** Parameters for creating a refund ticket (buyer-side). */
+interface CreateRefundTicketParams {
+    /** Payment ID to refund */
+    paymentId: string;
+    /** Reason for the refund request */
+    reason: string;
+    /** Requested refund amount */
+    requestedAmount: RequestedAmount;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Parameters for resubmitting a rejected refund ticket (buyer-side). */
+interface ResubmitRefundTicketParams {
+    /** Existing ticket ID */
+    ticketId: string;
+    /** Payment ID */
+    paymentId: string;
+    /** Updated reason */
+    reason: string;
+    /** Updated requested amount */
+    requestedAmount: RequestedAmount;
+}
+/** Refund ticket entity returned from create/resubmit operations. */
+interface RefundTicket {
+    /** Ticket ID */
+    id: string;
+    /** Ticket type (e.g., `"refund"`) */
+    type: string;
+    /** Ticket status (e.g., `"pending"`, `"approved"`, `"rejected"`) */
+    status: string;
+    /** Associated payment ID */
+    subjectId: string;
+    /** Submitter identifier (email or merchant ID) */
+    submitterId: string;
+    /** Submitter type (e.g., `"customer"`, `"merchant"`) */
+    submitterType: string;
+    /** Current version ID */
+    currentVersionId: string;
+    /** Reviewer ID (null if not yet reviewed) */
+    reviewerId: string | null;
+    /** Review timestamp (ISO 8601, null if not yet reviewed) */
+    reviewedAt: string | null;
+    /** Reviewer's note */
+    reviewNote: string | null;
+    /** Rejection reason (null if approved or pending) */
+    rejectReason: string | null;
+    /** Execution timestamp (ISO 8601, null if not yet executed) */
+    executedAt: string | null;
+    /** Custom metadata */
+    metadata: Record<string, unknown>;
+    /** Current version number */
+    versionNumber: number;
+    /** Current version data (includes reason, amount, etc.) */
+    versionData: Record<string, unknown>;
+}
+/**
+ * Parameters for anonymous checkout.
+ *
+ * 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.
+ *
+ * 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 */
@@ -681,10 +879,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;
 }
 /**
@@ -697,8 +895,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" }
  * }
@@ -766,6 +964,9 @@ interface VerifyWebhookOptions {
 /**
  * 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 {
@@ -802,27 +1003,253 @@ 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. */
+/**
+ * Internal HTTP client for buyer-side requests using Bearer token authentication.
+ *
+ * Unlike {@link HttpClient} which signs requests with RSA-SHA256 (API Key auth),
+ * this client attaches a session token as `Authorization: Bearer <token>`.
+ *
+ * Not exported publicly — used internally by {@link BuyerSession}.
+ */
+declare class BuyerHttpClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly _fetch;
+    constructor(token: string, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
+    /**
+     * Send a Bearer-authenticated POST request and return the parsed `data` field.
+     *
+     * @param path - API path
+     * @param body - Request body object
+     * @returns Parsed `data` field from the response
+     * @throws {WaffoPancakeError} When the API returns errors
+     */
+    post<T>(path: string, body: object): Promise<T>;
+}
+
+/**
+ * Buyer session — lets authenticated buyers manage their own orders and subscriptions.
+ *
+ * Created via `client.buyer(token)` using a session token issued by
+ * `client.auth.issueSessionToken()`. All requests use Bearer token authentication.
+ *
+ * @example
+ * const { token } = await client.auth.issueSessionToken({
+ *   storeId: "STO_xxx",
+ *   buyerIdentity: "customer@example.com",
+ * });
+ * const buyer = client.buyer(token);
+ * await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+ */
+declare class BuyerSession {
+    private readonly http;
+    /** GraphQL query access scoped to the buyer's data. */
+    readonly graphql: BuyerGraphQL;
+    constructor(http: BuyerHttpClient);
+    /**
+     * Cancel a subscription order.
+     *
+     * @param params - Order to cancel
+     * @returns Order ID and resulting status
+     *
+     * @example
+     * const { orderId, status } = await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+     * // status: "canceled" (was pending) or "canceling" (was active)
+     */
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult>;
+    /**
+     * Cancel a one-time order (only while payment is still pending).
+     *
+     * @param params - Order to cancel
+     * @returns Order ID and resulting status
+     *
+     * @example
+     * const { orderId, status } = await buyer.cancelOnetimeOrder({ orderId: "ORD_xxx" });
+     */
+    cancelOnetimeOrder(params: CancelOnetimeOrderParams): Promise<CancelOnetimeOrderResult>;
+    /**
+     * Reactivate a subscription that is in `canceling` status.
+     *
+     * @param params - Order to reactivate
+     * @returns Order ID and resulting status
+     *
+     * @example
+     * const { orderId, status } = await buyer.reactivateSubscription({ orderId: "ORD_xxx" });
+     * // status: "active"
+     */
+    reactivateSubscription(params: ReactivateSubscriptionParams): Promise<ReactivateSubscriptionResult>;
+    /**
+     * Submit a refund request for a payment.
+     *
+     * @param params - Refund ticket details
+     * @returns Created refund ticket
+     *
+     * @example
+     * const { ticket } = await buyer.createRefundTicket({
+     *   paymentId: "PAY_xxx",
+     *   reason: "Product not as described",
+     *   requestedAmount: { amount: "29.00", currency: "USD" },
+     * });
+     */
+    createRefundTicket(params: CreateRefundTicketParams): Promise<{
+        ticket: RefundTicket;
+    }>;
+    /**
+     * Resubmit a previously rejected refund ticket with updated details.
+     *
+     * @param params - Updated ticket details
+     * @returns Updated refund ticket
+     *
+     * @example
+     * const { ticket } = await buyer.resubmitRefundTicket({
+     *   ticketId: "TKT_xxx",
+     *   paymentId: "PAY_xxx",
+     *   reason: "Updated reason with more detail",
+     *   requestedAmount: { amount: "29.00", currency: "USD" },
+     * });
+     */
+    resubmitRefundTicket(params: ResubmitRefundTicketParams): Promise<{
+        ticket: RefundTicket;
+    }>;
+}
+/**
+ * GraphQL access scoped to the buyer's session token.
+ */
+declare class BuyerGraphQL {
+    private readonly http;
+    constructor(http: BuyerHttpClient);
+    /**
+     * Execute a GraphQL query scoped to the buyer's data.
+     *
+     * @param params - GraphQL query and variables
+     * @returns GraphQL response
+     *
+     * @example
+     * const result = await buyer.graphql.query({
+     *   query: `query { orders { id status } }`,
+     * });
+     */
+    query<T = Record<string, unknown>>(params: GraphQLParams): Promise<GraphQLResponse<T>>;
+}
+
+/**
+ * Anonymous checkout — no buyer identity provided.
+ *
+ * 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` — no buyer 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 (no identity)
+ * const result = await client.checkout.anonymous.create({
+ *   storeId: "STO_xxx",
+ *   productId: "PROD_xxx",
+ *   productType: "onetime",
+ *   currency: "USD",
+ * });
+ *
+ * @example
+ * // Authenticated checkout (with buyer identity)
+ * 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 — no buyer identity, empty form. */
+    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",
@@ -851,7 +1278,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>>;
@@ -869,9 +1296,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<{
@@ -885,9 +1312,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<{
@@ -900,7 +1327,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;
@@ -913,7 +1340,7 @@ declare class OnetimeProductsResource {
      *
      * @example
      * const { product } = await client.onetimeProducts.updateStatus({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   status: ProductVersionStatus.Inactive,
      * });
      */
@@ -937,7 +1364,7 @@ declare class OrdersResource {
      *
      * @example
      * const { orderId, status } = await client.orders.cancelSubscription({
-     *   orderId: "order_xxx",
+     *   orderId: "ORD_xxx",
      * });
      * // status: "canceled" or "canceling"
      */
@@ -956,7 +1383,7 @@ declare class StoreMerchantsResource {
      *
      * @example
      * const result = await client.storeMerchants.add({
-     *   storeId: "store_xxx",
+     *   storeId: "STO_xxx",
      *   email: "member@example.com",
      *   role: "admin",
      * });
@@ -970,8 +1397,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>;
@@ -983,8 +1410,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",
      * });
      */
@@ -1015,7 +1442,7 @@ declare class StoresResource {
      *
      * @example
      * const { store } = await client.stores.update({
-     *   id: "store_xxx",
+     *   id: "STO_xxx",
      *   name: "Updated Name",
      * });
      */
@@ -1029,7 +1456,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;
@@ -1048,10 +1475,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<{
@@ -1065,8 +1492,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<{
@@ -1079,7 +1506,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;
@@ -1091,7 +1518,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;
@@ -1110,10 +1537,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<{
@@ -1127,10 +1554,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<{
@@ -1143,7 +1570,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;
@@ -1156,7 +1583,7 @@ declare class SubscriptionProductsResource {
      *
      * @example
      * const { product } = await client.subscriptionProducts.updateStatus({
-     *   id: "prod_xxx",
+     *   id: "PROD_xxx",
      *   status: ProductVersionStatus.Active,
      * });
      */
@@ -1215,19 +1642,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" } },
+ *   prices: { USD: { amount: "29.00", taxCategory: "digital_goods" } },
  * });
+ * // => product.id = "PROD_..."
  *
  * // Create a checkout session
  * const session = await client.checkout.createSession({
@@ -1257,6 +1686,7 @@ declare class WebhooksResource {
  */
 declare class WaffoPancake {
     private readonly http;
+    private readonly config;
     readonly auth: AuthResource;
     readonly stores: StoresResource;
     readonly storeMerchants: StoreMerchantsResource;
@@ -1268,6 +1698,25 @@ declare class WaffoPancake {
     readonly graphql: GraphQLResource;
     readonly webhooks: WebhooksResource;
     constructor(config: WaffoPancakeConfig);
+    /**
+     * Create a buyer session for self-service operations.
+     *
+     * The returned session uses Bearer token authentication and provides
+     * methods for order cancellation, subscription management, refund tickets,
+     * and scoped GraphQL queries.
+     *
+     * @param token - Session token from `client.auth.issueSessionToken()`
+     * @returns A buyer session with self-service methods
+     *
+     * @example
+     * const { token } = await client.auth.issueSessionToken({
+     *   storeId: "STO_xxx",
+     *   buyerIdentity: "customer@example.com",
+     * });
+     * const buyer = client.buyer(token);
+     * await buyer.cancelSubscription({ orderId: "ORD_xxx" });
+     */
+    buyer(token: string): BuyerSession;
 }
 
 /**
@@ -1346,4 +1795,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 WebhookPublicKeys, 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 CancelOnetimeOrderParams, type CancelOnetimeOrderResult, type CancelSubscriptionParams, type CancelSubscriptionResult, CheckoutSessionProductType, type CheckoutSessionResult, type CheckoutSettings, type CheckoutThemeSettings, type CreateCheckoutSessionParams, type CreateOnetimeProductParams, type CreateRefundTicketParams, 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, type ReactivateSubscriptionParams, type ReactivateSubscriptionResult, RefundStatus, type RefundTicket, RefundTicketStatus, type RemoveMerchantParams, type RemoveMerchantResult, type RequestedAmount, type ResubmitRefundTicketParams, 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 };