@zippypay/checkout 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,265 @@
+type ZippyEnvironment = 'production' | 'staging' | 'development';
+/** API origin per environment. Paths such as `/api/v1/...` are appended by the SDK client. */
+declare const ZIPPY_API_BASE_URLS: Record<ZippyEnvironment, string>;
+declare const ZIPPY_API_PATH_PREFIX = "/api/v1";
+declare function isZippyEnvironment(value: string): value is ZippyEnvironment;
+declare function resolveApiBaseUrl(environment: ZippyEnvironment): string;
+declare function parseZippyEnvironment(value: string): ZippyEnvironment;
+
+type PaymentSessionStatus = 'CREATED' | 'AWAITING_PAYMENT' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED';
+type PaymentSessionPhase = 'IDLE' | 'PAYING';
+/** Server checkout method — locks after checkout start. */
+type ApiCheckoutMethod = 'QR' | 'MANUAL';
+type PaymentSessionPayer = {
+    paymentId: string;
+    displayName: string;
+    profileImage: string | null;
+};
+type PaymentSession = {
+    sessionId: string;
+    amount: string;
+    currency: 'USD';
+    status: PaymentSessionStatus;
+    successUrl: string | null;
+    failureUrl: string | null;
+    businessName: string;
+    transactionId: string | null;
+    transactionStatus: string | null;
+    payer: PaymentSessionPayer | null;
+    /** Idle shelf — customer must start checkout before this. */
+    expiresAt: string;
+    /** Hard max — session + client token expire here. */
+    absoluteExpiresAt: string;
+    phase: PaymentSessionPhase;
+    checkoutMethod: ApiCheckoutMethod | null;
+    paymentStartAt: string | null;
+    /** Pay window countdown — only meaningful when phase is PAYING. */
+    paymentExpiryAt: string | null;
+    createdAt: string;
+};
+type VerifyPayerResponse = PaymentSessionPayer;
+type ProblemJson = {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    code?: string;
+    correlationId?: string;
+    errors?: Record<string, string[]>;
+};
+
+type ZippyTheme = {
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    textMuted?: string;
+    border?: string;
+    error?: string;
+    success?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    mode?: 'light' | 'dark' | 'auto';
+};
+type EmbedMode = 'inline' | 'modal';
+type ZippyPayConfig = {
+    environment: ZippyEnvironment;
+    sessionId: string;
+    clientToken: string;
+    mode?: EmbedMode;
+    container?: HTMLElement | string;
+    theme?: ZippyTheme;
+    locale?: 'en';
+    redirectOnComplete?: boolean;
+    redirectOnFailure?: boolean;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    onReady?: (session: PaymentSession) => void;
+    onSessionUpdate?: (session: PaymentSession) => void;
+    onComplete?: (session: PaymentSession) => void;
+    onExpired?: (session: PaymentSession) => void;
+    onError?: (error: ZippyPayError) => void;
+    onClose?: () => void;
+};
+type CheckoutMethod = 'qr' | 'manual';
+type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'manual-entry' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
+declare const TERMINAL_STATUSES: readonly PaymentSessionStatus[];
+declare const POLLABLE_STATUSES: readonly PaymentSessionStatus[];
+declare class ZippyPayError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly correlationId?: string;
+    constructor(problem: ProblemJson);
+}
+type ZippyPayCheckoutInstance = {
+    open(): void;
+    close(): void;
+    destroy(): void;
+};
+
+type ApiClientConfig = {
+    baseUrl: string;
+    sessionId: string;
+    clientToken: string;
+};
+declare class PaymentSessionClient {
+    private readonly baseUrl;
+    private readonly sessionId;
+    private readonly clientToken;
+    constructor(config: ApiClientConfig);
+    getSession(): Promise<PaymentSession>;
+    verifyPayer(paymentId: string): Promise<VerifyPayerResponse>;
+    attachPayer(paymentId: string): Promise<PaymentSession>;
+    startCheckout(method: ApiCheckoutMethod): Promise<PaymentSession>;
+    startQrCheckout(): Promise<PaymentSession>;
+    startManualCheckout(): Promise<PaymentSession>;
+    private sessionPath;
+    private headers;
+    private request;
+    private parseError;
+}
+declare function attachPayerWithRetry(client: PaymentSessionClient, paymentId: string): Promise<PaymentSession>;
+
+type PollerOptions = {
+    intervalMs?: number;
+    hiddenIntervalMs?: number;
+    onUpdate: (session: PaymentSession) => void;
+    onError?: (error: unknown) => void;
+    shouldPoll?: (session: PaymentSession) => boolean;
+};
+declare class SessionPoller {
+    private readonly fetchSession;
+    private readonly options;
+    private timer;
+    private running;
+    private stopped;
+    constructor(fetchSession: () => Promise<PaymentSession>, options: PollerOptions);
+    start(initialSession?: PaymentSession): void;
+    stop(): void;
+    private shouldContinue;
+    private intervalMs;
+    private scheduleNext;
+    private tick;
+}
+declare function isTerminalStatus(status: PaymentSessionStatus): boolean;
+declare function phaseFromSession(status: PaymentSessionStatus): CheckoutPhase;
+
+/** Pay countdown target — only after checkout has started. */
+declare function getCountdownTarget(session: PaymentSession): string | null;
+/** Whether the checkout UI should show the pay-window progress bar. */
+declare function shouldShowPayProgress(session: PaymentSession | null, phase: CheckoutPhase): boolean;
+/** Remaining pay-window ratio (1 = full time left, 0 = expired). */
+declare function getPayWindowRemainingRatio(session: PaymentSession): number | null;
+/** Idle shelf deadline — show soft hint only, not a pay countdown. */
+declare function getSoftIdleHint(session: PaymentSession): string | null;
+declare function msUntil(iso: string): number;
+
+declare class CheckoutController implements ZippyPayCheckoutInstance {
+    private readonly config;
+    private readonly client;
+    private readonly embed;
+    private readonly poller;
+    private ui;
+    private session;
+    private paymentId;
+    private verifiedPayer;
+    private committedMethod;
+    private phase;
+    private errorMessage;
+    private loading;
+    private destroyed;
+    private modalOpen;
+    private exitMode;
+    private terminalFailureReason;
+    constructor(config: ZippyPayConfig);
+    open(): void;
+    close(): void;
+    destroy(): void;
+    private snapshotUiState;
+    private syncUi;
+    private bootstrap;
+    private applySession;
+    private resolveActivePhase;
+    private handleSessionUpdate;
+    private handleFailure;
+    private handleSuccess;
+    private executeTerminalExit;
+    private resolveExitMode;
+    private failurePhaseFromReason;
+    private teardownView;
+    private handleBootstrapError;
+    private handleError;
+    private chooseMethod;
+    private verify;
+    private attach;
+    private handleFlowError;
+    private refreshAfterConflict;
+}
+declare function createCheckout(config: ZippyPayConfig): ZippyPayCheckoutInstance;
+
+declare const ELEMENT_TAG = "zippy-pay-checkout";
+declare class ZippyPayCheckoutElement extends HTMLElement {
+    private instance;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    set clientToken(value: string);
+    get clientToken(): string;
+    private mount;
+    private unmount;
+    private readConfig;
+    private dispatch;
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+declare function defineZippyPayCheckoutElement(): void;
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'zippy-pay-checkout': ZippyPayCheckoutElement;
+    }
+}
+
+/** Personal Zippy handles: 3–20 chars, optional single dot, no leading/trailing dot. */
+declare const PAYMENT_ID_PATTERN: RegExp;
+declare function normalizePaymentId(value: string): string;
+declare function isValidPaymentId(value: string): boolean;
+declare function paymentIdValidationMessage(): string;
+declare function formatAmount(amount: string, currency: string): string;
+
+/** Deep link scanned by the Zippy app — sessionId only, never clientToken. */
+declare function buildPaymentQrPayload(sessionId: string): string;
+type QrErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+/** Renders a QR code as an SVG string for embedding in the checkout UI. */
+declare function renderQrSvg(payload: string, cellSize?: number, errorCorrection?: QrErrorCorrection, margin?: number): string;
+declare function renderPaymentQrSvg(sessionId: string, cellSize?: number, errorCorrection?: QrErrorCorrection): string;
+/** Branded QR SVG with centred Zippy mark — matches merchant dashboard rendering. */
+declare function renderBrandedPaymentQrSvg(sessionId: string, cellSize?: number): string;
+/** QR markup wrapper for the checkout UI. */
+declare function renderPaymentQrMarkup(sessionId: string, cellSize?: number): string;
+
+/** Aligned with zippy-kyc-web-sdk `src/styles/tokens.css` */
+declare const DEFAULT_THEME: Required<Omit<ZippyTheme, 'mode'>> & {
+    mode: ZippyTheme['mode'];
+    primaryGradientEnd: string;
+    primaryHover: string;
+    primarySoft: string;
+    surfaceMuted: string;
+    radiusButton: string;
+    radiusInput: string;
+    radiusCard: string;
+};
+type ResolvedTheme = typeof DEFAULT_THEME;
+declare function resolveTheme(theme?: ZippyTheme): ResolvedTheme;
+declare function applyThemeToHost(host: HTMLElement, theme?: ZippyTheme): void;
+
+declare const ZippyPay: {
+    create(config: ZippyPayConfig): ZippyPayCheckoutInstance;
+};
+
+export { type ApiCheckoutMethod, CheckoutController, type CheckoutMethod, type CheckoutPhase, DEFAULT_THEME, ELEMENT_TAG, type EmbedMode, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isTerminalStatus, isValidPaymentId, isZippyEnvironment, msUntil, normalizePaymentId, parseZippyEnvironment, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, resolveApiBaseUrl, resolveTheme, shouldShowPayProgress };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+type ZippyEnvironment = 'production' | 'staging' | 'development';
+/** API origin per environment. Paths such as `/api/v1/...` are appended by the SDK client. */
+declare const ZIPPY_API_BASE_URLS: Record<ZippyEnvironment, string>;
+declare const ZIPPY_API_PATH_PREFIX = "/api/v1";
+declare function isZippyEnvironment(value: string): value is ZippyEnvironment;
+declare function resolveApiBaseUrl(environment: ZippyEnvironment): string;
+declare function parseZippyEnvironment(value: string): ZippyEnvironment;
+
+type PaymentSessionStatus = 'CREATED' | 'AWAITING_PAYMENT' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED';
+type PaymentSessionPhase = 'IDLE' | 'PAYING';
+/** Server checkout method — locks after checkout start. */
+type ApiCheckoutMethod = 'QR' | 'MANUAL';
+type PaymentSessionPayer = {
+    paymentId: string;
+    displayName: string;
+    profileImage: string | null;
+};
+type PaymentSession = {
+    sessionId: string;
+    amount: string;
+    currency: 'USD';
+    status: PaymentSessionStatus;
+    successUrl: string | null;
+    failureUrl: string | null;
+    businessName: string;
+    transactionId: string | null;
+    transactionStatus: string | null;
+    payer: PaymentSessionPayer | null;
+    /** Idle shelf — customer must start checkout before this. */
+    expiresAt: string;
+    /** Hard max — session + client token expire here. */
+    absoluteExpiresAt: string;
+    phase: PaymentSessionPhase;
+    checkoutMethod: ApiCheckoutMethod | null;
+    paymentStartAt: string | null;
+    /** Pay window countdown — only meaningful when phase is PAYING. */
+    paymentExpiryAt: string | null;
+    createdAt: string;
+};
+type VerifyPayerResponse = PaymentSessionPayer;
+type ProblemJson = {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    code?: string;
+    correlationId?: string;
+    errors?: Record<string, string[]>;
+};
+
+type ZippyTheme = {
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    textMuted?: string;
+    border?: string;
+    error?: string;
+    success?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    mode?: 'light' | 'dark' | 'auto';
+};
+type EmbedMode = 'inline' | 'modal';
+type ZippyPayConfig = {
+    environment: ZippyEnvironment;
+    sessionId: string;
+    clientToken: string;
+    mode?: EmbedMode;
+    container?: HTMLElement | string;
+    theme?: ZippyTheme;
+    locale?: 'en';
+    redirectOnComplete?: boolean;
+    redirectOnFailure?: boolean;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    onReady?: (session: PaymentSession) => void;
+    onSessionUpdate?: (session: PaymentSession) => void;
+    onComplete?: (session: PaymentSession) => void;
+    onExpired?: (session: PaymentSession) => void;
+    onError?: (error: ZippyPayError) => void;
+    onClose?: () => void;
+};
+type CheckoutMethod = 'qr' | 'manual';
+type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'manual-entry' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
+declare const TERMINAL_STATUSES: readonly PaymentSessionStatus[];
+declare const POLLABLE_STATUSES: readonly PaymentSessionStatus[];
+declare class ZippyPayError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly correlationId?: string;
+    constructor(problem: ProblemJson);
+}
+type ZippyPayCheckoutInstance = {
+    open(): void;
+    close(): void;
+    destroy(): void;
+};
+
+type ApiClientConfig = {
+    baseUrl: string;
+    sessionId: string;
+    clientToken: string;
+};
+declare class PaymentSessionClient {
+    private readonly baseUrl;
+    private readonly sessionId;
+    private readonly clientToken;
+    constructor(config: ApiClientConfig);
+    getSession(): Promise<PaymentSession>;
+    verifyPayer(paymentId: string): Promise<VerifyPayerResponse>;
+    attachPayer(paymentId: string): Promise<PaymentSession>;
+    startCheckout(method: ApiCheckoutMethod): Promise<PaymentSession>;
+    startQrCheckout(): Promise<PaymentSession>;
+    startManualCheckout(): Promise<PaymentSession>;
+    private sessionPath;
+    private headers;
+    private request;
+    private parseError;
+}
+declare function attachPayerWithRetry(client: PaymentSessionClient, paymentId: string): Promise<PaymentSession>;
+
+type PollerOptions = {
+    intervalMs?: number;
+    hiddenIntervalMs?: number;
+    onUpdate: (session: PaymentSession) => void;
+    onError?: (error: unknown) => void;
+    shouldPoll?: (session: PaymentSession) => boolean;
+};
+declare class SessionPoller {
+    private readonly fetchSession;
+    private readonly options;
+    private timer;
+    private running;
+    private stopped;
+    constructor(fetchSession: () => Promise<PaymentSession>, options: PollerOptions);
+    start(initialSession?: PaymentSession): void;
+    stop(): void;
+    private shouldContinue;
+    private intervalMs;
+    private scheduleNext;
+    private tick;
+}
+declare function isTerminalStatus(status: PaymentSessionStatus): boolean;
+declare function phaseFromSession(status: PaymentSessionStatus): CheckoutPhase;
+
+/** Pay countdown target — only after checkout has started. */
+declare function getCountdownTarget(session: PaymentSession): string | null;
+/** Whether the checkout UI should show the pay-window progress bar. */
+declare function shouldShowPayProgress(session: PaymentSession | null, phase: CheckoutPhase): boolean;
+/** Remaining pay-window ratio (1 = full time left, 0 = expired). */
+declare function getPayWindowRemainingRatio(session: PaymentSession): number | null;
+/** Idle shelf deadline — show soft hint only, not a pay countdown. */
+declare function getSoftIdleHint(session: PaymentSession): string | null;
+declare function msUntil(iso: string): number;
+
+declare class CheckoutController implements ZippyPayCheckoutInstance {
+    private readonly config;
+    private readonly client;
+    private readonly embed;
+    private readonly poller;
+    private ui;
+    private session;
+    private paymentId;
+    private verifiedPayer;
+    private committedMethod;
+    private phase;
+    private errorMessage;
+    private loading;
+    private destroyed;
+    private modalOpen;
+    private exitMode;
+    private terminalFailureReason;
+    constructor(config: ZippyPayConfig);
+    open(): void;
+    close(): void;
+    destroy(): void;
+    private snapshotUiState;
+    private syncUi;
+    private bootstrap;
+    private applySession;
+    private resolveActivePhase;
+    private handleSessionUpdate;
+    private handleFailure;
+    private handleSuccess;
+    private executeTerminalExit;
+    private resolveExitMode;
+    private failurePhaseFromReason;
+    private teardownView;
+    private handleBootstrapError;
+    private handleError;
+    private chooseMethod;
+    private verify;
+    private attach;
+    private handleFlowError;
+    private refreshAfterConflict;
+}
+declare function createCheckout(config: ZippyPayConfig): ZippyPayCheckoutInstance;
+
+declare const ELEMENT_TAG = "zippy-pay-checkout";
+declare class ZippyPayCheckoutElement extends HTMLElement {
+    private instance;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    set clientToken(value: string);
+    get clientToken(): string;
+    private mount;
+    private unmount;
+    private readConfig;
+    private dispatch;
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+declare function defineZippyPayCheckoutElement(): void;
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'zippy-pay-checkout': ZippyPayCheckoutElement;
+    }
+}
+
+/** Personal Zippy handles: 3–20 chars, optional single dot, no leading/trailing dot. */
+declare const PAYMENT_ID_PATTERN: RegExp;
+declare function normalizePaymentId(value: string): string;
+declare function isValidPaymentId(value: string): boolean;
+declare function paymentIdValidationMessage(): string;
+declare function formatAmount(amount: string, currency: string): string;
+
+/** Deep link scanned by the Zippy app — sessionId only, never clientToken. */
+declare function buildPaymentQrPayload(sessionId: string): string;
+type QrErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+/** Renders a QR code as an SVG string for embedding in the checkout UI. */
+declare function renderQrSvg(payload: string, cellSize?: number, errorCorrection?: QrErrorCorrection, margin?: number): string;
+declare function renderPaymentQrSvg(sessionId: string, cellSize?: number, errorCorrection?: QrErrorCorrection): string;
+/** Branded QR SVG with centred Zippy mark — matches merchant dashboard rendering. */
+declare function renderBrandedPaymentQrSvg(sessionId: string, cellSize?: number): string;
+/** QR markup wrapper for the checkout UI. */
+declare function renderPaymentQrMarkup(sessionId: string, cellSize?: number): string;
+
+/** Aligned with zippy-kyc-web-sdk `src/styles/tokens.css` */
+declare const DEFAULT_THEME: Required<Omit<ZippyTheme, 'mode'>> & {
+    mode: ZippyTheme['mode'];
+    primaryGradientEnd: string;
+    primaryHover: string;
+    primarySoft: string;
+    surfaceMuted: string;
+    radiusButton: string;
+    radiusInput: string;
+    radiusCard: string;
+};
+type ResolvedTheme = typeof DEFAULT_THEME;
+declare function resolveTheme(theme?: ZippyTheme): ResolvedTheme;
+declare function applyThemeToHost(host: HTMLElement, theme?: ZippyTheme): void;
+
+declare const ZippyPay: {
+    create(config: ZippyPayConfig): ZippyPayCheckoutInstance;
+};
+
+export { type ApiCheckoutMethod, CheckoutController, type CheckoutMethod, type CheckoutPhase, DEFAULT_THEME, ELEMENT_TAG, type EmbedMode, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isTerminalStatus, isValidPaymentId, isZippyEnvironment, msUntil, normalizePaymentId, parseZippyEnvironment, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, resolveApiBaseUrl, resolveTheme, shouldShowPayProgress };