@waffo/pancake-ts 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -225,7 +225,7 @@ declare enum ErrorLayer {
     Sdk = "sdk"
 }
 /**
- * Parameters for issuing a buyer session token.
+ * Parameters for issuing a customer session token.
  *
  * Provide either `storeId` or `productId` (at least one required).
  * When `productId` is given without `storeId`, the server derives the store from the product.
@@ -234,7 +234,7 @@ declare enum ErrorLayer {
  */
 interface IssueSessionTokenParams {
     /**
-     * Buyer identity — encoded into the JWT payload for merchant-side buyer
+     * Customer identity — encoded into the JWT payload for merchant-side customer
      * identification. Accepts an email or any merchant-provided identifier string.
      * To pre-fill the checkout page's email field, use `buyerEmail` on
      * `checkout.authenticated.create`.
@@ -697,7 +697,7 @@ interface CancelSubscriptionResult {
     status: `${SubscriptionOrderStatus}`;
 }
 /**
- * Buyer billing details for checkout.
+ * Customer billing details for checkout.
  * @see waffo-pancake-order-service/app/lib/types.ts
  */
 interface BillingDetail {
@@ -727,7 +727,7 @@ interface CreateCheckoutSessionParams {
     priceSnapshot?: PriceInfo;
     /** Trial toggle override (subscription only) */
     withTrial?: boolean;
-    /** Pre-filled buyer email */
+    /** Pre-filled customer email */
     buyerEmail?: string;
     /** Pre-filled billing details */
     billingDetail?: BillingDetail;
@@ -751,7 +751,7 @@ interface CheckoutSessionResult {
     /** Session expiration time (ISO 8601 UTC) */
     expiresAt: string;
 }
-/** Parameters for canceling a one-time order (buyer-side). */
+/** Parameters for canceling a one-time order (customer-side). */
 interface CancelOnetimeOrderParams {
     /** Order ID */
     orderId: string;
@@ -763,7 +763,7 @@ interface CancelOnetimeOrderResult {
     /** Resulting status (`"canceled"`) */
     status: string;
 }
-/** Parameters for reactivating a subscription (buyer-side). */
+/** Parameters for reactivating a subscription (customer-side). */
 interface ReactivateSubscriptionParams {
     /** Subscription order ID */
     orderId: string;
@@ -787,12 +787,12 @@ interface RequestedAmount {
  * multiple times; this is the shape of a single submission.
  */
 interface RefundTicketVersionData {
-    /** Refund reason supplied by the buyer */
+    /** Refund reason supplied by the customer */
     reason: string;
     /** Requested refund amount; `null` if the version has no amount recorded */
     requestedAmount: RequestedAmount | null;
 }
-/** Parameters for creating a refund ticket (buyer-side). */
+/** Parameters for creating a refund ticket (customer-side). */
 interface CreateRefundTicketParams {
     /** Payment ID to refund */
     paymentId: string;
@@ -805,7 +805,7 @@ interface CreateRefundTicketParams {
     /** Refund-ticket business-side identifier (max 128 chars); inherited by the executed refund on PSP success */
     refundTicketMerchantExternalId?: string;
 }
-/** Parameters for resubmitting a rejected refund ticket (buyer-side). */
+/** Parameters for resubmitting a rejected refund ticket (customer-side). */
 interface ResubmitRefundTicketParams {
     /** Existing ticket ID */
     ticketId: string;
@@ -858,7 +858,7 @@ interface RefundTicket {
 /**
  * Parameters for anonymous checkout.
  *
- * The buyer reaches the checkout page without a session token. Merchants may still
+ * The customer reaches the checkout page without a session token. Merchants may still
  * pre-fill `buyerEmail` and `billingDetail`; omitting them leaves the form blank.
  *
  * Accepts every field of {@link CreateCheckoutSessionParams} — this wrapper simply
@@ -884,15 +884,15 @@ type AnonymousCheckoutParams = CreateCheckoutSessionParams;
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
- *   buyerIdentity: "user-123",            // merchant-side buyer id (goes into JWT)
+ *   buyerIdentity: "user-123",            // merchant-side customer id (goes into JWT)
  *   buyerEmail: "customer@example.com",   // pre-filled on the checkout page
  * });
  * // Redirect to result.checkoutUrl (includes #token=...)
  */
 interface AuthenticatedCheckoutParams extends CreateCheckoutSessionParams {
     /**
-     * Buyer identity — sent to `issue-session-token` and encoded into the JWT
-     * payload for merchant-side buyer identification. Accepts an email or any
+     * Customer identity — sent to `issue-session-token` and encoded into the JWT
+     * payload for merchant-side customer identification. Accepts an email or any
      * merchant-provided identifier string. Use `buyerEmail` to pre-fill the
      * checkout page's email input.
      */
@@ -953,9 +953,9 @@ declare enum WebhookEventType {
     SubscriptionActivated = "subscription.activated",
     /** Subscription renewal payment succeeded */
     SubscriptionPaymentSucceeded = "subscription.payment_succeeded",
-    /** Buyer initiated cancellation (expires at end of current period) */
+    /** Customer initiated cancellation (expires at end of current period) */
     SubscriptionCanceling = "subscription.canceling",
-    /** Buyer withdrew cancellation (subscription restored) */
+    /** Customer withdrew cancellation (subscription restored) */
     SubscriptionUncanceled = "subscription.uncanceled",
     /** Subscription product changed (upgrade/downgrade) */
     SubscriptionUpdated = "subscription.updated",
@@ -977,7 +977,7 @@ interface WebhookEventData {
     /** Order status (e.g., "completed", "active", "canceling") */
     orderStatus?: string;
     buyerEmail: string;
-    /** Merchant-provided buyer identity from checkout session */
+    /** Merchant-provided customer identity from checkout session */
     merchantProvidedBuyerIdentity?: string;
     /** Order business identifier; present on order/payment + refund events (inherited from order) */
     orderMerchantExternalId?: string;
@@ -1152,12 +1152,12 @@ declare class HttpClient {
     post<T>(path: string, body: object, options?: PostOptions): Promise<PostResult<T>>;
 }
 
-/** Authentication resource — issue session tokens for buyers. */
+/** Authentication resource — issue session tokens for customers. */
 declare class AuthResource {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Issue a session token for a buyer.
+     * Issue a session token for a customer.
      *
      * @param params - Token issuance parameters
      * @returns Issued session token with expiration
@@ -1182,147 +1182,9 @@ declare class AuthResource {
 }
 
 /**
- * Internal HTTP client for buyer-side requests using Bearer token authentication.
+ * Anonymous checkout — no customer identity provided.
  *
- * Unlike {@link HttpClient} which signs requests with RSA-SHA256 (API Key auth),
- * this client attaches a session token as `Authorization: Bearer <token>` and
- * never sends an idempotency key (buyer session actions are not protected by
- * gateway idempotency in the current architecture).
- *
- * 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 and return the full envelope plus HTTP status.
-     *
-     * 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.
-     */
-    post<T>(path: string, body: object): Promise<PostResult<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 & {
-        warnings?: Notice[];
-    }>;
-    /**
-     * 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 & {
-        warnings?: Notice[];
-    }>;
-    /**
-     * 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 & {
-        warnings?: Notice[];
-    }>;
-    /**
-     * 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" },
-     *   refundTicketMerchantExternalId: "REF-2026-00891",
-     * });
-     */
-    createRefundTicket(params: CreateRefundTicketParams): Promise<{
-        ticket: RefundTicket;
-        warnings?: Notice[];
-    }>;
-    /**
-     * 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;
-        warnings?: Notice[];
-    }>;
-}
-/**
- * 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 reaches the checkout page without a session token. Merchants may still
+ * The customer reaches the checkout page without a session token. Merchants may still
  * pre-fill `buyerEmail` and `billingDetail` on the page by passing them here.
  * Internally creates a checkout session and returns the redirect URL.
  */
@@ -1332,11 +1194,11 @@ declare class CheckoutAnonymousResource {
     /**
      * Create an anonymous checkout session.
      *
-     * @param params - Checkout parameters (no buyer identity required)
+     * @param params - Checkout parameters (no customer identity required)
      * @returns Session ID, checkout URL, and expiration
      *
      * @example
-     * // Minimal — buyer fills everything on the page
+     * // Minimal — customer fills everything on the page
      * const result = await client.checkout.anonymous.create({
      *   productId: "PROD_xxx",
      *   currency: "USD",
@@ -1358,11 +1220,11 @@ declare class CheckoutAnonymousResource {
 }
 
 /**
- * Authenticated checkout — merchant provides buyer identity.
+ * Authenticated checkout — merchant provides customer 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.
+ * The checkout page reads the fragment to pre-fill customer information.
  */
 declare class CheckoutAuthenticatedResource {
     private readonly http;
@@ -1378,7 +1240,7 @@ declare class CheckoutAuthenticatedResource {
      * `buyerIdentity` and `buyerEmail` are independent inputs: identity is for the JWT,
      * email is for pre-filling the checkout page. The SDK forwards each to its own endpoint.
      *
-     * @param params - Checkout parameters including buyer identity
+     * @param params - Checkout parameters including customer identity
      * @returns Session details with token-appended checkout URL
      *
      * @example
@@ -1400,8 +1262,8 @@ declare class CheckoutAuthenticatedResource {
  * 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
+ * - `anonymous` — no customer identity, empty form
+ * - `authenticated` — merchant provides customer identity, pre-filled form + token
  *
  * The low-level `createSession()` method is still available for full control.
  *
@@ -1413,7 +1275,7 @@ declare class CheckoutAuthenticatedResource {
  * });
  *
  * @example
- * // Authenticated checkout (with buyer identity)
+ * // Authenticated checkout (with customer identity)
  * const result = await client.checkout.authenticated.create({
  *   productId: "PROD_xxx",
  *   currency: "USD",
@@ -1424,9 +1286,9 @@ declare class CheckoutAuthenticatedResource {
  */
 declare class CheckoutResource {
     private readonly http;
-    /** Anonymous checkout — no buyer identity, empty form. */
+    /** Anonymous checkout — no customer identity, empty form. */
     readonly anonymous: CheckoutAnonymousResource;
-    /** Authenticated checkout — merchant provides buyer identity. */
+    /** Authenticated checkout — merchant provides customer identity. */
     readonly authenticated: CheckoutAuthenticatedResource;
     constructor(http: HttpClient);
     /**
@@ -1451,6 +1313,144 @@ declare class CheckoutResource {
     }>;
 }
 
+/**
+ * Internal HTTP client for customer-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>` and
+ * never sends an idempotency key (customer session actions are not protected by
+ * gateway idempotency in the current architecture).
+ *
+ * Not exported publicly — used internally by {@link CustomerSession}.
+ */
+declare class CustomerHttpClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly _fetch;
+    constructor(token: string, config: Pick<WaffoPancakeConfig, "baseUrl" | "fetch">);
+    /**
+     * Send a Bearer-authenticated POST and return the full envelope plus HTTP status.
+     *
+     * 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.
+     */
+    post<T>(path: string, body: object): Promise<PostResult<T>>;
+}
+
+/**
+ * Customer session — lets authenticated customers manage their own orders and subscriptions.
+ *
+ * Created via `client.customer(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 customer = client.customer(token);
+ * await customer.cancelSubscription({ orderId: "ORD_xxx" });
+ */
+declare class CustomerSession {
+    private readonly http;
+    /** GraphQL query access scoped to the customer's data. */
+    readonly graphql: CustomerGraphQL;
+    constructor(http: CustomerHttpClient);
+    /**
+     * Cancel a subscription order.
+     *
+     * @param params - Order to cancel
+     * @returns Order ID and resulting status
+     *
+     * @example
+     * const { orderId, status } = await customer.cancelSubscription({ orderId: "ORD_xxx" });
+     * // status: "canceled" (was pending) or "canceling" (was active)
+     */
+    cancelSubscription(params: CancelSubscriptionParams): Promise<CancelSubscriptionResult & {
+        warnings?: Notice[];
+    }>;
+    /**
+     * 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 customer.cancelOnetimeOrder({ orderId: "ORD_xxx" });
+     */
+    cancelOnetimeOrder(params: CancelOnetimeOrderParams): Promise<CancelOnetimeOrderResult & {
+        warnings?: Notice[];
+    }>;
+    /**
+     * Reactivate a subscription that is in `canceling` status.
+     *
+     * @param params - Order to reactivate
+     * @returns Order ID and resulting status
+     *
+     * @example
+     * const { orderId, status } = await customer.reactivateSubscription({ orderId: "ORD_xxx" });
+     * // status: "active"
+     */
+    reactivateSubscription(params: ReactivateSubscriptionParams): Promise<ReactivateSubscriptionResult & {
+        warnings?: Notice[];
+    }>;
+    /**
+     * Submit a refund request for a payment.
+     *
+     * @param params - Refund ticket details
+     * @returns Created refund ticket
+     *
+     * @example
+     * const { ticket } = await customer.createRefundTicket({
+     *   paymentId: "PAY_xxx",
+     *   reason: "Product not as described",
+     *   requestedAmount: { amount: "29.00", currency: "USD" },
+     *   refundTicketMerchantExternalId: "REF-2026-00891",
+     * });
+     */
+    createRefundTicket(params: CreateRefundTicketParams): Promise<{
+        ticket: RefundTicket;
+        warnings?: Notice[];
+    }>;
+    /**
+     * Resubmit a previously rejected refund ticket with updated details.
+     *
+     * @param params - Updated ticket details
+     * @returns Updated refund ticket
+     *
+     * @example
+     * const { ticket } = await customer.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;
+        warnings?: Notice[];
+    }>;
+}
+/**
+ * GraphQL access scoped to the customer's session token.
+ */
+declare class CustomerGraphQL {
+    private readonly http;
+    constructor(http: CustomerHttpClient);
+    /**
+     * Execute a GraphQL query scoped to the customer's data.
+     *
+     * @param params - GraphQL query and variables
+     * @returns GraphQL response
+     *
+     * @example
+     * const result = await customer.graphql.query({
+     *   query: `query { orders { id status } }`,
+     * });
+     */
+    query<T = Record<string, unknown>>(params: GraphQLParams): Promise<GraphQLResponse<T>>;
+}
+
 /** GraphQL query resource (Query only, no Mutations). */
 declare class GraphQLResource {
     private readonly http;
@@ -2026,24 +2026,38 @@ declare class WaffoPancake {
     readonly webhooks: WebhooksResource;
     constructor(config: WaffoPancakeConfig);
     /**
-     * Create a buyer session for self-service operations.
+     * Create a customer 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
+     * @returns A customer 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" });
+     * const customer = client.customer(token);
+     * await customer.cancelSubscription({ orderId: "ORD_xxx" });
+     */
+    customer(token: string): CustomerSession;
+    /**
+     * Create a customer session for self-service operations.
+     *
+     * @param token - Session token from `client.auth.issueSessionToken()`
+     * @returns A customer session with self-service methods
+     *
+     * @example
+     * ```typescript
+     * const session = client.buyer(token); // prefer client.customer(token)
+     * ```
+     *
+     * @deprecated Use {@link WaffoPancake.customer} instead.
      */
-    buyer(token: string): BuyerSession;
+    buyer(token: string): CustomerSession;
 }
 
 /**