@waffo/pancake-ts 0.1.9 → 0.2.1

package/dist/index.d.cts

@@ -150,11 +150,14 @@ declare enum PaymentStatus {
  */
 declare enum RefundTicketStatus {
     Pending = "pending",
+    UnderReview = "under_review",
     Approved = "approved",
     Rejected = "rejected",
+    Returned = "returned",
     Processing = "processing",
     Succeeded = "succeeded",
-    Failed = "failed"
+    Failed = "failed",
+    Cancelled = "cancelled"
 }
 /**
  * Refund status.
@@ -191,7 +194,9 @@ declare enum ErrorLayer {
     GraphQL = "graphql",
     Resource = "resource",
     /** SDK-specific layer for email delivery errors (not part of the service-side error layers). */
-    Email = "email"
+    Email = "email",
+    /** SDK-side input validation (caught before network request). */
+    Sdk = "sdk"
 }
 /**
  * Parameters for issuing a buyer session token.
@@ -367,7 +372,7 @@ interface UpdateRoleResult {
  *
  * @example
  * // JPY ¥1000
- * { amount: 1000, taxCategory: "software" }
+ * { amount: "1000", taxCategory: "software" }
  */
 interface PriceInfo {
     /** Price amount as display string (e.g., "9.99" for USD, "1000" for JPY) */
@@ -383,7 +388,7 @@ interface PriceInfo {
  * @example
  * {
  *   "USD": { amount: "9.99", taxCategory: "saas" },
- *   "EUR": { amount: 899, taxCategory: "saas" }
+ *   "EUR": { amount: "8.99", taxCategory: "saas" }
  * }
  */
 type Prices = Record<string, PriceInfo>;
@@ -642,8 +647,98 @@ 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 | null;
+    /** 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 | null;
+    /** Current version data (includes reason, amount, etc.) */
+    versionData: Record<string, unknown> | null;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last update timestamp (ISO 8601) */
+    updatedAt: string;
+}
 /**
- * Parameters for anonymous checkout (visitor → shopper).
+ * 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.
@@ -680,7 +775,7 @@ interface AnonymousCheckoutParams {
     metadata?: Record<string, string>;
 }
 /**
- * Parameters for authenticated checkout (customer).
+ * 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.
@@ -812,7 +907,7 @@ interface WebhookEventData {
  *   eventId: "PAY_5xK9mRtYvWnPqLsJ3hBfDe",
  *   storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  *   mode: "prod",
- *   data: { orderId: "...", buyerEmail: "...", currency: "USD", amount: 2900, taxAmount: 290, productName: "Pro Plan" }
+ *   data: { orderId: "...", buyerEmail: "...", currency: "USD", amount: "29.00", taxAmount: "2.90", productName: "Pro Plan" }
  * }
  */
 interface WebhookEvent<T = WebhookEventData> {
@@ -925,7 +1020,136 @@ declare class AuthResource {
 }
 
 /**
- * Anonymous checkout — visitor enters without a session token.
+ * 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.
@@ -990,13 +1214,13 @@ declare class CheckoutAuthenticatedResource {
  * 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)
+ * - `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 (visitor → shopper)
+ * // Anonymous checkout (no identity)
  * const result = await client.checkout.anonymous.create({
  *   storeId: "STO_xxx",
  *   productId: "PROD_xxx",
@@ -1005,7 +1229,7 @@ declare class CheckoutAuthenticatedResource {
  * });
  *
  * @example
- * // Authenticated checkout (customer)
+ * // Authenticated checkout (with buyer identity)
  * const result = await client.checkout.authenticated.create({
  *   storeId: "STO_xxx",
  *   productId: "PROD_xxx",
@@ -1017,7 +1241,7 @@ declare class CheckoutAuthenticatedResource {
  */
 declare class CheckoutResource {
     private readonly http;
-    /** Anonymous checkout — visitor enters without a session token. */
+    /** Anonymous checkout — no buyer identity, empty form. */
     readonly anonymous: CheckoutAnonymousResource;
     /** Authenticated checkout — merchant provides buyer identity. */
     readonly authenticated: CheckoutAuthenticatedResource;
@@ -1439,7 +1663,7 @@ declare class WebhooksResource {
  * const { product } = await client.onetimeProducts.create({
  *   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_..."
  *
@@ -1471,6 +1695,7 @@ declare class WebhooksResource {
  */
 declare class WaffoPancake {
     private readonly http;
+    private readonly config;
     readonly auth: AuthResource;
     readonly stores: StoresResource;
     readonly storeMerchants: StoreMerchantsResource;
@@ -1482,6 +1707,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;
 }
 
 /**
@@ -1560,4 +1804,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 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 };
+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 };