@waffo/pancake-nextjs 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,560 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { AnonymousCheckoutParams, AuthenticatedCheckoutParams, CheckoutSessionResult, AuthenticatedCheckoutResult, IssueSessionTokenParams, SessionToken, GraphQLParams, GraphQLResponse, CancelSubscriptionParams, CancelSubscriptionResult, CancelOnetimeOrderParams, CancelOnetimeOrderResult, ReactivateSubscriptionParams, ReactivateSubscriptionResult, CreateRefundTicketParams, RefundTicket, ResubmitRefundTicketParams, VerifyWebhookOptions, WebhookEventData, WebhookEvent } from '@waffo/pancake-ts';
+export { BillingDetail, PriceInfo, TaxCategory, WaffoPancakeError, WebhookEvent, WebhookEventData, WebhookEventType } from '@waffo/pancake-ts';
+
+/** Parameters for the checkout server action */
+type CheckoutActionParams = ({
+    type?: "anonymous";
+} & AnonymousCheckoutParams) | ({
+    type: "authenticated";
+} & AuthenticatedCheckoutParams);
+/** Result of the checkout server action */
+type CheckoutActionResult = CheckoutSessionResult | AuthenticatedCheckoutResult;
+/** Server action signature for checkout */
+type CheckoutAction = (params: CheckoutActionParams) => Promise<CheckoutActionResult>;
+/** Server action signature for issuing buyer tokens */
+type BuyerTokenAction = (params: IssueSessionTokenParams) => Promise<SessionToken>;
+/** Buyer action types */
+type BuyerSessionActionType = "cancelSubscription" | "cancelOnetimeOrder" | "reactivateSubscription" | "createRefundTicket" | "resubmitRefundTicket" | "query";
+/** Server action signature for buyer session operations */
+type BuyerSessionAction = (token: string, actionType: BuyerSessionActionType, params: unknown) => Promise<unknown>;
+/** Server action signature for merchant GraphQL queries */
+type MerchantQueryAction = (params: GraphQLParams) => Promise<GraphQLResponse>;
+
+/** Buyer configuration for automatic token management */
+interface BuyerConfig {
+    /** Buyer identity (email or merchant-provided identifier) */
+    identity: string;
+    /** Store ID (optional when `productId` is provided) */
+    storeId?: string;
+    /** Product ID — used to derive the store when `storeId` is omitted */
+    productId?: string;
+    /** Server action for issuing tokens — from `createBuyerTokenAction()` */
+    issueToken: BuyerTokenAction;
+    /** Server action for buyer operations — from `createBuyerSessionAction()` */
+    sessionAction: BuyerSessionAction;
+}
+interface WaffoPancakeProviderProps {
+    /** Buyer configuration for automatic token management */
+    buyer: BuyerConfig;
+    children: React.ReactNode;
+}
+/**
+ * Provider that manages buyer token lifecycle via server actions.
+ *
+ * Auto-issues session tokens on mount and refreshes before expiry.
+ * All buyer hooks (`useBuyer`, `useBuyerOrders`, etc.) read from context.
+ *
+ * The private key never leaves the server — token issuance and buyer
+ * operations are delegated to server actions.
+ *
+ * @param props - Provider configuration
+ * @param props.buyer - Buyer identity and server actions
+ * @param props.children - React children
+ *
+ * @example
+ * ```tsx
+ * <WaffoPancakeProvider buyer={{
+ *   identity: user.email,
+ *   storeId: "STO_xxx",
+ *   issueToken,       // from createBuyerTokenAction()
+ *   sessionAction,    // from createBuyerSessionAction()
+ * }}>
+ *   <App />
+ * </WaffoPancakeProvider>
+ * ```
+ */
+declare function WaffoPancakeProvider({ buyer, children }: WaffoPancakeProviderProps): react_jsx_runtime.JSX.Element;
+
+/** Redirect mode for checkout navigation */
+type CheckoutMode = "redirect" | "popup";
+/** Base checkout options shared by all checkout types */
+interface CheckoutBaseOptions {
+    /** How to navigate to checkout page. Default: `"redirect"` */
+    mode?: CheckoutMode;
+    /**
+     * Loading page URL shown in popup while checkout session is being created.
+     * Only used when `mode` is `"popup"`. Defaults to a minimal inline loading page.
+     */
+    popupLoadingUrl?: string;
+    /** Callback fired on error */
+    onError?: (error: Error) => void;
+}
+/** Link checkout — redirects to product page URL, no API call needed */
+interface LinkCheckoutProps extends CheckoutBaseOptions {
+    type: "link";
+    /** Store slug (from Dashboard) */
+    storeSlug: string;
+    /** Product ID */
+    productId: string;
+    /** Currency code (ISO 4217). If omitted, product page auto-detects. */
+    currency?: string;
+    /** Pre-fill buyer email */
+    email?: string;
+    /** Redirect URL after successful payment */
+    successUrl?: string;
+    /** Use test environment */
+    test?: boolean;
+    /** Pre-fill billing country (ISO 3166-1) */
+    country?: string;
+    /** Is business purchase */
+    isBusiness?: boolean;
+    /**
+     * Base URL of the storefront. Default: `"https://pancake.waffo.ai"`
+     */
+    baseUrl?: string;
+}
+/** Anonymous checkout — creates session via server action */
+type AnonymousCheckoutProps = CheckoutBaseOptions & {
+    type?: "anonymous";
+    /** Server action created by `createCheckoutAction()` */
+    action: CheckoutAction;
+    /** Callback fired when checkout session is successfully created */
+    onSuccess?: (result: CheckoutSessionResult) => void;
+} & AnonymousCheckoutParams;
+/** Authenticated checkout — creates session + token via server action */
+type AuthenticatedCheckoutProps = CheckoutBaseOptions & {
+    type: "authenticated";
+    /** Server action created by `createCheckoutAction()` */
+    action: CheckoutAction;
+    /** Callback fired when checkout session is successfully created */
+    onSuccess?: (result: AuthenticatedCheckoutResult) => void;
+} & AuthenticatedCheckoutParams;
+/** Union of all checkout prop types */
+type CheckoutProps = LinkCheckoutProps | AnonymousCheckoutProps | AuthenticatedCheckoutProps;
+/** Return type of useCheckout hook */
+interface UseCheckoutReturn {
+    /** Trigger the checkout flow */
+    checkout: () => void;
+    /** Whether a checkout session is being created */
+    isLoading: boolean;
+    /** Error from the last checkout attempt, if any */
+    error: Error | null;
+}
+
+type CheckoutButtonBaseProps = {
+    /** Button content */
+    children: React.ReactNode;
+    /** Content shown while checkout session is being created */
+    loadingChildren?: React.ReactNode;
+    /** Additional class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: React.CSSProperties;
+    /** Disabled state (merged with isLoading) */
+    disabled?: boolean;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "disabled" | "children">;
+/** Props for CheckoutButton — link mode */
+type LinkCheckoutButtonProps = CheckoutButtonBaseProps & LinkCheckoutProps;
+/** Props for CheckoutButton — anonymous mode */
+type AnonymousCheckoutButtonProps = CheckoutButtonBaseProps & AnonymousCheckoutProps;
+/** Props for CheckoutButton — authenticated mode */
+type AuthenticatedCheckoutButtonProps = CheckoutButtonBaseProps & AuthenticatedCheckoutProps;
+type CheckoutButtonProps = LinkCheckoutButtonProps | AnonymousCheckoutButtonProps | AuthenticatedCheckoutButtonProps;
+/**
+ * A button that triggers a Waffo Pancake checkout flow on click.
+ *
+ * Three checkout types:
+ * - **link**: Instant redirect to product page URL (no server action needed)
+ * - **anonymous**: Calls server action to create session, then redirects
+ * - **authenticated**: Calls server action to create session + token, then redirects
+ *
+ * The private key never leaves the server — anonymous and authenticated modes
+ * use a server action created by `createCheckoutAction()`.
+ *
+ * @param props - Flattened checkout props, button content, and optional styling
+ *
+ * @example
+ * ```tsx
+ * // Link checkout — no server action needed
+ * <CheckoutButton type="link" storeSlug="my-store" productId="PROD_xxx" currency="USD">
+ *   Buy Now
+ * </CheckoutButton>
+ *
+ * // Anonymous checkout — via server action
+ * <CheckoutButton action={checkout} productId="PROD_xxx" currency="USD">
+ *   Buy Now
+ * </CheckoutButton>
+ *
+ * // Authenticated checkout — via server action
+ * <CheckoutButton action={checkout} type="authenticated" productId="PROD_xxx" currency="USD" buyerIdentity="user@example.com">
+ *   Buy Now
+ * </CheckoutButton>
+ * ```
+ */
+declare function CheckoutButton(props: CheckoutButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React hook for triggering a Waffo Pancake checkout flow.
+ *
+ * Supports three checkout types:
+ * - **link**: Builds a product page URL and navigates directly (no API call, synchronous)
+ * - **anonymous**: Calls a server action to create a checkout session, then navigates
+ * - **authenticated**: Calls a server action to create a session + token, then navigates
+ *
+ * The private key never leaves the server — anonymous and authenticated modes
+ * use a server action created by `createCheckoutAction()`.
+ *
+ * @param args - Flattened checkout props
+ * @returns `{ checkout, isLoading, error }`
+ *
+ * @example
+ * ```tsx
+ * // Link checkout — no server action needed
+ * const { checkout } = useCheckout({
+ *   type: "link",
+ *   storeSlug: "my-store",
+ *   productId: "PROD_xxx",
+ *   currency: "USD",
+ * });
+ *
+ * // Anonymous checkout — via server action
+ * const { checkout, isLoading } = useCheckout({
+ *   action: checkout, // from createCheckoutAction()
+ *   productId: "PROD_xxx",
+ *   currency: "USD",
+ * });
+ * ```
+ */
+declare function useCheckout(args: CheckoutProps): UseCheckoutReturn;
+
+/** State of an async buyer action */
+interface BuyerActionState<T = unknown> {
+    /** Execute the action */
+    execute: (params: T) => Promise<void>;
+    /** Whether the action is in progress */
+    isLoading: boolean;
+    /** Error from the last attempt */
+    error: Error | null;
+}
+/** Return type of useBuyer hook */
+interface UseBuyerReturn {
+    /** Cancel a subscription order */
+    cancelSubscription: BuyerActionState<CancelSubscriptionParams> & {
+        data: CancelSubscriptionResult | null;
+    };
+    /** Cancel a one-time order */
+    cancelOnetimeOrder: BuyerActionState<CancelOnetimeOrderParams> & {
+        data: CancelOnetimeOrderResult | null;
+    };
+    /** Reactivate a canceling subscription */
+    reactivateSubscription: BuyerActionState<ReactivateSubscriptionParams> & {
+        data: ReactivateSubscriptionResult | null;
+    };
+    /** Create a refund ticket */
+    createRefundTicket: BuyerActionState<CreateRefundTicketParams> & {
+        data: RefundTicket | null;
+    };
+    /** Resubmit a rejected refund ticket */
+    resubmitRefundTicket: BuyerActionState<ResubmitRefundTicketParams> & {
+        data: RefundTicket | null;
+    };
+    /** Execute a GraphQL query */
+    query: <T = Record<string, unknown>>(params: GraphQLParams) => Promise<GraphQLResponse<T>>;
+}
+/**
+ * React hook for buyer self-service actions.
+ *
+ * Must be used within `<WaffoPancakeProvider>`. All operations are executed
+ * via server actions — the private key never leaves the server.
+ *
+ * @returns Buyer action handlers with loading/error states
+ *
+ * @example
+ * ```tsx
+ * function AccountPage() {
+ *   const buyer = useBuyer();
+ *   return (
+ *     <button onClick={() => buyer.cancelSubscription.execute({ orderId: "ORD_xxx" })}>
+ *       Cancel
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useBuyer(): UseBuyerReturn;
+
+/** Query state with typed data */
+interface QueryState<T> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+
+/** A buyer's one-time order */
+interface BuyerOnetimeOrder {
+    id: string;
+    status: string;
+    currency: string;
+    buyerEmail: string;
+    product: {
+        id: string;
+        name: string;
+    } | null;
+    payments: Array<{
+        id: string;
+        status: string;
+        snapshotDisplayAmount: string;
+        snapshotDisplayCurrency: string;
+        createdAt: string;
+    }>;
+    createdAt: string;
+}
+/** A buyer's subscription order */
+interface BuyerSubscriptionOrder {
+    id: string;
+    status: string;
+    currency: string;
+    buyerEmail: string;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    cancelAt: string | null;
+    product: {
+        id: string;
+        name: string;
+        billingPeriod: string;
+    } | null;
+    payments: Array<{
+        id: string;
+        status: string;
+        snapshotDisplayAmount: string;
+        snapshotDisplayCurrency: string;
+        createdAt: string;
+    }>;
+    createdAt: string;
+}
+/** A buyer's payment record */
+interface BuyerPayment {
+    id: string;
+    orderId: string;
+    status: string;
+    snapshotDisplayAmount: string;
+    snapshotDisplayCurrency: string;
+    failureReason: string | null;
+    createdAt: string;
+}
+/** A buyer's refund ticket */
+interface BuyerRefundTicket {
+    id: string;
+    status: string;
+    reason: string;
+    requestedAmount: string;
+    requestedCurrency: string;
+    createdAt: string;
+}
+interface BuyerOrdersData {
+    onetimeOrders: BuyerOnetimeOrder[];
+    subscriptionOrders: BuyerSubscriptionOrder[];
+}
+/**
+ * Fetch the buyer's order history (one-time + subscription).
+ *
+ * Must be used within `<WaffoPancakeProvider>`. Token is auto-managed.
+ *
+ * @returns Orders with product info and payment history
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, refetch } = useBuyerOrders();
+ * // data.onetimeOrders + data.subscriptionOrders
+ * ```
+ */
+declare function useBuyerOrders(): QueryState<BuyerOrdersData>;
+/**
+ * Fetch the buyer's payment history.
+ *
+ * Must be used within `<WaffoPancakeProvider>`. Token is auto-managed.
+ *
+ * @returns Payment records with amounts and status
+ *
+ * @example
+ * ```tsx
+ * const { data: payments, isLoading } = useBuyerPayments();
+ * ```
+ */
+declare function useBuyerPayments(): QueryState<BuyerPayment[]>;
+/**
+ * Fetch the buyer's refund tickets.
+ *
+ * Must be used within `<WaffoPancakeProvider>`. Token is auto-managed.
+ *
+ * @returns Refund tickets with status and requested amounts
+ *
+ * @example
+ * ```tsx
+ * const { data: tickets, isLoading } = useBuyerRefundTickets();
+ * ```
+ */
+declare function useBuyerRefundTickets(): QueryState<BuyerRefundTicket[]>;
+
+/** A merchant's recent order (one-time or subscription) */
+interface MerchantOrder {
+    id: string;
+    status: string;
+    currency: string;
+    buyerEmail: string;
+    testMode: boolean;
+    product: {
+        id: string;
+        name: string;
+    } | null;
+    payments: Array<{
+        id: string;
+        status: string;
+        snapshotDisplayAmount: string;
+        snapshotDisplayCurrency: string;
+    }>;
+    createdAt: string;
+}
+/** Sales overview statistics */
+interface SalesOverview {
+    totalOrders: number;
+    totalRevenue: string;
+    totalCustomers: number;
+    currency: string;
+    ordersByStatus: Array<{
+        status: string;
+        count: number;
+    }>;
+    revenueByPeriod: Array<{
+        period: string;
+        amount: string;
+    }>;
+}
+/** Subscription overview */
+interface SubscriptionOverview {
+    activeCount: number;
+    cancelingCount: number;
+    pastDueCount: number;
+    totalCount: number;
+    subscriptions: MerchantSubscription[];
+}
+/** A merchant's subscription with status details */
+interface MerchantSubscription {
+    id: string;
+    status: string;
+    currency: string;
+    buyerEmail: string;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    cancelAt: string | null;
+    product: {
+        id: string;
+        name: string;
+        billingPeriod: string;
+    } | null;
+    createdAt: string;
+}
+interface MerchantOrdersOptions {
+    /** Store ID to filter by */
+    storeId: string;
+    /** Max results (default: 20) */
+    limit?: number;
+}
+/**
+ * Fetch recent orders for a store (one-time + subscription).
+ *
+ * @param query - Server action from `createMerchantQueryAction()`
+ * @param options - Store ID and optional limit
+ * @returns Recent orders with product info and payment summary
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, refetch } = useMerchantOrders(merchantQuery, { storeId: "STO_xxx" });
+ * ```
+ */
+declare function useMerchantOrders(query: MerchantQueryAction, options: MerchantOrdersOptions): QueryState<{
+    onetimeOrders: MerchantOrder[];
+    subscriptionOrders: MerchantOrder[];
+}>;
+/**
+ * Fetch sales overview for a store.
+ *
+ * @param query - Server action from `createMerchantQueryAction()`
+ * @param storeId - Store ID
+ * @returns Aggregated sales statistics
+ *
+ * @example
+ * ```tsx
+ * const { data: sales } = useMerchantSales(merchantQuery, "STO_xxx");
+ * ```
+ */
+declare function useMerchantSales(query: MerchantQueryAction, storeId: string): QueryState<SalesOverview>;
+/**
+ * Fetch subscription overview for a store.
+ *
+ * @param query - Server action from `createMerchantQueryAction()`
+ * @param storeId - Store ID
+ * @returns Subscription counts and detailed list
+ *
+ * @example
+ * ```tsx
+ * const { data: subs } = useMerchantSubscriptions(merchantQuery, "STO_xxx");
+ * ```
+ */
+declare function useMerchantSubscriptions(query: MerchantQueryAction, storeId: string): QueryState<SubscriptionOverview>;
+
+/** Handler function for a specific webhook event */
+type EventHandler<T = WebhookEventData> = (event: WebhookEvent<T>) => void | Promise<void>;
+/** Configuration for the Webhook route handler factory */
+interface WebhookConfig {
+    /** Webhook signature verification options (environment, publicKey, tolerance, etc.) */
+    verifyOptions?: VerifyWebhookOptions;
+    /** Catch-all handler — called for every event regardless of type */
+    onPayload?: EventHandler;
+    /** One-time order first payment succeeded */
+    onOrderCompleted?: EventHandler;
+    /** Subscription first payment succeeded (newly activated) */
+    onSubscriptionActivated?: EventHandler;
+    /** Subscription renewal payment succeeded */
+    onSubscriptionPaymentSucceeded?: EventHandler;
+    /** Buyer initiated cancellation (expires at end of current period) */
+    onSubscriptionCanceling?: EventHandler;
+    /** Buyer withdrew cancellation (subscription restored) */
+    onSubscriptionUncanceled?: EventHandler;
+    /** Subscription product changed (upgrade/downgrade) */
+    onSubscriptionUpdated?: EventHandler;
+    /** Subscription fully terminated */
+    onSubscriptionCanceled?: EventHandler;
+    /** Renewal payment failed (past due) */
+    onSubscriptionPastDue?: EventHandler;
+    /** Refund succeeded */
+    onRefundSucceeded?: EventHandler;
+    /** Refund failed */
+    onRefundFailed?: EventHandler;
+}
+/**
+ * Create a Next.js POST route handler for Waffo Pancake webhooks.
+ *
+ * Automatically verifies the webhook signature using `@waffo/pancake-ts`,
+ * then dispatches to the matching event handler.
+ *
+ * @param config - Verification options and event handlers
+ * @returns A Next.js POST route handler
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/waffo/route.ts
+ * import { Webhook } from "@waffo/pancake-nextjs";
+ *
+ * export const POST = Webhook({
+ *   verifyOptions: { environment: "prod" },
+ *   onOrderCompleted: async (event) => {
+ *     console.log("Order completed:", event.data.orderId);
+ *     // Grant access to the product
+ *   },
+ *   onSubscriptionActivated: async (event) => {
+ *     console.log("Subscription activated:", event.data.orderId);
+ *   },
+ *   onRefundSucceeded: async (event) => {
+ *     console.log("Refund succeeded:", event.data.refundId);
+ *     // Revoke access
+ *   },
+ * });
+ * ```
+ */
+declare function Webhook(config: WebhookConfig): (request: Request) => Promise<Response>;
+
+export { type AnonymousCheckoutButtonProps, type AnonymousCheckoutProps, type AuthenticatedCheckoutButtonProps, type AuthenticatedCheckoutProps, type BuyerActionState, type BuyerConfig, type BuyerOnetimeOrder, type BuyerPayment, type BuyerRefundTicket, type BuyerSessionAction, type BuyerSubscriptionOrder, type BuyerTokenAction, type CheckoutAction, type CheckoutActionParams, type CheckoutActionResult, type CheckoutBaseOptions, CheckoutButton, type CheckoutButtonProps, type CheckoutMode, type CheckoutProps, type LinkCheckoutButtonProps, type LinkCheckoutProps, type MerchantOrder, type MerchantOrdersOptions, type MerchantQueryAction, type MerchantSubscription, type QueryState, type SalesOverview, type SubscriptionOverview, type UseBuyerReturn, type UseCheckoutReturn, WaffoPancakeProvider, type WaffoPancakeProviderProps, Webhook, type WebhookConfig, useBuyer, useBuyerOrders, useBuyerPayments, useBuyerRefundTickets, useCheckout, useMerchantOrders, useMerchantSales, useMerchantSubscriptions };