@invonetwork/web-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-06-30
+
+Initial scaffold.
+
+- `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
+  `createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
+  - Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
+    `purchaseReference`, and `rail:"steam"` rejected before the network call
+    (`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
+- `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
+  `confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
+  interchangeable-methods flow (§4.6).
+  - Optional `refreshToken` hook: transparently re-mints and retries once on
+    `SDK_TOKEN_EXPIRED` (§11.2).
+- Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
+- Tests: HTTP layer, server request mapping + purchase guards, browser client
+  flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
+- Contracts extracted + auditor-verified against the INVO backend.
+
+### Hardening (independent red-team pass)
+- **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
+  `initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
+  `guardianApproval` block on the guardian path, so callers don't route into the
+  PIN UI by mistake (§4.3).
+- `usdAmount` validation tightened: rejects non-plain-decimal strings
+  (`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
+- Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
+  instead of silently surfacing as empty strings.
+- `getOrderDetails` requires at least one of `orderId`/`transactionId`.
+- Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
+  (never replays a single-use assertion) and single-flights concurrent refreshes.
+- `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
+  in cleartext.
+- Published tarball excludes sourcemaps (no proprietary source shipped).

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Invo Tech Inc. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Invo Tech Inc. ("INVO"). The Software
+is licensed, not sold, for use solely in connection with integrating the INVO
+platform under a separate written agreement with INVO.
+
+Without a valid agreement with INVO, you may not use, copy, modify, merge,
+publish, distribute, sublicense, or sell copies of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL INVO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE.
+
+NOTE: Licensing for a partner-distributed SDK is a business decision — if INVO
+prefers a permissive license (e.g. MIT/Apache-2.0) so partners can freely
+vendor the package, replace this file and the "license" field in package.json.

package/README.md

@@ -0,0 +1,142 @@
+# @invonetwork/web-sdk
+
+INVO Web SDK for partner **web** platforms — **currency purchase** + **passkey (WebAuthn)** verification for cross-game **sends/transfers**. The web analog of the Unity/UE plugins.
+
+> **Status:** v0.1.0. The backend this wraps is **live** — the INVO-hosted checkout page, sessions, rails, and webhooks are deployed on sandbox + production, so you can build and test against sandbox today. Full, current API reference + flow docs: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
+
+## Install
+
+```bash
+npm install @invonetwork/web-sdk
+```
+
+> Published under the INVO-owned `@invonetwork` npm org. (Until the first `npm publish`, develop with `npm link` or a local install.)
+
+## Two entry points (the game secret never reaches the browser)
+
+| Import | Runs | Holds | Does |
+|---|---|---|---|
+| `@invonetwork/web-sdk/server` | your server (Node ≥18) | the **game secret** | mint player token, initiate send/transfer, currency purchase |
+| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | enroll passkey, approve, self-claim |
+
+## Base URLs
+
+- Production: `https://invo.network`
+- Sandbox: `https://sandbox.invo.network/sandbox`
+
+`baseUrl` must be `https://` (the game secret and player token travel in request headers); `http://localhost` is allowed for local development only.
+
+## Server (Node)
+
+```ts
+import { InvoServer } from "@invonetwork/web-sdk/server";
+
+const invo = new InvoServer({
+  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
+  baseUrl: "https://sandbox.invo.network/sandbox",
+});
+
+// 1. mint a short-lived token for the browser
+const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com" });
+
+// 2a. buy currency — hosted checkout (recommended; INVO's page handles the processor)
+const { checkoutUrl } = await invo.createCheckout({
+  playerEmail: "p@example.com",
+  usdAmount: "20.00",
+  rail: "platform",   // optional: "platform" (card, default) | "game" | "steam"
+  metadata: { yourOrderId: "ord_42" },  // echoed back on the purchase.completed webhook
+});
+// → open checkoutUrl in a WebView/redirect or an iframe (see "Consuming the checkout")
+
+// 2b. or initiate a send; inspect verificationMethod
+const send = await invo.initiateSend({
+  clientRequestId: crypto.randomUUID(),
+  senderPlayerName: "P", senderPlayerEmail: "p@example.com", senderPlayerPhone: "+15555550100",
+  receiverPlayerEmail: "q@example.com", receiverPlayerPhone: "+15555550111",
+  receivingGameId: 123456, amount: "50",
+});
+if (send.verificationMethod === "in_app") {
+  // hand send.transactionId + the player token to the browser to approve via passkey
+} else if (send.verificationMethod === "sms") {
+  // sender not enrolled — fall back to the SMS-PIN UI
+} else if (send.guardianApproval) {
+  // minor/guardian path (HTTP 202): pending guardian approval — do NOT show the PIN UI
+}
+```
+
+## Browser
+
+```ts
+import { InvoClient } from "@invonetwork/web-sdk";
+
+const invo = new InvoClient({
+  token,
+  baseUrl: "https://sandbox.invo.network/sandbox",
+  // Optional: player tokens live ~15 min. If a call fails with SDK_TOKEN_EXPIRED,
+  // the SDK calls this once for a fresh token (re-minted by your backend) and
+  // retries the request transparently.
+  refreshToken: () => fetch("/invo/token").then((r) => r.json()).then((j) => j.token),
+});
+
+await invo.enrollPasskey();                       // once per user
+await invo.approveSend(transactionId);            // or approveTransfer(...)
+await invo.confirmReceiptSend(transactionId);     // recipient self-claim
+
+// Interchangeable methods (optional): prove an already-enrolled method (e.g. the
+// INVO app device key) to authorize adding this passkey, then enroll it.
+await invo.linkDevice(linkId);                     // → { status: "authorized" }
+await invo.enrollPasskey();
+```
+
+Currency purchase has **no browser SDK method** — the server mints `checkoutUrl`; the browser just opens it.
+
+## Consuming the checkout (browser)
+
+`createCheckout` returns a `checkoutUrl` (15-min, single-use). Open it either way:
+
+- **WebView / full-page redirect** (works everywhere, no setup): on success the page redirects to your `successUrl`.
+- **Embedded `<iframe>`** — **works by default** (any https origin may frame it; no allow-listing): the page does *not* redirect your top window — listen for the `INVO_CHECKOUT_COMPLETE` postMessage.
+
+```ts
+const iframe = document.createElement("iframe");
+iframe.src = checkoutUrl;
+iframe.style.cssText = "width:440px;height:720px;border:0";
+document.body.appendChild(iframe);
+
+window.addEventListener("message", (e) => {
+  if (e.origin !== "https://invo.network") return;      // sandbox: "https://sandbox.invo.network"
+  if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
+    // UX hint only (unsigned). data = { status:'success', new_balance, currency_name, transaction_id }
+    refreshBalanceOptimistically(e.data.data.new_balance);
+  }
+});
+```
+
+The hosted page handles **card entry, saved cards, and 3-D Secure** (including a top-level break-out when embedded). You build no payment UI and never touch card data.
+
+**Completion is authoritative via the `purchase.completed` webhook** (HMAC-signed). **Dedupe on `X-Invo-Idempotency-Key`** (stable across retries/replays — *not* `X-Invo-Event-Id`, which changes per delivery). Treat `INVO_CHECKOUT_COMPLETE` as a UX hint; grant currency off the webhook (or re-read the balance).
+
+## Payment rails (neutral names)
+
+The `rail` passed to `createCheckout` selects the in-page experience — all branded as INVO, no visible redirect:
+- `"platform"` (default) — card checkout on the hosted page.
+- `"game"` — regional / game-store methods, embedded in-page.
+- `"steam"` — Steam titles use the dedicated Steam flow; a `steam` session only shows an in-client hand-off, it doesn't drive the purchase.
+
+Provider/processor names are an internal backend detail and never appear in the API. (`purchaseCurrency()` on the server is an advanced direct path for partners who tokenize cards themselves — most integrations should use `createCheckout`.)
+
+## Errors
+
+Every failure throws `InvoError` with `.code` (when present), `.status`, `.message`, `.body`. Branch on `.code`; for the handful of state errors with no `code` (e.g. `receiver_not_enrolled_use_claim_code`), use `.message` / the `.isReceiverNotEnrolled` helper. `.isTokenExpired` flags an expired token — if you pass `refreshToken` to `InvoClient` the SDK handles this for you (one re-mint + retry); otherwise re-mint server-side and retry. Client-side input guards (e.g. a USD amount outside `0 < x ≤ 999.99`, a missing `purchaseReference`, or `rail:"steam"` on `purchaseCurrency`) also throw `InvoError` with `.status === 0` before any network call.
+
+## Scripts
+
+```bash
+npm run build       # tsup → dist (ESM + CJS + d.ts)
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+```
+
+## License
+
+Proprietary — © Invo Tech Inc. See `LICENSE` (the partner-distribution license is a business decision; swap to MIT/Apache-2.0 if preferred).

package/dist/chunk-KUQVVH2P.js

@@ -0,0 +1,121 @@
+// src/shared/errors.ts
+var InvoError = class _InvoError extends Error {
+  constructor(args) {
+    super(args.message);
+    this.name = "InvoError";
+    this.code = args.code;
+    this.status = args.status;
+    this.body = args.body ?? null;
+    Object.setPrototypeOf(this, _InvoError.prototype);
+  }
+  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
+  get isReceiverNotEnrolled() {
+    return this.code === "receiver_not_enrolled_use_claim_code" || /receiver_not_enrolled_use_claim_code/i.test(this.message);
+  }
+  /** True if the session/SDK token has expired and the caller should re-mint + retry. */
+  get isTokenExpired() {
+    return this.code === "SDK_TOKEN_EXPIRED";
+  }
+};
+function errorFromResponse(status, body) {
+  let message = `INVO request failed (HTTP ${status})`;
+  let code;
+  if (body && typeof body === "object") {
+    const b = body;
+    if (typeof b["code"] === "string") code = b["code"];
+    if (typeof b["error"] === "string") message = b["error"];
+    else if (typeof b["message"] === "string") message = b["message"];
+  } else if (typeof body === "string" && body.trim()) {
+    message = body;
+  }
+  return new InvoError({ message, code, status, body });
+}
+
+// src/shared/http.ts
+var DEFAULT_TIMEOUT = 3e4;
+function assertSecureBaseUrl(baseUrl) {
+  let u;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid baseUrl: ${baseUrl}`);
+  }
+  const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
+  if (u.protocol === "https:" || u.protocol === "http:" && isLocal) return;
+  throw new Error(
+    `baseUrl must use https:// (got "${u.protocol}//"). Plaintext would expose the token/secret on the wire.`
+  );
+}
+var Http = class {
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    const f = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new Error(
+        "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
+      );
+    }
+    this.fetchImpl = f;
+    this.userAgent = opts.userAgent;
+  }
+  async post(path, body, auth) {
+    return this.request("POST", path, body, auth);
+  }
+  async get(path, auth) {
+    return this.request("GET", path, void 0, auth);
+  }
+  authHeaders(auth) {
+    switch (auth.kind) {
+      case "game-secret":
+        return { "X-Game-Secret-Key": auth.secret };
+      case "bearer":
+        return { Authorization: `Bearer ${auth.token}` };
+      case "none":
+        return {};
+    }
+  }
+  async request(method, path, body, auth) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Accept: "application/json",
+      ...this.authHeaders(auth)
+    };
+    if (this.userAgent) headers["User-Agent"] = this.userAgent;
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new InvoError({
+        message: err instanceof Error && err.name === "AbortError" ? `Request to ${path} timed out after ${this.timeoutMs}ms` : `Network error calling ${path}: ${err?.message ?? err}`,
+        status: 0,
+        body: null
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) throw errorFromResponse(res.status, parsed);
+    return parsed ?? {};
+  }
+};
+
+export { Http, InvoError, assertSecureBaseUrl };
+//# sourceMappingURL=chunk-KUQVVH2P.js.map
+//# sourceMappingURL=chunk-KUQVVH2P.js.map

