@invonetwork/web-sdk 0.3.0 → 0.4.1

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-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';
+import { I as InvoError, S as ServerConfig, a as CallOptions, P as PlayerToken, g as InitiateSendInput, h as InitiateResult, i as InitiateTransferInput, j as CreateCheckoutInput, k as CreateCheckoutResult, l as PurchaseInput, m as PurchaseResult, n as ConfirmPaymentResult, O as OrderDetailsResult, o as PurchaseItemInput, p as PurchaseItemResult, q as ItemHistoryQuery, r as ItemHistoryResult, s as ItemOrderQuery, t as PlayerBalanceQuery, u as PlayerBalanceResult, v as InboundPendingQuery, w as InboundPendingResult } from './types-CBMLNwbe.js';
+export { x as CurrencyBalance, y as InboundPendingItem, c as InvoErrorInfo, d as InvoHooks, e as InvoRequestInfo, f as InvoResponseInfo, R as Rail, V as VerificationMethod } from './types-CBMLNwbe.js';
 
 interface VerifyWebhookOptions {
     /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -94,15 +94,54 @@ type InvoWebhookEvent = (WebhookBase & {
     data: Record<string, unknown>;
 });
 /**
- * Verify an Invo webhook and return the parsed, typed event.
+ * Verify an Invo webhook and return the parsed, typed event. **Synchronous; uses
+ * `node:crypto`** — for non-Node runtimes (Cloudflare Workers, Deno, Vercel/Netlify
+ * Edge, Bun edge) use {@link verifyWebhookAsync}.
  *
- * @param rawBody  The exact raw request body (Buffer/Uint8Array or string).
+ * @param rawBody  The exact raw request body (bytes or string) — never a re-serialized object.
  * @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.
+ * @param secret  Your signing secret, or an array (to accept old + new during rotation).
+ * @throws InvoError (status 0): WEBHOOK_SIGNATURE_MISSING | WEBHOOK_SECRET_MISSING |
+ *         WEBHOOK_TIMESTAMP_EXPIRED | WEBHOOK_SIGNATURE_INVALID | WEBHOOK_MALFORMED.
  */
 declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): InvoWebhookEvent;
+/**
+ * Cross-runtime async variant of {@link verifyWebhook}. Uses the Web Crypto API
+ * (`crypto.subtle`) instead of `node:crypto`, so it works on Cloudflare Workers,
+ * Deno, Vercel/Netlify Edge, Bun, and modern browsers (as well as Node ≥ 18).
+ * Same arguments, errors, and return value — just `await` it.
+ */
+declare function verifyWebhookAsync(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): Promise<InvoWebhookEvent>;
+interface WebhookHandlerOptions {
+    /** Signing secret, or an array to accept old + new during rotation. */
+    secret: string | string[];
+    /** Called with the verified, typed event after the signature passes. De-dupe on
+     *  `ctx.idempotencyKey`. Throw to return a 500 (Invo will retry). */
+    onEvent: (event: InvoWebhookEvent, ctx: {
+        idempotencyKey: string | null;
+        request: Request;
+    }) => void | Promise<void>;
+    /** Optional: handle a verification failure. Return a Response to override the default 400. */
+    onError?: (error: InvoError, request: Request) => void | Response | Promise<void | Response>;
+    /** Replay tolerance (seconds). Default 300. */
+    toleranceSec?: number;
+}
+/**
+ * Build a webhook route handler from the Fetch API `(Request) => Promise<Response>` —
+ * works in Next.js App Router route handlers, Cloudflare Workers, Deno, Hono, and Bun.
+ * It reads the raw body, verifies with {@link verifyWebhookAsync}, and on success calls
+ * `onEvent` with the typed event and the idempotency key (de-dupe is yours). Verification
+ * failures return `400`; a throwing `onEvent` returns `500` so Invo retries.
+ *
+ * ```ts
+ * // app/invo/webhooks/route.ts (Next.js)
+ * export const POST = createWebhookHandler({
+ *   secret: process.env.INVO_WEBHOOK_SECRET!,
+ *   onEvent: async (event, { idempotencyKey }) => { await grantValue(event); },
+ * });
+ * ```
+ */
+declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
 
 declare class InvoServer {
     private readonly http;
@@ -111,16 +150,16 @@ declare class InvoServer {
     /** Mint a short-lived, game-scoped player token to hand to the browser InvoClient. */
     mintPlayerToken(input: {
         playerEmail: string;
-    }): Promise<PlayerToken>;
+    }, opts?: CallOptions): Promise<PlayerToken>;
     /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
