@invonetwork/web-sdk 0.1.0 → 0.2.1

package/dist/{errors-B7rVID2r.d.cts → errors-DV5QsftP.d.cts}

@@ -107,6 +107,47 @@ interface PurchaseResult {
     newBalance?: string | number | null;
     raw: Record<string, unknown>;
 }
+interface PurchaseItemInput {
+    /** Idempotency key, unique per game. Required. A duplicate returns 409. */
+    clientRequestId: string;
+    playerEmail: string;
+    playerName: string;
+    itemId: string;
+    itemName: string;
+    /** Integer quantity, 1..1000. */
+    itemQuantity: number;
+    /** Price PER UNIT, in game-currency units (not USD). > 0 and <= 999999.99. */
+    unitPrice: string | number;
+    /** Must equal unitPrice × itemQuantity (±0.01). > 0 and <= 999999.99. */
+    totalPrice: string | number;
+    playerPhone?: string;
+    itemDescription?: string;
+    itemCategory?: string;
+}
+interface PurchaseItemResult {
+    /** "success" on a completed spend. */
+    status: string;
+    transactionId: string;
+    orderId: string;
+    /** Canonical balance AFTER the spend (game-currency units). */
+    newBalance: string | number | null;
+    previousBalance: string | number | null;
+    currencyName: string;
+    /** { total_paid, developer_revenue, platform_fee } when present. */
+    financialBreakdown?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+interface ItemHistoryQuery {
+    playerEmail: string;
+    limit?: number;
+    offset?: number;
+}
+/** Look up an item order by EXACTLY ONE of these. */
+interface ItemOrderQuery {
+    orderId?: string;
+    transactionId?: string;
+    clientRequestId?: string;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -151,6 +192,20 @@ declare class InvoError extends Error {
     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 };
+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 };

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

@@ -107,6 +107,47 @@ interface PurchaseResult {
     newBalance?: string | number | null;
     raw: Record<string, unknown>;
 }
+interface PurchaseItemInput {
+    /** Idempotency key, unique per game. Required. A duplicate returns 409. */
+    clientRequestId: string;
+    playerEmail: string;
+    playerName: string;
+    itemId: string;
+    itemName: string;
+    /** Integer quantity, 1..1000. */
+    itemQuantity: number;
+    /** Price PER UNIT, in game-currency units (not USD). > 0 and <= 999999.99. */
+    unitPrice: string | number;
+    /** Must equal unitPrice × itemQuantity (±0.01). > 0 and <= 999999.99. */
+    totalPrice: string | number;
+    playerPhone?: string;
+    itemDescription?: string;
+    itemCategory?: string;
+}
+interface PurchaseItemResult {
+    /** "success" on a completed spend. */
+    status: string;
+    transactionId: string;
+    orderId: string;
+    /** Canonical balance AFTER the spend (game-currency units). */
+    newBalance: string | number | null;
+    previousBalance: string | number | null;
+    currencyName: string;
+    /** { total_paid, developer_revenue, platform_fee } when present. */
+    financialBreakdown?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+interface ItemHistoryQuery {
+    playerEmail: string;
+    limit?: number;
+    offset?: number;
+}
+/** Look up an item order by EXACTLY ONE of these. */
+interface ItemOrderQuery {
+    orderId?: string;
+    transactionId?: string;
+    clientRequestId?: string;
+}
 interface ApproveResult {
     status: string;
     next: string;
@@ -151,6 +192,20 @@ declare class InvoError extends Error {
     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 };
+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 };

package/dist/index.cjs

@@ -18,6 +18,32 @@ var InvoError = class _InvoError extends Error {
   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})`;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.cjs';
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-DV5QsftP.cjs';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.cjs';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-B7rVID2r.js';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.js';
+import { C as ClientConfig, A as ApproveResult, a as ConfirmReceiptResult, L as LinkDeviceResult } from './errors-DV5QsftP.js';
+export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-DV5QsftP.js';
 
 declare class InvoClient {
     private readonly http;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-KUQVVH2P.js';
-export { InvoError } from './chunk-KUQVVH2P.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
+export { InvoError } from './chunk-A44O4KC3.js';
 
 // src/shared/webauthn.ts
 function b64urlToBuffer(value) {

package/dist/server.cjs

@@ -18,6 +18,32 @@ var InvoError = class _InvoError extends Error {
   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})`;
@@ -121,29 +147,35 @@ var Http = class {
 // src/server.ts
 var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
-function invalidAmount(usdAmount, why) {
+var MAX_ITEM_PRICE = 999999.99;
+function invalidInput(label, value, why) {
   return new InvoError({
-    message: `usdAmount ${why} (got ${JSON.stringify(usdAmount)}).`,
+    message: `${label} ${why} (got ${JSON.stringify(value)}).`,
     code: "INVALID_INPUT",
     status: 0
   });
 }
-function assertUsdAmount(usdAmount) {
+var PLAIN_DECIMAL = /^\d+(\.\d{1,2})?$/;
+function parseMoney(value, max, label) {
   let n;
-  if (typeof usdAmount === "number") {
-    n = usdAmount;
-    if (Number.isFinite(n) && Math.abs(n * 100 - Math.round(n * 100)) > 1e-9) {
-      throw invalidAmount(usdAmount, "must have at most 2 decimal places");
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !PLAIN_DECIMAL.test(String(value))) {
+      throw invalidInput(label, value, "must be a positive decimal with at most 2 places");
     }
+    n = value;
   } else {
-    if (!/^\d+(\.\d{1,2})?$/.test(usdAmount)) {
-      throw invalidAmount(usdAmount, "must be a plain decimal USD value with at most 2 places");
+    if (!PLAIN_DECIMAL.test(value)) {
+      throw invalidInput(label, value, "must be a plain decimal value with at most 2 places");
     }
-    n = Number(usdAmount);
+    n = Number(value);
   }
-  if (!Number.isFinite(n) || n <= 0 || n > MAX_USD_AMOUNT) {
-    throw invalidAmount(usdAmount, `must be > 0 and <= ${MAX_USD_AMOUNT}`);
+  if (!Number.isFinite(n) || n <= 0 || n > max) {
+    throw invalidInput(label, value, `must be > 0 and <= ${max}`);
   }
+  return n;
+}
+function assertUsdAmount(usdAmount) {
+  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
 }
 function requireField(value, field, raw) {
   const s = value == null ? "" : String(value);
@@ -322,6 +354,104 @@ var InvoServer = class {
       this.auth
     );
   }
+  /**
+   * 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
+   * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+   * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+   * (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) {
+    const required = [
+      ["clientRequestId", input.clientRequestId],
+      ["playerEmail", input.playerEmail],
+      ["playerName", input.playerName],
+      ["itemId", input.itemId],
+      ["itemName", input.itemName]
+    ];
+    for (const [k, v] of required) {
+      if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
+    }
+    if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
+      throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
+    }
+    const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
+    const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
+    const expectedCents = Math.round(unit * input.itemQuantity * 100);
+    const totalCents = Math.round(total * 100);
+    if (Math.abs(totalCents - expectedCents) > 1) {
+      throw invalidInput(
+        "totalPrice",
+        input.totalPrice,
+        `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
+      );
+    }
+    const body = {
+      client_request_id: input.clientRequestId,
+      player_email: input.playerEmail,
+      player_name: input.playerName,
+      item_id: input.itemId,
+      item_name: input.itemName,
+      item_quantity: input.itemQuantity,
+      unit_price: input.unitPrice,
+      total_price: input.totalPrice
+    };
+    if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.itemDescription) body["item_description"] = input.itemDescription;
+    if (input.itemCategory) body["item_category"] = input.itemCategory;
+    const raw = await this.http.post(
+      "/api/item-purchases/purchase-item",
+      body,
+      this.auth
+    );
+    return {
+      status: String(raw["status"] ?? ""),
+      transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
+      orderId: requireField(raw["order_id"], "order_id", raw),
+      newBalance: raw["new_balance"] ?? null,
+      previousBalance: raw["previous_balance"] ?? null,
+      currencyName: String(raw["currency_name"] ?? ""),
+      financialBreakdown: raw["financial_breakdown"],
+      raw
+    };
+  }
+  /** Paginated item-purchase history for a player (§4.8 companion read). */
+  async getItemPurchaseHistory(query) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const q = new URLSearchParams();
+    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(
+      `/api/item-purchases/player-purchase-history?${q.toString()}`,
+      this.auth
+    );
+  }
+  /** 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) {
+    const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
+      (v) => typeof v === "string" && v.trim()
+    );
+    if (provided.length !== 1) {
+      throw new InvoError({
+        message: "getItemOrderDetails requires EXACTLY ONE of orderId, transactionId, or clientRequestId.",
+        code: "INVALID_INPUT",
+        status: 0
+      });
+    }
+    const q = new URLSearchParams();
+    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(
+      `/api/item-purchases/order-details?${q.toString()}`,
+      this.auth
+    );
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-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 } from './errors-B7rVID2r.cjs';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.cjs';
+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';
 
 declare class InvoServer {
     private readonly http;
@@ -36,7 +36,21 @@ declare class InvoServer {
         orderId?: string;
         transactionId?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * 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
+     * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+     * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+     * (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>;
+    /** Paginated item-purchase history for a player (§4.8 companion read). */
+    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<Record<string, unknown>>;
+    /** 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>>;
     private toInitiateResult;
 }
 
-export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, PlayerToken, PurchaseInput, PurchaseResult, ServerConfig };
+export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-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 } from './errors-B7rVID2r.js';
-export { I as InvoError, R as Rail, V as VerificationMethod } from './errors-B7rVID2r.js';
+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';
 
 declare class InvoServer {
     private readonly http;
@@ -36,7 +36,21 @@ declare class InvoServer {
         orderId?: string;
         transactionId?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * 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
+     * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+     * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+     * (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>;
+    /** Paginated item-purchase history for a player (§4.8 companion read). */
+    getItemPurchaseHistory(query: ItemHistoryQuery): Promise<Record<string, unknown>>;
+    /** 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>>;
     private toInitiateResult;
 }
 
-export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, PlayerToken, PurchaseInput, PurchaseResult, ServerConfig };
+export { CreateCheckoutInput, CreateCheckoutResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoServer, ItemHistoryQuery, ItemOrderQuery, PlayerToken, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, ServerConfig };

package/dist/server.js

@@ -1,32 +1,38 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-KUQVVH2P.js';
-export { InvoError } from './chunk-KUQVVH2P.js';
+import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
+export { InvoError } from './chunk-A44O4KC3.js';
 
 // src/server.ts
 var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
-function invalidAmount(usdAmount, why) {
+var MAX_ITEM_PRICE = 999999.99;
+function invalidInput(label, value, why) {
   return new InvoError({
-    message: `usdAmount ${why} (got ${JSON.stringify(usdAmount)}).`,
+    message: `${label} ${why} (got ${JSON.stringify(value)}).`,
     code: "INVALID_INPUT",
     status: 0
   });
 }
-function assertUsdAmount(usdAmount) {
+var PLAIN_DECIMAL = /^\d+(\.\d{1,2})?$/;
+function parseMoney(value, max, label) {
   let n;
-  if (typeof usdAmount === "number") {
-    n = usdAmount;
-    if (Number.isFinite(n) && Math.abs(n * 100 - Math.round(n * 100)) > 1e-9) {
-      throw invalidAmount(usdAmount, "must have at most 2 decimal places");
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !PLAIN_DECIMAL.test(String(value))) {
+      throw invalidInput(label, value, "must be a positive decimal with at most 2 places");
     }
+    n = value;
   } else {
-    if (!/^\d+(\.\d{1,2})?$/.test(usdAmount)) {
-      throw invalidAmount(usdAmount, "must be a plain decimal USD value with at most 2 places");
+    if (!PLAIN_DECIMAL.test(value)) {
+      throw invalidInput(label, value, "must be a plain decimal value with at most 2 places");
     }
-    n = Number(usdAmount);
+    n = Number(value);
   }
-  if (!Number.isFinite(n) || n <= 0 || n > MAX_USD_AMOUNT) {
-    throw invalidAmount(usdAmount, `must be > 0 and <= ${MAX_USD_AMOUNT}`);
+  if (!Number.isFinite(n) || n <= 0 || n > max) {
+    throw invalidInput(label, value, `must be > 0 and <= ${max}`);
   }
+  return n;
+}
+function assertUsdAmount(usdAmount) {
+  parseMoney(usdAmount, MAX_USD_AMOUNT, "usdAmount");
 }
 function requireField(value, field, raw) {
   const s = value == null ? "" : String(value);
@@ -205,6 +211,104 @@ var InvoServer = class {
       this.auth
     );
   }
+  /**
+   * 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
+   * server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
+   * a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
+   * (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) {
+    const required = [
+      ["clientRequestId", input.clientRequestId],
+      ["playerEmail", input.playerEmail],
+      ["playerName", input.playerName],
+      ["itemId", input.itemId],
+      ["itemName", input.itemName]
+    ];
+    for (const [k, v] of required) {
+      if (typeof v !== "string" || !v.trim()) throw invalidInput(k, v, "is required");
+    }
+    if (!Number.isInteger(input.itemQuantity) || input.itemQuantity < 1 || input.itemQuantity > 1e3) {
+      throw invalidInput("itemQuantity", input.itemQuantity, "must be an integer 1..1000");
+    }
+    const unit = parseMoney(input.unitPrice, MAX_ITEM_PRICE, "unitPrice");
+    const total = parseMoney(input.totalPrice, MAX_ITEM_PRICE, "totalPrice");
+    const expectedCents = Math.round(unit * input.itemQuantity * 100);
+    const totalCents = Math.round(total * 100);
+    if (Math.abs(totalCents - expectedCents) > 1) {
+      throw invalidInput(
+        "totalPrice",
+        input.totalPrice,
+        `must equal unitPrice \xD7 itemQuantity (\xB10.01): ${unit} \xD7 ${input.itemQuantity}`
+      );
+    }
+    const body = {
+      client_request_id: input.clientRequestId,
+      player_email: input.playerEmail,
+      player_name: input.playerName,
+      item_id: input.itemId,
+      item_name: input.itemName,
+      item_quantity: input.itemQuantity,
+      unit_price: input.unitPrice,
+      total_price: input.totalPrice
+    };
+    if (input.playerPhone) body["player_phone"] = input.playerPhone;
+    if (input.itemDescription) body["item_description"] = input.itemDescription;
+    if (input.itemCategory) body["item_category"] = input.itemCategory;
+    const raw = await this.http.post(
+      "/api/item-purchases/purchase-item",
+      body,
+      this.auth
+    );
+    return {
+      status: String(raw["status"] ?? ""),
+      transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
+      orderId: requireField(raw["order_id"], "order_id", raw),
+      newBalance: raw["new_balance"] ?? null,
+      previousBalance: raw["previous_balance"] ?? null,
+      currencyName: String(raw["currency_name"] ?? ""),
+      financialBreakdown: raw["financial_breakdown"],
+      raw
+    };
+  }
+  /** Paginated item-purchase history for a player (§4.8 companion read). */
+  async getItemPurchaseHistory(query) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const q = new URLSearchParams();
+    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(
+      `/api/item-purchases/player-purchase-history?${q.toString()}`,
+      this.auth
+    );
+  }
+  /** 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) {
+    const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
+      (v) => typeof v === "string" && v.trim()
+    );
+    if (provided.length !== 1) {
+      throw new InvoError({
+        message: "getItemOrderDetails requires EXACTLY ONE of orderId, transactionId, or clientRequestId.",
+        code: "INVALID_INPUT",
+        status: 0
+      });
+    }
+    const q = new URLSearchParams();
+    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(
+      `/api/item-purchases/order-details?${q.toString()}`,
+      this.auth
+    );
+  }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
     const guardian = raw["guardian_approval"];