@invonetwork/web-sdk 0.2.1 → 0.4.0

package/dist/server.js

@@ -1,8 +1,167 @@
-import { assertSecureBaseUrl, Http, InvoError } from './chunk-A44O4KC3.js';
-export { InvoError } from './chunk-A44O4KC3.js';
+import { InvoError, assertSecureBaseUrl, Http } from './chunk-EEWOAUXO.js';
+export { InvoError } from './chunk-EEWOAUXO.js';
+import { createHmac } from 'crypto';
+
+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 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 prepareVerification(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);
+  return { secrets, sigs, message, bodyBytes };
+}
+function finalizeEvent(bodyBytes) {
+  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;
+}
+function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+  const { secrets, sigs, message, bodyBytes } = prepareVerification(
+    rawBody,
+    signatureHeader,
+    secret,
+    opts
+  );
+  const matched = secrets.some((s) => {
+    const expected = hmacHex(s, message);
+    return sigs.some((sig) => safeEqualHex(sig, expected));
+  });
+  if (!matched) {
+    throw webhookError("Webhook signature verification failed.", "WEBHOOK_SIGNATURE_INVALID");
+  }
+  return finalizeEvent(bodyBytes);
+}
+async function verifyWebhookAsync(rawBody, signatureHeader, secret, opts = {}) {
+  const { secrets, sigs, message, bodyBytes } = prepareVerification(
+    rawBody,
+    signatureHeader,
+    secret,
+    opts
+  );
+  for (const s of secrets) {
+    const expected = await hmacHexSubtle(s, message);
+    if (sigs.some((sig) => safeEqualHex(sig, expected))) {
+      return finalizeEvent(bodyBytes);
+    }
+  }
+  throw webhookError("Webhook signature verification failed.", "WEBHOOK_SIGNATURE_INVALID");
+}
+function createWebhookHandler(opts) {
+  return async (request) => {
+    const raw = await request.text();
+    let event;
+    try {
+      event = await verifyWebhookAsync(raw, request.headers.get("x-invo-signature"), opts.secret, {
+        toleranceSec: opts.toleranceSec
+      });
+    } catch (e) {
+      const err = e instanceof InvoError ? e : new InvoError({ message: String(e), status: 0 });
+      if (opts.onError) {
+        try {
+          const r = await opts.onError(err, request);
+          if (r instanceof Response) return r;
+        } catch {
+        }
+      }
+      return new Response(err.code ?? "invalid_signature", { status: 400 });
+    }
+    try {
+      await opts.onEvent(event, {
+        // Prefer the signature-covered body field over the (unauthenticated, optional)
+        // header — the body value is HMAC-verified and always present.
+        idempotencyKey: event.idempotency_key ?? request.headers.get("x-invo-idempotency-key"),
+        request
+      });
+    } catch {
+      return new Response("handler_error", { status: 500 });
+    }
+    return new Response(null, { status: 200 });
+  };
+}
+async function hmacHexSubtle(secret, message) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw webhookError(
+      "Web Crypto (crypto.subtle) is unavailable in this runtime.",
+      "WEBHOOK_UNSUPPORTED"
+    );
+  }
+  const key = await subtle.importKey(
+    "raw",
+    ENCODER.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await subtle.sign("HMAC", key, message);
+  const bytes = new Uint8Array(sig);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
 
 // src/server.ts
-var DEFAULT_UA = "invonetwork-web-sdk/0.1.0 (+https://invo.network)";
+var DEFAULT_UA = "invonetwork-web-sdk/0.4.0 (+https://invo.network)";
 var MAX_USD_AMOUNT = 999.99;
 var MAX_ITEM_PRICE = 999999.99;
 function invalidInput(label, value, why) {
@@ -34,6 +193,41 @@ 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 toInboundPendingItem(row) {
+  return {
+    transactionId: String(row["transaction_id"] ?? ""),
+    flow: String(row["flow"] ?? ""),
+    amount: String(row["amount"] ?? ""),
+    netAmount: String(row["net_amount"] ?? ""),
+    sourceGameId: row["source_game_id"] ?? "",
+    sourceGame: String(row["source_game"] ?? ""),
+    toPhone: String(row["to_phone"] ?? ""),
+    toIdentityId: row["to_identity_id"] ?? null,
+    createdAt: String(row["created_at"] ?? ""),
+    claimCodeExpiresAt: String(row["claim_code_expires_at"] ?? ""),
+    raw: row
+  };
+}
+function toCurrencyBalance(row) {
+  return {
+    currencyId: row["currency_id"] ?? "",
+    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) {
@@ -55,17 +249,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) {
+  async mintPlayerToken(input, opts) {
+    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, signal: opts?.signal }
+      // safe to retry: re-mint just issues a fresh token
     );
     return {
       token: requireField(raw["token"], "token", raw),
@@ -74,7 +276,7 @@ var InvoServer = class {
     };
   }
   /** Initiate a cross-game currency SEND. Inspect result.verificationMethod. */
-  async initiateSend(input) {
+  async initiateSend(input, opts) {
     const raw = await this.http.post(
       "/api/currency-sends/initiate-send",
       {
@@ -87,12 +289,14 @@ var InvoServer = class {
         receiving_game_id: input.receivingGameId,
         amount: input.amount
       },
-      this.auth
+      this.auth,
+      { idempotent: true, signal: opts?.signal }
+      // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
   }
   /** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. */
-  async initiateTransfer(input) {
+  async initiateTransfer(input, opts) {
     const raw = await this.http.post(
       "/api/transfers/initiate-transfer",
       {
@@ -105,7 +309,9 @@ var InvoServer = class {
         target_game_id: input.targetGameId,
         amount: input.amount
       },
-      this.auth
+      this.auth,
+      { idempotent: true, signal: opts?.signal }
+      // client_request_id makes this safe to retry (backend dedupes)
     );
     return this.toInitiateResult(raw);
   }
@@ -113,7 +319,10 @@ var InvoServer = class {
    *  returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
    *  handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
    *  purchase.completed webhook. */
-  async createCheckout(input) {
+  async createCheckout(input, opts) {
+    if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
+      throw invalidInput("playerEmail", input.playerEmail, "is required");
+    }
     assertUsdAmount(input.usdAmount);
     const body = {
       player_email: input.playerEmail,
@@ -126,7 +335,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/checkout/sessions",
       body,
-      this.auth
+      this.auth,
+      { signal: opts?.signal }
+      // not idempotent — never auto-retried
     );
     return {
       sessionId: String(raw["session_id"] ?? ""),
@@ -142,7 +353,10 @@ var InvoServer = class {
    * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
    * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
    */
-  async purchaseCurrency(input) {
+  async purchaseCurrency(input, opts) {
+    if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
+      throw invalidInput("playerEmail", input.playerEmail, "is required");
+    }
     assertUsdAmount(input.usdAmount);
     if (!input.purchaseReference) {
       throw new InvoError({
@@ -171,7 +385,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/currency-purchases/purchase-currency",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true, signal: opts?.signal }
+      // purchase_reference makes this safe to retry (backend dedupes)
     );
     return {
       status: String(raw["status"] ?? ""),
@@ -185,17 +401,25 @@ var InvoServer = class {
     };
   }
   /** Complete the Stripe-rail 3-D Secure step after the client finished card action. */
-  async confirmPayment(input) {
+  async confirmPayment(input, opts) {
     const body = { payment_intent_id: input.paymentIntentId };
     if (input.orderId) body["order_id"] = input.orderId;
-    return this.http.post(
+    const raw = await this.http.post(
       "/api/currency-purchases/confirm-payment",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true, signal: opts?.signal }
+      // 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) {
+  async getOrderDetails(query, opts) {
     if (!query.orderId && !query.transactionId) {
       throw new InvoError({
         message: "getOrderDetails requires an `orderId` or `transactionId`.",
@@ -206,10 +430,12 @@ 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
+      this.auth,
+      { signal: opts?.signal }
     );
+    return toOrderDetails(raw);
   }
   /**
    * Buy an in-game item by SPENDING the player's existing game currency (§4.8).
@@ -219,7 +445,7 @@ var InvoServer = class {
    * (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
    * item to your inventory off the `item.purchased` webhook, not just this response.
    */
-  async purchaseItem(input) {
+  async purchaseItem(input, opts) {
     const required = [
       ["clientRequestId", input.clientRequestId],
       ["playerEmail", input.playerEmail],
@@ -260,7 +486,9 @@ var InvoServer = class {
     const raw = await this.http.post(
       "/api/item-purchases/purchase-item",
       body,
-      this.auth
+      this.auth,
+      { idempotent: true, signal: opts?.signal }
+      // client_request_id makes this safe to retry (dup → 409)
     );
     return {
       status: String(raw["status"] ?? ""),
@@ -274,7 +502,7 @@ var InvoServer = class {
     };
   }
   /** Paginated item-purchase history for a player (§4.8 companion read). */
-  async getItemPurchaseHistory(query) {
+  async getItemPurchaseHistory(query, opts) {
     if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
       throw invalidInput("playerEmail", query.playerEmail, "is required");
     }
@@ -282,14 +510,20 @@ 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
+      this.auth,
+      { signal: opts?.signal }
     );
+    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?" */
-  async getItemOrderDetails(query) {
+  async getItemOrderDetails(query, opts) {
     const provided = [query.orderId, query.transactionId, query.clientRequestId].filter(
       (v) => typeof v === "string" && v.trim()
     );
@@ -304,10 +538,86 @@ 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
+      this.auth,
+      { signal: opts?.signal }
+    );
+    return toOrderDetails(raw);
+  }
+  /**
+   * Async iterator over a player's entire item-purchase history — pages through
+   * `getItemPurchaseHistory` (limit/offset) until exhausted, yielding one row at a time.
+   *
+   * ```ts
+   * for await (const row of invo.iterateItemPurchaseHistory({ playerEmail })) { … }
+   * ```
+   */
+  async *iterateItemPurchaseHistory(query, opts) {
+    if (typeof query.playerEmail !== "string" || !query.playerEmail.trim()) {
+      throw invalidInput("playerEmail", query.playerEmail, "is required");
+    }
+    const pageSize = typeof query.pageSize === "number" && query.pageSize > 0 ? Math.floor(query.pageSize) : 50;
+    let yielded = 0;
+    for (let offset = 0; ; offset += pageSize) {
+      const { history, pagination } = await this.getItemPurchaseHistory(
+        { playerEmail: query.playerEmail, limit: pageSize, offset },
+        opts
+      );
+      if (history.length === 0) return;
+      for (const row of history) yield row;
+      yielded += history.length;
+      if (history.length < pageSize) return;
+      const total = Number(pagination?.["total"]);
+      if (Number.isFinite(total) && yielded >= total) return;
+    }
+  }
+  /** Read a player's currency balances, by email or playerId (game-secret). */
+  async getPlayerBalance(query, opts) {
+    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, { signal: opts?.signal });
+    const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
+    return {
+      player: raw["player"] ?? {},
+      balances: rows.map(toCurrencyBalance),
+      summary: raw["summary"] ?? {},
+      raw
+    };
+  }
+  /**
+   * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
+   * the source of truth for a "you have X to collect" badge. Pass the player's email
+   * or phone. Match `toPhone` to the logged-in player (don't require `toIdentityId`,
+   * which is null when the phone maps to more than one of your players). Pairs with the
+   * `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
+   */
+  async getInboundPending(query, opts) {
+    const hasEmail = typeof query.playerEmail === "string" && query.playerEmail.trim();
+    const hasPhone = typeof query.playerPhone === "string" && query.playerPhone.trim();
+    if (!hasEmail && !hasPhone) {
+      throw invalidInput("query", query, "requires a playerEmail or playerPhone");
+    }
+    const q = new URLSearchParams();
+    if (hasEmail) q.set("player_email", query.playerEmail.trim());
+    if (hasPhone) q.set("player_phone", query.playerPhone.trim());
+    const raw = await this.http.get(
+      `/api/transfers/inbound-pending?${q.toString()}`,
+      this.auth,
+      { signal: opts?.signal }
     );
+    const rows = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
+    return { inboundPending: rows.map(toInboundPendingItem), raw };
   }
   toInitiateResult(raw) {
     const vm = raw["verification_method"];
@@ -321,6 +631,6 @@ var InvoServer = class {
   }
 };
 
-export { InvoServer };
+export { InvoServer, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
 //# sourceMappingURL=server.js.map
 //# sourceMappingURL=server.js.map