@invonetwork/web-sdk 0.2.1 → 0.3.0

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

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@invonetwork/web-sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "private": false,
   "repository": {
     "type": "git",

package/dist/chunk-A44O4KC3.js

@@ -1,147 +0,0 @@
-// src/shared/errors.ts
-var InvoError = class _InvoError extends Error {
-  constructor(args) {
-    super(args.message);
-    this.name = "InvoError";
-    this.code = args.code;
-    this.status = args.status;
-    this.body = args.body ?? null;
-    Object.setPrototypeOf(this, _InvoError.prototype);
-  }
-  /** True if this is the "recipient isn't passkey-enrolled, fall back to claim code" signal. */
-  get isReceiverNotEnrolled() {
-    return this.code === "receiver_not_enrolled_use_claim_code" || /receiver_not_enrolled_use_claim_code/i.test(this.message);
-  }
-  /** True if the session/SDK token has expired and the caller should re-mint + retry. */
-  get isTokenExpired() {
-    return this.code === "SDK_TOKEN_EXPIRED";
-  }
-  /**
-   * True if an item purchase failed because the player's balance was too low (§4.8 → 400).
-   * The backend carries `required_amount` + `current_balance` on the body for the UI.
-   * Gated to status 400 so the `429 insufficient_balance_blocked` abuse throttle (which
-   * is a rate-limit, not a top-up condition) is NOT misclassified as this.
-   */
-  get isInsufficientBalance() {
-    if (this.status !== 400) return false;
-    const b = this.bodyObject();
-    return this.code === "INSUFFICIENT_BALANCE" || "required_amount" in b || /insufficient[_ ]balance/i.test(this.message);
-  }
-  /** True if an idempotency-keyed request was a duplicate (item purchase → 409). */
-  get isDuplicateRequest() {
-    return this.code === "DUPLICATE_REQUEST" || this.status === 409 && /duplicate/i.test(this.message);
-  }
-  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
-  get retryAfter() {
-    const v = this.bodyObject()["retry_after"];
-    const n = typeof v === "string" ? Number(v) : v;
-    return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : void 0;
-  }
-  /** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
-   *  The `in` operator throws on primitives, so callers must go through this. */
-  bodyObject() {
-    return this.body && typeof this.body === "object" ? this.body : {};
-  }
-};
-function errorFromResponse(status, body) {
-  let message = `INVO request failed (HTTP ${status})`;
-  let code;
-  if (body && typeof body === "object") {
-    const b = body;
-    if (typeof b["code"] === "string") code = b["code"];
-    if (typeof b["error"] === "string") message = b["error"];
-    else if (typeof b["message"] === "string") message = b["message"];
-  } else if (typeof body === "string" && body.trim()) {
-    message = body;
-  }
-  return new InvoError({ message, code, status, body });
-}
-
-// src/shared/http.ts
-var DEFAULT_TIMEOUT = 3e4;
-function assertSecureBaseUrl(baseUrl) {
-  let u;
-  try {
-    u = new URL(baseUrl);
-  } catch {
-    throw new Error(`Invalid baseUrl: ${baseUrl}`);
-  }
-  const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
-  if (u.protocol === "https:" || u.protocol === "http:" && isLocal) return;
-  throw new Error(
-    `baseUrl must use https:// (got "${u.protocol}//"). Plaintext would expose the token/secret on the wire.`
-  );
-}
-var Http = class {
-  constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
-    const f = opts.fetchImpl ?? globalThis.fetch;
-    if (typeof f !== "function") {
-      throw new Error(
-        "No fetch implementation available. Use Node >=18, or pass `fetch` in the config."
-      );
-    }
-    this.fetchImpl = f;
-    this.userAgent = opts.userAgent;
-  }
-  async post(path, body, auth) {
-    return this.request("POST", path, body, auth);
-  }
-  async get(path, auth) {
-    return this.request("GET", path, void 0, auth);
-  }
-  authHeaders(auth) {
-    switch (auth.kind) {
-      case "game-secret":
-        return { "X-Game-Secret-Key": auth.secret };
-      case "bearer":
-        return { Authorization: `Bearer ${auth.token}` };
-      case "none":
-        return {};
-    }
-  }
-  async request(method, path, body, auth) {
-    const url = `${this.baseUrl}${path}`;
-    const headers = {
-      Accept: "application/json",
-      ...this.authHeaders(auth)
-    };
-    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, {
-        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
-      });
-    } finally {
-      clearTimeout(timer);
-    }
-    const text = await res.text();
-    let parsed = null;
-    if (text) {
-      try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
-      }
-    }
-    if (!res.ok) throw errorFromResponse(res.status, parsed);
-    return parsed ?? {};
-  }
-};
-
-export { Http, InvoError, assertSecureBaseUrl };
-//# sourceMappingURL=chunk-A44O4KC3.js.map
-//# sourceMappingURL=chunk-A44O4KC3.js.map