-    initiateSend(input: InitiateSendInput): Promise<InitiateResult>;
+    initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
     /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
-    initiateTransfer(input: InitiateTransferInput): Promise<InitiateResult>;
+    initiateTransfer(input: InitiateTransferInput, opts?: CallOptions): Promise<InitiateResult>;
     /** Create a hosted checkout session (the recommended purchase path). Open the
      *  returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
      *  handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
      *  purchase.completed webhook. */
-    createCheckout(input: CreateCheckoutInput): Promise<CreateCheckoutResult>;
+    createCheckout(input: CreateCheckoutInput, opts?: CallOptions): Promise<CreateCheckoutResult>;
     /**
      * Direct purchase via the rail selector. Use when you need a specific rail.
      * - rail "platform" (default): standard card. May return status "requires_action"
@@ -128,17 +167,17 @@ declare class InvoServer {
      * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
      * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
      */
-    purchaseCurrency(input: PurchaseInput): Promise<PurchaseResult>;
+    purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
     /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
     confirmPayment(input: {
         paymentIntentId: string;
         orderId?: string;
-    }): Promise<ConfirmPaymentResult>;
+    }, opts?: CallOptions): Promise<ConfirmPaymentResult>;
     /** Fetch purchase status (order + financial summary + timeline). */
     getOrderDetails(query: {
         orderId?: string;
         transactionId?: string;
-    }): Promise<OrderDetailsResult>;
+    }, opts?: CallOptions): 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
@@ -147,15 +186,35 @@ declare class InvoServer {
      * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
      * item to your inventory off the `item.purchased` webhook, not just this response.
      */
-    purchaseItem(input: PurchaseItemInput): Promise<PurchaseItemResult>;
+    purchaseItem(input: PurchaseItemInput, opts?: CallOptions): Promise<PurchaseItemResult>;
     /** Paginated item-purchase history for a player (§4.8 companion read). */
-    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<ItemHistoryResult>;
+    getItemPurchaseHistory(query: ItemHistoryQuery, opts?: CallOptions): 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<OrderDetailsResult>;
+    getItemOrderDetails(query: ItemOrderQuery, opts?: CallOptions): Promise<OrderDetailsResult>;
+    /**
+     * Async iterator over a player's entire item-purchase history — pages through
+     * `getItemPurchaseHistory` (limit/offset) until exhausted, yielding one row at a time.
+     *
+     * ```ts
+     * for await (const row of invo.iterateItemPurchaseHistory({ playerEmail })) { … }
+     * ```
+     */
+    iterateItemPurchaseHistory(query: {
+        playerEmail: string;
+        pageSize?: number;
+    }, opts?: CallOptions): AsyncGenerator<Record<string, unknown>, void, unknown>;
     /** Read a player's currency balances, by email or playerId (game-secret). */
-    getPlayerBalance(query: PlayerBalanceQuery): Promise<PlayerBalanceResult>;
+    getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
+    /**
+     * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
+     * the source of truth for a "you have X to collect" badge. Pass the player's email
+     * or phone. Match `toPhone` to the logged-in player (don't require `toIdentityId`,
+     * which is null when the phone maps to more than one of your players). Pairs with the
+     * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
+     */
+    getInboundPending(query: InboundPendingQuery, opts?: CallOptions): Promise<InboundPendingResult>;
     private toInitiateResult;
 }
 
-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 };
+export { CallOptions, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, 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, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };

package/dist/server.js

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-DV3WZGMH.js';
-export { InvoError } from './chunk-DV3WZGMH.js';
+import { InvoError, assertSecureBaseUrl, Http } from './chunk-EEWOAUXO.js';
+export { InvoError } from './chunk-EEWOAUXO.js';
 import { createHmac } from 'crypto';
 
 var DEFAULT_TOLERANCE_SEC = 300;
