@invonetwork/web-sdk 3.19.0 → 3.21.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
@@ -821,9 +821,47 @@ var InvoError = class _InvoError extends Error {
821
821
  * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
822
822
  * same reason; those two never create players, so create the member first (for
823
823
  * example with `createSetupSession` and a `playerName`, or a currency purchase).
824
+ * `getPlayerRewards` answers it when no player has that email in this game.
824
825
  */
825
826
  get isPlayerNotFound() {
826
- return this.code === "PLAYER_NOT_FOUND";
827
+ if (this.code === "PLAYER_NOT_FOUND") return true;
828
+ return this.status === 404 && this.bodyObject()["error"] === "player_not_found";
829
+ }
830
+ // ---- Player registration, phone changes, identity re-key ----
831
+ /**
832
+ * True when an approve was refused because the player token predates a change to the
833
+ * sender's identity (`PLAYER_TOKEN_STALE`, 403): their phone was added (for example on
834
+ * the initiate), which gives them a new identity. Nothing moved and the token stays
835
+ * refused. Re-mint the player token (or use the `playerToken` from the initiate result)
836
+ * and retry once. The SDK never retries a money call on its own.
837
+ */
838
+ get isPlayerTokenStale() {
839
+ return this.code === "PLAYER_TOKEN_STALE";
840
+ }
841
+ /**
842
+ * True when `updatePlayerPhone` was refused because the player has secured this account,
843
+ * 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
+ */
846
+ get isPhoneChangeRequiresVerification() {
847
+ return this.code === "PHONE_CHANGE_REQUIRES_VERIFICATION";
848
+ }
849
+ /**
850
+ * True when `registerPlayer` found the player already in your game with a DIFFERENT
851
+ * phone (`PHONE_MISMATCH`, 409). Nothing changed; use `updatePlayerPhone` to change it.
852
+ * (`mintPlayerToken` reports the same situation as `phoneMismatch: true` on success.)
853
+ */
854
+ get isPhoneMismatch() {
855
+ return this.code === "PHONE_MISMATCH";
856
+ }
857
+ /**
858
+ * True when the phone you supplied belongs to another email
859
+ * (`PHONE_SHARE_APPROVAL_REQUIRED`, 409) on `mintPlayerToken`, `registerPlayer` or
860
+ * `updatePlayerPhone`. Nothing was created or changed. The same condition as
861
+ * {@link isPhoneShareApprovalRequired}, named for these registration calls.
862
+ */
863
+ get isPhoneShareRefused() {
864
+ return this.isPhoneShareApprovalRequired;
827
865
  }
828
866
  /**
829
867
  * True when `cards.createSetupSession` was asked to create a new member (`playerName`
@@ -835,7 +873,8 @@ var InvoError = class _InvoError extends Error {
835
873
  }
836
874
  /**
837
875
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
838
- * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
876
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400). `getPlayerRewards` answers it
877
+ * for an email that is not an email address (a blank one never leaves the SDK).
839
878
  */
840
879
  get isInvalidPlayerEmail() {
841
880
  return this.code === "INVALID_PLAYER_EMAIL";
@@ -886,6 +925,26 @@ var InvoError = class _InvoError extends Error {
886
925
  get isIdentityCheckUnavailable() {
887
926
  return this.code === "IDENTITY_CHECK_UNAVAILABLE";
888
927
  }
928
+ // ---- Loyalty rewards (InvoClient.redeemReward) ----
929
+ /** True when a reward was already redeemed and its code can no longer be shown (`already_redeemed`, 409). */
930
+ get isRewardAlreadyRedeemed() {
931
+ return this.code === "already_redeemed";
932
+ }
933
+ /** True when the player has no such reward (`vault_entry_not_found`, 404). */
934
+ get isRewardNotFound() {
935
+ return this.code === "vault_entry_not_found";
936
+ }
937
+ /**
938
+ * True when the reward cannot be redeemed right now (409): `inventory_exhausted` (no units or
939
+ * codes are left for it) or `conflict` (the reward is reserved or revoked).
940
+ */
941
+ get isRewardUnavailable() {
942
+ return this.code === "inventory_exhausted" || this.code === "conflict";
943
+ }
944
+ /** True when the reward expired before it was redeemed (`vault_entry_expired`, 410). */
945
+ get isRewardExpired() {
946
+ return this.code === "vault_entry_expired";
947
+ }
889
948
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
890
949
  get retryAfter() {
891
950
  const v = this.bodyObject()["retry_after"];
@@ -1168,6 +1227,89 @@ function toDestinationsResult(raw, direction) {
1168
1227
  };
1169
1228
  }
1170
1229
 
1230
+ // src/shared/loyalty.ts
1231
+ var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
1232
+ var rows = (v) => Array.isArray(v) ? v.filter((r) => r && typeof r === "object" && !Array.isArray(r)) : [];
1233
+ var str = (v) => v === void 0 || v === null ? "" : String(v);
1234
+ var strOrNull = (v) => v === void 0 || v === null ? null : String(v);
1235
+ var numOrNull = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
1236
+ var int = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
1237
+ var passThrough = (v) => v;
1238
+ function toLoyaltyStepProgress(value) {
1239
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;
1240
+ const v = value;
1241
+ const current = v["current"];
1242
+ const target = v["target"];
1243
+ if (!Number.isInteger(current) || !Number.isInteger(target)) return null;
1244
+ return { current, target };
1245
+ }
1246
+ function toStep(row) {
1247
+ return {
1248
+ stepId: strOrNull(row["step_id"]),
1249
+ index: int(row["index"]),
1250
+ action: str(row["action"]),
1251
+ label: str(row["label"]),
1252
+ summary: str(row["summary"]),
1253
+ windowHours: numOrNull(row["window_hours"]),
1254
+ state: str(row["state"]),
1255
+ progress: toLoyaltyStepProgress(row["progress"]),
1256
+ raw: row
1257
+ };
1258
+ }
1259
+ function toCardReward(row) {
1260
+ return {
1261
+ vaultEntryId: str(row["vault_entry_id"]),
1262
+ rewardId: str(row["reward_id"]),
1263
+ state: str(row["state"]),
1264
+ unlockedAt: str(row["unlocked_at"]),
1265
+ expiresAt: str(row["expires_at"]),
1266
+ redeemedAt: strOrNull(row["redeemed_at"]),
1267
+ codeMasked: strOrNull(row["code_masked"]),
1268
+ canRedeem: row["can_redeem"] === true,
1269
+ canRevealAgain: row["can_reveal_again"] === true,
1270
+ revealUntil: strOrNull(row["reveal_until"]),
1271
+ raw: row
1272
+ };
1273
+ }
1274
+ function toLoyaltyCard(row) {
1275
+ const brand = obj(row["brand"]);
1276
+ const reward = obj(row["reward"]);
1277
+ const steps = rows(row["steps"]).map(toStep);
1278
+ return {
1279
+ cardVersion: passThrough(row["card_version"]),
1280
+ mode: str(row["mode"]),
1281
+ programId: strOrNull(row["program_id"]),
1282
+ questId: strOrNull(row["quest_id"]),
1283
+ questVersion: numOrNull(row["quest_version"]),
1284
+ campaignId: strOrNull(row["campaign_id"]),
1285
+ title: str(row["title"]),
1286
+ description: str(row["description"]),
1287
+ brand: { name: strOrNull(brand["name"]), logoUrl: strOrNull(brand["logo_url"]) },
1288
+ artUrl: strOrNull(row["art_url"]),
1289
+ reward: { rewardId: strOrNull(reward["reward_id"]), name: strOrNull(reward["name"]) },
1290
+ orderMode: str(row["order_mode"]),
1291
+ status: str(row["status"]),
1292
+ startsAt: strOrNull(row["starts_at"]),
1293
+ endsAt: strOrNull(row["ends_at"]),
1294
+ completionHours: numOrNull(row["completion_hours"]),
1295
+ completionNote: strOrNull(row["completion_note"]),
1296
+ windowEndsAt: strOrNull(row["window_ends_at"]),
1297
+ completedAt: strOrNull(row["completed_at"]),
1298
+ stepsRequired: passThrough(row["steps_required"]),
1299
+ stepsComplete: passThrough(row["steps_complete"]),
1300
+ steps,
1301
+ rewards: rows(row["rewards"]).map(toCardReward),
1302
+ raw: row
1303
+ };
1304
+ }
1305
+ function toLoyaltyCardsResult(raw) {
1306
+ return {
1307
+ cardVersion: passThrough(raw["card_version"]),
1308
+ cards: rows(raw["cards"]).map(toLoyaltyCard),
1309
+ raw
1310
+ };
1311
+ }
1312
+
1171
1313
  // src/shared/receipt-fields.ts
1172
1314
  function creditFields(raw) {
1173
1315
  const c = raw["credited"];
@@ -1186,7 +1328,7 @@ function receiptFields(raw) {
1186
1328
  }
1187
1329
 
1188
1330
  // src/version.ts
1189
- var SDK_VERSION = "3.19.0";
1331
+ var SDK_VERSION = "3.21.0";
1190
1332
 
1191
1333
  // src/shared/types.ts
1192
1334
  function isRefundPendingApproval(r) {
@@ -1741,6 +1883,16 @@ function toCurrencyBalance(row) {
1741
1883
  raw: row
1742
1884
  };
1743
1885
  }
1886
+ function playerTokenFields(raw) {
1887
+ const out = {};
1888
+ if (typeof raw["player_token"] === "string" && raw["player_token"]) {
1889
+ out.playerToken = raw["player_token"];
1890
+ if (typeof raw["player_token_expires_at"] === "string") {
1891
+ out.playerTokenExpiresAt = raw["player_token_expires_at"];
1892
+ }
1893
+ }
1894
+ return out;
1895
+ }
1744
1896
  function requireField(value, field, raw) {
1745
1897
  const s = value == null ? "" : String(value);
1746
1898
  if (!s) {
@@ -2419,13 +2571,13 @@ var SubscriptionsServer = class {
2419
2571
  this.auth,
2420
2572
  { signal: opts?.signal }
2421
2573
  );
2422
- const rows = Array.isArray(raw["subscriptions"]) ? raw["subscriptions"] : [];
2574
+ const rows2 = Array.isArray(raw["subscriptions"]) ? raw["subscriptions"] : [];
2423
2575
  const p = raw["pagination"] ?? {};
2424
2576
  return {
2425
2577
  playerEmail: String(raw["player_email"] ?? playerEmail),
2426
- subscriptions: rows.map(toSubscription),
2578
+ subscriptions: rows2.map(toSubscription),
2427
2579
  pagination: {
2428
- totalCount: Number(p["total_count"] ?? rows.length),
2580
+ totalCount: Number(p["total_count"] ?? rows2.length),
2429
2581
  limit: Number(p["limit"] ?? 50),
2430
2582
  offset: Number(p["offset"] ?? 0),
2431
2583
  hasMore: p["has_more"] === true
@@ -2924,9 +3076,9 @@ var CardsServer = class {
2924
3076
  this.auth,
2925
3077
  { signal: opts?.signal }
2926
3078
  );
2927
- const rows = Array.isArray(raw["cards"]) ? raw["cards"] : [];
3079
+ const rows2 = Array.isArray(raw["cards"]) ? raw["cards"] : [];
2928
3080
  return {
2929
- cards: rows.map(toSavedCard).filter((c) => c !== null),
3081
+ cards: rows2.map(toSavedCard).filter((c) => c !== null),
2930
3082
  raw
2931
3083
  };
2932
3084
  }
@@ -3038,16 +3190,19 @@ var InvoServer = class {
3038
3190
  /**
3039
3191
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
3040
3192
  *
3041
- * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
3042
- * registration call. The backend looks the player up by `playerEmail` and returns a
3043
- * token for their existing identity; if no such player exists it responds 404. The
3044
- * network identity (which encodes the player's phone) is established when the player
3045
- * is created and on the money-routing calls, so phone is NOT required or read here.
3193
+ * For a player who already exists in your game, this is a session mint: INVO looks the
3194
+ * player up by `playerEmail` and returns a token for their identity. `playerPhone` and
3195
+ * `playerName` do not change an existing player.
3196
+ *
3197
+ * For a player who is NOT in your game yet: without `playerPhone` INVO answers 404
3198
+ * (`err.isPlayerNotFound`); with `playerPhone` INVO creates the player and the result
3199
+ * carries `created: true`, so a first-time receiver can collect without buying first.
3200
+ * Use `registerPlayer` when you want creation to be explicit.
3046
3201
  *
3047
- * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
3048
- * ignores it on this endpoint, so an existing email-only player can still mint a token.
3049
- * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
3050
- * sender's phone, and the recipient's when known) and at player creation.
3202
+ * `phoneMismatch: true` means the existing player has a different phone than the one
3203
+ * you passed; the token is still for that player and their phone is unchanged
3204
+ * (`updatePlayerPhone` changes it). A phone already held by another email is a 409
3205
+ * (`err.isPhoneShareRefused`).
3051
3206
  */
3052
3207
  async mintPlayerToken(input, opts) {
3053
3208
  if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
@@ -3058,18 +3213,103 @@ var InvoServer = class {
3058
3213
  assertE164(input.playerPhone, "playerPhone");
3059
3214
  body["player_phone"] = input.playerPhone;
3060
3215
  }
3216
+ if (input.playerName !== void 0) {
3217
+ if (typeof input.playerName !== "string") {
3218
+ throw invalidInput("playerName", input.playerName, "must be a string");
3219
+ }
3220
+ body["player_name"] = input.playerName;
3221
+ }
3061
3222
  const raw = await this.http.post(
3062
3223
  "/api/sdk/player-token",
3063
3224
  body,
3064
3225
  this.auth,
3226
+ // Safe to retry: a re-mint issues a fresh token, and a create that already happened
3227
+ // answers the retry for the existing player.
3065
3228
  { idempotent: true, signal: opts?.signal }
3066
- // safe to retry: re-mint just issues a fresh token
3067
3229
  );
3068
- return {
3230
+ const out = {
3069
3231
  token: requireField(raw["token"], "token", raw),
3070
3232
  expiresAt: String(raw["expires_at"] ?? ""),
3071
3233
  identityId: String(raw["identity_id"] ?? "")
3072
3234
  };
3235
+ if (raw["created"] === true) out.created = true;
3236
+ if (raw["phone_mismatch"] === true) out.phoneMismatch = true;
3237
+ return out;
3238
+ }
3239
+ /**
3240
+ * Create a player in your game without moving money (`POST /api/sdk/players`), so a
3241
+ * first-time receiver can collect in-game. Sends no message to the player.
3242
+ *
3243
+ * Returns `status: "created"` (new) or `"exists"` (already in your game with that
3244
+ * phone), with a player token when INVO can issue one. Refusals: 409
3245
+ * `err.isPhoneMismatch` (already in your game with a different phone; use
3246
+ * `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
3247
+ * email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
3248
+ */
3249
+ async registerPlayer(input, opts) {
3250
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
3251
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
3252
+ }
3253
+ assertE164(input.playerPhone, "playerPhone");
3254
+ const body = {
3255
+ player_email: input.playerEmail,
3256
+ player_phone: input.playerPhone
3257
+ };
3258
+ if (input.playerName !== void 0) {
3259
+ if (typeof input.playerName !== "string") {
3260
+ throw invalidInput("playerName", input.playerName, "must be a string");
3261
+ }
3262
+ body["player_name"] = input.playerName;
3263
+ }
3264
+ const raw = await this.http.post(
3265
+ "/api/sdk/players",
3266
+ body,
3267
+ this.auth,
3268
+ // Find-or-create, no money: a retry after a create answers "exists".
3269
+ { idempotent: true, signal: opts?.signal }
3270
+ );
3271
+ const status = requireField(raw["status"], "status", raw);
3272
+ return {
3273
+ status: status === "created" ? "created" : "exists",
3274
+ identityId: String(raw["identity_id"] ?? ""),
3275
+ ...playerTokenFields(raw),
3276
+ raw
3277
+ };
3278
+ }
3279
+ /**
3280
+ * Set a player's phone from your server (`POST /api/sdk/players/phone`). A phone change
3281
+ * can give the player a new INVO identity: `identityRekeyed: true`, and the result
3282
+ * carries a fresh `playerToken` for it (tokens minted before the change are then out
3283
+ * of date).
3284
+ *
3285
+ * 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
3289
+ * (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
3290
+ *
3291
+ * Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
3292
+ * hide `identityRekeyed`.
3293
+ */
3294
+ async updatePlayerPhone(input, opts) {
3295
+ if (typeof input.playerEmail !== "string" || !input.playerEmail.trim()) {
3296
+ throw invalidInput("playerEmail", input.playerEmail, "is required");
3297
+ }
3298
+ assertE164(input.newPhone, "newPhone");
3299
+ const raw = await this.http.post(
3300
+ "/api/sdk/players/phone",
3301
+ { player_email: input.playerEmail, new_phone: input.newPhone },
3302
+ this.auth,
3303
+ { signal: opts?.signal }
3304
+ );
3305
+ const status = requireField(raw["status"], "status", raw);
3306
+ return {
3307
+ status: status === "updated" ? "updated" : "unchanged",
3308
+ identityRekeyed: raw["identity_rekeyed"] === true,
3309
+ identityId: String(raw["identity_id"] ?? ""),
3310
+ ...playerTokenFields(raw),
3311
+ raw
3312
+ };
3073
3313
  }
3074
3314
  /**
3075
3315
  * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
@@ -3634,14 +3874,40 @@ var InvoServer = class {
3634
3874
  });
3635
3875
  }
3636
3876
  const raw = await this.http.get(path, this.auth, { signal: opts?.signal });
3637
- const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
3877
+ const rows2 = Array.isArray(raw["balances"]) ? raw["balances"] : [];
3638
3878
  return {
3639
3879
  player: raw["player"] ?? {},
3640
- balances: rows.map(toCurrencyBalance),
3880
+ balances: rows2.map(toCurrencyBalance),
3641
3881
  summary: raw["summary"] ?? {},
3642
3882
  raw
3643
3883
  };
3644
3884
  }
3885
+ /**
3886
+ * One player's loyalty cards, read by your SERVER with the game secret: the same cards
3887
+ * the player sees through `InvoClient.getMyRewards()`, for the player with this email in
3888
+ * your game. Each step carries `state` and `progress` (`{ current, target }`, or `null`
3889
+ * when the number could not be read this time: render `state` alone then). Rewards carry
3890
+ * their masked code only; a code is never returned here.
3891
+ *
3892
+ * Refusals (all `InvoError`): a blank email throws `INVALID_INPUT` before the network;
3893
+ * `400 INVALID_PLAYER_EMAIL` (`err.isInvalidPlayerEmail`), `401 INVALID_GAME_SECRET` for a missing or wrong key, or
3894
+ * a per-channel key (this read takes the game's server secret only), `404 PLAYER_NOT_FOUND`
3895
+ * (`err.isPlayerNotFound`: no player with this email in this game), `429` (back off;
3896
+ * `err.retryAfter`). Also `409 NO_TENANT` (the game is not set up for loyalty), `503`
3897
+ * (temporarily unavailable) and `502` / `504` (the loyalty service could not be reached or
3898
+ * timed out): retry later. A GET, so transient failures are retried automatically.
3899
+ */
3900
+ async getPlayerRewards(playerEmail, opts) {
3901
+ if (typeof playerEmail !== "string" || !playerEmail.trim()) {
3902
+ throw invalidInput("playerEmail", playerEmail, "is required");
3903
+ }
3904
+ const raw = await this.http.get(
3905
+ `/api/sdk/loyalty/players/rewards?player_email=${encodeURIComponent(playerEmail.trim())}`,
3906
+ this.auth,
3907
+ { signal: opts?.signal }
3908
+ );
3909
+ return toLoyaltyCardsResult(raw);
3910
+ }
3645
3911
  /**
3646
3912
  * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
3647
3913
  * the source of truth for a "you have X to collect" badge. Pass the player's email
@@ -3663,8 +3929,8 @@ var InvoServer = class {
3663
3929
  this.auth,
3664
3930
  { signal: opts?.signal }
3665
3931
  );
3666
- const rows = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
3667
- return { inboundPending: rows.map(toInboundPendingItem), raw };
3932
+ const rows2 = Array.isArray(raw["inbound_pending"]) ? raw["inbound_pending"] : [];
3933
+ return { inboundPending: rows2.map(toInboundPendingItem), raw };
3668
3934
  }
3669
3935
  /**
3670
3936
  * Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
@@ -4091,8 +4357,10 @@ var InvoServer = class {
4091
4357
  *
4092
4358
  * Throws `InvoError`: `err.isDeviceApprovalNotApproved` (400 — wrong/foreign code,
4093
4359
  * wrong flow, or the poll never said approved), `err.isPasskeyRecoveryCooldown` (403,
4094
- * money-out after a passkey recovery — `err.retryAfterAt`), guardian terminal states
4095
- * (410). Never auto-retried: the device_code is a single-use factor.
4360
+ * money-out after a passkey recovery — `err.retryAfterAt`), `err.isPlayerTokenStale`
4361
+ * (403, the player token predates the sender's phone being added: re-mint, or use the
4362
+ * initiate's `playerToken`, and retry once), guardian terminal states (410). Never
4363
+ * auto-retried: the device_code is a single-use factor.
4096
4364
  *
4097
4365
  * **A FAILURE HERE IS AMBIGUOUS ABOUT THE MONEY.** The backend commits the transfer and
4098
4366
  * *then* builds its 200 by reading the transaction back, so a fault raised after that
@@ -4249,6 +4517,10 @@ var InvoServer = class {
4249
4517
  transactionId: String(raw["transaction_id"] ?? ""),
4250
4518
  verificationMethod: guardian ? void 0 : vm === "in_app" || vm === "sms" ? vm : void 0,
4251
4519
  guardianApproval: guardian ?? void 0,
4520
+ ...raw["identity_rekeyed"] === true ? { identityRekeyed: true } : {},
4521
+ ...playerTokenFields(raw),
4522
+ ...typeof raw["identity_id"] === "string" && raw["identity_id"] ? { identityId: raw["identity_id"] } : {},
4523
+ ...typeof raw["claim_delivery_planned"] === "string" && raw["claim_delivery_planned"] ? { claimDeliveryPlanned: raw["claim_delivery_planned"] } : {},
4252
4524
  raw
4253
4525
  };
4254
4526
  }
package/dist/server.d.cts CHANGED
@@ -1,12 +1,12 @@
1
- import { I as InvoError, H as Http, x as AuthHeader, y as CardSetupSessionInput, g as CallOptions, z as CardSetupSessionResult, F as CardSetupInput, G as CardSetupResult, J as CardSetupConfirmInput, K as CardSetupConfirmResult, N as PlayerCardsResult, O as PlatformPurchaseInput, Q as PlatformPurchaseResult, S as PlatformOrderStatusResult, T as PlatformRefundInput, U as PlatformRefundResult, X as CreateSubscriptionInput, Y as SubscriptionResult, Z as GetSubscriptionOptions, _ as GetSubscriptionResult, $ as ListSubscriptionsOptions, a0 as SubscriptionListResult, a1 as CancelSubscriptionOptions, a2 as CancelResult, a3 as ChangeAmountResult, a4 as SetPaymentMethodInput, a5 as SetPaymentMethodResult, a6 as RefundSubscriptionInput, a7 as RefundResult, a8 as SteamSubscriptionInitInput, a9 as SteamInitResult, aa as SteamFinalizeSubscriptionResult, ab as SandboxClockResult, ac as SandboxFailureOutcome, ad as SandboxForceFailureOptions, ae as SandboxForceAuthChallengeOptions, af as ServerConfig, ag as PlayerToken, ah as InitiateSendInput, ai as InitiateResult, aj as InitiateTransferInput, ak as CreateCheckoutInput, al as CreateCheckoutResult, am as PurchaseInput, an as PurchaseResult, ao as CurrencyPurchaseQuoteInput, ap as CurrencyPurchaseQuote, aq as ConfirmPaymentResult, ar as OrderDetailsResult, as as SteamPacksQuery, at as SteamPacksResult, au as SteamInitPurchaseInput, av as SteamInitPurchaseResult, aw as SteamFinalizeInput, ax as SteamFinalizeResult, ay as PurchaseItemInput, az as PurchaseItemResult, aA as ItemHistoryQuery, aB as ItemHistoryResult, aC as ItemOrderQuery, aD as PlayerBalanceQuery, aE as PlayerBalanceResult, aF as InboundPendingQuery, aG as InboundPendingResult, aH as LinkedIdentitiesQuery, aI as LinkedIdentitiesResult, aJ as SmsVerifyResult, aK as ClaimTransferInput, aL as ClaimResult, aM as ClaimCurrencyInput, aN as TransactionStatusResult, aO as GuardianApprovalStatusResult, aP as ServerDestinationsQuery, k as DestinationsResult, aQ as PhoneShareContact, aR as PhoneShareInitiateResult, aS as PhoneShareApproveInput, aT as PhoneShareApproveResult, aU as PhoneShareStatusResult, aV as BeginDeviceApprovalInput, aW as DeviceApprovalGrant, aX as PollDeviceApprovalInput, aY as DeviceApprovalPollResult, aZ as ConfirmDeviceEnrollmentInput, a_ as ConfirmDeviceEnrollmentResult, a$ as ApproveWithDeviceCodeInput, b0 as DeviceApprovalSettleResult, b1 as CompleteDeviceApprovalInput, b2 as CompleteDeviceApprovalResult } from './types-CCqgVhzf.cjs';
2
- export { b3 as CardSetupStatus, b4 as CheckoutWarning, b5 as CurrencyBalance, b6 as CurrencyPurchaseQuoteBreakdown, p as DestinationGame, b7 as DeviceApprovalChannel, b8 as DeviceApprovalEnrollment, b9 as DeviceApprovalFlow, ba as DeviceApprovalPollStatus, bb as DeviceEnrollmentDecision, bc as DeviceEnrollmentRespond, bd as FeeTakenFrom, be as FirstCharge, bf as FirstChargeStatus, bg as FundingSource, bh as InboundPendingItem, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, bi as LinkedIdentityEmail, bj as MinPurchaseWarning, bk as PlatformPurchaseStatus, w as Rail, bl as RefundInitiation, bm as RefundPendingApproval, bn as RefundProcessingFeeBasis, bo as RefundReceipt, bp as RefundRevenueShareAttribution, bq as RefundWarning, br as SandboxClockState, bs as SavedCard, bt as SteamPack, bu as SteamUserSession, bv as Subscription, bw as SubscriptionBaseInput, bx as SubscriptionConsent, by as SubscriptionConsentInput, bz as SubscriptionFundingRail, bA as SubscriptionInterval, bB as SubscriptionRevenueShare, bC as SubscriptionRevenueShareInput, bD as SubscriptionStatus, bE as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bF as isRefundPendingApproval } from './types-CCqgVhzf.cjs';
1
+ import { I as InvoError, H as Http, U as AuthHeader, X as CardSetupSessionInput, g as CallOptions, Y as CardSetupSessionResult, Z as CardSetupInput, _ as CardSetupResult, $ as CardSetupConfirmInput, a0 as CardSetupConfirmResult, a1 as PlayerCardsResult, a2 as PlatformPurchaseInput, a3 as PlatformPurchaseResult, a4 as PlatformOrderStatusResult, a5 as PlatformRefundInput, a6 as PlatformRefundResult, a7 as CreateSubscriptionInput, a8 as SubscriptionResult, a9 as GetSubscriptionOptions, aa as GetSubscriptionResult, ab as ListSubscriptionsOptions, ac as SubscriptionListResult, ad as CancelSubscriptionOptions, ae as CancelResult, af as ChangeAmountResult, ag as SetPaymentMethodInput, ah as SetPaymentMethodResult, ai as RefundSubscriptionInput, aj as RefundResult, ak as SteamSubscriptionInitInput, al as SteamInitResult, am as SteamFinalizeSubscriptionResult, an as SandboxClockResult, ao as SandboxFailureOutcome, ap as SandboxForceFailureOptions, aq as SandboxForceAuthChallengeOptions, ar as ServerConfig, as as MintPlayerTokenInput, at as PlayerToken, au as RegisterPlayerInput, av as RegisterPlayerResult, aw as UpdatePlayerPhoneInput, ax as UpdatePlayerPhoneResult, ay as InitiateSendInput, az as InitiateResult, aA as InitiateTransferInput, aB as CreateCheckoutInput, aC as CreateCheckoutResult, aD as PurchaseInput, aE as PurchaseResult, aF as CurrencyPurchaseQuoteInput, aG as CurrencyPurchaseQuote, aH as ConfirmPaymentResult, aI as OrderDetailsResult, aJ as SteamPacksQuery, aK as SteamPacksResult, aL as SteamInitPurchaseInput, aM as SteamInitPurchaseResult, aN as SteamFinalizeInput, aO as SteamFinalizeResult, aP as PurchaseItemInput, aQ as PurchaseItemResult, aR as ItemHistoryQuery, aS as ItemHistoryResult, aT as ItemOrderQuery, aU as PlayerBalanceQuery, aV as PlayerBalanceResult, l as LoyaltyCardsResult, aW as InboundPendingQuery, aX as InboundPendingResult, aY as LinkedIdentitiesQuery, aZ as LinkedIdentitiesResult, a_ as SmsVerifyResult, a$ as ClaimTransferInput, b0 as ClaimResult, b1 as ClaimCurrencyInput, b2 as TransactionStatusResult, b3 as GuardianApprovalStatusResult, b4 as ServerDestinationsQuery, k as DestinationsResult, b5 as PhoneShareContact, b6 as PhoneShareInitiateResult, b7 as PhoneShareApproveInput, b8 as PhoneShareApproveResult, b9 as PhoneShareStatusResult, ba as BeginDeviceApprovalInput, bb as DeviceApprovalGrant, bc as PollDeviceApprovalInput, bd as DeviceApprovalPollResult, be as ConfirmDeviceEnrollmentInput, bf as ConfirmDeviceEnrollmentResult, bg as ApproveWithDeviceCodeInput, bh as DeviceApprovalSettleResult, bi as CompleteDeviceApprovalInput, bj as CompleteDeviceApprovalResult } from './types-BXcPz6Xw.cjs';
2
+ export { bk as CardSetupStatus, bl as CheckoutWarning, t as ClaimDelivery, bm as CurrencyBalance, bn as CurrencyPurchaseQuoteBreakdown, u as DestinationGame, bo as DeviceApprovalChannel, bp as DeviceApprovalEnrollment, bq as DeviceApprovalFlow, br as DeviceApprovalPollStatus, bs as DeviceEnrollmentDecision, bt as DeviceEnrollmentRespond, bu as FeeTakenFrom, bv as FirstCharge, bw as FirstChargeStatus, bx as FundingSource, by as InboundPendingItem, v as InvoErrorInfo, w as InvoHooks, x as InvoRequestInfo, y as InvoResponseInfo, bz as LinkedIdentityEmail, z as LoyaltyCard, F as LoyaltyCardReward, G as LoyaltyCardStep, J as LoyaltyRewardState, K as LoyaltyStepProgress, N as LoyaltyStepState, bA as MinPurchaseWarning, bB as PlatformPurchaseStatus, T as Rail, bC as RefundInitiation, bD as RefundPendingApproval, bE as RefundProcessingFeeBasis, bF as RefundReceipt, bG as RefundRevenueShareAttribution, bH as RefundWarning, bI as SandboxClockState, bJ as SavedCard, bK as SteamPack, bL as SteamUserSession, bM as Subscription, bN as SubscriptionBaseInput, bO as SubscriptionConsent, bP as SubscriptionConsentInput, bQ as SubscriptionFundingRail, bR as SubscriptionInterval, bS as SubscriptionRevenueShare, bT as SubscriptionRevenueShareInput, bU as SubscriptionStatus, bV as UnacknowledgedPurchaseOutcome, V as VerificationMethod, bW as isRefundPendingApproval } from './types-BXcPz6Xw.cjs';
3
3
 
4
4
  /**
5
5
  * The package version, as sent in the server User-Agent. A test pins this to
6
6
  * `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
7
7
  * Bump it with the changeset flow.
8
8
  */
9
- declare const SDK_VERSION = "3.19.0";
9
+ declare const SDK_VERSION = "3.21.0";
10
10
 
11
11
  interface VerifyWebhookOptions {
12
12
  /** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
@@ -1216,21 +1216,48 @@ declare class InvoServer {
1216
1216
  /**
1217
1217
  * Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
1218
1218
  *
1219
- * This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game — not a
1220
- * registration call. The backend looks the player up by `playerEmail` and returns a
1221
- * token for their existing identity; if no such player exists it responds 404. The
1222
- * network identity (which encodes the player's phone) is established when the player
1223
- * is created and on the money-routing calls, so phone is NOT required or read here.
1219
+ * For a player who already exists in your game, this is a session mint: INVO looks the
1220
+ * player up by `playerEmail` and returns a token for their identity. `playerPhone` and
1221
+ * `playerName` do not change an existing player.
1224
1222
  *
1225
- * `playerPhone` is optional and only validated (E.164) if you pass it — the backend
1226
- * ignores it on this endpoint, so an existing email-only player can still mint a token.
1227
- * Phone is enforced where it actually matters: `initiateSend`/`initiateTransfer` (the
1228
- * sender's phone, and the recipient's when known) and at player creation.
1223
+ * For a player who is NOT in your game yet: without `playerPhone` INVO answers 404
1224
+ * (`err.isPlayerNotFound`); with `playerPhone` INVO creates the player and the result
1225
+ * carries `created: true`, so a first-time receiver can collect without buying first.
1226
+ * Use `registerPlayer` when you want creation to be explicit.
1227
+ *
1228
+ * `phoneMismatch: true` means the existing player has a different phone than the one
1229
+ * you passed; the token is still for that player and their phone is unchanged
1230
+ * (`updatePlayerPhone` changes it). A phone already held by another email is a 409
1231
+ * (`err.isPhoneShareRefused`).
1229
1232
  */
1230
- mintPlayerToken(input: {
1231
- playerEmail: string;
1232
- playerPhone?: string;
1233
- }, opts?: CallOptions): Promise<PlayerToken>;
1233
+ mintPlayerToken(input: MintPlayerTokenInput, opts?: CallOptions): Promise<PlayerToken>;
1234
+ /**
1235
+ * Create a player in your game without moving money (`POST /api/sdk/players`), so a
1236
+ * first-time receiver can collect in-game. Sends no message to the player.
1237
+ *
1238
+ * Returns `status: "created"` (new) or `"exists"` (already in your game with that
1239
+ * phone), with a player token when INVO can issue one. Refusals: 409
1240
+ * `err.isPhoneMismatch` (already in your game with a different phone; use
1241
+ * `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
1242
+ * email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
1243
+ */
1244
+ registerPlayer(input: RegisterPlayerInput, opts?: CallOptions): Promise<RegisterPlayerResult>;
1245
+ /**
1246
+ * Set a player's phone from your server (`POST /api/sdk/players/phone`). A phone change
1247
+ * can give the player a new INVO identity: `identityRekeyed: true`, and the result
1248
+ * carries a fresh `playerToken` for it (tokens minted before the change are then out
1249
+ * of date).
1250
+ *
1251
+ * Refusals: 409 `err.isPhoneChangeRequiresVerification` (the player has secured this
1252
+ * account, so the change needs the player's own confirmation; contact INVO support
1253
+ * meanwhile), 409 `err.isPhoneShareRefused` (the number belongs to another email),
1254
+ * 404 `err.isPlayerNotFound`, 400 `INVALID_INPUT` / `INVALID_PHONE`, 429
1255
+ * (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
1256
+ *
1257
+ * Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
1258
+ * hide `identityRekeyed`.
1259
+ */
1260
+ updatePlayerPhone(input: UpdatePlayerPhoneInput, opts?: CallOptions): Promise<UpdatePlayerPhoneResult>;
1234
1261
  /**
1235
1262
  * Initiate a cross-game currency SEND. Inspect result.verificationMethod.
1236
1263
  *
@@ -1408,6 +1435,22 @@ declare class InvoServer {
1408
1435
  * client-side read, or `playerEmail` here server-side.
1409
1436
  */
1410
1437
  getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
1438
+ /**
1439
+ * One player's loyalty cards, read by your SERVER with the game secret: the same cards
1440
+ * the player sees through `InvoClient.getMyRewards()`, for the player with this email in
1441
+ * your game. Each step carries `state` and `progress` (`{ current, target }`, or `null`
1442
+ * when the number could not be read this time: render `state` alone then). Rewards carry
1443
+ * their masked code only; a code is never returned here.
1444
+ *
1445
+ * Refusals (all `InvoError`): a blank email throws `INVALID_INPUT` before the network;
1446
+ * `400 INVALID_PLAYER_EMAIL` (`err.isInvalidPlayerEmail`), `401 INVALID_GAME_SECRET` for a missing or wrong key, or
1447
+ * a per-channel key (this read takes the game's server secret only), `404 PLAYER_NOT_FOUND`
1448
+ * (`err.isPlayerNotFound`: no player with this email in this game), `429` (back off;
1449
+ * `err.retryAfter`). Also `409 NO_TENANT` (the game is not set up for loyalty), `503`
1450
+ * (temporarily unavailable) and `502` / `504` (the loyalty service could not be reached or
1451
+ * timed out): retry later. A GET, so transient failures are retried automatically.
1452
+ */
1453
+ getPlayerRewards(playerEmail: string, opts?: CallOptions): Promise<LoyaltyCardsResult>;
1411
1454
  /**
1412
1455
  * List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
1413
1456
  * the source of truth for a "you have X to collect" badge. Pass the player's email
@@ -1575,8 +1618,10 @@ declare class InvoServer {
1575
1618
  *
1576
1619
  * Throws `InvoError`: `err.isDeviceApprovalNotApproved` (400 — wrong/foreign code,
1577
1620
  * wrong flow, or the poll never said approved), `err.isPasskeyRecoveryCooldown` (403,
1578
- * money-out after a passkey recovery — `err.retryAfterAt`), guardian terminal states
1579
- * (410). Never auto-retried: the device_code is a single-use factor.
1621
+ * money-out after a passkey recovery — `err.retryAfterAt`), `err.isPlayerTokenStale`
1622
+ * (403, the player token predates the sender's phone being added: re-mint, or use the
1623
+ * initiate's `playerToken`, and retry once), guardian terminal states (410). Never
1624
+ * auto-retried: the device_code is a single-use factor.
1580
1625
  *
1581
1626
  * **A FAILURE HERE IS AMBIGUOUS ABOUT THE MONEY.** The backend commits the transfer and
1582
1627
  * *then* builds its 200 by reading the transaction back, so a fault raised after that
@@ -1619,4 +1664,4 @@ declare class InvoServer {
1619
1664
  private toInitiateResult;
1620
1665
  }
1621
1666
 
1622
- export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardSetupSessionInput, CardSetupSessionResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, CurrencyPurchaseQuote, CurrencyPurchaseQuoteInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundApprovedData, type SubscriptionRefundDetail, type SubscriptionRefundRejectedData, type SubscriptionRefundRequestData, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, type SubscriptionTrialEventFields, SubscriptionsServer, TransactionStatusResult, type TransferEventData, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };
1667
+ export { ApproveWithDeviceCodeInput, BeginDeviceApprovalInput, CallOptions, CancelResult, CancelSubscriptionOptions, CardSetupConfirmInput, CardSetupConfirmResult, CardSetupInput, CardSetupResult, CardSetupSessionInput, CardSetupSessionResult, CardsServer, ChangeAmountResult, ClaimCurrencyInput, ClaimResult, ClaimTransferInput, CompleteDeviceApprovalInput, CompleteDeviceApprovalResult, ConfirmDeviceEnrollmentInput, ConfirmDeviceEnrollmentResult, ConfirmPaymentResult, CreateCheckoutInput, CreateCheckoutResult, CreateSubscriptionInput, CurrencyPurchaseQuote, CurrencyPurchaseQuoteInput, DestinationsResult, DeviceApprovalGrant, DeviceApprovalPollResult, DeviceApprovalSettleResult, GetSubscriptionOptions, GetSubscriptionResult, GuardianApprovalStatusResult, InboundPendingQuery, InboundPendingResult, InitiateResult, InitiateSendInput, InitiateTransferInput, InvoError, InvoServer, type InvoWebhookEvent, ItemHistoryQuery, ItemHistoryResult, ItemOrderQuery, type ItemPurchasedData, LinkedIdentitiesQuery, LinkedIdentitiesResult, ListSubscriptionsOptions, LoyaltyCardsResult, MintPlayerTokenInput, OrderDetailsResult, PhoneShareApproveInput, PhoneShareApproveResult, PhoneShareContact, PhoneShareInitiateResult, PhoneShareStatusResult, type PlatformCommercePurchasedData, type PlatformCommerceRefundedData, PlatformCommerceServer, PlatformOrderStatusResult, PlatformPurchaseInput, PlatformPurchaseResult, PlatformRefundInput, PlatformRefundResult, PlayerBalanceQuery, PlayerBalanceResult, PlayerCardsResult, PlayerToken, PollDeviceApprovalInput, type PurchaseCompletedData, type PurchaseEventData, PurchaseInput, PurchaseItemInput, PurchaseItemResult, PurchaseResult, RefundResult, RefundSubscriptionInput, RegisterPlayerInput, RegisterPlayerResult, SDK_VERSION, SandboxClockResult, SandboxFailureOutcome, SandboxForceAuthChallengeOptions, SandboxForceFailureOptions, SandboxServer, SandboxSubscriptionsServer, ServerConfig, ServerDestinationsQuery, SetPaymentMethodInput, SetPaymentMethodResult, SmsVerifyResult, SteamFinalizeInput, SteamFinalizeResult, SteamFinalizeSubscriptionResult, SteamInitPurchaseInput, SteamInitPurchaseResult, SteamInitResult, SteamPacksQuery, SteamPacksResult, SteamSubscriptionInitInput, type SubscriptionAuthenticationRequiredData, type SubscriptionCanceledData, type SubscriptionEventCommon, type SubscriptionExpiredData, SubscriptionListResult, type SubscriptionPastDueData, type SubscriptionPaymentFailedData, type SubscriptionRefundApprovedData, type SubscriptionRefundDetail, type SubscriptionRefundRejectedData, type SubscriptionRefundRequestData, type SubscriptionRefundedData, type SubscriptionRenewalFunding, type SubscriptionRenewalSplit, type SubscriptionRenewedData, SubscriptionResult, type SubscriptionRevenueShareAttribution, type SubscriptionTrialEventFields, SubscriptionsServer, TransactionStatusResult, type TransferEventData, UpdatePlayerPhoneInput, UpdatePlayerPhoneResult, type VerifyWebhookOptions, type WebhookHandlerOptions, createWebhookHandler, verifyWebhook, verifyWebhookAsync };