Configuration and lifecycle

type ZippyPayConfig = {
  // Required
  environment: "production" | "staging" | "development";
  sessionId: string;       // UUID v4
  clientToken: string;     // zps_…

  // Embed
  mode?: "inline" | "modal";              // default: "inline"
  container?: HTMLElement | string;       // required for inline

  // Appearance
  theme?: ZippyTheme;
  appLinks?: { ios?: string; android?: string };
  locale?: "en";                          // reserved — currently only "en"

  // Checkout methods (SDK >= 1.1.0; default mobileApp.policy enforce in 1.2.0+)
  checkoutPolicy?: "QR" | "MANUAL";       // omit for full chooser
  mobileApp?: { policy?: "off" | "option" | "enforce" }; // phone only; default enforce (1.2.0+)

  // Redirects (after terminal screen countdown)
  redirectOnComplete?: boolean;
  redirectOnFailure?: boolean;

  // Modal only
  closeOnBackdropClick?: boolean;         // default: false
  closeOnEscape?: boolean;                // default: false

  // Callbacks
  onReady?: (session: PaymentSession) => void;
  onSessionUpdate?: (session: PaymentSession) => void;
  onComplete?: (session: PaymentSession) => void;
  onExpired?: (session: PaymentSession) => void;
  onError?: (error: ZippyPayError) => void;
  onClose?: () => void;                  // modal only
};

// Omitting mobileApp is equivalent to { policy: 'enforce' } on phone
ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "inline",
  container: "#zippy-checkout",
});

ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "inline",
  container: "#zippy-checkout",
  mobileApp: { policy: "off" },
});

ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "inline",
  container: "#zippy-checkout",
  mobileApp: { policy: "option" },
  checkoutPolicy: "QR", // optional — restrict web fallbacks after failed handoff
});

<!-- Default: enforce on phone (SDK 1.2.0+) -->
<zippy-pay-checkout
  environment="production"
  session-id="550e8400-e29b-41d4-a716-446655440000"
></zippy-pay-checkout>

<!-- Web-only on phone -->
<zippy-pay-checkout
  environment="production"
  session-id="550e8400-e29b-41d4-a716-446655440000"
  mobile-app-policy="off"
></zippy-pay-checkout>

import { ZippyPay } from "@zippypay/checkout";

ZippyPay.create({
  environment: "production",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  mode: "inline",
  container: "#zippy-checkout",
  redirectOnComplete: true,
  redirectOnFailure: true,
  theme: { primary: "#1a56db", mode: "auto" },
  onReady: (session) => console.log(session.amount),
  onComplete: (session) => console.log(session.transactionId),
});

class ZippyPayError extends Error {
  readonly code: string;
  readonly status: number;
  readonly detail: string;
  readonly correlationId?: string;
}

?sessionId=550e8400-e29b-41d4-a716-446655440000&status=COMPLETED&transactionId=…

?sessionId=550e8400-e29b-41d4-a716-446655440000&status=EXPIRED

ZippyPay.create({
  theme: {
    primary: "#1a56db",
    primaryForeground: "#ffffff",
    borderRadius: "12px",
    fontFamily: "'Inter', sans-serif",
    mode: "auto",
  },
  // …session + token…
});

ZippyPay.create({
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "zps_REDACTED",
  environment: "production",
  appLinks: {
    ios: "https://apps.apple.com/app/your-app/id1234567890",
    android: "https://play.google.com/store/apps/details?id=your.package",
  },
});