@invonetwork/web-sdk 3.20.0 → 3.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/server.cjs CHANGED
@@ -11,6 +11,7 @@ var InvoError = class _InvoError extends Error {
11
11
  this.name = "InvoError";
12
12
  this.code = args.code;
13
13
  this.rawCode = args.rawCode ?? args.code;
14
+ this.publicCode = args.publicCode;
14
15
  this.status = args.status;
15
16
  this.body = args.body ?? null;
16
17
  this.requestId = args.requestId;
@@ -396,7 +397,7 @@ var InvoError = class _InvoError extends Error {
396
397
  * unaffected. Raise the amount; do not retry it unchanged.
397
398
  */
398
399
  get isBelowCardMinimum() {
399
- return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
400
+ return this.code === "BELOW_CARD_MINIMUM" || this.code === "BELOW_STRIPE_MINIMUM" || this.publicCode === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
400
401
  }
401
402
  /** On `BELOW_CARD_MINIMUM`: the minimum card purchase in force (`min_usd`), USD decimal
402
403
  * string, for example `"2.99"`. `undefined` when the body does not carry it. */
@@ -824,7 +825,167 @@ var InvoError = class _InvoError extends Error {
824
825
  * `getPlayerRewards` answers it when no player has that email in this game.
825
826
  */
826
827
  get isPlayerNotFound() {
827
- return this.code === "PLAYER_NOT_FOUND";
828
+ if (this.code === "PLAYER_NOT_FOUND") return true;
829
+ return this.status === 404 && this.bodyObject()["error"] === "player_not_found";
830
+ }
831
+ // ---- Player registration, phone changes, identity re-key ----
832
+ /**
833
+ * True when an approve was refused because the player token predates a change to the
834
+ * sender's identity (`PLAYER_TOKEN_STALE`, 403): their phone was added (for example on
835
+ * the initiate), which gives them a new identity. Nothing moved and the token stays
836
+ * refused. Re-mint the player token (or use the `playerToken` from the initiate result)
837
+ * and retry once. The SDK never retries a money call on its own.
838
+ */
839
+ get isPlayerTokenStale() {
840
+ return this.code === "PLAYER_TOKEN_STALE";
841
+ }
842
+ /**
843
+ * True when `updatePlayerPhone` was refused because the player has secured this account,
844
+ * so the change needs the player's own confirmation (`PHONE_CHANGE_REQUIRES_VERIFICATION`,
845
+ * 409). Nothing changed. Call `requestPhoneChange`: INVO emails the player, who confirms
846
+ * on INVO's page. {@link changeRequestEndpoint} names the route.
847
+ */
848
+ get isPhoneChangeRequiresVerification() {
849
+ return this.code === "PHONE_CHANGE_REQUIRES_VERIFICATION";
850
+ }
851
+ /**
852
+ * On `PHONE_CHANGE_REQUIRES_VERIFICATION`: the route to create a change request on, as INVO
853
+ * returned it (`change_request_endpoint`; it carries the `/sandbox` prefix in sandbox).
854
+ * `requestPhoneChange` already calls it. `undefined` when the body does not carry it.
855
+ */
856
+ get changeRequestEndpoint() {
857
+ const v = this.bodyObject()["change_request_endpoint"];
858
+ return typeof v === "string" && v ? v : void 0;
859
+ }
860
+ // ---- Player-confirmed phone change (change requests) ----
861
+ /**
862
+ * True when a game tried to confirm a phone change itself (`CONFIRM_ON_INVO_PAGE`, 409).
863
+ * The player confirms only on INVO's page, from the link in INVO's email; a game never
864
+ * collects the code.
865
+ */
866
+ get isConfirmOnInvoPage() {
867
+ return this.code === "CONFIRM_ON_INVO_PAGE";
868
+ }
869
+ /**
870
+ * True when the change request is unknown, belongs to another game (`getPhoneChange`), or
871
+ * to another player (`approvePhoneChange`) (`CHANGE_REQUEST_NOT_FOUND`, 404).
872
+ */
873
+ get isChangeRequestNotFound() {
874
+ return this.code === "CHANGE_REQUEST_NOT_FOUND";
875
+ }
876
+ /**
877
+ * True when `approvePhoneChange` came before the player entered the emailed code on INVO's
878
+ * page (`CHANGE_REQUEST_NOT_READY`, 409). Nothing changed; approve after they do.
879
+ */
880
+ get isChangeRequestNotReady() {
881
+ return this.code === "CHANGE_REQUEST_NOT_READY";
882
+ }
883
+ /**
884
+ * True when the change request is no longer pending (`CHANGE_REQUEST_NOT_PENDING`, 409):
885
+ * already confirmed, expired, cancelled, refused or declined. See
886
+ * {@link changeRequestStatus}.
887
+ */
888
+ get isChangeRequestNotPending() {
889
+ return this.code === "CHANGE_REQUEST_NOT_PENDING";
890
+ }
891
+ /** On `CHANGE_REQUEST_NOT_PENDING`: the request's current `status`. */
892
+ get changeRequestStatus() {
893
+ if (this.code !== "CHANGE_REQUEST_NOT_PENDING") return void 0;
894
+ const v = this.bodyObject()["status"];
895
+ return typeof v === "string" && v ? v : void 0;
896
+ }
897
+ /**
898
+ * True when another game's change request for this player is waiting for the player
899
+ * (`CHANGE_REQUEST_IN_PROGRESS`, 409). Retry after it is confirmed or expires.
900
+ */
901
+ get isChangeRequestInProgress() {
902
+ return this.code === "CHANGE_REQUEST_IN_PROGRESS";
903
+ }
904
+ /**
905
+ * True when phone changes for this player are paused after repeated failed confirmations
906
+ * (`PHONE_CHANGE_LOCKED`, 409). The player has been emailed. Retry later.
907
+ */
908
+ get isPhoneChangeLocked() {
909
+ return this.code === "PHONE_CHANGE_LOCKED";
910
+ }
911
+ /**
912
+ * True when `requestPhoneChange` was refused because there were too many change requests
913
+ * for this player (`TOO_MANY_CHANGE_REQUESTS`, 429). Try again later; do not loop.
914
+ */
915
+ get isTooManyChangeRequests() {
916
+ return this.code === "TOO_MANY_CHANGE_REQUESTS";
917
+ }
918
+ /**
919
+ * True when a phone change call could not be served right now (`PHONE_CHANGE_UNAVAILABLE`,
920
+ * 503) or the confirmation email could not be sent (`CONFIRMATION_EMAIL_UNAVAILABLE`, 503;
921
+ * that request is closed). Retry shortly.
922
+ */
923
+ get isPhoneChangeUnavailable() {
924
+ return this.code === "PHONE_CHANGE_UNAVAILABLE" || this.code === "CONFIRMATION_EMAIL_UNAVAILABLE";
925
+ }
926
+ /**
927
+ * True when a phone change was refused because transfers to the player's CURRENT number
928
+ * are still waiting to be collected (`PENDING_TRANSFERS_TO_OLD_PHONE`, 409), on
929
+ * `updatePlayerPhone`, `requestPhoneChange` or `approvePhoneChange`. Changing the number
930
+ * now would strand them. Nothing changed. Ask the player to collect them first (or wait
931
+ * until they expire), then retry.
932
+ */
933
+ get isPendingTransfersToOldPhone() {
934
+ return this.code === "PENDING_TRANSFERS_TO_OLD_PHONE";
935
+ }
936
+ /**
937
+ * True when a phone change was refused because transfers to the NEW number are still
938
+ * waiting to be collected (`PENDING_TRANSFERS_TO_NEW_PHONE`, 409), on `updatePlayerPhone`,
939
+ * `requestPhoneChange` or `approvePhoneChange`. Nothing changed. Retry after they are
940
+ * collected or expire.
941
+ */
942
+ get isPendingTransfersToNewPhone() {
943
+ return this.code === "PENDING_TRANSFERS_TO_NEW_PHONE";
944
+ }
945
+ /**
946
+ * True when the player's account recently went through a sign-in recovery, so the number
947
+ * cannot be changed yet (`PHONE_CHANGE_RECOVERY_COOLDOWN`, 409), on `requestPhoneChange`
948
+ * or `approvePhoneChange`. Nothing changed. Retry later; on `approvePhoneChange`,
949
+ * declining (`decision: "deny"`) still works.
950
+ */
951
+ get isPhoneChangeRecoveryCooldown() {
952
+ return this.code === "PHONE_CHANGE_RECOVERY_COOLDOWN";
953
+ }
954
+ /**
955
+ * True when `approvePhoneChange` was refused because this device (or its key) was set up
956
+ * after the change was requested, so it cannot approve it
957
+ * (`DEVICE_ENROLLED_AFTER_REQUEST`, 409). Nothing changed. The player approves on their
958
+ * earlier device, or your game creates a new request.
959
+ */
960
+ get isDeviceEnrolledAfterRequest() {
961
+ return this.code === "DEVICE_ENROLLED_AFTER_REQUEST";
962
+ }
963
+ /**
964
+ * True when `approvePhoneChange` was refused because the device signal did not verify
965
+ * (401, the reason in `error`, for example `SIGNAL_INVALID`). Nothing changed. Sign the
966
+ * exact message again with a fresh nonce and timestamp.
967
+ */
968
+ get isDeviceSignalRejected() {
969
+ if (this.status !== 401) return false;
970
+ const e = this.bodyObject()["error"];
971
+ return typeof e === "string" && e.startsWith("SIGNAL_");
972
+ }
973
+ /**
974
+ * True when `registerPlayer` found the player already in your game with a DIFFERENT
975
+ * phone (`PHONE_MISMATCH`, 409). Nothing changed; use `updatePlayerPhone` to change it.
976
+ * (`mintPlayerToken` reports the same situation as `phoneMismatch: true` on success.)
977
+ */
978
+ get isPhoneMismatch() {
979
+ return this.code === "PHONE_MISMATCH";
980
+ }
981
+ /**
982
+ * True when the phone you supplied belongs to another email
983
+ * (`PHONE_SHARE_APPROVAL_REQUIRED`, 409) on `mintPlayerToken`, `registerPlayer` or
984
+ * `updatePlayerPhone`. Nothing was created or changed. The same condition as
985
+ * {@link isPhoneShareApprovalRequired}, named for these registration calls.
986
+ */
987
+ get isPhoneShareRefused() {
988
+ return this.isPhoneShareApprovalRequired;
828
989
  }
829
990
  /**
830
991
  * True when `cards.createSetupSession` was asked to create a new member (`playerName`
@@ -924,11 +1085,13 @@ function errorFromResponse(status, body, requestId) {
924
1085
  let message = `INVO request failed (HTTP ${status})`;
925
1086
  let code;
926
1087
  let rawCode;
1088
+ let publicCode;
927
1089
  if (body && typeof body === "object") {
928
1090
  const b = body;
929
1091
  if (typeof b["code"] === "string") rawCode = b["code"];
930
1092
  else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
931
- code = typeof b["error_code_public"] === "string" ? b["error_code_public"] : rawCode;
1093
+ if (typeof b["error_code_public"] === "string") publicCode = b["error_code_public"];
1094
+ code = publicCode ?? rawCode;
932
1095
  if (typeof b["error"] === "string") message = b["error"];
933
1096
  else if (typeof b["message"] === "string") message = b["message"];
934
1097
  if (!code && typeof b["error"] === "string" && /^(flow_paused|spending_limit_exceeded|receiver_not_enrolled_use_claim_code|no_channel_on_file|rate_limited|service_unavailable|authorization_pending|slow_down|expired_token|access_denied|invalid_grant)$/.test(
@@ -940,7 +1103,7 @@ function errorFromResponse(status, body, requestId) {
940
1103
  } else if (typeof body === "string" && body.trim()) {
941
1104
  message = body;
942
1105
  }
943
- return new InvoError({ message, code, rawCode, status, body, requestId });
1106
+ return new InvoError({ message, code, rawCode, publicCode, status, body, requestId });
944
1107
  }
945
1108
 
946
1109
  // src/shared/http.ts
@@ -1290,8 +1453,49 @@ function receiptFields(raw) {
1290
1453
  return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
1291
1454
  }
1292
1455
 
1456
+ // src/shared/phone-change.ts
1457
+ function requireField(value, field, raw) {
1458
+ const s = value == null ? "" : String(value);
1459
+ if (!s) {
1460
+ throw new InvoError({
1461
+ message: `INVO response was missing the required \`${field}\` field.`,
1462
+ code: "INVALID_RESPONSE",
1463
+ status: 0,
1464
+ body: raw
1465
+ });
1466
+ }
1467
+ return s;
1468
+ }
1469
+ var str2 = (v) => v == null ? "" : String(v);
1470
+ var strOrNull2 = (v) => typeof v === "string" ? v : v == null ? null : String(v);
1471
+ function toRequestPhoneChangeResult(raw) {
1472
+ return {
1473
+ changeRequestId: requireField(raw["change_request_id"], "change_request_id", raw),
1474
+ status: requireField(raw["status"], "status", raw),
1475
+ expiresAt: str2(raw["expires_at"]),
1476
+ delivery: str2(raw["delivery"]),
1477
+ confirmation: str2(raw["confirmation"]),
1478
+ message: str2(raw["message"]),
1479
+ raw
1480
+ };
1481
+ }
1482
+ function toPhoneChangeRequest(raw) {
1483
+ return {
1484
+ changeRequestId: requireField(raw["change_request_id"], "change_request_id", raw),
1485
+ status: requireField(raw["status"], "status", raw),
1486
+ confirmation: str2(raw["confirmation"]),
1487
+ delivery: str2(raw["delivery"]),
1488
+ newPhoneMasked: strOrNull2(raw["new_phone_masked"]),
1489
+ createdAt: strOrNull2(raw["created_at"]),
1490
+ expiresAt: strOrNull2(raw["expires_at"]),
1491
+ confirmedAt: strOrNull2(raw["confirmed_at"]),
1492
+ confirmedVia: strOrNull2(raw["confirmed_via"]),
1493
+ raw
1494
+ };
1495
+ }
1496
+
1293
1497
  // src/version.ts
1294
- var SDK_VERSION = "3.20.0";
1498
+ var SDK_VERSION = "3.22.0";
1295
1499
 
1296
1500
  // src/shared/types.ts
1297
1501
  function isRefundPendingApproval(r) {
@@ -1535,7 +1739,7 @@ function unacknowledgedFeeFallback(row, quote) {
1535
1739
  function toCurrencyPurchaseQuote(raw) {
1536
1740
  const breakdown = toQuoteBreakdown(raw["breakdown"]);
1537
1741
  return {
1538
- totalUsd: requireField(raw["total_usd"], "total_usd", raw),
1742
+ totalUsd: requireField2(raw["total_usd"], "total_usd", raw),
1539
1743
  amountCents: Number(raw["amount_cents"] ?? 0),
1540
1744
  // Top-level since 2026-09-23; the breakdown has always carried the same figures.
1541
1745
  subtotalUsd: String(raw["subtotal_usd"] ?? breakdown.subtotalUsd),
@@ -1673,9 +1877,65 @@ function toTransactionStatus(raw) {
1673
1877
  orderId: raw["order_id"],
1674
1878
  toPhone: raw["to_phone"],
1675
1879
  toIdentityId: raw["to_identity_id"] ?? null,
1880
+ ...typeof raw["expiry_reason"] === "string" && raw["expiry_reason"] ? { expiryReason: raw["expiry_reason"] } : {},
1881
+ raw
1882
+ };
1883
+ }
1884
+ function assertPageLimit(limit) {
1885
+ if (limit === void 0) return;
1886
+ if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) {
1887
+ throw invalidInput("limit", limit, "must be a positive integer (INVO caps it at 100)");
1888
+ }
1889
+ }
1890
+ function assertCursor(cursor) {
1891
+ if (cursor === void 0) return;
1892
+ if (typeof cursor !== "string" || !cursor.trim()) {
1893
+ throw invalidInput("cursor", cursor, "must be the previous page's nextCursor");
1894
+ }
1895
+ }
1896
+ function strOrNull3(v) {
1897
+ return v == null ? null : String(v);
1898
+ }
1899
+ function toPlayerActivityEntry(raw) {
1900
+ const ccy = raw["currency"] && typeof raw["currency"] === "object" ? raw["currency"] : {};
1901
+ const cg = raw["counterparty_game"];
1902
+ const cgo = cg && typeof cg === "object" ? cg : null;
1903
+ return {
1904
+ id: String(raw["id"] ?? ""),
1905
+ type: String(raw["type"] ?? ""),
1906
+ direction: String(raw["direction"] ?? ""),
1907
+ amount: strOrNull3(raw["amount"]),
1908
+ amountUnit: String(raw["amount_unit"] ?? "currency"),
1909
+ currency: {
1910
+ currencyId: ccy["currency_id"] ?? null,
1911
+ currencyName: strOrNull3(ccy["currency_name"])
1912
+ },
1913
+ status: String(raw["status"] ?? ""),
1914
+ statusDetail: strOrNull3(raw["status_detail"]),
1915
+ expiryReason: strOrNull3(raw["expiry_reason"]) || null,
1916
+ counterpartyGame: cgo ? { gameId: String(cgo["game_id"] ?? ""), gameName: strOrNull3(cgo["game_name"]) } : null,
1917
+ createdAt: strOrNull3(raw["created_at"]),
1918
+ completedAt: strOrNull3(raw["completed_at"]),
1919
+ orderId: strOrNull3(raw["order_id"]),
1920
+ raw
1921
+ };
1922
+ }
1923
+ function toPlatformOrderStatus(raw, fallbackOrderId) {
1924
+ return {
1925
+ orderId: raw["order_id"] ?? fallbackOrderId ?? "",
1926
+ status: String(raw["status"] ?? ""),
1927
+ gameCurrencyAmount: raw["game_currency_amount"] ?? null,
1928
+ usdAmount: raw["usd_amount"] ?? null,
1929
+ paymentMethod: raw["payment_method"],
1930
+ createdAt: raw["created_at"],
1931
+ ...receiptFields(raw),
1676
1932
  raw
1677
1933
  };
1678
1934
  }
1935
+ function nextCursorOf(raw) {
1936
+ const c = raw["next_cursor"];
1937
+ return typeof c === "string" && c ? c : null;
1938
+ }
1679
1939
  function toGuardianApprovalStatus(raw) {
1680
1940
  const approval = raw["approval"] ?? {};
1681
1941
  return {
@@ -1773,10 +2033,10 @@ function assertDeviceApprovalFlow(flow) {
1773
2033
  }
1774
2034
  function toDeviceApprovalGrant(raw) {
1775
2035
  return {
1776
- deviceCode: requireField(raw["device_code"], "device_code", raw),
2036
+ deviceCode: requireField2(raw["device_code"], "device_code", raw),
1777
2037
  userCode: String(raw["user_code"] ?? ""),
1778
2038
  verificationUri: String(raw["verification_uri"] ?? ""),
1779
- verificationUriComplete: requireField(raw["verification_uri_complete"], "verification_uri_complete", raw),
2039
+ verificationUriComplete: requireField2(raw["verification_uri_complete"], "verification_uri_complete", raw),
1780
2040
  expiresIn: Number(raw["expires_in"] ?? 0) || 0,
1781
2041
  interval: Math.max(1, Number(raw["interval"] ?? 5) || 5),
1782
2042
  channel: String(raw["channel"] ?? "qr"),
@@ -1846,7 +2106,17 @@ function toCurrencyBalance(row) {
1846
2106
  raw: row
1847
2107
  };
1848
2108
  }
1849
- function requireField(value, field, raw) {
2109
+ function playerTokenFields(raw) {
2110
+ const out = {};
2111
+ if (typeof raw["player_token"] === "string" && raw["player_token"]) {
2112
+ out.playerToken = raw["player_token"];
2113
+ if (typeof raw["player_token_expires_at"] === "string") {
2114
+ out.playerTokenExpiresAt = raw["player_token_expires_at"];
2115
+ }
2116
+ }
2117
+ return out;
2118
+ }
2119
+ function requireField2(value, field, raw) {
1850
2120
  const s = value == null ? "" : String(value);
1851
2121
  if (!s) {
1852
2122
  throw new InvoError({
@@ -1922,7 +2192,9 @@ var PlatformCommerceServer = class {
1922
2192
  throw new InvoError({
1923
2193
  message: `Card purchases must be at least $${CARD_MIN_USD.toFixed(2)}.`,
1924
2194
  code: "BELOW_STRIPE_MINIMUM",
1925
- status: 0
2195
+ publicCode: "BELOW_CARD_MINIMUM",
2196
+ status: 0,
2197
+ body: { min_usd: CARD_MIN_USD.toFixed(2) }
1926
2198
  });
1927
2199
  }
1928
2200
  }
@@ -1953,9 +2225,9 @@ var PlatformCommerceServer = class {
1953
2225
  );
1954
2226
  const status = String(raw["status"] ?? "");
1955
2227
  if (status === "requires_payment") {
1956
- requireField(raw["checkout_url"], "checkout_url", raw);
2228
+ requireField2(raw["checkout_url"], "checkout_url", raw);
1957
2229
  } else {
1958
- requireField(raw["order_id"], "order_id", raw);
2230
+ requireField2(raw["order_id"], "order_id", raw);
1959
2231
  }
1960
2232
  const expiresAtRaw = raw["expires_at"];
1961
2233
  return {
@@ -1987,17 +2259,71 @@ var PlatformCommerceServer = class {
1987
2259
  this.auth,
1988
2260
  { signal: opts?.signal }
1989
2261
  );
2262
+ return toPlatformOrderStatus(raw, orderId);
2263
+ }
2264
+ /**
2265
+ * One player's Platform Commerce purchases in your app, newest first, one page at a time
2266
+ * (`GET /api/platform-commerce/purchase-history`). Each entry carries exactly the fields
2267
+ * `getStatus` returns for that order (including `receiptNumber` / `receiptUrl` on a
2268
+ * Merchant of Record card sale once issued). Pass `nextCursor` back as `cursor` for the
2269
+ * next page; it is `null` on the last one. `iteratePurchaseHistory` walks every page.
2270
+ *
2271
+ * Refusals (`InvoError`; this route reports its code in `error_code`, surfaced as
2272
+ * `err.code`): a blank `playerEmail` or a bad `limit` / `cursor` throws `INVALID_INPUT`
2273
+ * before the network; `400 INVALID_INPUT`, `400 INVALID_CURSOR` (a cursor from another
2274
+ * player), `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`), `403` for a non-platform
2275
+ * tenant (`err.isNotPlatformTenant`), `429` (back off; `err.retryAfter`). A GET, so
2276
+ * transient failures are retried automatically.
2277
+ */
2278
+ async getPurchaseHistory(query, opts) {
2279
+ if (typeof query?.playerEmail !== "string" || !query.playerEmail.trim()) {
2280
+ throw invalidInput("playerEmail", query?.playerEmail, "is required");
2281
+ }
2282
+ assertPageLimit(query.limit);
2283
+ assertCursor(query.cursor);
2284
+ const q = new URLSearchParams();
2285
+ q.set("player_email", query.playerEmail.trim());
2286
+ if (query.limit !== void 0) q.set("limit", String(query.limit));
2287
+ if (query.cursor !== void 0) q.set("cursor", query.cursor);
2288
+ const raw = await this.http.get(
2289
+ `/api/platform-commerce/purchase-history?${q.toString()}`,
2290
+ this.auth,
2291
+ { signal: opts?.signal }
2292
+ );
2293
+ const purchases = Array.isArray(raw["purchases"]) ? raw["purchases"].map((r) => toPlatformOrderStatus(r)) : [];
2294
+ const nextCursor = nextCursorOf(raw);
1990
2295
  return {
1991
- orderId: raw["order_id"] ?? orderId,
1992
- status: String(raw["status"] ?? ""),
1993
- gameCurrencyAmount: raw["game_currency_amount"] ?? null,
1994
- usdAmount: raw["usd_amount"] ?? null,
1995
- paymentMethod: raw["payment_method"],
1996
- createdAt: raw["created_at"],
1997
- ...receiptFields(raw),
2296
+ playerEmail: String(raw["player_email"] ?? query.playerEmail.trim()),
2297
+ gameId: String(raw["game_id"] ?? ""),
2298
+ purchases,
2299
+ limit: typeof raw["limit"] === "number" ? raw["limit"] : purchases.length,
2300
+ hasMore: raw["has_more"] === true && nextCursor !== null,
2301
+ nextCursor,
1998
2302
  raw
1999
2303
  };
2000
2304
  }
2305
+ /**
2306
+ * Async iterator over ALL of a player's Platform Commerce purchases, newest first: pages
2307
+ * through `getPurchaseHistory` by `nextCursor`, yielding one order at a time.
2308
+ *
2309
+ * ```ts
2310
+ * for await (const order of invo.platformCommerce.iteratePurchaseHistory({ playerEmail })) { … }
2311
+ * ```
2312
+ */
2313
+ async *iteratePurchaseHistory(query, opts) {
2314
+ let cursor;
2315
+ const seen = /* @__PURE__ */ new Set();
2316
+ for (; ; ) {
2317
+ const page = await this.getPurchaseHistory(
2318
+ { playerEmail: query.playerEmail, limit: query.pageSize, cursor },
2319
+ opts
2320
+ );
2321
+ for (const row of page.purchases) yield row;
2322
+ if (!page.hasMore || page.nextCursor === null || seen.has(page.nextCursor)) return;
2323
+ seen.add(page.nextCursor);
2324
+ cursor = page.nextCursor;
2325
+ }
2326
+ }
2001
2327
  /**
2002
2328
  * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
2003
2329
  * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
@@ -2931,7 +3257,7 @@ var CardsServer = class {
2931
3257
  return {
2932
3258
  sessionId: String(raw["session_id"] ?? ""),
2933
3259
  // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
2934
- cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
3260
+ cardSetupUrl: requireField2(raw["card_setup_url"], "card_setup_url", raw),
2935
3261
  expiresAt: String(raw["expires_at"] ?? ""),
2936
3262
  raw
2937
3263
  };
@@ -2976,7 +3302,7 @@ var CardsServer = class {
2976
3302
  );
2977
3303
  return {
2978
3304
  status: String(raw["status"] ?? ""),
2979
- setupIntentId: requireField(raw["setup_intent_id"], "setup_intent_id", raw),
3305
+ setupIntentId: requireField2(raw["setup_intent_id"], "setup_intent_id", raw),
2980
3306
  clientSecret: typeof raw["client_secret"] === "string" ? raw["client_secret"] : void 0,
2981
3307
  publishableKey: typeof raw["publishable_key"] === "string" ? raw["publishable_key"] : void 0,
2982
3308
  card: toSavedCard(raw["card"]),
@@ -3143,16 +3469,19 @@ var InvoServer = class {
3143
3469
  /**
3144
3470
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
3145
3471
  *
3146
- * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
3147
- * registration call. The backend looks the player up by `playerEmail` and returns a
3148
- * token for their existing identity; if no such player exists it responds 404. The
3149
- * network identity (which encodes the player's phone) is established when the player
3150
- * is created and on the money-routing calls, so phone is NOT required or read here.
3472
+ * For a player who already exists in your game, this is a session mint: INVO looks the
3473
+ * player up by `playerEmail` and returns a token for their identity. `playerPhone` and
3474
+ * `playerName` do not change an existing player.
3151
3475
  *
3152
- * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
3153
- * ignores it on this endpoint, so an existing email-only player can still mint a token.
3154
- * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
3155
- * sender's phone, and the recipient's when known) and at player creation.
3476
+ * For a player who is NOT in your game yet: without `playerPhone` INVO answers 404
3477
+ * (`err.isPlayerNotFound`); with `playerPhone` INVO creates the player and the result
3478
+ * carries `created: true`, so a first-time receiver can collect without buying first.
3479
+ * Use `registerPlayer` when you want creation to be explicit.
3480
+ *
3481
+ * `phoneMismatch: true` means the existing player has a different phone than the one
3482
+ * you passed; the token is still for that player and their phone is unchanged
3483
+ * (`updatePlayerPhone` changes it). A phone already held by another email is a 409
3484
+ * (`err.isPhoneShareRefused`).
3156
3485
  */
3157
3486
  async mintPlayerToken(input, opts) {
3158
3487
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -3163,18 +3492,160 @@ var InvoServer = class {
3163
3492
  assertE164(input.playerPhone, "playerPhone");
3164
3493
  body["player_phone"] = input.playerPhone;
3165
3494
  }
3495
+ if (input.playerName !== void 0) {
3496
+ if (typeof input.playerName !== "string") {
3497
+ throw invalidInput("playerName", input.playerName, "must be a string");
3498
+ }
3499
+ body["player_name"] = input.playerName;
3500
+ }
3166
3501
  const raw = await this.http.post(
3167
3502
  "/api/sdk/player-token",
3168
3503
  body,
3169
3504
  this.auth,
3505
+ // Safe to retry: a re-mint issues a fresh token, and a create that already happened
3506
+ // answers the retry for the existing player.
3170
3507
  { idempotent: true, signal: opts?.signal }
3171
- // safe to retry: re-mint just issues a fresh token
3172
3508
  );
3173
- return {
3174
- token: requireField(raw["token"], "token", raw),
3509
+ const out = {
3510
+ token: requireField2(raw["token"], "token", raw),
3175
3511
  expiresAt: String(raw["expires_at"] ?? ""),
3176
3512
  identityId: String(raw["identity_id"] ?? "")
3177
3513
  };
3514
+ if (raw["created"] === true) out.created = true;
3515
+ if (raw["phone_mismatch"] === true) out.phoneMismatch = true;
3516
+ return out;
3517
+ }
3518
+ /**
3519
+ * Create a player in your game without moving money (`POST /api/sdk/players`), so a
3520
+ * first-time receiver can collect in-game. Sends no message to the player.
3521
+ *
3522
+ * Returns `status: "created"` (new) or `"exists"` (already in your game with that
3523
+ * phone), with a player token when INVO can issue one. Refusals: 409
3524
+ * `err.isPhoneMismatch` (already in your game with a different phone; use
3525
+ * `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
3526
+ * email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
3527
+ */
3528
+ async registerPlayer(input, opts) {
3529
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
3530
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
3531
+ }
3532
+ assertE164(input.playerPhone, "playerPhone");
3533
+ const body = {
3534
+ player_email: input.playerEmail,
3535
+ player_phone: input.playerPhone
3536
+ };
3537
+ if (input.playerName !== void 0) {
3538
+ if (typeof input.playerName !== "string") {
3539
+ throw invalidInput("playerName", input.playerName, "must be a string");
3540
+ }
3541
+ body["player_name"] = input.playerName;
3542
+ }
3543
+ const raw = await this.http.post(
3544
+ "/api/sdk/players",
3545
+ body,
3546
+ this.auth,
3547
+ // Find-or-create, no money: a retry after a create answers "exists".
3548
+ { idempotent: true, signal: opts?.signal }
3549
+ );
3550
+ const status = requireField2(raw["status"], "status", raw);
3551
+ return {
3552
+ status: status === "created" ? "created" : "exists",
3553
+ identityId: String(raw["identity_id"] ?? ""),
3554
+ ...playerTokenFields(raw),
3555
+ raw
3556
+ };
3557
+ }
3558
+ /**
3559
+ * Set a player's phone from your server (`POST /api/sdk/players/phone`). A phone change
3560
+ * can give the player a new INVO identity: `identityRekeyed: true`, and the result
3561
+ * carries a fresh `playerToken` for it (tokens minted before the change are then out
3562
+ * of date).
3563
+ *
3564
+ * Refusals: 409 `err.isPhoneChangeRequiresVerification` (the player has secured this
3565
+ * account, so the change needs the player's own confirmation: call `requestPhoneChange`;
3566
+ * `err.changeRequestEndpoint` names the route), 409 `err.isPhoneShareRefused` (the
3567
+ * number belongs to another email), 409 `err.isPendingTransfersToOldPhone` /
3568
+ * `err.isPendingTransfersToNewPhone` (transfers to the current or the new number are still
3569
+ * waiting to be collected), 404 `err.isPlayerNotFound`, 400 `INVALID_INPUT` / `INVALID_PHONE`, 429
3570
+ * (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
3571
+ *
3572
+ * Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
3573
+ * hide `identityRekeyed`.
3574
+ */
3575
+ async updatePlayerPhone(input, opts) {
3576
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
3577
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
3578
+ }
3579
+ assertE164(input.newPhone, "newPhone");
3580
+ const raw = await this.http.post(
3581
+ "/api/sdk/players/phone",
3582
+ { player_email: input.playerEmail, new_phone: input.newPhone },
3583
+ this.auth,
3584
+ { signal: opts?.signal }
3585
+ );
3586
+ const status = requireField2(raw["status"], "status", raw);
3587
+ return {
3588
+ status: status === "updated" ? "updated" : "unchanged",
3589
+ identityRekeyed: raw["identity_rekeyed"] === true,
3590
+ identityId: String(raw["identity_id"] ?? ""),
3591
+ ...playerTokenFields(raw),
3592
+ raw
3593
+ };
3594
+ }
3595
+ /**
3596
+ * Ask the player to confirm a new phone number
3597
+ * (`POST /api/sdk/players/phone/change-requests`, HTTP 202). Use it when `updatePlayerPhone`
3598
+ * answers 409 `err.isPhoneChangeRequiresVerification`.
3599
+ *
3600
+ * Nothing about the player changes here. INVO emails the player a code and a link to a
3601
+ * page on INVO's site, and the player confirms there (plus their passkey on that page, or
3602
+ * an approval on their enrolled device, when they have one: see `confirmation`). Your game
3603
+ * never collects the code and never receives the link: do not ask the player for it.
3604
+ * Follow up with `getPhoneChange`, or wait for the `player.phone_changed` webhook.
3605
+ *
3606
+ * Refusals carry `err.code`, for example 409 `PHONE_SAME`, `PHONE_IN_USE_BY_ANOTHER_PLAYER`,
3607
+ * `PENDING_TRANSFERS_TO_NEW_PHONE` (`err.isPendingTransfersToNewPhone`),
3608
+ * `PENDING_TRANSFERS_TO_OLD_PHONE` (`err.isPendingTransfersToOldPhone`),
3609
+ * `CHANGE_REQUEST_IN_PROGRESS` (`err.isChangeRequestInProgress`), `PHONE_CHANGE_LOCKED`
3610
+ * (`err.isPhoneChangeLocked`), `PHONE_CHANGE_RECOVERY_COOLDOWN`
3611
+ * (`err.isPhoneChangeRecoveryCooldown`), `STEP_UP_UNAVAILABLE`, `WALLET_SECURED`,
3612
+ * `PHONE_NOT_SET`;
3613
+ * 429 `err.isTooManyChangeRequests`; 404 `err.isPlayerNotFound`; 503
3614
+ * `err.isPhoneChangeUnavailable`.
3615
+ *
3616
+ * Never auto-retried: a new request replaces your earlier pending one and sends the player
3617
+ * another email.
3618
+ */
3619
+ async requestPhoneChange(input, opts) {
3620
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
3621
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
3622
+ }
3623
+ assertE164(input.newPhone, "newPhone");
3624
+ const raw = await this.http.post(
3625
+ "/api/sdk/players/phone/change-requests",
3626
+ { player_email: input.playerEmail, new_phone: input.newPhone },
3627
+ this.auth,
3628
+ { signal: opts?.signal }
3629
+ );
3630
+ return toRequestPhoneChangeResult(raw);
3631
+ }
3632
+ /**
3633
+ * Read a change request your game created
3634
+ * (`GET /api/sdk/players/phone/change-requests/{changeRequestId}`). `status` is `pending`,
3635
+ * `confirmed`, `expired`, `cancelled`, `refused` or `denied`. A request another game
3636
+ * created, or an unknown id, is 404 `err.isChangeRequestNotFound`. Poll sparingly, or wait
3637
+ * for the `player.phone_changed` webhook.
3638
+ */
3639
+ async getPhoneChange(changeRequestId, opts) {
3640
+ if (typeof changeRequestId !== "string" || !changeRequestId.trim()) {
3641
+ throw invalidInput("changeRequestId", changeRequestId, "is required");
3642
+ }
3643
+ const raw = await this.http.get(
3644
+ `/api/sdk/players/phone/change-requests/${encodeURIComponent(changeRequestId)}`,
3645
+ this.auth,
3646
+ { signal: opts?.signal }
3647
+ );
3648
+ return toPhoneChangeRequest(raw);
3178
3649
  }
3179
3650
  /**
3180
3651
  * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
@@ -3249,7 +3720,7 @@ var InvoServer = class {
3249
3720
  { signal: opts?.signal }
3250
3721
  // not idempotent — never auto-retried
3251
3722
  );
3252
- const checkoutUrl = requireField(raw["checkout_url"], "checkout_url", raw);
3723
+ const checkoutUrl = requireField2(raw["checkout_url"], "checkout_url", raw);
3253
3724
  return {
3254
3725
  sessionId: String(raw["session_id"] ?? ""),
3255
3726
  checkoutUrl,
@@ -3271,7 +3742,7 @@ var InvoServer = class {
3271
3742
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
3272
3743
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
3273
3744
  *
3274
- * INVO's card fee (4.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of
3745
+ * INVO's card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of
3275
3746
  * the listed price (before tax) on a card issued outside the US) is charged to you, the partner. The player
3276
3747
  * pays the listed price (plus any tax) and receives the listed coins. Card purchases only;
3277
3748
  * purchases through a third-party storefront or payment rail are unaffected. Two shapes,
@@ -3360,9 +3831,9 @@ var InvoServer = class {
3360
3831
  *
3361
3832
  * The player pays the listed price plus any tax (when you pass `country`) and receives the
3362
3833
  * listed coins: `totalUsd` carries no card fee, and `processingFeeUsd` is `"0.00"`. INVO's
3363
- * card fee (4.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record) is charged to you;
3834
+ * card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record) is charged to you;
3364
3835
  * `partnerFeeUsd` carries it when INVO sends it. $10.00 quotes a $10.00 total, 100.00 coins
3365
- * at the default 10 per USD, and a $0.75 partner fee on Open. Show the player `totalUsd`,
3836
+ * at the default 10 per USD, and a $0.65 partner fee on Open. Show the player `totalUsd`,
3366
3837
  * then send the same figure back as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the
3367
3838
  * card is never charged more than that. `ifUnacknowledged` shows the purchase without the
3368
3839
  * acknowledgement (the card charged exactly `usdAmount`), or `null` when INVO sends none.
@@ -3632,8 +4103,8 @@ var InvoServer = class {
3632
4103
  );
3633
4104
  return {
3634
4105
  status: String(raw["status"] ?? ""),
3635
- transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
3636
- orderId: requireField(raw["order_id"], "order_id", raw),
4106
+ transactionId: requireField2(raw["transaction_id"], "transaction_id", raw),
4107
+ orderId: requireField2(raw["order_id"], "order_id", raw),
3637
4108
  newBalance: raw["new_balance"] ?? null,
3638
4109
  previousBalance: raw["previous_balance"] ?? null,
3639
4110
  currencyName: String(raw["currency_name"] ?? ""),
@@ -3713,6 +4184,86 @@ var InvoServer = class {
3713
4184
  if (Number.isFinite(total) && yielded >= total) return;
3714
4185
  }
3715
4186
  }
4187
+ /**
4188
+ * One merged, newest-first list of a player's money activity in your game, one page at a
4189
+ * time (`GET /api/sdk/players/activity`): currency purchases, item purchases, Platform
4190
+ * Commerce purchases, sends and transfers, in both directions. Only rows where your game
4191
+ * is a party through this player are listed; the other side of a cross-game send or
4192
+ * transfer is named by game only (`counterpartyGame`).
4193
+ *
4194
+ * An inbound (`direction: "in"`) send or transfer is listed as soon as it names this
4195
+ * player, in ANY status (awaiting collection, completed, expired, refunded): read `status`
4196
+ * and `statusDetail` before treating it as credited. `direction` is `"in"` / `"out"` /
4197
+ * `"self"`, not the `"incoming"` / `"outgoing"` of the per-type history reads.
4198
+ *
4199
+ * Pass `nextCursor` back as `cursor` (with the same `types`) for the next page; it is
4200
+ * `null` on the last one. `iteratePlayerActivity` walks every page.
4201
+ *
4202
+ * Refusals (`InvoError`): a blank `playerEmail` or a bad `limit` / `cursor` / `types`
4203
+ * throws `INVALID_INPUT` before the network; `400 INVALID_INPUT` (for example an unknown
4204
+ * kind in `types`), `400 INVALID_CURSOR` (a cursor from another player or other `types`),
4205
+ * `401 INVALID_GAME_SECRET`, `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`),
4206
+ * `500 PLAYER_ACTIVITY_FAILED` (retry later), `429` (back off; `err.retryAfter`). A GET, so
4207
+ * transient failures are retried automatically.
4208
+ */
4209
+ async getPlayerActivity(query, opts) {
4210
+ if (typeof query?.playerEmail !== "string" || !query.playerEmail.trim()) {
4211
+ throw invalidInput("playerEmail", query?.playerEmail, "is required");
4212
+ }
4213
+ assertPageLimit(query.limit);
4214
+ assertCursor(query.cursor);
4215
+ if (query.types !== void 0) {
4216
+ if (!Array.isArray(query.types) || query.types.some((t) => typeof t !== "string" || !t.trim() || t.includes(","))) {
4217
+ throw invalidInput("types", query.types, "must be an array of activity kinds");
4218
+ }
4219
+ }
4220
+ const q = new URLSearchParams();
4221
+ q.set("player_email", query.playerEmail.trim());
4222
+ if (query.limit !== void 0) q.set("limit", String(query.limit));
4223
+ if (query.cursor !== void 0) q.set("cursor", query.cursor);
4224
+ if (query.types && query.types.length > 0) {
4225
+ q.set("types", query.types.map((t) => t.trim()).join(","));
4226
+ }
4227
+ const raw = await this.http.get(
4228
+ `/api/sdk/players/activity?${q.toString()}`,
4229
+ this.auth,
4230
+ { signal: opts?.signal }
4231
+ );
4232
+ const activity = Array.isArray(raw["activity"]) ? raw["activity"].map(toPlayerActivityEntry) : [];
4233
+ const nextCursor = nextCursorOf(raw);
4234
+ return {
4235
+ playerEmail: String(raw["player_email"] ?? query.playerEmail.trim()),
4236
+ gameId: String(raw["game_id"] ?? ""),
4237
+ types: Array.isArray(raw["types"]) ? raw["types"].map(String) : [],
4238
+ activity,
4239
+ limit: typeof raw["limit"] === "number" ? raw["limit"] : activity.length,
4240
+ hasMore: raw["has_more"] === true && nextCursor !== null,
4241
+ nextCursor,
4242
+ raw
4243
+ };
4244
+ }
4245
+ /**
4246
+ * Async iterator over a player's ENTIRE activity, newest first: pages through
4247
+ * `getPlayerActivity` by `nextCursor`, yielding one row at a time.
4248
+ *
4249
+ * ```ts
4250
+ * for await (const row of invo.iteratePlayerActivity({ playerEmail, types: ["send", "transfer"] })) { … }
4251
+ * ```
4252
+ */
4253
+ async *iteratePlayerActivity(query, opts) {
4254
+ let cursor;
4255
+ const seen = /* @__PURE__ */ new Set();
4256
+ for (; ; ) {
4257
+ const page = await this.getPlayerActivity(
4258
+ { playerEmail: query.playerEmail, types: query.types, limit: query.pageSize, cursor },
4259
+ opts
4260
+ );
4261
+ for (const row of page.activity) yield row;
4262
+ if (!page.hasMore || page.nextCursor === null || seen.has(page.nextCursor)) return;
4263
+ seen.add(page.nextCursor);
4264
+ cursor = page.nextCursor;
4265
+ }
4266
+ }
3716
4267
  /**
3717
4268
  * Read a player's currency balances by email (server-side, game-secret).
3718
4269
  *
@@ -4222,8 +4773,10 @@ var InvoServer = class {
4222
4773
  *
4223
4774
  * Throws `InvoError`: `err.isDeviceApprovalNotApproved` (400 — wrong/foreign code,
4224
4775
  * wrong flow, or the poll never said approved), `err.isPasskeyRecoveryCooldown` (403,
4225
- * money-out after a passkey recovery — `err.retryAfterAt`), guardian terminal states
4226
- * (410). Never auto-retried: the device_code is a single-use factor.
4776
+ * money-out after a passkey recovery — `err.retryAfterAt`), `err.isPlayerTokenStale`
4777
+ * (403, the player token predates the sender's phone being added: re-mint, or use the
4778
+ * initiate's `playerToken`, and retry once), guardian terminal states (410). Never
4779
+ * auto-retried: the device_code is a single-use factor.
4227
4780
  *
4228
4781
  * **A FAILURE HERE IS AMBIGUOUS ABOUT THE MONEY.** The backend commits the transfer and
4229
4782
  * *then* builds its 200 by reading the transaction back, so a fault raised after that
@@ -4380,6 +4933,10 @@ var InvoServer = class {
4380
4933
  transactionId: String(raw["transaction_id"] ?? ""),
4381
4934
  verificationMethod: guardian ? void 0 : vm === "in_app" || vm === "sms" ? vm : void 0,
4382
4935
  guardianApproval: guardian ?? void 0,
4936
+ ...raw["identity_rekeyed"] === true ? { identityRekeyed: true } : {},
4937
+ ...playerTokenFields(raw),
4938
+ ...typeof raw["identity_id"] === "string" && raw["identity_id"] ? { identityId: raw["identity_id"] } : {},
4939
+ ...typeof raw["claim_delivery_planned"] === "string" && raw["claim_delivery_planned"] ? { claimDeliveryPlanned: raw["claim_delivery_planned"] } : {},
4383
4940
  raw
4384
4941
  };
4385
4942
  }