@invonetwork/web-sdk 0.2.1 → 0.4.0

package/dist/server.d.cts

@@ -1,5 +1,147 @@
-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.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.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). */
+    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. **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 (bytes or string) — never a re-serialized object.
+ * @param signatureHeader  The `X-Invo-Signature` header value.
+ * @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;
@@ -8,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"
@@ -25,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<Record<string, unknown>>;
+    }, opts?: CallOptions): Promise<ConfirmPaymentResult>;
     /** Fetch purchase status (order + financial summary + timeline). */
     getOrderDetails(query: {
         orderId?: string;
         transactionId?: string;
-    }): Promise<Record<string, unknown>>;
+    }, 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
@@ -44,13 +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<Record<string, unknown>>;
+    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<Record<string, unknown>>;
+    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, 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 { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };
+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.d.ts

@@ -1,5 +1,147 @@
-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 { 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). */
+    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. **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 (bytes or string) — never a re-serialized object.
+ * @param signatureHeader  The `X-Invo-Signature` header value.
+ * @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;
@@ -8,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"
@@ -25,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<Record<string, unknown>>;
+    }, opts?: CallOptions): Promise<ConfirmPaymentResult>;
     /** Fetch purchase status (order + financial summary + timeline). */
     getOrderDetails(query: {
         orderId?: string;
         transactionId?: string;
-    }): Promise<Record<string, unknown>>;
+    }, 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
@@ -44,13 +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<Record<string, unknown>>;
+    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<Record<string, unknown>>;
+    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, 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 { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };
+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 };