package/dist/errors-B7rVID2r.d.cts

@@ -0,0 +1,156 @@
+/** Public, neutral payment-rail names. Provider/processor names are an internal
+ *  backend routing detail and are deliberately NOT exposed here. */
+type Rail = "platform" | "game" | "steam";
+/** Verification method returned by initiate-send / initiate-transfer. */
+type VerificationMethod = "in_app" | "sms";
+interface InvoConfig {
+    /** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
+    baseUrl: string;
+    /** Per-request timeout (ms). Default 30000. */
+    timeoutMs?: number;
+    /** Optional fetch override (e.g. a custom agent). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface ServerConfig extends InvoConfig {
+    /** The game secret. Server-side ONLY — never ship this to a browser. */
+    gameSecret: string;
+}
+interface ClientConfig extends InvoConfig {
+    /** Short-lived, game-scoped player token minted server-side via mintPlayerToken(). */
+    token: string;
+    /**
+     * Optional. Called when a request fails with `SDK_TOKEN_EXPIRED` (token TTL is
+     * ~15 min, §11.2). Return a freshly minted token — typically by calling your own
+     * backend, which re-mints server-side with the game secret. The failed request
+     * is retried once with the new token, and the client keeps using it thereafter.
+     */
+    refreshToken?: () => Promise<string> | string;
+}
+interface PlayerToken {
+    token: string;
+    expiresAt: string;
+    identityId: string;
+}
+interface InitiateSendInput {
+    clientRequestId: string;
+    senderPlayerName: string;
+    senderPlayerEmail: string;
+    senderPlayerPhone: string;
+    receiverPlayerEmail: string;
+    receiverPlayerPhone: string;
+    receivingGameId: string | number;
+    amount: string | number;
+}
+interface InitiateTransferInput {
+    clientRequestId: string;
+    sourcePlayerName: string;
+    sourcePlayerEmail: string;
+    sourcePlayerPhone: string;
+    targetPlayerEmail: string;
+    targetPlayerPhone: string;
+    targetGameId: string | number;
+    amount: string | number;
+}
+interface InitiateResult {
+    transactionId: string;
+    /**
+     * "in_app" → proceed to the passkey approve flow; "sms" → un-enrolled fallback.
+     * `undefined` when the backend returned the minor/guardian path (HTTP 202) and
+     * no verification method applies yet — check `guardianApproval` and do NOT route
+     * the user into the SMS-PIN UI in that case (§4.3 / §8).
+     */
+    verificationMethod: VerificationMethod | undefined;
+    /** Present on the minor/guardian path (HTTP 202): the backend's guardian_approval block. */
+    guardianApproval?: unknown;
+    /** Full raw backend body (fees preview, order id, new balance, guardian block, …). */
+    raw: Record<string, unknown>;
+}
+interface CreateCheckoutInput {
+    playerEmail: string;
+    usdAmount: string | number;
+    /** Which rail the hosted page presents. Default "platform" (card). The page
+     *  renders the right experience per rail — all branded as INVO. */
+    rail?: Rail;
+    successUrl?: string;
+    cancelUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateCheckoutResult {
+    sessionId: string;
+    /** Send the browser here; INVO's hosted page handles the processor + 3-D Secure. */
+    checkoutUrl: string;
+    expiresAt: string;
+    raw: Record<string, unknown>;
+}
+interface PurchaseInput {
+    playerEmail: string;
+    usdAmount: string | number;
+    /** Idempotency key. Required. */
+    purchaseReference: string;
+    rail?: Rail;
+    /** Required for the `platform` rail: a tokenized payment method. */
+    paymentMethodId?: string;
+    savedCardId?: string;
+    playerName?: string;
+    playerPhone?: string;
+}
+type PurchaseStatus = "success" | "requires_action" | "pending_payment";
+interface PurchaseResult {
+    status: PurchaseStatus;
+    /** Present when status === "requires_action" (client-side 3-D Secure step). */
+    clientSecret?: string;
+    paymentIntentId?: string;
+    /** Present when status === "pending_payment" (redirect the browser here). */
+    paymentUrl?: string;
+    transactionId?: string;
+    orderId?: string;
+    newBalance?: string | number | null;
+    raw: Record<string, unknown>;
+}
+interface ApproveResult {
+    status: string;
+    next: string;
+    transactionId: string;
+    /** transfer-approve returns the sender's claim code; send-approve does not. */
+    claimCode?: string;
+    claimCodeExpiresAt?: string;
+    raw: Record<string, unknown>;
+}
+interface ConfirmReceiptResult {
+    status: string;
+    raw: Record<string, unknown>;
+}
+interface LinkDeviceResult {
+    /** "authorized" on success — a single-use grant that register/complete consumes. */
+    status: string;
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Typed error for every INVO backend failure.
+ *
+ * The backend error envelope is usually `{ "error": <message>, "code": <STABLE_CODE> }`,
+ * but a few txn-state/claim errors carry only `error` (no `code`) and some use
+ * `{ "status": "error", "message": ... }`. So `code` may be undefined — branch on
+ * `code` when present, else fall back to `message`. See the handoff doc §8.
+ */
+declare class InvoError extends Error {
+    /** Stable machine code from the backend (`code`), when present. */
+    readonly code: string | undefined;
+    /** HTTP status. */
+    readonly status: number;
+    /** Raw parsed body, for debugging / fields not surfaced here. */
+    readonly body: unknown;
+    constructor(args: {
+        message: string;
+        code?: string;
+        status: number;
+        body?: unknown;
+    });
+    /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
+    get isReceiverNotEnrolled(): boolean;
+    /** True if the session/SDK token has expired and the caller should re-mint + retry. */
+    get isTokenExpired(): boolean;
+}
+
+export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h };

package/dist/errors-B7rVID2r.d.ts

@@ -0,0 +1,156 @@
+/** Public, neutral payment-rail names. Provider/processor names are an internal
+ *  backend routing detail and are deliberately NOT exposed here. */
+type Rail = "platform" | "game" | "steam";
+/** Verification method returned by initiate-send / initiate-transfer. */
+type VerificationMethod = "in_app" | "sms";
+interface InvoConfig {
+    /** API base URL. Prod: "https://invo.network". Sandbox: "https://sandbox.invo.network/sandbox". */
+    baseUrl: string;
+    /** Per-request timeout (ms). Default 30000. */
+    timeoutMs?: number;
+    /** Optional fetch override (e.g. a custom agent). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface ServerConfig extends InvoConfig {
+    /** The game secret. Server-side ONLY — never ship this to a browser. */
+    gameSecret: string;
+}
+interface ClientConfig extends InvoConfig {
+    /** Short-lived, game-scoped player token minted server-side via mintPlayerToken(). */
+    token: string;
+    /**
+     * Optional. Called when a request fails with `SDK_TOKEN_EXPIRED` (token TTL is
+     * ~15 min, §11.2). Return a freshly minted token — typically by calling your own
+     * backend, which re-mints server-side with the game secret. The failed request
+     * is retried once with the new token, and the client keeps using it thereafter.
+     */
+    refreshToken?: () => Promise<string> | string;
+}
+interface PlayerToken {
+    token: string;
+    expiresAt: string;
+    identityId: string;
+}
+interface InitiateSendInput {
+    clientRequestId: string;
+    senderPlayerName: string;
+    senderPlayerEmail: string;
+    senderPlayerPhone: string;
+    receiverPlayerEmail: string;
+    receiverPlayerPhone: string;
+    receivingGameId: string | number;
+    amount: string | number;
+}
+interface InitiateTransferInput {
+    clientRequestId: string;
+    sourcePlayerName: string;
+    sourcePlayerEmail: string;
+    sourcePlayerPhone: string;
+    targetPlayerEmail: string;
+    targetPlayerPhone: string;
+    targetGameId: string | number;
+    amount: string | number;
+}
+interface InitiateResult {
+    transactionId: string;
+    /**
+     * "in_app" → proceed to the passkey approve flow; "sms" → un-enrolled fallback.
+     * `undefined` when the backend returned the minor/guardian path (HTTP 202) and
+     * no verification method applies yet — check `guardianApproval` and do NOT route
+     * the user into the SMS-PIN UI in that case (§4.3 / §8).
+     */
+    verificationMethod: VerificationMethod | undefined;
+    /** Present on the minor/guardian path (HTTP 202): the backend's guardian_approval block. */
+    guardianApproval?: unknown;
+    /** Full raw backend body (fees preview, order id, new balance, guardian block, …). */
+    raw: Record<string, unknown>;
+}
+interface CreateCheckoutInput {
+    playerEmail: string;
+    usdAmount: string | number;
+    /** Which rail the hosted page presents. Default "platform" (card). The page
+     *  renders the right experience per rail — all branded as INVO. */
+    rail?: Rail;
+    successUrl?: string;
+    cancelUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateCheckoutResult {
+    sessionId: string;
+    /** Send the browser here; INVO's hosted page handles the processor + 3-D Secure. */
+    checkoutUrl: string;
+    expiresAt: string;
+    raw: Record<string, unknown>;
+}
+interface PurchaseInput {
+    playerEmail: string;
+    usdAmount: string | number;
+    /** Idempotency key. Required. */
+    purchaseReference: string;
+    rail?: Rail;
+    /** Required for the `platform` rail: a tokenized payment method. */
+    paymentMethodId?: string;
+    savedCardId?: string;
+    playerName?: string;
+    playerPhone?: string;
+}
+type PurchaseStatus = "success" | "requires_action" | "pending_payment";
+interface PurchaseResult {
+    status: PurchaseStatus;
+    /** Present when status === "requires_action" (client-side 3-D Secure step). */
+    clientSecret?: string;
+    paymentIntentId?: string;
+    /** Present when status === "pending_payment" (redirect the browser here). */
+    paymentUrl?: string;
+    transactionId?: string;
+    orderId?: string;
+    newBalance?: string | number | null;
+    raw: Record<string, unknown>;
+}
+interface ApproveResult {
+    status: string;
+    next: string;
+    transactionId: string;
+    /** transfer-approve returns the sender's claim code; send-approve does not. */
+    claimCode?: string;
+    claimCodeExpiresAt?: string;
+    raw: Record<string, unknown>;
+}
+interface ConfirmReceiptResult {
+    status: string;
+    raw: Record<string, unknown>;
+}
+interface LinkDeviceResult {
+    /** "authorized" on success — a single-use grant that register/complete consumes. */
+    status: string;
+    raw: Record<string, unknown>;
+}
+
+/**
+ * Typed error for every INVO backend failure.
+ *
+ * The backend error envelope is usually `{ "error": <message>, "code": <STABLE_CODE> }`,
+ * but a few txn-state/claim errors carry only `error` (no `code`) and some use
+ * `{ "status": "error", "message": ... }`. So `code` may be undefined — branch on
+ * `code` when present, else fall back to `message`. See the handoff doc §8.
+ */
+declare class InvoError extends Error {
+    /** Stable machine code from the backend (`code`), when present. */
+    readonly code: string | undefined;
+    /** HTTP status. */
+    readonly status: number;
+    /** Raw parsed body, for debugging / fields not surfaced here. */
+    readonly body: unknown;
+    constructor(args: {
+        message: string;
+        code?: string;
+        status: number;
+        body?: unknown;
+    });
+    /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
+    get isReceiverNotEnrolled(): boolean;
+    /** True if the session/SDK token has expired and the caller should re-mint + retry. */
+    get isTokenExpired(): boolean;
+}
+
+export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InitiateSendInput as b, type InitiateResult as c, type InitiateTransferInput as d, type CreateCheckoutInput as e, type CreateCheckoutResult as f, type PurchaseInput as g, type PurchaseResult as h };