@invonetwork/web-sdk 0.2.0 → 0.3.0

package/dist/server.d.ts

@@ -1,5 +1,108 @@
-import { S as ServerConfig, P as PlayerToken, b as InitiateSendInput, c as InitiateResult, d as InitiateTransferInput, e as CreateCheckoutInput, f as CreateCheckoutResult, g as PurchaseInput, h as PurchaseResult, i as PurchaseItemInput, j as PurchaseItemResult, k as ItemHistoryQuery, l as ItemOrderQuery } from './errors-DV5QsftP.js';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.js';
+import { S as ServerConfig, P as PlayerToken, f as InitiateSendInput, g as InitiateResult, h as InitiateTransferInput, i as CreateCheckoutInput, j as CreateCheckoutResult, k as PurchaseInput, l as PurchaseResult, m as ConfirmPaymentResult, O as OrderDetailsResult, n as PurchaseItemInput, o as PurchaseItemResult, p as ItemHistoryQuery, q as ItemHistoryResult, r as ItemOrderQuery, s as PlayerBalanceQuery, t as PlayerBalanceResult } from './types-CBkoUymV.js';
+export { u as CurrencyBalance, I as InvoError, b as InvoErrorInfo, c as InvoHooks, d as InvoRequestInfo, e as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBkoUymV.js';
+
+interface VerifyWebhookOptions {
+    /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
+    toleranceSec?: number;
+    /** Override the current time (unix seconds) — for tests. Defaults to Date.now(). */
+    nowSec?: number;
+}
+interface WebhookBase {
+    event_id: string;
+    idempotency_key: string;
+    schema_version: string;
+    created_at: string;
+    /** Your game_id. */
+    tenant_id: string;
+}
+interface PurchaseCompletedData {
+    transaction_id: string;
+    order_id: string;
+    player_email: string;
+    identity_id: string;
+    usd_amount: string;
+    currency_amount: string;
+    currency_name: string;
+    new_balance: string;
+    rail: string;
+    [key: string]: unknown;
+}
+interface PurchaseEventData {
+    transaction_id: string;
+    order_id?: string;
+    player_email?: string;
+    identity_id?: string;
+    /** Present on purchase.disputed, e.g. "lost". */
+    dispute_status?: string;
+    [key: string]: unknown;
+}
+interface ItemPurchasedData {
+    transaction_id: string;
+    order_id: string;
+    player_email: string;
+    identity_id: string;
+    item_id: string;
+    item_name: string;
+    item_quantity: number;
+    unit_price: string;
+    total_price: string;
+    currency_name: string;
+    new_balance: string;
+    fee_breakdown?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface TransferEventData {
+    transaction_id: string;
+    /** "transfer" | "send". */
+    flow?: string;
+    amount?: string;
+    net_amount?: string;
+    /** "inbound" | "outbound" (relative to the receiving tenant). */
+    direction?: string;
+    /** On inbound claim_pending: the recipient's phone (match to your player). */
+    to_phone?: string;
+    /** Recipient's opaque identity, present only when the phone maps to a single player. */
+    to_identity_id?: string | null;
+    [key: string]: unknown;
+}
+type PurchaseEventType = "purchase.failed" | "purchase.refunded" | "purchase.disputed" | "purchase.fraud_warning";
+type TransferEventType = "transfer.sent" | "transfer.received" | "transfer.claim_pending" | "transfer.claim_expired" | "transfer.refunded";
+/**
+ * A verified webhook event. Discriminate on `event_type` to narrow `data`.
+ * Unknown/future event types fall through to the generic member (data is a record).
+ */
+type InvoWebhookEvent = (WebhookBase & {
+    event_type: "purchase.completed";
+    data: PurchaseCompletedData;
+}) | (WebhookBase & {
+    event_type: "item.purchased";
+    data: ItemPurchasedData;
+}) | (WebhookBase & {
+    event_type: PurchaseEventType;
+    data: PurchaseEventData;
+}) | (WebhookBase & {
+    event_type: TransferEventType;
+    data: TransferEventData;
+}) | (WebhookBase & {
+    event_type: "payout.status_changed";
+    data: Record<string, unknown>;
+}) | (WebhookBase & {
+    event_type: "webhook.test";
+    data: Record<string, unknown>;
+}) | (WebhookBase & {
+    event_type: string;
+    data: Record<string, unknown>;
+});
+/**
+ * Verify an Invo webhook and return the parsed, typed event.
+ *
+ * @param rawBody  The exact raw request body (Buffer/Uint8Array or string).
+ * @param signatureHeader  The `X-Invo-Signature` header value.
+ * @param secret  Your signing secret, or an array of secrets (to accept old + new during rotation).
+ * @throws InvoError (status 0) with code WEBHOOK_SIGNATURE_MISSING | WEBHOOK_TIMESTAMP_EXPIRED |
+ *         WEBHOOK_SIGNATURE_INVALID | WEBHOOK_MALFORMED on any failure.
+ */
+declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): InvoWebhookEvent;
 
 declare class InvoServer {
     private readonly http;
@@ -30,12 +133,12 @@ declare class InvoServer {
     confirmPayment(input: {
         paymentIntentId: string;
         orderId?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<ConfirmPaymentResult>;
     /** Fetch purchase status (order + financial summary + timeline). */
     getOrderDetails(query: {
         orderId?: string;
         transactionId?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<OrderDetailsResult>;
     /**
      * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
      * No real money, no payment rail, no passkey — it's a balance debit, authenticated
@@ -46,11 +149,13 @@ declare class InvoServer {
      */
     purchaseItem(input: PurchaseItemInput): Promise<PurchaseItemResult>;
     /** Paginated item-purchase history for a player (§4.8 companion read). */
-    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<Record<string, unknown>>;
+    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<ItemHistoryResult>;
     /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
      *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
-    getItemOrderDetails(query: ItemOrderQuery): Promise<Record<string, unknown>>;
+    getItemOrderDetails(query: ItemOrderQuery): Promise<OrderDetailsResult>;
+    /** Read a player's currency balances, by email or playerId (game-secret). */
+    getPlayerBalance(query: PlayerBalanceQuery): Promise<PlayerBalanceResult>;
     private toInitiateResult;
 }
 
-export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };
+export { ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, OrderDetailsResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerToken, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig, type TransferEventData, type VerifyWebhookOptions, verifyWebhook };

package/dist/server.js

@@ -1,5 +1,84 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
-export { InvoError } from './chunk-A44O4KC3.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-DV3WZGMH.js';
+export { InvoError } from './chunk-DV3WZGMH.js';
+import { createHmac } from 'crypto';
+
+var DEFAULT_TOLERANCE_SEC = 300;
+var ENCODER = new TextEncoder();
+function toBytes(body) {
+  return typeof body === "string" ? ENCODER.encode(body) : body;
+}
+function concatBytes(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+function webhookError(message, code) {
+  return new InvoError({ message, code, status: 0 });
+}
+function parseSignatureHeader(header) {
+  let t = "";
+  const sigs = [];
+  for (const part of header.split(",")) {
+    const idx = part.indexOf("=");
+    if (idx === -1) continue;
+    const key = part.slice(0, idx).trim();
+    const val = part.slice(idx + 1).trim();
+    if (key === "t") t = val;
+    else if (key === "v1" && val) sigs.push(val);
+  }
+  return { t, sigs };
+}
+function hmacHex(secret, message) {
+  return createHmac("sha256", secret).update(message).digest("hex");
+}
+function safeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+  if (!signatureHeader) {
+    throw webhookError("Missing X-Invo-Signature header.", "WEBHOOK_SIGNATURE_MISSING");
+  }
+  const secrets = (Array.isArray(secret) ? secret : [secret]).filter(Boolean);
+  if (secrets.length === 0) {
+    throw webhookError("A signing secret is required to verify webhooks.", "WEBHOOK_SECRET_MISSING");
+  }
+  const { t, sigs } = parseSignatureHeader(signatureHeader);
+  if (!t || sigs.length === 0) {
+    throw webhookError("Malformed X-Invo-Signature header.", "WEBHOOK_MALFORMED");
+  }
+  const ts = Number(t);
+  const now = opts.nowSec ?? Math.floor(Date.now() / 1e3);
+  const tolerance = opts.toleranceSec ?? DEFAULT_TOLERANCE_SEC;
+  if (!Number.isFinite(ts) || Math.abs(now - ts) > tolerance) {
+    throw webhookError(
+      `Webhook timestamp outside the ${tolerance}s tolerance (replay guard).`,
+      "WEBHOOK_TIMESTAMP_EXPIRED"
+    );
+  }
+  const bodyBytes = toBytes(rawBody);
+  const message = concatBytes(ENCODER.encode(`${t}.`), bodyBytes);
+  const matched = secrets.some((s) => {
+    const expected = hmacHex(s, message);
+    return sigs.some((sig) => safeEqualHex(sig, expected));
+  });
+  if (!matched) {
+    throw webhookError("Webhook signature verification failed.", "WEBHOOK_SIGNATURE_INVALID");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bodyBytes));
+  } catch {
+    throw webhookError("Webhook body is not valid JSON.", "WEBHOOK_MALFORMED");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || typeof parsed.event_type !== "string") {
+    throw webhookError("Webhook body is not a valid event object.", "WEBHOOK_MALFORMED");
+  }
+  return parsed;
+}
 
 // src/server.ts
 var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
@@ -34,6 +113,26 @@ function parseMoney(value, max, label) {
 function assertUsdAmount(usdAmount) {
   parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
 }
+function toOrderDetails(raw) {
+  return {
+    order: raw["order"] ?? {},
+    financialSummary: raw["financial_summary"] ?? {},
+    statusTimeline: raw["status_timeline"] ?? null,
+    raw
+  };
+}
+function toCurrencyBalance(row) {
+  return {
+    currencyId: row["currency_id"] ?? "",
+    currencyName: String(row["currency_name"] ?? ""),
+    currencySymbol: String(row["currency_symbol"] ?? ""),
+    availableBalance: String(row["available_balance"] ?? ""),
+    reservedBalance: String(row["reserved_balance"] ?? ""),
+    totalBalance: String(row["total_balance"] ?? ""),
+    lastTransaction: row["last_transaction"],
+    raw: row
+  };
+}
 function requireField(value, field, raw) {
   const s = value == null ? "" : String(value);
   if (!s) {
@@ -55,17 +154,25 @@ var InvoServer = class {
       baseUrl: config.baseUrl,
       timeoutMs: config.timeoutMs,
       fetchImpl: config.fetch,
-      userAgent: DEFAULT_UA
+      userAgent: DEFAULT_UA,
       // must be a non-blocked UA (handoff doc §9)
+      maxRetries: config.maxRetries,
+      retryBaseDelayMs: config.retryBaseDelayMs,
+      hooks: config.hooks
     });
     this.auth = { kind: "game-secret", secret: config.gameSecret };
   }
   /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
   async mintPlayerToken(input) {
+    if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
+      throw invalidInput("playerEmail", input.playerEmail, "is required");
+    }
     const raw = await this.http.post(
       "/api/sdk/player-token",
       { player_email: input.playerEmail },
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // safe to retry: re-mint just issues a fresh token
     );
     return {
       token: requireField(raw["token"], "token", raw),
@@ -87,7 +194,9 @@ var InvoServer = class {
         receiving_game_id: input.receivingGameId,
         amount: input.amount
       },
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
   }
@@ -105,7 +214,9 @@ var InvoServer = class {
         target_game_id: input.targetGameId,
         amount: input.amount
       },
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
   }
@@ -114,6 +225,9 @@ var InvoServer = class {
    *  handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
    *  purchase.completed webhook. */
   async createCheckout(input) {
+    if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
+      throw invalidInput("playerEmail", input.playerEmail, "is required");
+    }
     assertUsdAmount(input.usdAmount);
     const body = {
       player_email: input.playerEmail,
@@ -143,6 +257,9 @@ var InvoServer = class {
    * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
    */
   async purchaseCurrency(input) {
+    if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
+      throw invalidInput("playerEmail", input.playerEmail, "is required");
+    }
     assertUsdAmount(input.usdAmount);
     if (!input.purchaseReference) {
       throw new InvoError({
@@ -171,7 +288,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // purchase_reference makes this safe to retry (backend dedupes)
     );
     return {
       status: String(raw["status"] ?? ""),
@@ -188,11 +307,19 @@ var InvoServer = class {
   async confirmPayment(input) {
     const body = { payment_intent_id: input.paymentIntentId };
     if (input.orderId) body["order_id"] = input.orderId;
-    return this.http.post(
+    const raw = await this.http.post(
       "/api/currency-purchases/confirm-payment",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // keyed by payment_intent_id — safe to retry
     );
+    return {
+      status: String(raw["status"] ?? ""),
+      transactionId: raw["transaction_id"],
+      newBalance: raw["new_balance"] ?? null,
+      raw
+    };
   }
   /** Fetch purchase status (order + financial summary + timeline). */
   async getOrderDetails(query) {
@@ -206,10 +333,11 @@ var InvoServer = class {
     const q = new URLSearchParams();
     if (query.orderId) q.set("order_id", query.orderId);
     if (query.transactionId) q.set("transaction_id", query.transactionId);
-    return this.http.get(
+    const raw = await this.http.get(
       `/api/currency-purchases/order-details?${q.toString()}`,
       this.auth
     );
+    return toOrderDetails(raw);
   }
   /**
    * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
@@ -260,7 +388,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/item-purchases/purchase-item",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true }
+      // client_request_id makes this safe to retry (dup → 409)
     );
     return {
       status: String(raw["status"] ?? ""),
@@ -282,10 +412,15 @@ var InvoServer = class {
     q.set("player_email", query.playerEmail);
     if (query.limit != null) q.set("limit", String(query.limit));
     if (query.offset != null) q.set("offset", String(query.offset));
-    return this.http.get(
+    const raw = await this.http.get(
       `/api/item-purchases/player-purchase-history?${q.toString()}`,
       this.auth
     );
+    return {
+      history: Array.isArray(raw["item_purchase_history"]) ? raw["item_purchase_history"] : [],
+      pagination: raw["pagination"] ?? {},
+      raw
+    };
   }
   /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
    *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
@@ -304,10 +439,34 @@ var InvoServer = class {
     if (query.orderId) q.set("order_id", query.orderId);
     if (query.transactionId) q.set("transaction_id", query.transactionId);
     if (query.clientRequestId) q.set("client_request_id", query.clientRequestId);
-    return this.http.get(
+    const raw = await this.http.get(
       `/api/item-purchases/order-details?${q.toString()}`,
       this.auth
     );
+    return toOrderDetails(raw);
+  }
+  /** Read a player's currency balances, by email or playerId (game-secret). */
+  async getPlayerBalance(query) {
+    let path;
+    if (query.playerId != null && String(query.playerId).trim()) {
+      path = `/api/player-balances/player/${encodeURIComponent(String(query.playerId))}`;
+    } else if (typeof query.playerEmail === "string" && query.playerEmail.trim()) {
+      path = `/api/player-balances/player/by-email/${encodeURIComponent(query.playerEmail)}`;
+    } else {
+      throw new InvoError({
+        message: "getPlayerBalance requires a playerEmail or playerId.",
+        code: "INVALID_INPUT",
+        status: 0
+      });
+    }
+    const raw = await this.http.get(path, this.auth);
+    const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
+    return {
+      player: raw["player"] ?? {},
+      balances: rows.map(toCurrencyBalance),
+      summary: raw["summary"] ?? {},
+      raw
+    };
   }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
@@ -321,6 +480,6 @@ var InvoServer = class {
   }
 };
 
-export { InvoServer };
+export { InvoServer, verifyWebhook };
 //# sourceMappingURL=server.js.map
 //# sourceMappingURL=server.js.map

package/dist/{errors-DV5QsftP.d.cts → types-CBkoUymV.d.cts}

@@ -1,3 +1,71 @@
+/**
+ * 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;
+    /** Backend request id (from the response headers), when present — quote it in support tickets. */
+    readonly requestId: string | undefined;
+    constructor(args: {
+        message: string;
+        code?: string;
+        status: number;
+        body?: unknown;
+        requestId?: string;
+    });
+    /** 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;
+    /**
+     * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
+     * The backend carries `required_amount` + `current_balance` on the body for the UI.
+     * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
+     * is a rate-limit, not a top-up condition) is NOT misclassified as this.
+     */
+    get isInsufficientBalance(): boolean;
+    /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
+    get isDuplicateRequest(): boolean;
+    /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
+    get retryAfter(): number | undefined;
+    /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
+     *  The `in` operator throws on primitives, so callers must go through this. */
+    private bodyObject;
+}
+
+interface InvoRequestInfo {
+    method: string;
+    url: string;
+    /** 0-based attempt number (0 = first try, 1 = first retry, …). */
+    attempt: number;
+}
+interface InvoResponseInfo extends InvoRequestInfo {
+    status: number;
+    durationMs: number;
+    /** Backend request id from the response headers, when present. */
+    requestId?: string;
+}
+interface InvoErrorInfo extends InvoRequestInfo {
+    error: InvoError;
+    /** Whether the SDK will retry after this error. */
+    willRetry: boolean;
+}
+/** Optional observability callbacks. All are best-effort — a throwing hook is swallowed. */
+interface InvoHooks {
+    onRequest?: (info: InvoRequestInfo) => void;
+    onResponse?: (info: InvoResponseInfo) => void;
+    onError?: (info: InvoErrorInfo) => void;
+}
+
 /** 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";
@@ -10,6 +78,16 @@ interface InvoConfig {
     timeoutMs?: number;
     /** Optional fetch override (e.g. a custom agent). Defaults to global fetch. */
     fetch?: typeof fetch;
+    /**
+     * Max automatic retries on transient failures — network error/timeout, `429`
+     * (honoring `retry_after`), and `5xx`. Default 2. Set 0 to disable. Mutating
+     * calls carry idempotency keys, so retries are safe.
+     */
+    maxRetries?: number;
+    /** Base backoff delay in ms (exponential + jitter). Default 250. */
+    retryBaseDelayMs?: number;
+    /** Optional observability callbacks: onRequest / onResponse / onError (best-effort). */
+    hooks?: InvoHooks;
 }
 interface ServerConfig extends InvoConfig {
     /** The game secret. Server-side ONLY — never ship this to a browser. */
@@ -107,6 +185,24 @@ interface PurchaseResult {
     newBalance?: string | number | null;
     raw: Record<string, unknown>;
 }
+interface ConfirmPaymentResult {
+    status: string;
+    transactionId?: string;
+    newBalance?: string | number | null;
+    raw: Record<string, unknown>;
+}
+/** Shape of the order-details reads (currency purchase + item purchase). */
+interface OrderDetailsResult {
+    order: Record<string, unknown>;
+    financialSummary: Record<string, unknown>;
+    statusTimeline: unknown;
+    raw: Record<string, unknown>;
+}
+interface ItemHistoryResult {
+    history: Record<string, unknown>[];
+    pagination: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
 interface PurchaseItemInput {
     /** Idempotency key, unique per game. Required. A duplicate returns 409. */
     clientRequestId: string;
@@ -148,6 +244,30 @@ interface ItemOrderQuery {
     transactionId?: string;
     clientRequestId?: string;
 }
+interface PlayerBalanceQuery {
+    /** Look up by email, or by playerId — provide one. */
+    playerEmail?: string;
+    playerId?: string | number;
+}
+interface CurrencyBalance {
+    currencyId: string | number;
+    currencyName: string;
+    currencySymbol: string;
+    availableBalance: string;
+    reservedBalance: string;
+    totalBalance: string;
+    lastTransaction?: string;
+    /** Raw balance row for any field not surfaced here. */
+    raw: Record<string, unknown>;
+}
+interface PlayerBalanceResult {
+    /** { player_id, player_name, player_email, date_joined, last_active }. */
+    player: Record<string, unknown>;
+    balances: CurrencyBalance[];
+    /** { total_currencies, total_value_usd, has_funds, last_updated }. */
+    summary: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -167,45 +287,4 @@ interface LinkDeviceResult {
     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;
-    /**
-     * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
-     * The backend carries `required_amount` + `current_balance` on the body for the UI.
-     * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
-     * is a rate-limit, not a top-up condition) is NOT misclassified as this.
-     */
-    get isInsufficientBalance(): boolean;
-    /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
-    get isDuplicateRequest(): boolean;
-    /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
-    get retryAfter(): number | undefined;
-    /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
-     *  The `in` operator throws on primitives, so callers must go through this. */
-    private bodyObject;
-}
-
-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, type PurchaseItemInput as i, type PurchaseItemResult as j, type ItemHistoryQuery as k, type ItemOrderQuery as l };
+export { type ApproveResult as A, type ClientConfig as C, InvoError as I, type LinkDeviceResult as L, type OrderDetailsResult as O, type PlayerToken as P, type Rail as R, type ServerConfig as S, type VerificationMethod as V, type ConfirmReceiptResult as a, type InvoErrorInfo as b, type InvoHooks as c, type InvoRequestInfo as d, type InvoResponseInfo as e, type InitiateSendInput as f, type InitiateResult as g, type InitiateTransferInput as h, type CreateCheckoutInput as i, type CreateCheckoutResult as j, type PurchaseInput as k, type PurchaseResult as l, type ConfirmPaymentResult as m, type PurchaseItemInput as n, type PurchaseItemResult as o, type ItemHistoryQuery as p, type ItemHistoryResult as q, type ItemOrderQuery as r, type PlayerBalanceQuery as s, type PlayerBalanceResult as t, type CurrencyBalance as u };