@snap-pay/js 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0
+
+Initial public release.
+
+- `Snap` class — constructs from a publishable key (`pk_test_` or `pk_live_`). Rejects secret keys.
+- `snap.elements({ clientSecret, appearance })` — creates an Elements container bound to a checkout session.
+- `snap.confirmPayment({ elements, clientSecret })` — reads the customer's selection from the mounted Elements and dispatches the payment. Attaches billing/customer/otp form data automatically when those elements are mounted.
+- Provider environment derived from the key prefix (`pk_live_*` → live).
+- Publishable-key HTTP client with a 30s AbortController-backed timeout.
+- Element registry — `@snap-pay/elements` populates it on import; `snap.elements(...).create(type)` looks up the factory.

package/README.md

@@ -0,0 +1,57 @@
+# @snap-pay/js
+
+SNAP.js — client-side SDK for creating and confirming SNAP payments in the browser.
+
+Pairs with `@snap-pay/elements` (UI components) and `@snap-pay/react` (React bindings).
+
+```bash
+bun add @snap-pay/js @snap-pay/elements
+```
+
+## Quick start
+
+```ts
+import { Snap } from "@snap-pay/js";
+import "@snap-pay/elements";
+
+const snap = new Snap("pk_test_…");
+const elements = snap.elements({ clientSecret: sessionId });
+const payment = elements.create("payment");
+payment.mount("#pay");
+
+const result = await snap.confirmPayment({ elements, clientSecret: sessionId });
+if (result.status === "succeeded") window.location.href = "/thanks";
+```
+
+## Options
+
+```ts
+new Snap(publishableKey, {
+  apiBase: "http://localhost:3210", // for local dev / self-hosted
+  cardFrameUrl: "http://localhost:3000/elements/card-frame",
+});
+```
+
+- `apiBase` — defaults to the SNAP production API. Point at a local Convex deployment during development.
+- `cardFrameUrl` — the origin hosting the Card iframe. Defaults to SNAP's hosted page; override for local dev or self-hosted deployments.
+
+## `confirmPayment`
+
+```ts
+const result = await snap.confirmPayment({ elements, clientSecret });
+// result.status: "succeeded" | "processing" | "pending" | "failed" | ...
+// result.transactionId: the SNAP transaction id
+```
+
+The SDK reads the customer's selection from the mounted Elements. Wallet selection sends `provider` directly; Card selection sends `provider: "mock"` alongside `card_token` / `card_brand` / `card_last4` metadata in sandbox. Live-mode Card tokenization throws explicitly — it's on the roadmap for a subsequent release.
+
+Any form-collecting elements (BillingAddressElement, CustomerElement, OtpElement) that are mounted inside the same Elements set contribute their values automatically — no extra plumbing.
+
+## Security
+
+- Always pass a **publishable** key (`pk_test_` or `pk_live_`). Secret keys (`sk_…`) belong on the server and must never ship to the browser — the constructor refuses them.
+- The `clientSecret` is a checkout session id. It grants payment rights only for that session and its owning merchant.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,319 @@
+'use strict';
+
+// src/errors.ts
+var SnapError = class extends Error {
+  constructor(message, code, type, requestId) {
+    super(message);
+    this.name = "SnapError";
+    this.code = code;
+    this.type = type;
+    this.requestId = requestId;
+  }
+};
+var SnapAuthenticationError = class extends SnapError {
+  constructor(message, requestId) {
+    super(message, "authentication_failed", "authentication_error", requestId);
+    this.name = "SnapAuthenticationError";
+  }
+};
+var SnapValidationError = class extends SnapError {
+  constructor(message, requestId) {
+    super(message, "validation_error", "invalid_request_error", requestId);
+    this.name = "SnapValidationError";
+  }
+};
+
+// src/session-client.ts
+var DEFAULT_API_BASE = "https://api.snap.so";
+var DEFAULT_TIMEOUT_MS = 3e4;
+async function fetchWithTimeout(url, init, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SnapError(
+        `Request timed out after ${timeoutMs} ms.`,
+        "timeout",
+        "api_connection_error"
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function throwFromResponse(response) {
+  let envelope;
+  try {
+    envelope = await response.json();
+  } catch {
+  }
+  const err = envelope?.error;
+  const message = err?.message ?? `Request failed with status ${response.status}`;
+  const code = err?.code ?? `http_${response.status}`;
+  const type = err?.type ?? "api_error";
+  const requestId = err?.request_id;
+  if (response.status === 401 || code === "authentication_failed") {
+    throw new SnapAuthenticationError(message, requestId);
+  }
+  if (response.status === 400 || code === "validation_error") {
+    throw new SnapValidationError(message, requestId);
+  }
+  throw new SnapError(message, code, type, requestId);
+}
+async function fetchSession(apiBase, publishableKey, clientSecret) {
+  const url = `${apiBase.replace(/\/+$/, "")}/v1/checkout/sessions/${encodeURIComponent(clientSecret)}`;
+  const response = await fetchWithTimeout(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${publishableKey}`,
+      Accept: "application/json"
+    },
+    // Elements are cross-origin by construction — the merchant's
+    // page is not on snap.so. `cors` is the fetch default but
+    // stating it makes the intent readable.
+    mode: "cors",
+    credentials: "omit"
+  });
+  if (!response.ok) await throwFromResponse(response);
+  const body = await response.json();
+  return toPublicSession(body);
+}
+async function startPayment(apiBase, publishableKey, clientSecret, provider, customer, metadata) {
+  const url = `${apiBase.replace(/\/+$/, "")}/v1/checkout/sessions/${encodeURIComponent(clientSecret)}/pay`;
+  const body = { provider };
+  if (customer) body.customer = customer;
+  if (metadata) Object.assign(body, metadata);
+  const response = await fetchWithTimeout(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${publishableKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(body),
+    mode: "cors",
+    credentials: "omit"
+  });
+  if (!response.ok) await throwFromResponse(response);
+  const wire = await response.json();
+  return { transactionId: wire.transaction_id, status: wire.status };
+}
+function toPublicSession(w) {
+  return {
+    id: w.id,
+    amount: w.amount,
+    currency: w.currency,
+    allowedProviders: w.allowed_providers,
+    status: w.status,
+    expiresAt: w.expires_at,
+    transactionId: w.transaction_id,
+    merchantName: w.merchant_name,
+    customer: w.customer,
+    successUrl: w.success_url,
+    cancelUrl: w.cancel_url
+  };
+}
+
+// src/elements.ts
+var REGISTRY = /* @__PURE__ */ new Map();
+function registerElement(type, factory) {
+  REGISTRY.set(type, factory);
+}
+function registeredTypes() {
+  return Array.from(REGISTRY.keys());
+}
+var SnapElements = class {
+  constructor(args) {
+    // Registration-order children — each carries a getter for its
+    // current selection. Insertion-order iteration on JavaScript
+    // Sets is stable; new elements append to the tail. Deregistration
+    // (via the returned cleanup fn) drops the child entirely so a
+    // destroyed element can't accidentally answer a later
+    // `_getSelection` call.
+    this.children = /* @__PURE__ */ new Set();
+    // Form-data getters, keyed by (type, opaque token). One element
+    // may register a getter and another element of the same type may
+    // register another — first-registered wins on `_getValue`, which
+    // matches the visual convention that the earliest-mounted
+    // element on the page is the primary one.
+    this.values = /* @__PURE__ */ new Map();
+    if (!args.options.clientSecret) {
+      throw new Error("`clientSecret` is required when creating Elements.");
+    }
+    this.clientSecret = args.options.clientSecret;
+    this.appearance = args.options.appearance ?? {};
+    this.publishableKey = args.publishableKey;
+    this.apiBase = args.apiBase;
+    this.environment = args.environment;
+    this.cardFrameUrl = args.cardFrameUrl;
+  }
+  create(type, options = {}) {
+    const factory = REGISTRY.get(type);
+    if (!factory) {
+      throw new Error(
+        `Element type "${type}" is not implemented in this SDK version. Supported: ${registeredTypes().map((t) => `'${t}'`).join(", ") || "(none \u2014 did you import @snap-pay/elements?)"}.`
+      );
+    }
+    return factory({
+      clientSecret: this.clientSecret,
+      appearance: this.appearance,
+      publishableKey: this.publishableKey,
+      apiBase: this.apiBase,
+      environment: this.environment,
+      cardFrameUrl: this.cardFrameUrl,
+      registerChild: (getSelection) => {
+        this.children.add(getSelection);
+        return () => this.children.delete(getSelection);
+      },
+      registerValue: (childType, getValue) => {
+        let bucket = this.values.get(childType);
+        if (!bucket) {
+          bucket = /* @__PURE__ */ new Set();
+          this.values.set(childType, bucket);
+        }
+        bucket.add(getValue);
+        return () => bucket.delete(getValue);
+      },
+      options
+    });
+  }
+  _getSelection() {
+    for (const getSelection of this.children) {
+      const s = getSelection();
+      if (s !== null) return s;
+    }
+    return null;
+  }
+  _getValue(type) {
+    const bucket = this.values.get(type);
+    if (!bucket) return null;
+    for (const getValue of bucket) {
+      const v = getValue();
+      if (v !== null && v !== void 0) return v;
+    }
+    return null;
+  }
+};
+
+// src/snap.ts
+var DEFAULT_CARD_FRAME_URL = "https://checkout.snap.so/elements/card-frame";
+var Snap = class {
+  constructor(publishableKey, options = {}) {
+    if (typeof publishableKey !== "string" || publishableKey.length === 0) {
+      throw new Error("Snap requires a publishable key (pk_test_\u2026 or pk_live_\u2026).");
+    }
+    if (!publishableKey.startsWith("pk_")) {
+      throw new Error(
+        "Publishable key must start with 'pk_test_' or 'pk_live_'. Secret keys (sk_\u2026) are for server code only and must NEVER be shipped to the browser."
+      );
+    }
+    this.publishableKey = publishableKey;
+    this.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    this.environment = publishableKey.startsWith("pk_live_") ? "live" : "sandbox";
+    this.cardFrameUrl = options.cardFrameUrl ?? DEFAULT_CARD_FRAME_URL;
+  }
+  // Creates an Elements set bound to a specific client secret
+  // (checkout session id). Returned handle stays local — the SDK
+  // deliberately does NOT stash it in module scope so multiple
+  // sessions can coexist on the same page (useful for merchants
+  // rendering upsell + main-cart Elements simultaneously).
+  elements(options) {
+    return new SnapElements({
+      publishableKey: this.publishableKey,
+      apiBase: this.apiBase,
+      environment: this.environment,
+      cardFrameUrl: this.cardFrameUrl,
+      options
+    });
+  }
+  // Confirms the payment by asking the server to dispatch it to
+  // the payment method the customer chose inside the mounted
+  // Elements. Two selection kinds:
+  //   - "provider": Wallet flow (evcPlus / zaad / …). Sends the
+  //     provider straight to the /pay endpoint.
+  //   - "card": Card Element sandbox flow. Sends provider="mock"
+  //     alongside `card_token` metadata so the backend can drive
+  //     the transaction through the mock adapter (real Mastercard
+  //     tokenization is deferred to a future PR). Live-mode card
+  //     tokens throw explicitly.
+  //
+  // Throws if no selection is available — the UI should keep the
+  // confirm button disabled until an Element reports a `change`
+  // with `complete: true`.
+  async confirmPayment(options) {
+    const selection = options.elements._getSelection();
+    if (selection === null) {
+      throw new Error(
+        "No payment method selected. Ask the customer to pick a provider before confirming."
+      );
+    }
+    const getVal = options.elements._getValue?.bind(options.elements);
+    const customer = getVal?.("customer") ?? void 0;
+    const billing = getVal?.("billingAddress") ?? void 0;
+    const otp = getVal?.("otp") ?? null;
+    const extraMetadata = {};
+    if (billing) {
+      const billingKeyMap = {
+        name: "billing_name",
+        line1: "billing_line1",
+        line2: "billing_line2",
+        city: "billing_city",
+        region: "billing_region",
+        postalCode: "billing_postal_code",
+        country: "billing_country"
+      };
+      for (const [k, v] of Object.entries(billing)) {
+        if (typeof v === "string" && v.length > 0) {
+          const wireKey = billingKeyMap[k];
+          if (wireKey) extraMetadata[wireKey] = v;
+        }
+      }
+    }
+    if (otp && typeof otp.code === "string" && otp.code.length > 0) {
+      extraMetadata.otp_code = otp.code;
+    }
+    if (selection.kind === "card") {
+      if (this.environment === "live") {
+        throw new Error(
+          "Card Element live-mode tokenization is not yet supported. Use a `pk_test_` key or wire a wallet Element for live payments."
+        );
+      }
+      const result2 = await startPayment(
+        this.apiBase,
+        this.publishableKey,
+        options.clientSecret,
+        "mock",
+        customer,
+        {
+          card_token: selection.token,
+          card_brand: selection.brand,
+          card_last4: selection.last4,
+          ...extraMetadata
+        }
+      );
+      return { transactionId: result2.transactionId, status: result2.status };
+    }
+    const result = await startPayment(
+      this.apiBase,
+      this.publishableKey,
+      options.clientSecret,
+      selection.provider,
+      customer,
+      Object.keys(extraMetadata).length > 0 ? extraMetadata : void 0
+    );
+    return { transactionId: result.transactionId, status: result.status };
+  }
+};
+
+exports.DEFAULT_API_BASE = DEFAULT_API_BASE;
+exports.Snap = Snap;
+exports.SnapAuthenticationError = SnapAuthenticationError;
+exports.SnapElements = SnapElements;
+exports.SnapError = SnapError;
+exports.SnapValidationError = SnapValidationError;
+exports.fetchSession = fetchSession;
+exports.registerElement = registerElement;
+exports.startPayment = startPayment;

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+import * as _snap_pay_types from '@snap-pay/types';
+import { Appearance, Environment, SnapSelection, ElementType, CreateElementOptions, SnapElementHandle, SnapElementsHandle, ElementsOptions, SnapOptions, ConfirmPaymentOptions, PaymentResult, PublicSession, CheckoutProvider } from '@snap-pay/types';
+export { Appearance, CheckoutProvider, ConfirmPaymentOptions, CreateElementOptions, ElementEventHandler, ElementEventMap, ElementEventName, ElementType, ElementsOptions, Environment, PaymentResult, PaymentStatus, PublicSession, PublicSessionResponse, SessionStatus, SnapElementHandle, SnapElementsHandle, SnapOptions, WalletProvider } from '@snap-pay/types';
+
+type ElementFactory = (args: {
+    clientSecret: string;
+    appearance: Appearance;
+    publishableKey: string;
+    apiBase: string;
+    environment: Environment;
+    cardFrameUrl: string | undefined;
+    registerChild: (getSelection: () => SnapSelection | null) => () => void;
+    registerValue: (type: ElementType, getValue: () => unknown | null) => () => void;
+    options: CreateElementOptions;
+}) => SnapElementHandle;
+declare function registerElement(type: ElementType, factory: ElementFactory): void;
+interface SnapElementsConstructorArgs {
+    publishableKey: string;
+    apiBase: string;
+    environment: Environment;
+    cardFrameUrl: string | undefined;
+    options: ElementsOptions;
+}
+declare class SnapElements implements SnapElementsHandle {
+    readonly clientSecret: string;
+    readonly appearance: Appearance;
+    private children;
+    private values;
+    private readonly publishableKey;
+    private readonly apiBase;
+    private readonly environment;
+    private readonly cardFrameUrl;
+    constructor(args: SnapElementsConstructorArgs);
+    create(type: ElementType, options?: CreateElementOptions): SnapElementHandle;
+    _getSelection(): SnapSelection | null;
+    _getValue(type: ElementType): unknown | null;
+}
+
+declare class Snap {
+    private readonly publishableKey;
+    private readonly apiBase;
+    private readonly environment;
+    private readonly cardFrameUrl;
+    constructor(publishableKey: string, options?: SnapOptions);
+    elements(options: ElementsOptions): SnapElements;
+    confirmPayment(options: ConfirmPaymentOptions): Promise<PaymentResult>;
+}
+
+declare class SnapError extends Error {
+    readonly code: string;
+    readonly type: string;
+    readonly requestId?: string;
+    constructor(message: string, code: string, type: string, requestId?: string);
+}
+declare class SnapAuthenticationError extends SnapError {
+    constructor(message: string, requestId?: string);
+}
+declare class SnapValidationError extends SnapError {
+    constructor(message: string, requestId?: string);
+}
+
+declare const DEFAULT_API_BASE = "https://api.snap.so";
+declare function fetchSession(apiBase: string, publishableKey: string, clientSecret: string): Promise<PublicSession>;
+declare function startPayment(apiBase: string, publishableKey: string, clientSecret: string, provider: CheckoutProvider, customer?: {
+    name?: string;
+    email?: string;
+    phone?: string;
+    country?: string;
+}, metadata?: Record<string, string>): Promise<{
+    transactionId: string;
+    status: _snap_pay_types.PaymentStatus;
+}>;
+
+export { DEFAULT_API_BASE, type ElementFactory, Snap, SnapAuthenticationError, SnapElements, SnapError, SnapValidationError, fetchSession, registerElement, startPayment };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import * as _snap_pay_types from '@snap-pay/types';
+import { Appearance, Environment, SnapSelection, ElementType, CreateElementOptions, SnapElementHandle, SnapElementsHandle, ElementsOptions, SnapOptions, ConfirmPaymentOptions, PaymentResult, PublicSession, CheckoutProvider } from '@snap-pay/types';
+export { Appearance, CheckoutProvider, ConfirmPaymentOptions, CreateElementOptions, ElementEventHandler, ElementEventMap, ElementEventName, ElementType, ElementsOptions, Environment, PaymentResult, PaymentStatus, PublicSession, PublicSessionResponse, SessionStatus, SnapElementHandle, SnapElementsHandle, SnapOptions, WalletProvider } from '@snap-pay/types';
+
+type ElementFactory = (args: {
+    clientSecret: string;
+    appearance: Appearance;
+    publishableKey: string;
+    apiBase: string;
+    environment: Environment;
+    cardFrameUrl: string | undefined;
+    registerChild: (getSelection: () => SnapSelection | null) => () => void;
+    registerValue: (type: ElementType, getValue: () => unknown | null) => () => void;
+    options: CreateElementOptions;
+}) => SnapElementHandle;
+declare function registerElement(type: ElementType, factory: ElementFactory): void;
+interface SnapElementsConstructorArgs {
+    publishableKey: string;
+    apiBase: string;
+    environment: Environment;
+    cardFrameUrl: string | undefined;
+    options: ElementsOptions;
+}
+declare class SnapElements implements SnapElementsHandle {
+    readonly clientSecret: string;
+    readonly appearance: Appearance;
+    private children;
+    private values;
+    private readonly publishableKey;
+    private readonly apiBase;
+    private readonly environment;
+    private readonly cardFrameUrl;
+    constructor(args: SnapElementsConstructorArgs);
+    create(type: ElementType, options?: CreateElementOptions): SnapElementHandle;
+    _getSelection(): SnapSelection | null;
+    _getValue(type: ElementType): unknown | null;
+}
+
+declare class Snap {
+    private readonly publishableKey;
+    private readonly apiBase;
+    private readonly environment;
+    private readonly cardFrameUrl;
+    constructor(publishableKey: string, options?: SnapOptions);
+    elements(options: ElementsOptions): SnapElements;
+    confirmPayment(options: ConfirmPaymentOptions): Promise<PaymentResult>;
+}
+
+declare class SnapError extends Error {
+    readonly code: string;
+    readonly type: string;
+    readonly requestId?: string;
+    constructor(message: string, code: string, type: string, requestId?: string);
+}
+declare class SnapAuthenticationError extends SnapError {
+    constructor(message: string, requestId?: string);
+}
+declare class SnapValidationError extends SnapError {
+    constructor(message: string, requestId?: string);
+}
+
+declare const DEFAULT_API_BASE = "https://api.snap.so";
+declare function fetchSession(apiBase: string, publishableKey: string, clientSecret: string): Promise<PublicSession>;
+declare function startPayment(apiBase: string, publishableKey: string, clientSecret: string, provider: CheckoutProvider, customer?: {
+    name?: string;
+    email?: string;
+    phone?: string;
+    country?: string;
+}, metadata?: Record<string, string>): Promise<{
+    transactionId: string;
+    status: _snap_pay_types.PaymentStatus;
+}>;
+
+export { DEFAULT_API_BASE, type ElementFactory, Snap, SnapAuthenticationError, SnapElements, SnapError, SnapValidationError, fetchSession, registerElement, startPayment };

package/dist/index.js

@@ -0,0 +1,309 @@
+// src/errors.ts
+var SnapError = class extends Error {
+  constructor(message, code, type, requestId) {
+    super(message);
+    this.name = "SnapError";
+    this.code = code;
+    this.type = type;
+    this.requestId = requestId;
+  }
+};
+var SnapAuthenticationError = class extends SnapError {
+  constructor(message, requestId) {
+    super(message, "authentication_failed", "authentication_error", requestId);
+    this.name = "SnapAuthenticationError";
+  }
+};
+var SnapValidationError = class extends SnapError {
+  constructor(message, requestId) {
+    super(message, "validation_error", "invalid_request_error", requestId);
+    this.name = "SnapValidationError";
+  }
+};
+
+// src/session-client.ts
+var DEFAULT_API_BASE = "https://api.snap.so";
+var DEFAULT_TIMEOUT_MS = 3e4;
+async function fetchWithTimeout(url, init, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SnapError(
+        `Request timed out after ${timeoutMs} ms.`,
+        "timeout",
+        "api_connection_error"
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function throwFromResponse(response) {
+  let envelope;
+  try {
+    envelope = await response.json();
+  } catch {
+  }
+  const err = envelope?.error;
+  const message = err?.message ?? `Request failed with status ${response.status}`;
+  const code = err?.code ?? `http_${response.status}`;
+  const type = err?.type ?? "api_error";
+  const requestId = err?.request_id;
+  if (response.status === 401 || code === "authentication_failed") {
+    throw new SnapAuthenticationError(message, requestId);
+  }
+  if (response.status === 400 || code === "validation_error") {
+    throw new SnapValidationError(message, requestId);
+  }
+  throw new SnapError(message, code, type, requestId);
+}
+async function fetchSession(apiBase, publishableKey, clientSecret) {
+  const url = `${apiBase.replace(/\/+$/, "")}/v1/checkout/sessions/${encodeURIComponent(clientSecret)}`;
+  const response = await fetchWithTimeout(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${publishableKey}`,
+      Accept: "application/json"
+    },
+    // Elements are cross-origin by construction — the merchant's
+    // page is not on snap.so. `cors` is the fetch default but
+    // stating it makes the intent readable.
+    mode: "cors",
+    credentials: "omit"
+  });
+  if (!response.ok) await throwFromResponse(response);
+  const body = await response.json();
+  return toPublicSession(body);
+}
+async function startPayment(apiBase, publishableKey, clientSecret, provider, customer, metadata) {
+  const url = `${apiBase.replace(/\/+$/, "")}/v1/checkout/sessions/${encodeURIComponent(clientSecret)}/pay`;
+  const body = { provider };
+  if (customer) body.customer = customer;
+  if (metadata) Object.assign(body, metadata);
+  const response = await fetchWithTimeout(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${publishableKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(body),
+    mode: "cors",
+    credentials: "omit"
+  });
+  if (!response.ok) await throwFromResponse(response);
+  const wire = await response.json();
+  return { transactionId: wire.transaction_id, status: wire.status };
+}
+function toPublicSession(w) {
+  return {
+    id: w.id,
+    amount: w.amount,
+    currency: w.currency,
+    allowedProviders: w.allowed_providers,
+    status: w.status,
+    expiresAt: w.expires_at,
+    transactionId: w.transaction_id,
+    merchantName: w.merchant_name,
+    customer: w.customer,
+    successUrl: w.success_url,
+    cancelUrl: w.cancel_url
+  };
+}
+
+// src/elements.ts
+var REGISTRY = /* @__PURE__ */ new Map();
+function registerElement(type, factory) {
+  REGISTRY.set(type, factory);
+}
+function registeredTypes() {
+  return Array.from(REGISTRY.keys());
+}
+var SnapElements = class {
+  constructor(args) {
+    // Registration-order children — each carries a getter for its
+    // current selection. Insertion-order iteration on JavaScript
+    // Sets is stable; new elements append to the tail. Deregistration
+    // (via the returned cleanup fn) drops the child entirely so a
+    // destroyed element can't accidentally answer a later
+    // `_getSelection` call.
+    this.children = /* @__PURE__ */ new Set();
+    // Form-data getters, keyed by (type, opaque token). One element
+    // may register a getter and another element of the same type may
+    // register another — first-registered wins on `_getValue`, which
+    // matches the visual convention that the earliest-mounted
+    // element on the page is the primary one.
+    this.values = /* @__PURE__ */ new Map();
+    if (!args.options.clientSecret) {
+      throw new Error("`clientSecret` is required when creating Elements.");
+    }
+    this.clientSecret = args.options.clientSecret;
+    this.appearance = args.options.appearance ?? {};
+    this.publishableKey = args.publishableKey;
+    this.apiBase = args.apiBase;
+    this.environment = args.environment;
+    this.cardFrameUrl = args.cardFrameUrl;
+  }
+  create(type, options = {}) {
+    const factory = REGISTRY.get(type);
+    if (!factory) {
+      throw new Error(
+        `Element type "${type}" is not implemented in this SDK version. Supported: ${registeredTypes().map((t) => `'${t}'`).join(", ") || "(none \u2014 did you import @snap-pay/elements?)"}.`
+      );
+    }
+    return factory({
+      clientSecret: this.clientSecret,
+      appearance: this.appearance,
+      publishableKey: this.publishableKey,
+      apiBase: this.apiBase,
+      environment: this.environment,
+      cardFrameUrl: this.cardFrameUrl,
+      registerChild: (getSelection) => {
+        this.children.add(getSelection);
+        return () => this.children.delete(getSelection);
+      },
+      registerValue: (childType, getValue) => {
+        let bucket = this.values.get(childType);
+        if (!bucket) {
+          bucket = /* @__PURE__ */ new Set();
+          this.values.set(childType, bucket);
+        }
+        bucket.add(getValue);
+        return () => bucket.delete(getValue);
+      },
+      options
+    });
+  }
+  _getSelection() {
+    for (const getSelection of this.children) {
+      const s = getSelection();
+      if (s !== null) return s;
+    }
+    return null;
+  }
+  _getValue(type) {
+    const bucket = this.values.get(type);
+    if (!bucket) return null;
+    for (const getValue of bucket) {
+      const v = getValue();
+      if (v !== null && v !== void 0) return v;
+    }
+    return null;
+  }
+};
+
+// src/snap.ts
+var DEFAULT_CARD_FRAME_URL = "https://checkout.snap.so/elements/card-frame";
+var Snap = class {
+  constructor(publishableKey, options = {}) {
+    if (typeof publishableKey !== "string" || publishableKey.length === 0) {
+      throw new Error("Snap requires a publishable key (pk_test_\u2026 or pk_live_\u2026).");
+    }
+    if (!publishableKey.startsWith("pk_")) {
+      throw new Error(
+        "Publishable key must start with 'pk_test_' or 'pk_live_'. Secret keys (sk_\u2026) are for server code only and must NEVER be shipped to the browser."
+      );
+    }
+    this.publishableKey = publishableKey;
+    this.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    this.environment = publishableKey.startsWith("pk_live_") ? "live" : "sandbox";
+    this.cardFrameUrl = options.cardFrameUrl ?? DEFAULT_CARD_FRAME_URL;
+  }
+  // Creates an Elements set bound to a specific client secret
+  // (checkout session id). Returned handle stays local — the SDK
+  // deliberately does NOT stash it in module scope so multiple
+  // sessions can coexist on the same page (useful for merchants
+  // rendering upsell + main-cart Elements simultaneously).
+  elements(options) {
+    return new SnapElements({
+      publishableKey: this.publishableKey,
+      apiBase: this.apiBase,
+      environment: this.environment,
+      cardFrameUrl: this.cardFrameUrl,
+      options
+    });
+  }
+  // Confirms the payment by asking the server to dispatch it to
+  // the payment method the customer chose inside the mounted
+  // Elements. Two selection kinds:
+  //   - "provider": Wallet flow (evcPlus / zaad / …). Sends the
+  //     provider straight to the /pay endpoint.
+  //   - "card": Card Element sandbox flow. Sends provider="mock"
+  //     alongside `card_token` metadata so the backend can drive
+  //     the transaction through the mock adapter (real Mastercard
+  //     tokenization is deferred to a future PR). Live-mode card
+  //     tokens throw explicitly.
+  //
+  // Throws if no selection is available — the UI should keep the
+  // confirm button disabled until an Element reports a `change`
+  // with `complete: true`.
+  async confirmPayment(options) {
+    const selection = options.elements._getSelection();
+    if (selection === null) {
+      throw new Error(
+        "No payment method selected. Ask the customer to pick a provider before confirming."
+      );
+    }
+    const getVal = options.elements._getValue?.bind(options.elements);
+    const customer = getVal?.("customer") ?? void 0;
+    const billing = getVal?.("billingAddress") ?? void 0;
+    const otp = getVal?.("otp") ?? null;
+    const extraMetadata = {};
+    if (billing) {
+      const billingKeyMap = {
+        name: "billing_name",
+        line1: "billing_line1",
+        line2: "billing_line2",
+        city: "billing_city",
+        region: "billing_region",
+        postalCode: "billing_postal_code",
+        country: "billing_country"
+      };
+      for (const [k, v] of Object.entries(billing)) {
+        if (typeof v === "string" && v.length > 0) {
+          const wireKey = billingKeyMap[k];
+          if (wireKey) extraMetadata[wireKey] = v;
+        }
+      }
+    }
+    if (otp && typeof otp.code === "string" && otp.code.length > 0) {
+      extraMetadata.otp_code = otp.code;
+    }
+    if (selection.kind === "card") {
+      if (this.environment === "live") {
+        throw new Error(
+          "Card Element live-mode tokenization is not yet supported. Use a `pk_test_` key or wire a wallet Element for live payments."
+        );
+      }
+      const result2 = await startPayment(
+        this.apiBase,
+        this.publishableKey,
+        options.clientSecret,
+        "mock",
+        customer,
+        {
+          card_token: selection.token,
+          card_brand: selection.brand,
+          card_last4: selection.last4,
+          ...extraMetadata
+        }
+      );
+      return { transactionId: result2.transactionId, status: result2.status };
+    }
+    const result = await startPayment(
+      this.apiBase,
+      this.publishableKey,
+      options.clientSecret,
+      selection.provider,
+      customer,
+      Object.keys(extraMetadata).length > 0 ? extraMetadata : void 0
+    );
+    return { transactionId: result.transactionId, status: result.status };
+  }
+};
+
+export { DEFAULT_API_BASE, Snap, SnapAuthenticationError, SnapElements, SnapError, SnapValidationError, fetchSession, registerElement, startPayment };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@snap-pay/js",
+  "version": "1.0.0",
+  "description": "SNAP.js — client-side SDK for creating and confirming SNAP payments in the browser.",
+  "license": "MIT",
+  "author": "SNAP",
+  "homepage": "https://github.com/khaledhussein957/SNAP/tree/main/packages/js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khaledhussein957/SNAP.git",
+    "directory": "packages/js"
+  },
+  "bugs": {
+    "url": "https://github.com/khaledhussein957/SNAP/issues"
+  },
+  "keywords": ["snap", "payments", "checkout", "sdk", "browser", "somalia", "mobile-money"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@snap-pay/types": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.9"
+  }
+}