@@ -38,7 +38,7 @@ function safeEqualHex(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
-function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+function prepareVerification(rawBody, signatureHeader, secret, opts) {
   if (!signatureHeader) {
     throw webhookError("Missing X-Invo-Signature header.", "WEBHOOK_SIGNATURE_MISSING");
   }
@@ -61,13 +61,9 @@ function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
   }
   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");
-  }
+  return { secrets, sigs, message, bodyBytes };
+}
+function finalizeEvent(bodyBytes) {
   let parsed;
   try {
     parsed = JSON.parse(new TextDecoder().decode(bodyBytes));
@@ -79,9 +75,93 @@ function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
   }
   return parsed;
 }
+function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+  const { secrets, sigs, message, bodyBytes } = prepareVerification(
+    rawBody,
+    signatureHeader,
+    secret,
+    opts
+  );
+  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");
+  }
+  return finalizeEvent(bodyBytes);
+}
+async function verifyWebhookAsync(rawBody, signatureHeader, secret, opts = {}) {
+  const { secrets, sigs, message, bodyBytes } = prepareVerification(
+    rawBody,
+    signatureHeader,
+    secret,
+    opts
+  );
+  for (const s of secrets) {
+    const expected = await hmacHexSubtle(s, message);
+    if (sigs.some((sig) => safeEqualHex(sig, expected))) {
+      return finalizeEvent(bodyBytes);
+    }
+  }
+  throw webhookError("Webhook signature verification failed.", "WEBHOOK_SIGNATURE_INVALID");
+}
+function createWebhookHandler(opts) {
+  return async (request) => {
+    const raw = await request.text();
+    let event;
+    try {
+      event = await verifyWebhookAsync(raw, request.headers.get("x-invo-signature"), opts.secret, {
+        toleranceSec: opts.toleranceSec
+      });
+    } catch (e) {
+      const err = e instanceof InvoError ? e : new InvoError({ message: String(e), status: 0 });
+      if (opts.onError) {
+        try {
+          const r = await opts.onError(err, request);
+          if (r instanceof Response) return r;
+        } catch {
+        }
+      }
+      return new Response(err.code ?? "invalid_signature", { status: 400 });
+    }
+    try {
+      await opts.onEvent(event, {
+        // Prefer the signature-covered body field over the (unauthenticated, optional)
+        // header — the body value is HMAC-verified and always present.
+        idempotencyKey: event.idempotency_key ?? request.headers.get("x-invo-idempotency-key"),
+        request
+      });
+    } catch {
+      return new Response("handler_error", { status: 500 });
+    }
+    return new Response(null, { status: 200 });
+  };
+}
+async function hmacHexSubtle(secret, message) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw webhookError(
+      "Web Crypto (crypto.subtle) is unavailable in this runtime.",
+      "WEBHOOK_UNSUPPORTED"
+    );
+  }
+  const key = await subtle.importKey(
+    "raw",
+    ENCODER.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await subtle.sign("HMAC", key, message);
+  const bytes = new Uint8Array(sig);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
 
 // src/server.ts
-var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
+var DEFAULT_UA = "invonetwork-web-sdk/0.4.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
 var MAX_ITEM_PRICE = 999999.99;
 function invalidInput(label, value, why) {
@@ -121,6 +201,21 @@ function toOrderDetails(raw) {
     raw
   };
 }
+function toInboundPendingItem(row) {
+  return {
+    transactionId: String(row["transaction_id"] ?? ""),
+    flow: String(row["flow"] ?? ""),
+    amount: String(row["amount"] ?? ""),
+    netAmount: String(row["net_amount"] ?? ""),
+    sourceGameId: row["source_game_id"] ?? "",
+    sourceGame: String(row["source_game"] ?? ""),
+    toPhone: String(row["to_phone"] ?? ""),
+    toIdentityId: row["to_identity_id"] ?? null,
+    createdAt: String(row["created_at"] ?? ""),
+    claimCodeExpiresAt: String(row["claim_code_expires_at"] ?? ""),
+    raw: row
+  };
+}
 function toCurrencyBalance(row) {
   return {
     currencyId: row["currency_id"] ?? "",
@@ -163,7 +258,7 @@ var InvoServer = class {
     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) {
+  async mintPlayerToken(input, opts) {
     if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
       throw invalidInput("playerEmail", input.playerEmail, "is required");
     }
@@ -171,7 +266,7 @@ var InvoServer = class {
       "/api/sdk/player-token",
       { player_email: input.playerEmail },
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // safe to retry: re-mint just issues a fresh token
     );
     return {
@@ -181,7 +276,7 @@ var InvoServer = class {
     };
   }
   /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
-  async initiateSend(input) {
+  async initiateSend(input, opts) {
     const raw = await this.http.post(
       "/api/currency-sends/initiate-send",
       {
@@ -195,13 +290,13 @@ var InvoServer = class {
         amount: input.amount
       },
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
   }
   /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
-  async initiateTransfer(input) {
+  async initiateTransfer(input, opts) {
     const raw = await this.http.post(
       "/api/transfers/initiate-transfer",
       {
@@ -215,7 +310,7 @@ var InvoServer = class {
         amount: input.amount
       },
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
@@ -224,7 +319,7 @@ var InvoServer = class {
    *  returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
    *  handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
    *  purchase.completed webhook. */
-  async createCheckout(input) {
+  async createCheckout(input, opts) {
     if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
       throw invalidInput("playerEmail", input.playerEmail, "is required");
     }
@@ -240,7 +335,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/checkout/sessions",
       body,
-      this.auth
+      this.auth,
+      { signal: opts?.signal }
+      // not idempotent — never auto-retried
     );
     return {
       sessionId: String(raw["session_id"] ?? ""),
@@ -256,7 +353,7 @@ var InvoServer = class {
    * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
    * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
    */
-  async purchaseCurrency(input) {
+  async purchaseCurrency(input, opts) {
     if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
       throw invalidInput("playerEmail", input.playerEmail, "is required");
     }
@@ -289,7 +386,7 @@ var InvoServer = class {
       "/api/currency-purchases/purchase-currency",
       body,
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // purchase_reference makes this safe to retry (backend dedupes)
     );
     return {
@@ -304,14 +401,14 @@ var InvoServer = class {
     };
   }
   /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
-  async confirmPayment(input) {
+  async confirmPayment(input, opts) {
     const body = { payment_intent_id: input.paymentIntentId };
     if (input.orderId) body["order_id"] = input.orderId;
     const raw = await this.http.post(
       "/api/currency-purchases/confirm-payment",
       body,
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // keyed by payment_intent_id — safe to retry
     );
     return {
@@ -322,7 +419,7 @@ var InvoServer = class {
     };
   }
   /** Fetch purchase status (order + financial summary + timeline). */
-  async getOrderDetails(query) {
+  async getOrderDetails(query, opts) {
     if (!query.orderId && !query.transactionId) {
       throw new InvoError({
         message: "getOrderDetails requires an `orderId` or `transactionId`.",
@@ -335,7 +432,8 @@ var InvoServer = class {
     if (query.transactionId) q.set("transaction_id", query.transactionId);
     const raw = await this.http.get(
       `/api/currency-purchases/order-details?${q.toString()}`,
-      this.auth
+      this.auth,
+      { signal: opts?.signal }
     );
     return toOrderDetails(raw);
   }
@@ -347,7 +445,7 @@ var InvoServer = class {
    * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
    * item to your inventory off the `item.purchased` webhook, not just this response.
    */
-  async purchaseItem(input) {
+  async purchaseItem(input, opts) {
     const required = [
       ["clientRequestId", input.clientRequestId],
       ["playerEmail", input.playerEmail],
@@ -389,7 +487,7 @@ var InvoServer = class {
       "/api/item-purchases/purchase-item",
       body,
       this.auth,
-      { idempotent: true }
+      { idempotent: true, signal: opts?.signal }
       // client_request_id makes this safe to retry (dup → 409)
     );
     return {
@@ -404,7 +502,7 @@ var InvoServer = class {
     };
   }
   /** Paginated item-purchase history for a player (§4.8 companion read). */
-  async getItemPurchaseHistory(query) {
+  async getItemPurchaseHistory(query, opts) {
     if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
       throw invalidInput("playerEmail", query.playerEmail, "is required");
     }
@@ -414,7 +512,8 @@ var InvoServer = class {
     if (query.offset != null) q.set("offset", String(query.offset));
     const raw = await this.http.get(
       `/api/item-purchases/player-purchase-history?${q.toString()}`,
-      this.auth
+      this.auth,
+      { signal: opts?.signal }
     );
     return {
       history: Array.isArray(raw["item_purchase_history"]) ? raw["item_purchase_history"] : [],
@@ -424,7 +523,7 @@ var InvoServer = class {
   }
   /** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
    *  (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
-  async getItemOrderDetails(query) {
+  async getItemOrderDetails(query, opts) {
     const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
       (v) => typeof v === "string" && v.trim()
     );
@@ -441,12 +540,40 @@ var InvoServer = class {
     if (query.clientRequestId) q.set("client_request_id", query.clientRequestId);
     const raw = await this.http.get(
       `/api/item-purchases/order-details?${q.toString()}`,
-      this.auth
+      this.auth,
+      { signal: opts?.signal }
     );
     return toOrderDetails(raw);
   }
+  /**
+   * Async iterator over a player's entire item-purchase history — pages through
+   * `getItemPurchaseHistory` (limit/offset) until exhausted, yielding one row at a time.
+   *
+   * ```ts
+   * for await (const row of invo.iterateItemPurchaseHistory({ playerEmail })) { … }
+   * ```
+   */
+  async *iterateItemPurchaseHistory(query, opts) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const pageSize = typeof query.pageSize === "number" && query.pageSize > 0 ? Math.floor(query.pageSize) : 50;
+    let yielded = 0;
+    for (let offset = 0; ; offset += pageSize) {
+      const { history, pagination } = await this.getItemPurchaseHistory(
+        { playerEmail: query.playerEmail, limit: pageSize, offset },
+        opts
+      );
+      if (history.length === 0) return;
+      for (const row of history) yield row;
+      yielded += history.length;
+      if (history.length < pageSize) return;
+      const total = Number(pagination?.["total"]);
+      if (Number.isFinite(total) && yielded >= total) return;
+    }
+  }
   /** Read a player's currency balances, by email or playerId (game-secret). */
-  async getPlayerBalance(query) {
+  async getPlayerBalance(query, opts) {
     let path;
     if (query.playerId != null && String(query.playerId).trim()) {
       path = `/api/player-balances/player/${encodeURIComponent(String(query.playerId))}`;
@@ -459,7 +586,7 @@ var InvoServer = class {
         status: 0
       });
     }
-    const raw = await this.http.get(path, this.auth);
+    const raw = await this.http.get(path, this.auth, { signal: opts?.signal });
     const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
     return {
       player: raw["player"] ?? {},
@@ -468,6 +595,30 @@ var InvoServer = class {
       raw
     };
   }
+  /**
+   * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
+   * the source of truth for a "you have X to collect" badge. Pass the player's email
+   * or phone. Match `toPhone` to the logged-in player (don't require `toIdentityId`,
+   * which is null when the phone maps to more than one of your players). Pairs with the
+   * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
+   */
+  async getInboundPending(query, opts) {
+    const hasEmail = typeof query.playerEmail === "string" && query.playerEmail.trim();
+    const hasPhone = typeof query.playerPhone === "string" && query.playerPhone.trim();
+    if (!hasEmail && !hasPhone) {
+      throw invalidInput("query", query, "requires a playerEmail or playerPhone");
+    }
+    const q = new URLSearchParams();
+    if (hasEmail) q.set("player_email", query.playerEmail.trim());
+    if (hasPhone) q.set("player_phone", query.playerPhone.trim());
+    const raw = await this.http.get(
+      `/api/transfers/inbound-pending?${q.toString()}`,
+      this.auth,
+      { signal: opts?.signal }
+    );
+    const rows = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
+    return { inboundPending: rows.map(toInboundPendingItem), raw };
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];
@@ -480,6 +631,6 @@ var InvoServer = class {
   }
 };
 
-export { InvoServer, verifyWebhook };
+export { InvoServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
 //# sourceMappingURL=server.js.map
 //# sourceMappingURL=server.js.map

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

@@ -66,6 +66,11 @@ interface InvoHooks {
     onError?: (info: InvoErrorInfo) => void;
 }
 
+/** Per-call options (e.g. cancellation). Accepted as an optional last arg on SDK methods. */
+interface CallOptions {
+    /** Cancel this call. Aborting throws an InvoError (code "ABORTED"); aborted calls are never retried. */
+    signal?: AbortSignal;
+}
 /** 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";
@@ -268,6 +273,32 @@ interface PlayerBalanceResult {
     summary: Record<string, unknown>;
     raw: Record<string, unknown>;
 }
+interface InboundPendingQuery {
+    /** Provide one: the player's email or phone. */
+    playerEmail?: string;
+    playerPhone?: string;
+}
+interface InboundPendingItem {
+    transactionId: string;
+    /** "transfer" | "send". */
+    flow: string;
+    amount: string;
+    /** What the recipient receives (after fees). */
+    netAmount: string;
+    sourceGameId: string | number;
+    sourceGame: string;
+    /** Match to the logged-in player's phone. */
+    toPhone: string;
+    /** Recipient identity; null when the phone maps to >1 of your players. */
+    toIdentityId: string | null;
+    createdAt: string;
+    claimCodeExpiresAt: string;
+    raw: Record<string, unknown>;
+}
+interface InboundPendingResult {
+    inboundPending: InboundPendingItem[];
+    raw: Record<string, unknown>;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -287,4 +318,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
 
-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 };
+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 CallOptions as a, type ConfirmReceiptResult as b, type InvoErrorInfo as c, type InvoHooks as d, type InvoRequestInfo as e, type InvoResponseInfo as f, type InitiateSendInput as g, type InitiateResult as h, type InitiateTransferInput as i, type CreateCheckoutInput as j, type CreateCheckoutResult as k, type PurchaseInput as l, type PurchaseResult as m, type ConfirmPaymentResult as n, type PurchaseItemInput as o, type PurchaseItemResult as p, type ItemHistoryQuery as q, type ItemHistoryResult as r, type ItemOrderQuery as s, type PlayerBalanceQuery as t, type PlayerBalanceResult as u, type InboundPendingQuery as v, type InboundPendingResult as w, type CurrencyBalance as x, type InboundPendingItem as y };

package/dist/{types-CBkoUymV.d.ts → types-CBMLNwbe.d.ts}

@@ -66,6 +66,11 @@ interface InvoHooks {
     onError?: (info: InvoErrorInfo) => void;
 }
 
+/** Per-call options (e.g. cancellation). Accepted as an optional last arg on SDK methods. */
+interface CallOptions {
+    /** Cancel this call. Aborting throws an InvoError (code "ABORTED"); aborted calls are never retried. */
+    signal?: AbortSignal;
+}
 /** 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";
@@ -268,6 +273,32 @@ interface PlayerBalanceResult {
     summary: Record<string, unknown>;
     raw: Record<string, unknown>;
 }
+interface InboundPendingQuery {
+    /** Provide one: the player's email or phone. */
+    playerEmail?: string;
+    playerPhone?: string;
+}
+interface InboundPendingItem {
+    transactionId: string;
+    /** "transfer" | "send". */
+    flow: string;
+    amount: string;
+    /** What the recipient receives (after fees). */
+    netAmount: string;
+    sourceGameId: string | number;
+    sourceGame: string;
+    /** Match to the logged-in player's phone. */
+    toPhone: string;
+    /** Recipient identity; null when the phone maps to >1 of your players. */
+    toIdentityId: string | null;
+    createdAt: string;
+    claimCodeExpiresAt: string;
+    raw: Record<string, unknown>;
+}
+interface InboundPendingResult {
+    inboundPending: InboundPendingItem[];
+    raw: Record<string, unknown>;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -287,4 +318,4 @@ interface LinkDeviceResult {
     raw: Record<string, unknown>;
 }
 
-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 };
+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 CallOptions as a, type ConfirmReceiptResult as b, type InvoErrorInfo as c, type InvoHooks as d, type InvoRequestInfo as e, type InvoResponseInfo as f, type InitiateSendInput as g, type InitiateResult as h, type InitiateTransferInput as i, type CreateCheckoutInput as j, type CreateCheckoutResult as k, type PurchaseInput as l, type PurchaseResult as m, type ConfirmPaymentResult as n, type PurchaseItemInput as o, type PurchaseItemResult as p, type ItemHistoryQuery as q, type ItemHistoryResult as r, type ItemOrderQuery as s, type PlayerBalanceQuery as t, type PlayerBalanceResult as u, type InboundPendingQuery as v, type InboundPendingResult as w, type CurrencyBalance as x, type InboundPendingItem as y };