import { Order, StaleSplit } from '@platform-modules/commerce-checkout';
export { OrderIdempotencyConflictError, StaleSplit, isCheckoutValidationError, isFulfillmentIncompleteError, isOrderIdempotencyConflictError, isOrderNotChargeableError, isPaymentFailedError } from '@platform-modules/commerce-checkout';
import { PaymentConfirmError } from '@platform-modules/billing-react';
export { PaymentConfirmError, isPaymentConfirmError } from '@platform-modules/billing-react';

/** Server status union — the source of money-truth. `Order['status']` from the core. */
type CheckoutStatus = Order['status'];
/**
 * Browser-facing checkout start input. NO buyerRef — the host API route resolves
 * buyer identity from the session/cookie server-side (the browser never sends it).
 * `idempotencyKey` is minted + persisted by the sibling (§0.1) and arrives unchanged
 * on every retry/resume.
 */
type CheckoutStartInput = {
    cartId: string;
    priceMode: 'inclusive' | 'exclusive';
    currency: string;
    buyerCountry: string;
    idempotencyKey: string;
};
/**
 * Injected, DB-free async data seam (§2). The host wires each method to an API route
 * it owns; the route runs startCheckout/getCheckoutStatus server-side and enforces the
 * price/currency/stock/authz floors. HTTP is the one production transport; an in-process
 * core wrapper + a mock are test doubles. The browser island never holds a db handle.
 *
 * Error contract the host's client MUST honor (the sibling branches on these):
 *  - 409 stale-items   → decode body via reviveStaleSplit, throw CheckoutWireError({ stale }).
 *  - 409 idempotency   → throw the core's OrderIdempotencyConflictError.
 *  - other failures     → throw CheckoutWireError (no stale) or a core typed error.
 */
interface CheckoutClient {
    /** Claim/resume an order. Resolves orderId + (for card flows) a PSP clientSecret. */
    start(input: CheckoutStartInput): Promise<{
        orderId: string;
        clientSecret?: string;
    }>;
    /** Poll server-authoritative order status. clientSecret reappears on requires_action. */
    getStatus(orderId: string): Promise<{
        status: CheckoutStatus;
        clientSecret?: string;
    }>;
}

declare function CheckoutProvider(props: {
    client: CheckoutClient;
    cartId: string;
    cartVersion?: string | number;
    makeIdempotencyKey?: () => string;
    children: React.ReactNode;
}): JSX.Element;

/** Thrown when a checkout hook is used outside <CheckoutProvider> (§2). */
declare class CheckoutProviderError extends Error {
    readonly name = "CheckoutProviderError";
    constructor(hook: string);
}
declare function isCheckoutProviderError(e: unknown): e is CheckoutProviderError;
/**
 * Thrown by the host's CheckoutClient on a non-typed wire failure, and by the stale
 * path carrying a revived StaleSplit (§4). `code` is stable for cross-package branching.
 */
declare class CheckoutWireError extends Error {
    readonly name = "CheckoutWireError";
    readonly code: "CHECKOUT_WIRE";
    readonly stale?: StaleSplit;
    constructor(message: string, opts?: {
        stale?: StaleSplit;
    });
}
declare function isCheckoutWireError(e: unknown): e is CheckoutWireError;

type CheckoutPhase = 'idle' | 'starting' | 'awaiting_payment' | 'confirming' | 'settling' | 'settle_timeout' | 'cart_changed' | 'paid' | 'failed' | 'stale';
type CheckoutState = {
    phase: CheckoutPhase;
    orderId: string | null;
    clientSecret: string | null;
    mintCartVersion: string | number | null;
    stale: StaleSplit | null;
    error: CheckoutWireError | PaymentConfirmError | null;
};

declare function useCheckout(): {
    phase: CheckoutPhase;
    orderId: string | null;
    clientSecret: string | null;
    stale: StaleSplit | null;
    error: CheckoutWireError | PaymentConfirmError | null;
    submit: (input: Omit<CheckoutStartInput, 'idempotencyKey'>) => Promise<void>;
    reset: () => void;
    retry: () => void;
};

declare function useCheckoutConfirm(): {
    confirm: (opts: {
        returnUrl: string;
    }) => Promise<void>;
    status: 'idle' | 'confirming' | 'succeeded' | 'error';
};

/** Wire JSON (409 stale body) → typed StaleSplit. The ONE revive helper. §3 */
declare function reviveStaleSplit(raw: unknown): StaleSplit;

type CheckoutRecord = {
    idempotencyKey: string;
    orderId?: string;
    clientSecret?: string;
    mintCartVersion?: string | number;
};
/** Read the persisted record for a cart, or null if absent/malformed. */
declare function loadRecord(cartId: string): CheckoutRecord | null;
/** Write the full record (mint-once survival across the 3DS redirect). */
declare function persistRecord(cartId: string, record: CheckoutRecord): void;
/** Drop the record — terminal-success, reset(), or cart-content invalidation. */
declare function clearRecord(cartId: string): void;
/**
 * Return the cart's existing key, or mint + persist a new one. Idempotent per cart:
 * repeated calls reuse the stored key (never regenerate per submit-click).
 */
declare function ensureKey(cartId: string, makeKey?: () => string): string;

export { type CheckoutClient, type CheckoutPhase, CheckoutProvider, CheckoutProviderError, type CheckoutRecord, type CheckoutStartInput, type CheckoutState, type CheckoutStatus, CheckoutWireError, clearRecord, ensureKey, isCheckoutProviderError, isCheckoutWireError, loadRecord, persistRecord, reviveStaleSplit, useCheckout, useCheckoutConfirm };