@invonetwork/web-sdk 0.2.0 → 0.3.0

package/dist/server.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var crypto = require('crypto');
+
 // src/shared/errors.ts
 var InvoError = class _InvoError extends Error {
   constructor(args) {
@@ -8,6 +10,7 @@ var InvoError = class _InvoError extends Error {
     this.code = args.code;
     this.status = args.status;
     this.body = args.body ?? null;
+    this.requestId = args.requestId;
     Object.setPrototypeOf(this, _InvoError.prototype);
   }
   /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
@@ -45,7 +48,7 @@ var InvoError = class _InvoError extends Error {
     return this.body && typeof this.body === "object" ? this.body : {};
   }
 };
-function errorFromResponse(status, body) {
+function errorFromResponse(status, body, requestId) {
   let message = `INVO request failed (HTTP ${status})`;
   let code;
   if (body && typeof body === "object") {
@@ -56,11 +59,12 @@ function errorFromResponse(status, body) {
   } else if (typeof body === "string" && body.trim()) {
     message = body;
   }
-  return new InvoError({ message, code, status, body });
+  return new InvoError({ message, code, status, body, requestId });
 }
 
 // src/shared/http.ts
 var DEFAULT_TIMEOUT = 3e4;
+var MAX_RETRY_AFTER_MS = 2e4;
 function assertSecureBaseUrl(baseUrl) {
   let u;
   try {
@@ -74,7 +78,7 @@ function assertSecureBaseUrl(baseUrl) {
     `baseUrl must use https:// (got "${u.protocol}//"). Plaintext would expose the token/secret on the wire.`
   );
 }
-var Http = class {
+var _Http = class _Http {
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
@@ -86,12 +90,21 @@ var Http = class {
     }
     this.fetchImpl = f;
     this.userAgent = opts.userAgent;
+    this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+    this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 250;
+    this.hooks = opts.hooks;
   }
-  async post(path, body, auth) {
-    return this.request("POST", path, body, auth);
+  /**
+   * @param opts.idempotent - mark this POST safe to auto-retry (it carries an
+   *   idempotency key, or has no side effect). Default false: non-idempotent POSTs
+   *   (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);
   }
+  // GET is always idempotent → safe to retry.
   async get(path, auth) {
-    return this.request("GET", path, void 0, auth);
+    return this.request("GET", path, void 0, auth, true);
   }
   authHeaders(auth) {
     switch (auth.kind) {
@@ -103,7 +116,7 @@ var Http = class {
         return {};
     }
   }
-  async request(method, path, body, auth) {
+  async request(method, path, body, auth, idempotent) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
       Accept: "application/json",
@@ -111,38 +124,188 @@ var Http = class {
     };
     if (this.userAgent) headers["User-Agent"] = this.userAgent;
     if (body !== void 0) headers["Content-Type"] = "application/json";
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-    let res;
-    try {
-      res = await this.fetchImpl(url, {
+    const payload = body !== void 0 ? JSON.stringify(body) : void 0;
+    for (let attempt = 0; ; attempt++) {
+      const start = Date.now();
+      this.fire("onRequest", { method, url, attempt });
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let res;
+      let networkError;
+      try {
+        res = await this.fetchImpl(url, { method, headers, body: payload, signal: controller.signal });
+      } catch (err) {
+        networkError = new InvoError({
+          message: err instanceof Error && err.name === "AbortError" ? `Request to ${path} timed out after ${this.timeoutMs}ms` : `Network error calling ${path}: ${err?.message ?? err}`,
+          status: 0,
+          body: null
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+      if (networkError) {
+        const willRetry = idempotent && attempt < this.maxRetries;
+        this.fire("onError", { method, url, attempt, error: networkError, willRetry });
+        if (willRetry) {
+          await sleep(this.backoff(attempt));
+          continue;
+        }
+        throw networkError;
+      }
+      const requestId = pickRequestId(res.headers);
+      const text = await res.text();
+      let parsed = null;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      }
+      this.fire("onResponse", {
         method,
-        headers,
-        body: body !== void 0 ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-    } catch (err) {
-      throw new InvoError({
-        message: err instanceof Error && err.name === "AbortError" ? `Request to ${path} timed out after ${this.timeoutMs}ms` : `Network error calling ${path}: ${err?.message ?? err}`,
-        status: 0,
-        body: null
+        url,
+        attempt,
+        status: res.status,
+        durationMs: Date.now() - start,
+        requestId
       });
-    } finally {
-      clearTimeout(timer);
-    }
-    const text = await res.text();
-    let parsed = null;
-    if (text) {
-      try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
+      if (!res.ok) {
+        const err = errorFromResponse(res.status, parsed, requestId);
+        let wait;
+        if (idempotent && attempt < this.maxRetries && _Http.RETRIABLE_STATUS.has(res.status)) {
+          if (res.status === 429) {
+            const ra = retryAfterMs(parsed, res.headers);
+            wait = ra === void 0 ? this.backoff(attempt) : ra <= MAX_RETRY_AFTER_MS ? ra : void 0;
+          } else {
+            wait = this.backoff(attempt);
+          }
+        }
+        this.fire("onError", { method, url, attempt, error: err, willRetry: wait !== void 0 });
+        if (wait !== void 0) {
+          await sleep(wait);
+          continue;
+        }
+        throw err;
       }
+      return parsed ?? {};
     }
-    if (!res.ok) throw errorFromResponse(res.status, parsed);
-    return parsed ?? {};
+  }
+  /** Invoke an observability hook, swallowing any error it throws (best-effort). */
+  fire(name, info) {
+    const hook = this.hooks?.[name];
+    if (!hook) return;
+    try {
+      hook(info);
+    } catch {
+    }
+  }
+  /** Exponential backoff with full jitter: base * 2^attempt, randomized. */
+  backoff(attempt) {
+    const ceil = this.retryBaseDelayMs * 2 ** attempt;
+    return Math.floor(Math.random() * ceil) + this.retryBaseDelayMs;
   }
 };
+/** 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 pickRequestId(headers) {
+  if (!headers || typeof headers.get !== "function") return void 0;
+  return headers.get("x-invo-request-id") ?? headers.get("x-request-id") ?? void 0;
+}
+function retryAfterMs(parsed, headers) {
+  if (parsed && typeof parsed === "object") {
+    const v = parsed["retry_after"];
+    const n = typeof v === "string" ? Number(v) : v;
+    if (typeof n === "number" && Number.isFinite(n) && n >= 0) return n * 1e3;
+  }
+  const header = headers && typeof headers.get === "function" ? headers.get("retry-after") : null;
+  if (header) {
+    const n = Number(header);
+    if (Number.isFinite(n) && n >= 0) return n * 1e3;
+  }
+  return void 0;
+}
+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 crypto.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)";
@@ -177,6 +340,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) {
@@ -198,17 +381,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),
@@ -230,7 +421,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);
   }
@@ -248,7 +441,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);
   }
@@ -257,6 +452,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,
@@ -286,6 +484,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({
@@ -314,7 +515,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"] ?? ""),
@@ -331,11 +534,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) {
@@ -349,10 +560,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).
@@ -403,7 +615,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"] ?? ""),
@@ -425,10 +639,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?" */
@@ -447,10 +666,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"];
@@ -466,5 +709,6 @@ var InvoServer = class {
 
 exports.InvoError = InvoError;
 exports.InvoServer = InvoServer;
+exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=server.cjs.map
 //# sourceMappingURL=server.cjs.map

package/dist/server.d.cts

@@ -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.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.cjs';
+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';
+
+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 };