@wajub/js 1.3.0

package/dist/wajub-checkout.d.ts

@@ -0,0 +1,431 @@
+/**
+ * Wajub Checkout SDK — TypeScript definitions
+ *
+ * npm loader (recommended — loads runtime from CDN):
+ *   npm install @wajub/js
+ *   import { loadWajub, mount } from "@wajub/js";
+ *   const rt = await loadWajub();
+ *
+ * Deferred load (no side effect on import):
+ *   import { loadWajub } from "@wajub/js/pure";
+ *
+ * CDN script tag (full runtime):
+ *   <script src="https://js.wajub.com"></script>
+ *
+ * CDN ESM (full runtime):
+ *   import { mount } from "https://js.wajub.com/wajub.mjs";
+ */
+
+export interface LoadWajubOptions {
+  /** CDN origin (default https://js.wajub.com). */
+  jsOrigin?: string;
+  /** Full script URL override (default `{jsOrigin}/wajub.js`). */
+  jsUrl?: string;
+}
+
+/** Runtime globals after Wajub.js CDN script loads. */
+export interface WajubRuntime {
+  wajub: WajubSDK;
+  Wajub: WajubFactory;
+  WajubError: typeof WajubError;
+}
+
+export interface LoadWajubFn {
+  (options?: LoadWajubOptions): Promise<WajubRuntime | null>;
+  setLoadParameters(params: LoadWajubOptions): void;
+}
+
+/**
+ * Load Wajub.js from the CDN. Resolves to `null` on the server (SSR-safe).
+ */
+export const loadWajub: LoadWajubFn;
+
+/** @wajub/js async helpers — load CDN then call API. Return null on SSR. */
+export function mount(
+  container: string | HTMLElement,
+  config: EmbeddedConfig,
+): Promise<CheckoutInstance | null>;
+export function open(config: PopupConfig): Promise<PopupInstance | null>;
+export function checkout(config: EmbeddedConfig): Promise<void | null>;
+export function preload(sessionId: string, options?: { iframe?: boolean }): Promise<void | null>;
+export function fetchSession(sessionId: string): Promise<SessionPreview>;
+export function components(
+  sessionId: string,
+  options?: Partial<ComponentConfig>,
+): Promise<ComponentsFactory | null>;
+export function confirmPayment(
+  options: ConfirmPaymentOptions,
+): Promise<{ status: string; transaction?: Record<string, unknown> | null }>;
+export function getVersion(): Promise<string | null>;
+export function getCheckoutOrigin(): Promise<string | null>;
+
+export type CheckoutState =
+  | "INITIATED"
+  | "COLLECTING_DETAILS"
+  | "PROCESSING"
+  | "OTP_REQUIRED"
+  | "3DS_REQUIRED"
+  | "USSD_REQUIRED"
+  | "APPROVAL_REQUIRED"
+  | "VERIFYING"
+  | "PENDING"
+  | "SUCCESS"
+  | "FAILED"
+  | "EXPIRED"
+  | "CANCELLED";
+
+export type WajubErrorType =
+  | "api_error"
+  | "authentication_error"
+  | "invalid_request_error"
+  | "payment_error"
+  | "rate_limit_error";
+
+export interface WajubErrorShape {
+  name: "WajubError";
+  message: string;
+  type: WajubErrorType;
+  code: string;
+  decline_code: string | null;
+  retryable: boolean;
+  param: string | null;
+}
+
+export declare class WajubError extends Error implements WajubErrorShape {
+  type: WajubErrorType;
+  code: string;
+  decline_code: string | null;
+  retryable: boolean;
+  param: string | null;
+  static fromPayload(payload: unknown): WajubError;
+  toJSON(): WajubErrorShape;
+}
+
+export type AppearanceThemePreset = "stripe" | "night" | "flat" | "none";
+export type AppearanceColorScheme = "light" | "dark" | "auto";
+export type AppearanceLabels = "above" | "floating";
+
+export interface AppearanceVariables {
+  colorPrimary?: string;
+  colorBackground?: string;
+  colorText?: string;
+  colorTextSecondary?: string;
+  colorTextPlaceholder?: string;
+  colorDanger?: string;
+  colorSuccess?: string;
+  fontFamily?: string;
+  fontSizeBase?: string;
+  fontWeightNormal?: string;
+  fontWeightMedium?: string;
+  fontWeightBold?: string;
+  spacingUnit?: string;
+  borderRadius?: string;
+  spacingGridRow?: string;
+  spacingGridColumn?: string;
+}
+
+export type AppearanceRules = Record<string, Record<string, string>>;
+
+export interface AppearanceConfig {
+  /** Built-in preset (layered before explicit keys). */
+  theme?: AppearanceThemePreset;
+  primaryColor?: string;
+  secondaryColor?: string;
+  backgroundColor?: string;
+  fontFamily?: string;
+  borderRadius?: string;
+  buttonTextColor?: string;
+  inputBackgroundColor?: string;
+  inputBorderColor?: string;
+  textMutedColor?: string;
+  successColor?: string;
+  errorColor?: string;
+  shadow?: string;
+  colorScheme?: AppearanceColorScheme;
+  labels?: AppearanceLabels;
+  disableAnimations?: boolean;
+  variables?: AppearanceVariables;
+  rules?: AppearanceRules;
+}
+
+/** @deprecated Use AppearanceConfig */
+export interface EmbedTheme {
+  primaryColor?: string;
+  fontFamily?: string;
+  borderRadius?: string;
+}
+
+export type CheckoutLayout = "classic" | "compact" | "tabs" | "accordion";
+
+export interface EmbedBreakdown {
+  subtotal: number;
+  discount: number;
+  tax: number;
+  total: number;
+  currency: string;
+}
+
+export interface SessionPreview {
+  session_id: string;
+  status: string;
+  environment: "sandbox" | "live";
+  amount: number;
+  currency: string;
+  merchant_name: string;
+  payment_methods: Array<{ id: string; type: string; label: string }>;
+  saved_methods?: Array<{ id: string; type: string; label: string }>;
+  features: Record<string, boolean>;
+}
+
+export interface EmbeddedConfig {
+  sessionId: string;
+  locale?: string;
+  embedOrigin?: string;
+  /** @deprecated Prefer appearance */
+  theme?: EmbedTheme;
+  appearance?: AppearanceConfig;
+  layout?: CheckoutLayout;
+  loadingText?: string;
+  showLoading?: boolean;
+  onReady?: (instance: CheckoutInstance) => void;
+  onSuccess?: (transaction: Record<string, unknown>) => void;
+  onError?: (error: WajubError | Record<string, unknown>) => void;
+  onLoadError?: (error: WajubError | Record<string, unknown>) => void;
+  onCancel?: () => void;
+  onExpired?: () => void;
+  onStateChange?: (payload: { state?: CheckoutState; method?: string }) => void;
+  onMethodChange?: (payload: { methodId?: string; method_id?: string }) => void;
+  onBreakdown?: (breakdown: EmbedBreakdown) => void;
+  onResize?: (height: number) => void;
+  onClose?: () => void;
+}
+
+export interface CheckoutInstance {
+  mount(): void;
+  unmount(): void;
+  update(
+    config: Partial<
+      Pick<EmbeddedConfig, "locale" | "theme" | "appearance" | "layout"> & { currency?: string }
+    >,
+  ): void;
+  getState(): CheckoutState | string;
+  submit(): void;
+  cancel(): void;
+  retry(): void;
+  selectMethod(methodId: string): void;
+  close(): void;
+  destroy(): void;
+}
+
+export interface PopupConfig extends EmbeddedConfig {
+  width?: number;
+  height?: number;
+  closeOnOverlay?: boolean;
+  closeOnEscape?: boolean;
+}
+
+export interface PopupInstance extends CheckoutInstance {
+  isOpen?(): boolean;
+}
+
+export type ComponentType = "card" | "mobileMoney" | "wallet" | "payment" | "address";
+
+export type AddressMode = "shipping" | "billing";
+export type PhoneFieldMode = "always" | "auto" | "never";
+export type CollectAddressMode = "shipping" | "billing";
+
+export interface AddressValue {
+  line1: string;
+  line2?: string;
+  city: string;
+  state?: string;
+  postal_code?: string;
+  country: string;
+}
+
+export interface ComponentAddressValue {
+  name?: string;
+  phone?: string;
+  address?: AddressValue | null;
+  mode?: AddressMode;
+}
+
+export interface ComponentChangeEvent {
+  complete?: boolean;
+  empty?: boolean;
+  error?: WajubErrorShape | Record<string, unknown>;
+  value?: ComponentAddressValue | Record<string, unknown>;
+}
+
+export interface ComponentFieldsConfig {
+  phone?: PhoneFieldMode;
+}
+
+export interface ComponentConfig {
+  sessionId: string;
+  locale?: string;
+  componentOrigin?: string;
+  appearance?: AppearanceConfig;
+  layout?: CheckoutLayout;
+  /** Payment component — collect shipping/billing address inline. */
+  collectAddress?: CollectAddressMode;
+  /** Address component — shipping vs billing labels. */
+  addressMode?: AddressMode;
+  collectName?: boolean;
+  fields?: ComponentFieldsConfig;
+  onReady?: (component: ComponentInstance) => void;
+  onChange?: (event: ComponentChangeEvent) => void;
+  onFocus?: () => void;
+  onBlur?: () => void;
+  onLoadError?: (error: WajubError | Record<string, unknown>) => void;
+  onSuccess?: (transaction: Record<string, unknown>) => void;
+  onError?: (error: WajubError | Record<string, unknown>) => void;
+  onMethodChange?: (payload: { methodId?: string }) => void;
+}
+
+export interface ComponentInstance {
+  mount(container: string | HTMLElement): ComponentInstance;
+  unmount(): void;
+  destroy(): void;
+  on(event: string, fn: (data?: unknown) => void): ComponentInstance;
+  off(event: string, fn: (data?: unknown) => void): ComponentInstance;
+  update(config: Partial<Pick<ComponentConfig, "locale" | "appearance" | "layout">>): ComponentInstance;
+  focus(): ComponentInstance;
+  blur(): ComponentInstance;
+  submit(): ComponentInstance;
+  selectMethod(methodId: string): ComponentInstance;
+  getState(): CheckoutState | string;
+  isComplete(): boolean;
+  getError(): WajubError | null;
+  /** Address component — current field values (also on `change.value`). */
+  getValue(): ComponentAddressValue | Record<string, unknown> | null;
+}
+
+export interface ComponentsFactory {
+  sessionId: string;
+  create(type: ComponentType, config?: Partial<ComponentConfig>): ComponentInstance;
+}
+
+export interface ConfirmPaymentOptions {
+  sessionId: string;
+  components?: ComponentInstance & { _paymentComponent?: ComponentInstance };
+  callback?: string;
+}
+
+export interface CreatePaymentParams {
+  amount: number;
+  currency: string;
+  reference?: string;
+  description?: string;
+  customer?: {
+    email?: string;
+    name?: string;
+    phone?: string;
+    country?: string;
+  };
+  bearer?: "merchant" | "customer";
+  /** URL HTTPS where the payer is redirected after payment (redirect flow). */
+  callback?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface CreatePaymentResult {
+  sessionId: string;
+  authorizationToken: string;
+  authorizationUrl: string | null;
+  transaction: Record<string, unknown> | null;
+  raw: Record<string, unknown>;
+}
+
+export interface WajubInitOptions {
+  /** Existing session token from your backend (authorization_token). */
+  sessionId?: string;
+  /** Publishable key when using object form: Wajub({ publishableKey, sessionId }). */
+  publishableKey?: string;
+  /** @deprecated Alias for publishableKey */
+  apiKey?: string;
+  /** API origin (default baked at SDK build — https://api.wajub.com). */
+  apiBase?: string;
+  /** Full POST /payments URL override. */
+  paymentsUrl?: string;
+  /** Route via checkout BFF (/api/payments) — useful for local demos / CORS. */
+  useCheckoutProxy?: boolean;
+  componentOrigin?: string;
+}
+
+export interface InitCheckoutOptions extends Partial<EmbeddedConfig> {
+  mode?: "inline" | "overlay" | "redirect";
+  container?: string | HTMLElement;
+  /** Use an existing session — skips createPayment(). */
+  sessionId?: string;
+  payment?: CreatePaymentParams;
+  checkout?: Partial<EmbeddedConfig>;
+}
+
+export interface InitCheckoutResult {
+  session: CreatePaymentResult | { sessionId: string };
+  instance: CheckoutInstance | PopupInstance | null;
+}
+
+/** Wajub.js client — create a session (pk) and/or use an existing sessionId. */
+export interface WajubClient {
+  publishableKey: string | null;
+  sessionId: string | null;
+  environment: "sandbox" | "live" | null;
+  apiBase: string;
+  checkoutOrigin: string;
+  useSession(sessionId: string): WajubClient;
+  createPayment(params: CreatePaymentParams): Promise<CreatePaymentResult>;
+  initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
+  fetchSession(sessionId?: string): Promise<SessionPreview>;
+  preload(sessionId?: string, options?: { iframe?: boolean }): void;
+  checkout(config?: Partial<EmbeddedConfig>): void;
+  mount(container: string | HTMLElement, config?: Partial<EmbeddedConfig>): CheckoutInstance;
+  open(config?: Partial<PopupConfig>): PopupInstance;
+  components(sessionIdOrConfig?: string | Partial<ComponentConfig>, config?: Partial<ComponentConfig>): ComponentsFactory;
+  confirmPayment(options?: ConfirmPaymentOptions): Promise<{ status: string; transaction?: Record<string, unknown> | null }>;
+}
+
+export interface WajubFactory {
+  (publishableKeyOrSessionId: string, options?: WajubInitOptions): WajubClient;
+  (options: WajubInitOptions): WajubClient;
+  session(sessionId: string, options?: WajubInitOptions): WajubClient;
+  parsePublishableKey(key: string): { key: string; environment: "sandbox" | "live" };
+  createPayment(
+    publishableKey: string,
+    params: CreatePaymentParams,
+    options?: WajubInitOptions,
+  ): Promise<CreatePaymentResult>;
+}
+
+export interface WajubSDK {
+  checkout(config: EmbeddedConfig): void;
+  mount(container: string | HTMLElement, config: EmbeddedConfig): CheckoutInstance;
+  open(config: PopupConfig): PopupInstance;
+  preload(sessionId: string, options?: { iframe?: boolean }): void;
+  fetchSession(sessionId: string): Promise<SessionPreview>;
+  components(sessionId: string, options?: Partial<ComponentConfig>): ComponentsFactory;
+  confirmPayment(options: ConfirmPaymentOptions): Promise<{ status: string }>;
+  /** @deprecated Removed in SDK 2.1 — use components or mount(). */
+  createHeadless(config: EmbeddedConfig): never;
+  /** Wajub(pk | sessionId | options) — session-bound client with createPayment + mount. */
+  create: WajubFactory;
+  version: string;
+  sdkMajor: string;
+  checkoutOrigin: string;
+}
+
+declare global {
+  interface Window {
+    wajub: WajubSDK;
+    Wajub: WajubFactory;
+    WajubError: typeof WajubError;
+    WajubPay: { create(opts: EmbeddedConfig & { container: string | HTMLElement }): unknown };
+    __WajubCheckoutCore?: unknown;
+    __WajubComponentsCore?: unknown;
+    __WajubAppearance?: unknown;
+    __WajubError?: unknown;
+  }
+}
+
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wajub/js",
+  "version": "1.3.0",
+  "description": "JavaScript SDK for Wajub Components — hosted checkout, payment fields, and TypeScript types",
+  "license": "MIT",
+  "author": "Wajub",
+  "homepage": "https://wajub.com",
+  "keywords": [
+    "wajub",
+    "checkout",
+    "payments",
+    "mobile-money",
+    "embed",
+    "components"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/index.mjs"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./pure": {
+      "types": "./dist/pure.d.ts",
+      "import": "./dist/pure.mjs",
+      "default": "./dist/pure.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}