@invonetwork/web-sdk 3.21.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. */
@@ -841,11 +842,134 @@ var InvoError = class _InvoError extends Error {
841
842
  /**
842
843
  * True when `updatePlayerPhone` was refused because the player has secured this account,
843
844
  * so the change needs the player's own confirmation (`PHONE_CHANGE_REQUIRES_VERIFICATION`,
844
- * 409). Nothing changed. Until that confirmation flow is available, contact INVO support.
845
+ * 409). Nothing changed. Call `requestPhoneChange`: INVO emails the player, who confirms
846
+ * on INVO's page. {@link changeRequestEndpoint} names the route.
845
847
  */
846
848
  get isPhoneChangeRequiresVerification() {
847
849
  return this.code === "PHONE_CHANGE_REQUIRES_VERIFICATION";
848
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
+ }
849
973
  /**
850
974
  * True when `registerPlayer` found the player already in your game with a DIFFERENT
851
975
  * phone (`PHONE_MISMATCH`, 409). Nothing changed; use `updatePlayerPhone` to change it.
@@ -961,11 +1085,13 @@ function errorFromResponse(status, body, requestId) {
961
1085
  let message = `INVO request failed (HTTP ${status})`;
962
1086
  let code;
963
1087
  let rawCode;
1088
+ let publicCode;
964
1089
  if (body && typeof body === "object") {
965
1090
  const b = body;
966
1091
  if (typeof b["code"] === "string") rawCode = b["code"];
967
1092
  else if (typeof b["error_code"] === "string") rawCode = b["error_code"];
968
- 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;
969
1095
  if (typeof b["error"] === "string") message = b["error"];
970
1096
  else if (typeof b["message"] === "string") message = b["message"];
971
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(
@@ -977,7 +1103,7 @@ function errorFromResponse(status, body, requestId) {
977
1103
  } else if (typeof body === "string" && body.trim()) {
978
1104
  message = body;
979
1105
  }
980
- return new InvoError({ message, code, rawCode, status, body, requestId });
1106
+ return new InvoError({ message, code, rawCode, publicCode, status, body, requestId });
981
1107
  }
982
1108
 
983
1109
  // src/shared/http.ts
@@ -1327,8 +1453,49 @@ function receiptFields(raw) {
1327
1453
  return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
1328
1454
  }
1329
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
+
1330
1497
  // src/version.ts
1331
- var SDK_VERSION = "3.21.0";
1498
+ var SDK_VERSION = "3.22.0";
1332
1499
 
1333
1500
  // src/shared/types.ts
1334
1501
  function isRefundPendingApproval(r) {
@@ -1572,7 +1739,7 @@ function unacknowledgedFeeFallback(row, quote) {
1572
1739
  function toCurrencyPurchaseQuote(raw) {
1573
1740
  const breakdown = toQuoteBreakdown(raw["breakdown"]);
1574
1741
  return {
1575
- totalUsd: requireField(raw["total_usd"], "total_usd", raw),
1742
+ totalUsd: requireField2(raw["total_usd"], "total_usd", raw),
1576
1743
  amountCents: Number(raw["amount_cents"] ?? 0),
1577
1744
  // Top-level since 2026-09-23; the breakdown has always carried the same figures.
1578
1745
  subtotalUsd: String(raw["subtotal_usd"] ?? breakdown.subtotalUsd),
@@ -1710,9 +1877,65 @@ function toTransactionStatus(raw) {
1710
1877
  orderId: raw["order_id"],
1711
1878
  toPhone: raw["to_phone"],
1712
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"]),
1713
1920
  raw
1714
1921
  };
1715
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),
1932
+ raw
1933
+ };
1934
+ }
1935
+ function nextCursorOf(raw) {
1936
+ const c = raw["next_cursor"];
1937
+ return typeof c === "string" && c ? c : null;
1938
+ }
1716
1939
  function toGuardianApprovalStatus(raw) {
1717
1940
  const approval = raw["approval"] ?? {};
1718
1941
  return {
@@ -1810,10 +2033,10 @@ function assertDeviceApprovalFlow(flow) {
1810
2033
  }
1811
2034
  function toDeviceApprovalGrant(raw) {
1812
2035
  return {
1813
- deviceCode: requireField(raw["device_code"], "device_code", raw),
2036
+ deviceCode: requireField2(raw["device_code"], "device_code", raw),
1814
2037
  userCode: String(raw["user_code"] ?? ""),
1815
2038
  verificationUri: String(raw["verification_uri"] ?? ""),
1816
- verificationUriComplete: requireField(raw["verification_uri_complete"], "verification_uri_complete", raw),
2039
+ verificationUriComplete: requireField2(raw["verification_uri_complete"], "verification_uri_complete", raw),
1817
2040
  expiresIn: Number(raw["expires_in"] ?? 0) || 0,
1818
2041
  interval: Math.max(1, Number(raw["interval"] ?? 5) || 5),
1819
2042
  channel: String(raw["channel"] ?? "qr"),
@@ -1893,7 +2116,7 @@ function playerTokenFields(raw) {
1893
2116
  }
1894
2117
  return out;
1895
2118
  }
1896
- function requireField(value, field, raw) {
2119
+ function requireField2(value, field, raw) {
1897
2120
  const s = value == null ? "" : String(value);
1898
2121
  if (!s) {
1899
2122
  throw new InvoError({
@@ -1969,7 +2192,9 @@ var PlatformCommerceServer = class {
1969
2192
  throw new InvoError({
1970
2193
  message: `Card purchases must be at least $${CARD_MIN_USD.toFixed(2)}.`,
1971
2194
  code: "BELOW_STRIPE_MINIMUM",
1972
- status: 0
2195
+ publicCode: "BELOW_CARD_MINIMUM",
2196
+ status: 0,
2197
+ body: { min_usd: CARD_MIN_USD.toFixed(2) }
1973
2198
  });
1974
2199
  }
1975
2200
  }
@@ -2000,9 +2225,9 @@ var PlatformCommerceServer = class {
2000
2225
  );
2001
2226
  const status = String(raw["status"] ?? "");
2002
2227
  if (status === "requires_payment") {
2003
- requireField(raw["checkout_url"], "checkout_url", raw);
2228
+ requireField2(raw["checkout_url"], "checkout_url", raw);
2004
2229
  } else {
2005
- requireField(raw["order_id"], "order_id", raw);
2230
+ requireField2(raw["order_id"], "order_id", raw);
2006
2231
  }
2007
2232
  const expiresAtRaw = raw["expires_at"];
2008
2233
  return {
@@ -2034,17 +2259,71 @@ var PlatformCommerceServer = class {
2034
2259
  this.auth,
2035
2260
  { signal: opts?.signal }
2036
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);
2037
2295
  return {
2038
- orderId: raw["order_id"] ?? orderId,
2039
- status: String(raw["status"] ?? ""),
2040
- gameCurrencyAmount: raw["game_currency_amount"] ?? null,
2041
- usdAmount: raw["usd_amount"] ?? null,
2042
- paymentMethod: raw["payment_method"],
2043
- createdAt: raw["created_at"],
2044
- ...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,
2045
2302
  raw
2046
2303
  };
2047
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
+ }
2048
2327
  /**
2049
2328
  * Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
2050
2329
  * INVO retains its fee — the customer is made whole (balance re-credit or card refund)
@@ -2978,7 +3257,7 @@ var CardsServer = class {
2978
3257
  return {
2979
3258
  sessionId: String(raw["session_id"] ?? ""),
2980
3259
  // Load-bearing: the member must be sent here. A 2xx without it is a broken response.
2981
- cardSetupUrl: requireField(raw["card_setup_url"], "card_setup_url", raw),
3260
+ cardSetupUrl: requireField2(raw["card_setup_url"], "card_setup_url", raw),
2982
3261
  expiresAt: String(raw["expires_at"] ?? ""),
2983
3262
  raw
2984
3263
  };
@@ -3023,7 +3302,7 @@ var CardsServer = class {
3023
3302
  );
3024
3303
  return {
3025
3304
  status: String(raw["status"] ?? ""),
3026
- setupIntentId: requireField(raw["setup_intent_id"], "setup_intent_id", raw),
3305
+ setupIntentId: requireField2(raw["setup_intent_id"], "setup_intent_id", raw),
3027
3306
  clientSecret: typeof raw["client_secret"] === "string" ? raw["client_secret"] : void 0,
3028
3307
  publishableKey: typeof raw["publishable_key"] === "string" ? raw["publishable_key"] : void 0,
3029
3308
  card: toSavedCard(raw["card"]),
@@ -3228,7 +3507,7 @@ var InvoServer = class {
3228
3507
  { idempotent: true, signal: opts?.signal }
3229
3508
  );
3230
3509
  const out = {
3231
- token: requireField(raw["token"], "token", raw),
3510
+ token: requireField2(raw["token"], "token", raw),
3232
3511
  expiresAt: String(raw["expires_at"] ?? ""),
3233
3512
  identityId: String(raw["identity_id"] ?? "")
3234
3513
  };
@@ -3268,7 +3547,7 @@ var InvoServer = class {
3268
3547
  // Find-or-create, no money: a retry after a create answers "exists".
3269
3548
  { idempotent: true, signal: opts?.signal }
3270
3549
  );
3271
- const status = requireField(raw["status"], "status", raw);
3550
+ const status = requireField2(raw["status"], "status", raw);
3272
3551
  return {
3273
3552
  status: status === "created" ? "created" : "exists",
3274
3553
  identityId: String(raw["identity_id"] ?? ""),
@@ -3283,9 +3562,11 @@ var InvoServer = class {
3283
3562
  * of date).
3284
3563
  *
3285
3564
  * Refusals: 409 `err.isPhoneChangeRequiresVerification` (the player has secured this
3286
- * account, so the change needs the player's own confirmation; contact INVO support
3287
- * meanwhile), 409 `err.isPhoneShareRefused` (the number belongs to another email),
3288
- * 404 `err.isPlayerNotFound`, 400 `INVALID_INPUT` / `INVALID_PHONE`, 429
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
3289
3570
  * (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
3290
3571
  *
3291
3572
  * Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
@@ -3302,7 +3583,7 @@ var InvoServer = class {
3302
3583
  this.auth,
3303
3584
  { signal: opts?.signal }
3304
3585
  );
3305
- const status = requireField(raw["status"], "status", raw);
3586
+ const status = requireField2(raw["status"], "status", raw);
3306
3587
  return {
3307
3588
  status: status === "updated" ? "updated" : "unchanged",
3308
3589
  identityRekeyed: raw["identity_rekeyed"] === true,
@@ -3311,6 +3592,61 @@ var InvoServer = class {
3311
3592
  raw
3312
3593
  };
3313
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);
3649
+ }
3314
3650
  /**
3315
3651
  * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
3316
3652
  *
@@ -3384,7 +3720,7 @@ var InvoServer = class {
3384
3720
  { signal: opts?.signal }
3385
3721
  // not idempotent — never auto-retried
3386
3722
  );
3387
- const checkoutUrl = requireField(raw["checkout_url"], "checkout_url", raw);
3723
+ const checkoutUrl = requireField2(raw["checkout_url"], "checkout_url", raw);
3388
3724
  return {
3389
3725
  sessionId: String(raw["session_id"] ?? ""),
3390
3726
  checkoutUrl,
@@ -3406,7 +3742,7 @@ var InvoServer = class {
3406
3742
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
3407
3743
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
3408
3744
  *
3409
- * 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
3410
3746
  * the listed price (before tax) on a card issued outside the US) is charged to you, the partner. The player
3411
3747
  * pays the listed price (plus any tax) and receives the listed coins. Card purchases only;
3412
3748
  * purchases through a third-party storefront or payment rail are unaffected. Two shapes,
@@ -3495,9 +3831,9 @@ var InvoServer = class {
3495
3831
  *
3496
3832
  * The player pays the listed price plus any tax (when you pass `country`) and receives the
3497
3833
  * listed coins: `totalUsd` carries no card fee, and `processingFeeUsd` is `"0.00"`. INVO's
3498
- * 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;
3499
3835
  * `partnerFeeUsd` carries it when INVO sends it. $10.00 quotes a $10.00 total, 100.00 coins
3500
- * 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`,
3501
3837
  * then send the same figure back as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the
3502
3838
  * card is never charged more than that. `ifUnacknowledged` shows the purchase without the
3503
3839
  * acknowledgement (the card charged exactly `usdAmount`), or `null` when INVO sends none.
@@ -3767,8 +4103,8 @@ var InvoServer = class {
3767
4103
  );
3768
4104
  return {
3769
4105
  status: String(raw["status"] ?? ""),
3770
- transactionId: requireField(raw["transaction_id"], "transaction_id", raw),
3771
- 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),
3772
4108
  newBalance: raw["new_balance"] ?? null,
3773
4109
  previousBalance: raw["previous_balance"] ?? null,
3774
4110
  currencyName: String(raw["currency_name"] ?? ""),
@@ -3848,6 +4184,86 @@ var InvoServer = class {
3848
4184
  if (Number.isFinite(total) && yielded >= total) return;
3849
4185
  }
3850
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
+ }
3851
4267
  /**
3852
4268
  * Read a player's currency balances by email (server-side, game-secret).
3853
4269
  *