@invonetwork/web-sdk 0.3.0 → 0.4.1

package/dist/server.cjs

@@ -100,11 +100,11 @@ var _Http = class _Http {
    *   (e.g. single-use WebAuthn assertions) are NEVER auto-retried.
    */
   async post(path, body, auth, opts) {
-    return this.request("POST", path, body, auth, opts?.idempotent ?? false);
+    return this.request("POST", path, body, auth, opts?.idempotent ?? false, opts?.signal);
   }
   // GET is always idempotent → safe to retry.
-  async get(path, auth) {
-    return this.request("GET", path, void 0, auth, true);
+  async get(path, auth, opts) {
+    return this.request("GET", path, void 0, auth, true, opts?.signal);
   }
   authHeaders(auth) {
     switch (auth.kind) {
@@ -116,7 +116,7 @@ var _Http = class _Http {
         return {};
     }
   }
-  async request(method, path, body, auth, idempotent) {
+  async request(method, path, body, auth, idempotent, signal) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
       Accept: "application/json",
@@ -126,10 +126,13 @@ var _Http = class _Http {
     if (body !== void 0) headers["Content-Type"] = "application/json";
     const payload = body !== void 0 ? JSON.stringify(body) : void 0;
     for (let attempt = 0; ; attempt++) {
+      if (signal?.aborted) throw abortError(path);
       const start = Date.now();
       this.fire("onRequest", { method, url, attempt });
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      const onAbort = () => controller.abort();
+      signal?.addEventListener("abort", onAbort, { once: true });
       let res;
       let networkError;
       try {
@@ -142,12 +145,14 @@ var _Http = class _Http {
         });
       } finally {
         clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
       }
       if (networkError) {
+        if (signal?.aborted) throw abortError(path);
         const willRetry = idempotent && attempt < this.maxRetries;
         this.fire("onError", { method, url, attempt, error: networkError, willRetry });
         if (willRetry) {
-          await sleep(this.backoff(attempt));
+          await sleep(this.backoff(attempt), signal);
           continue;
         }
         throw networkError;
@@ -183,7 +188,7 @@ var _Http = class _Http {
         }
         this.fire("onError", { method, url, attempt, error: err, willRetry: wait !== void 0 });
         if (wait !== void 0) {
-          await sleep(wait);
+          await sleep(wait, signal);
           continue;
         }
         throw err;
@@ -209,8 +214,21 @@ var _Http = class _Http {
 /** HTTP statuses worth retrying — rate limit + transient gateway/server errors. */
 _Http.RETRIABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var Http = _Http;
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    const onAbort = () => done();
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function abortError(path) {
+  return new InvoError({ message: `Request to ${path} was aborted`, code: "ABORTED", status: 0 });
 }
 function pickRequestId(headers) {
   if (!headers || typeof headers.get !== "function") return void 0;
@@ -265,7 +283,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");
   }
@@ -288,13 +306,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));
@@ -306,9 +320,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) {
@@ -348,6 +446,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"] ?? "",
@@ -390,7 +503,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");
     }
@@ -398,7 +511,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 {
@@ -408,7 +521,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",
       {
@@ -422,13 +535,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",
       {
@@ -442,7 +555,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);
@@ -451,7 +564,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");
     }
@@ -467,7 +580,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"] ?? ""),
@@ -483,7 +598,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");
     }
@@ -516,7 +631,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 {
@@ -531,14 +646,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 {
@@ -549,7 +664,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`.",
@@ -562,7 +677,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);
   }
@@ -574,7 +690,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],
@@ -616,7 +732,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 {
@@ -631,7 +747,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");
     }
@@ -641,7 +757,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"] : [],
@@ -651,7 +768,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()
     );
@@ -668,12 +785,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))}`;
@@ -686,7 +831,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"] ?? {},
@@ -695,6 +840,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"];
@@ -709,6 +878,8 @@ var InvoServer = class {
 
 exports.InvoError = InvoError;
 exports.InvoServer = InvoServer;
+exports.createWebhookHandler = createWebhookHandler;
 exports.verifyWebhook = verifyWebhook;
+exports.verifyWebhookAsync = verifyWebhookAsync;
 //# sourceMappingURL=server.cjs.map
 //# sourceMappingURL=server.cjs.map

package/dist/server.d.cts

@@ -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.cjs';
-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.cjs';
+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.cjs';
+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.cjs';
 
 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 };