@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/index.cjs CHANGED
@@ -819,9 +819,47 @@ var InvoError = class _InvoError extends Error {
819
819
  * The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
820
820
  * same reason; those two never create players, so create the member first (for
821
821
  * example with `createSetupSession` and a `playerName`, or a currency purchase).
822
+ * `getPlayerRewards` answers it when no player has that email in this game.
822
823
  */
823
824
  get isPlayerNotFound() {
824
- return this.code === "PLAYER_NOT_FOUND";
825
+ if (this.code === "PLAYER_NOT_FOUND") return true;
826
+ return this.status === 404 && this.bodyObject()["error"] === "player_not_found";
827
+ }
828
+ // ---- Player registration, phone changes, identity re-key ----
829
+ /**
830
+ * True when an approve was refused because the player token predates a change to the
831
+ * sender's identity (`PLAYER_TOKEN_STALE`, 403): their phone was added (for example on
832
+ * the initiate), which gives them a new identity. Nothing moved and the token stays
833
+ * refused. Re-mint the player token (or use the `playerToken` from the initiate result)
834
+ * and retry once. The SDK never retries a money call on its own.
835
+ */
836
+ get isPlayerTokenStale() {
837
+ return this.code === "PLAYER_TOKEN_STALE";
838
+ }
839
+ /**
840
+ * True when `updatePlayerPhone` was refused because the player has secured this account,
841
+ * so the change needs the player's own confirmation (`PHONE_CHANGE_REQUIRES_VERIFICATION`,
842
+ * 409). Nothing changed. Until that confirmation flow is available, contact INVO support.
843
+ */
844
+ get isPhoneChangeRequiresVerification() {
845
+ return this.code === "PHONE_CHANGE_REQUIRES_VERIFICATION";
846
+ }
847
+ /**
848
+ * True when `registerPlayer` found the player already in your game with a DIFFERENT
849
+ * phone (`PHONE_MISMATCH`, 409). Nothing changed; use `updatePlayerPhone` to change it.
850
+ * (`mintPlayerToken` reports the same situation as `phoneMismatch: true` on success.)
851
+ */
852
+ get isPhoneMismatch() {
853
+ return this.code === "PHONE_MISMATCH";
854
+ }
855
+ /**
856
+ * True when the phone you supplied belongs to another email
857
+ * (`PHONE_SHARE_APPROVAL_REQUIRED`, 409) on `mintPlayerToken`, `registerPlayer` or
858
+ * `updatePlayerPhone`. Nothing was created or changed. The same condition as
859
+ * {@link isPhoneShareApprovalRequired}, named for these registration calls.
860
+ */
861
+ get isPhoneShareRefused() {
862
+ return this.isPhoneShareApprovalRequired;
825
863
  }
826
864
  /**
827
865
  * True when `cards.createSetupSession` was asked to create a new member (`playerName`
@@ -833,7 +871,8 @@ var InvoError = class _InvoError extends Error {
833
871
  }
834
872
  /**
835
873
  * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
836
- * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
874
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400). `getPlayerRewards` answers it
875
+ * for an email that is not an email address (a blank one never leaves the SDK).
837
876
  */
838
877
  get isInvalidPlayerEmail() {
839
878
  return this.code === "INVALID_PLAYER_EMAIL";
@@ -884,6 +923,26 @@ var InvoError = class _InvoError extends Error {
884
923
  get isIdentityCheckUnavailable() {
885
924
  return this.code === "IDENTITY_CHECK_UNAVAILABLE";
886
925
  }
926
+ // ---- Loyalty rewards (InvoClient.redeemReward) ----
927
+ /** True when a reward was already redeemed and its code can no longer be shown (`already_redeemed`, 409). */
928
+ get isRewardAlreadyRedeemed() {
929
+ return this.code === "already_redeemed";
930
+ }
931
+ /** True when the player has no such reward (`vault_entry_not_found`, 404). */
932
+ get isRewardNotFound() {
933
+ return this.code === "vault_entry_not_found";
934
+ }
935
+ /**
936
+ * True when the reward cannot be redeemed right now (409): `inventory_exhausted` (no units or
937
+ * codes are left for it) or `conflict` (the reward is reserved or revoked).
938
+ */
939
+ get isRewardUnavailable() {
940
+ return this.code === "inventory_exhausted" || this.code === "conflict";
941
+ }
942
+ /** True when the reward expired before it was redeemed (`vault_entry_expired`, 410). */
943
+ get isRewardExpired() {
944
+ return this.code === "vault_entry_expired";
945
+ }
887
946
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
888
947
  get retryAfter() {
889
948
  const v = this.bodyObject()["retry_after"];
@@ -1902,7 +1961,125 @@ function nothingWasCharged(r) {
1902
1961
  return r.reasonCode !== null && NOTHING_CHARGED_REASONS.has(r.reasonCode);
1903
1962
  }
1904
1963
 
1964
+ // src/shared/loyalty.ts
1965
+ var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
1966
+ var rows = (v) => Array.isArray(v) ? v.filter((r) => r && typeof r === "object" && !Array.isArray(r)) : [];
1967
+ var str2 = (v) => v === void 0 || v === null ? "" : String(v);
1968
+ var strOrNull = (v) => v === void 0 || v === null ? null : String(v);
1969
+ var numOrNull = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
1970
+ var int = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
1971
+ var passThrough = (v) => v;
1972
+ function toLoyaltyStepProgress(value) {
1973
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;
1974
+ const v = value;
1975
+ const current = v["current"];
1976
+ const target = v["target"];
1977
+ if (!Number.isInteger(current) || !Number.isInteger(target)) return null;
1978
+ return { current, target };
1979
+ }
1980
+ function toStep(row) {
1981
+ return {
1982
+ stepId: strOrNull(row["step_id"]),
1983
+ index: int(row["index"]),
1984
+ action: str2(row["action"]),
1985
+ label: str2(row["label"]),
1986
+ summary: str2(row["summary"]),
1987
+ windowHours: numOrNull(row["window_hours"]),
1988
+ state: str2(row["state"]),
1989
+ progress: toLoyaltyStepProgress(row["progress"]),
1990
+ raw: row
1991
+ };
1992
+ }
1993
+ function toCardReward(row) {
1994
+ return {
1995
+ vaultEntryId: str2(row["vault_entry_id"]),
1996
+ rewardId: str2(row["reward_id"]),
1997
+ state: str2(row["state"]),
1998
+ unlockedAt: str2(row["unlocked_at"]),
1999
+ expiresAt: str2(row["expires_at"]),
2000
+ redeemedAt: strOrNull(row["redeemed_at"]),
2001
+ codeMasked: strOrNull(row["code_masked"]),
2002
+ canRedeem: row["can_redeem"] === true,
2003
+ canRevealAgain: row["can_reveal_again"] === true,
2004
+ revealUntil: strOrNull(row["reveal_until"]),
2005
+ raw: row
2006
+ };
2007
+ }
2008
+ function toLoyaltyCard(row) {
2009
+ const brand = obj(row["brand"]);
2010
+ const reward = obj(row["reward"]);
2011
+ const steps = rows(row["steps"]).map(toStep);
2012
+ return {
2013
+ cardVersion: passThrough(row["card_version"]),
2014
+ mode: str2(row["mode"]),
2015
+ programId: strOrNull(row["program_id"]),
2016
+ questId: strOrNull(row["quest_id"]),
2017
+ questVersion: numOrNull(row["quest_version"]),
2018
+ campaignId: strOrNull(row["campaign_id"]),
2019
+ title: str2(row["title"]),
2020
+ description: str2(row["description"]),
2021
+ brand: { name: strOrNull(brand["name"]), logoUrl: strOrNull(brand["logo_url"]) },
2022
+ artUrl: strOrNull(row["art_url"]),
2023
+ reward: { rewardId: strOrNull(reward["reward_id"]), name: strOrNull(reward["name"]) },
2024
+ orderMode: str2(row["order_mode"]),
2025
+ status: str2(row["status"]),
2026
+ startsAt: strOrNull(row["starts_at"]),
2027
+ endsAt: strOrNull(row["ends_at"]),
2028
+ completionHours: numOrNull(row["completion_hours"]),
2029
+ completionNote: strOrNull(row["completion_note"]),
2030
+ windowEndsAt: strOrNull(row["window_ends_at"]),
2031
+ completedAt: strOrNull(row["completed_at"]),
2032
+ stepsRequired: passThrough(row["steps_required"]),
2033
+ stepsComplete: passThrough(row["steps_complete"]),
2034
+ steps,
2035
+ rewards: rows(row["rewards"]).map(toCardReward),
2036
+ raw: row
2037
+ };
2038
+ }
2039
+ function toLoyaltyCardsResult(raw) {
2040
+ return {
2041
+ cardVersion: passThrough(raw["card_version"]),
2042
+ cards: rows(raw["cards"]).map(toLoyaltyCard),
2043
+ raw
2044
+ };
2045
+ }
2046
+ function toVaultEntry(row) {
2047
+ return {
2048
+ vaultEntryId: str2(row["vault_entry_id"]),
2049
+ rewardRef: str2(row["reward_ref"]),
2050
+ programId: str2(row["program_id"]),
2051
+ questId: strOrNull(row["quest_id"]),
2052
+ units: str2(row["units"]),
2053
+ state: str2(row["state"]),
2054
+ unlockedAt: strOrNull(row["unlocked_at"]),
2055
+ expiresAt: strOrNull(row["expires_at"]),
2056
+ redeemedAt: strOrNull(row["redeemed_at"]),
2057
+ codeMasked: strOrNull(row["code_masked"]),
2058
+ raw: row
2059
+ };
2060
+ }
2061
+ function toLoyaltyVaultResult(raw) {
2062
+ return { items: rows(raw["items"]).map(toVaultEntry), raw };
2063
+ }
2064
+ function toRedeemRewardResult(raw, vaultEntryId) {
2065
+ return {
2066
+ vaultEntryId: str2(raw["vault_entry_id"] ?? vaultEntryId),
2067
+ rewardRef: str2(raw["reward_ref"]),
2068
+ state: str2(raw["state"]),
2069
+ redeemedAt: strOrNull(raw["redeemed_at"]),
2070
+ code: strOrNull(raw["code"]),
2071
+ codeMasked: strOrNull(raw["code_masked"]),
2072
+ revealedAgain: raw["revealed_again"] === true,
2073
+ revealUntil: strOrNull(raw["reveal_until"]),
2074
+ raw
2075
+ };
2076
+ }
2077
+ function toRewardsPageLink(raw) {
2078
+ return { url: str2(raw["url"]), expiresAt: str2(raw["expires_at"]), raw };
2079
+ }
2080
+
1905
2081
  // src/index.ts
2082
+ var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
1906
2083
  function toPendingCollectItem(row) {
1907
2084
  return {
1908
2085
  transferId: String(row["transfer_id"] ?? ""),
@@ -1942,6 +2119,7 @@ function toApproveResult(raw, transactionId) {
1942
2119
  risk: raw["risk"],
1943
2120
  guardianApproval: raw["guardian_approval"] ?? void 0,
1944
2121
  pollEndpoint: raw["poll_endpoint"],
2122
+ ...typeof raw["claim_delivery"] === "string" && raw["claim_delivery"] ? { claimDelivery: raw["claim_delivery"] } : {},
1945
2123
  raw
1946
2124
  };
1947
2125
  }
@@ -2303,11 +2481,19 @@ var InvoClient = class {
2303
2481
  };
2304
2482
  return runHostedApproval(opts, api);
2305
2483
  }
2306
- /** Approve a SEND with the player's passkey. */
2484
+ /**
2485
+ * Approve a SEND with the player's passkey.
2486
+ *
2487
+ * Throws 403 `err.isPlayerTokenStale` when the player token predates a change to the
2488
+ * sender's identity (their phone was added on the initiate). Not retried automatically,
2489
+ * because this call moves money: re-mint the player token (or use the `playerToken`
2490
+ * your server got back from `initiateSend`) and retry once.
2491
+ */
2307
2492
  async approveSend(transactionId, opts) {
2308
2493
  return this.approve("send", transactionId, opts);
2309
2494
  }
2310
- /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
2495
+ /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). Same
2496
+ * `err.isPlayerTokenStale` handling as {@link approveSend}: re-mint and retry once. */
2311
2497
  async approveTransfer(transactionId, opts) {
2312
2498
  return this.approve("transfers", transactionId, opts);
2313
2499
  }
@@ -2379,8 +2565,8 @@ var InvoClient = class {
2379
2565
  "/api/sdk/transfers/pending",
2380
2566
  opts?.signal
2381
2567
  );
2382
- const rows = Array.isArray(raw["pending"]) ? raw["pending"] : [];
2383
- return { pending: rows.map(toPendingCollectItem), raw };
2568
+ const rows2 = Array.isArray(raw["pending"]) ? raw["pending"] : [];
2569
+ return { pending: rows2.map(toPendingCollectItem), raw };
2384
2570
  });
2385
2571
  }
2386
2572
  /**
@@ -2407,19 +2593,85 @@ var InvoClient = class {
2407
2593
  async getBalance(opts) {
2408
2594
  return this.withTokenRetry(async () => {
2409
2595
  const raw = await this.get("/api/sdk/balance", opts?.signal);
2410
- const rows = Array.isArray(raw["balances"]) ? raw["balances"] : [];
2596
+ const rows2 = Array.isArray(raw["balances"]) ? raw["balances"] : [];
2411
2597
  const summary = raw["summary"] ?? {};
2412
2598
  return {
2413
2599
  gameId: raw["game_id"] ?? "",
2414
2600
  gameName: String(raw["game_name"] ?? ""),
2415
- balances: rows.map(toBalanceRow),
2601
+ balances: rows2.map(toBalanceRow),
2416
2602
  totalValue: String(summary["total_value"] ?? "0"),
2417
- currencyCount: Number(summary["currency_count"] ?? rows.length),
2603
+ currencyCount: Number(summary["currency_count"] ?? rows2.length),
2418
2604
  hasFunds: summary["has_funds"] === true,
2419
2605
  raw
2420
2606
  };
2421
2607
  });
2422
2608
  }
2609
+ // ---- Loyalty and rewards (player token) ----
2610
+ /**
2611
+ * The signed-in player's loyalty cards in this game: one card per program, each step with
2612
+ * its `state` and `progress` (`{ current, target }`, or `null` when the number could not
2613
+ * be read this time: render `state` alone then), and the rewards the player unlocked.
2614
+ * A card never carries a code; a redeemed reward shows its mask. Your server reads the
2615
+ * same cards for any of your players with `InvoServer.getPlayerRewards(playerEmail)`.
2616
+ */
2617
+ async getMyRewards(opts) {
2618
+ return this.withTokenRetry(async () => {
2619
+ const raw = await this.get("/api/sdk/loyalty/me/card", opts?.signal);
2620
+ return toLoyaltyCardsResult(raw);
2621
+ });
2622
+ }
2623
+ /** Every reward the signed-in player holds or held, newest first. Codes are masked. */
2624
+ async getMyVault(opts) {
2625
+ return this.withTokenRetry(async () => {
2626
+ const raw = await this.get("/api/sdk/loyalty/me/vault", opts?.signal);
2627
+ return toLoyaltyVaultResult(raw);
2628
+ });
2629
+ }
2630
+ /**
2631
+ * Redeem one unlocked reward and return its code. This is the only response that
2632
+ * carries a code: show it straight away and never log, cache or store it. Calling again
2633
+ * for a reward this player already redeemed shows the code once more while the card's
2634
+ * `canRevealAgain` is true (`revealedAgain: true`). Never auto-retried.
2635
+ *
2636
+ * Refusals: `409 already_redeemed` (`err.isRewardAlreadyRedeemed`), `404
2637
+ * vault_entry_not_found` (`err.isRewardNotFound`), `410 vault_entry_expired`
2638
+ * (`err.isRewardExpired`), `409 inventory_exhausted` / `409 conflict`
2639
+ * (`err.isRewardUnavailable`: no units or codes left, or the reward is reserved or revoked).
2640
+ */
2641
+ async redeemReward(vaultEntryId, opts) {
2642
+ if (typeof vaultEntryId !== "string" || !UUID_RE.test(vaultEntryId.trim())) {
2643
+ throw new InvoError({
2644
+ message: `vaultEntryId must be a reward's vaultEntryId (got ${JSON.stringify(vaultEntryId)}).`,
2645
+ code: "INVALID_INPUT",
2646
+ status: 0
2647
+ });
2648
+ }
2649
+ const id = vaultEntryId.trim();
2650
+ return this.withTokenRetry(async () => {
2651
+ const raw = await this.post(
2652
+ `/api/sdk/loyalty/me/vault/${encodeURIComponent(id)}/redeem`,
2653
+ void 0,
2654
+ opts?.signal
2655
+ );
2656
+ return toRedeemRewardResult(raw, id);
2657
+ });
2658
+ }
2659
+ /**
2660
+ * A short-lived link to INVO's hosted "My rewards" page for the signed-in player: their
2661
+ * cards, progress and rewards, with a Redeem button. Open `url` in a browser or web view
2662
+ * (it cannot be embedded in an iframe). Ask for a fresh link each time the player opens
2663
+ * the page; never share or store it.
2664
+ */
2665
+ async getRewardsPageLink(opts) {
2666
+ return this.withTokenRetry(async () => {
2667
+ const raw = await this.post(
2668
+ "/api/sdk/loyalty/me/rewards-page",
2669
+ void 0,
2670
+ opts?.signal
2671
+ );
2672
+ return toRewardsPageLink(raw);
2673
+ });
2674
+ }
2423
2675
  /**
2424
2676
  * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
2425
2677
  * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CCqgVhzf.cjs';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CCqgVhzf.cjs';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, l as LoyaltyCardsResult, m as LoyaltyVaultResult, R as RedeemRewardResult, n as RewardsPageLink, E as EnrollmentBeginResult, o as EnrollmentVerifyResult, p as RecoveryBeginResult, q as RecoveryCompleteResult } from './types-BXcPz6Xw.cjs';
2
+ export { r as BalanceRow, s as CheckoutPurchaseStatus, t as ClaimDelivery, u as DestinationGame, I as InvoError, v as InvoErrorInfo, w as InvoHooks, x as InvoRequestInfo, y as InvoResponseInfo, z as LoyaltyCard, F as LoyaltyCardReward, G as LoyaltyCardStep, J as LoyaltyRewardState, K as LoyaltyStepProgress, N as LoyaltyStepState, O as LoyaltyVaultEntry, Q as PendingCollectItem, S as PurchaseRefusalReason, T as Rail, V as VerificationMethod } from './types-BXcPz6Xw.cjs';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
@@ -309,9 +309,17 @@ declare class InvoClient {
309
309
  flow: "send_receipt" | "transfer_receipt";
310
310
  }): Promise<ApproveHostedResult<ConfirmReceiptResult>>;
311
311
  approveHosted(opts: ApproveHostedOptions): Promise<ApproveHostedResult>;
312
- /** Approve a SEND with the player's passkey. */
312
+ /**
313
+ * Approve a SEND with the player's passkey.
314
+ *
315
+ * Throws 403 `err.isPlayerTokenStale` when the player token predates a change to the
316
+ * sender's identity (their phone was added on the initiate). Not retried automatically,
317
+ * because this call moves money: re-mint the player token (or use the `playerToken`
318
+ * your server got back from `initiateSend`) and retry once.
319
+ */
313
320
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
314
- /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
321
+ /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). Same
322
+ * `err.isPlayerTokenStale` handling as {@link approveSend}: re-mint and retry once. */
315
323
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
316
324
  /**
317
325
  * Recipient self-claims a SEND with their passkey.
@@ -362,6 +370,35 @@ declare class InvoClient {
362
370
  * throws. Rows include the currency symbol + icon URL (each may be null).
363
371
  */
364
372
  getBalance(opts?: CallOptions): Promise<BalanceResult>;
373
+ /**
374
+ * The signed-in player's loyalty cards in this game: one card per program, each step with
375
+ * its `state` and `progress` (`{ current, target }`, or `null` when the number could not
376
+ * be read this time: render `state` alone then), and the rewards the player unlocked.
377
+ * A card never carries a code; a redeemed reward shows its mask. Your server reads the
378
+ * same cards for any of your players with `InvoServer.getPlayerRewards(playerEmail)`.
379
+ */
380
+ getMyRewards(opts?: CallOptions): Promise<LoyaltyCardsResult>;
381
+ /** Every reward the signed-in player holds or held, newest first. Codes are masked. */
382
+ getMyVault(opts?: CallOptions): Promise<LoyaltyVaultResult>;
383
+ /**
384
+ * Redeem one unlocked reward and return its code. This is the only response that
385
+ * carries a code: show it straight away and never log, cache or store it. Calling again
386
+ * for a reward this player already redeemed shows the code once more while the card's
387
+ * `canRevealAgain` is true (`revealedAgain: true`). Never auto-retried.
388
+ *
389
+ * Refusals: `409 already_redeemed` (`err.isRewardAlreadyRedeemed`), `404
390
+ * vault_entry_not_found` (`err.isRewardNotFound`), `410 vault_entry_expired`
391
+ * (`err.isRewardExpired`), `409 inventory_exhausted` / `409 conflict`
392
+ * (`err.isRewardUnavailable`: no units or codes left, or the reward is reserved or revoked).
393
+ */
394
+ redeemReward(vaultEntryId: string, opts?: CallOptions): Promise<RedeemRewardResult>;
395
+ /**
396
+ * A short-lived link to INVO's hosted "My rewards" page for the signed-in player: their
397
+ * cards, progress and rewards, with a Redeem button. Open `url` in a browser or web view
398
+ * (it cannot be embedded in an iframe). Ask for a fresh link each time the player opens
399
+ * the page; never share or store it.
400
+ */
401
+ getRewardsPageLink(opts?: CallOptions): Promise<RewardsPageLink>;
365
402
  /**
366
403
  * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
367
404
  * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
@@ -424,4 +461,4 @@ declare class InvoClient {
424
461
  private confirmReceipt;
425
462
  }
426
463
 
427
- export { type ApproveHostedOptions, type ApproveHostedResult, ApproveResult, BalanceResult, CallOptions, CheckoutClient, CheckoutClientConfig, CheckoutMountHandle, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, type EnrollmentDecision, type EnrollmentRespond, EnrollmentVerifyResult, type HostedApprovalStatus, type HostedEnrollment, type HostedEnrollmentInput, type HostedFlow, InvoClient, LinkDeviceResult, MountCheckoutOptions, PendingCollectResult, PlatformCommerceClient, PurchaseCredited, PurchaseExpired, PurchaseRefunded, PurchaseRefused, PurchaseStatusInput, PurchaseStatusResult, RecoveryBeginResult, RecoveryCompleteResult, WaitForPurchaseInput, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, nothingWasCharged };
464
+ export { type ApproveHostedOptions, type ApproveHostedResult, ApproveResult, BalanceResult, CallOptions, CheckoutClient, CheckoutClientConfig, CheckoutMountHandle, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, type EnrollmentDecision, type EnrollmentRespond, EnrollmentVerifyResult, type HostedApprovalStatus, type HostedEnrollment, type HostedEnrollmentInput, type HostedFlow, InvoClient, LinkDeviceResult, LoyaltyCardsResult, LoyaltyVaultResult, MountCheckoutOptions, PendingCollectResult, PlatformCommerceClient, PurchaseCredited, PurchaseExpired, PurchaseRefunded, PurchaseRefused, PurchaseStatusInput, PurchaseStatusResult, RecoveryBeginResult, RecoveryCompleteResult, RedeemRewardResult, RewardsPageLink, WaitForPurchaseInput, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, nothingWasCharged };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CCqgVhzf.js';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CCqgVhzf.js';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, l as LoyaltyCardsResult, m as LoyaltyVaultResult, R as RedeemRewardResult, n as RewardsPageLink, E as EnrollmentBeginResult, o as EnrollmentVerifyResult, p as RecoveryBeginResult, q as RecoveryCompleteResult } from './types-BXcPz6Xw.js';
2
+ export { r as BalanceRow, s as CheckoutPurchaseStatus, t as ClaimDelivery, u as DestinationGame, I as InvoError, v as InvoErrorInfo, w as InvoHooks, x as InvoRequestInfo, y as InvoResponseInfo, z as LoyaltyCard, F as LoyaltyCardReward, G as LoyaltyCardStep, J as LoyaltyRewardState, K as LoyaltyStepProgress, N as LoyaltyStepState, O as LoyaltyVaultEntry, Q as PendingCollectItem, S as PurchaseRefusalReason, T as Rail, V as VerificationMethod } from './types-BXcPz6Xw.js';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
@@ -309,9 +309,17 @@ declare class InvoClient {
309
309
  flow: "send_receipt" | "transfer_receipt";
310
310
  }): Promise<ApproveHostedResult<ConfirmReceiptResult>>;
311
311
  approveHosted(opts: ApproveHostedOptions): Promise<ApproveHostedResult>;
312
- /** Approve a SEND with the player's passkey. */
312
+ /**
313
+ * Approve a SEND with the player's passkey.
314
+ *
315
+ * Throws 403 `err.isPlayerTokenStale` when the player token predates a change to the
316
+ * sender's identity (their phone was added on the initiate). Not retried automatically,
317
+ * because this call moves money: re-mint the player token (or use the `playerToken`
318
+ * your server got back from `initiateSend`) and retry once.
319
+ */
313
320
  approveSend(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
314
- /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
321
+ /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). Same
322
+ * `err.isPlayerTokenStale` handling as {@link approveSend}: re-mint and retry once. */
315
323
  approveTransfer(transactionId: string, opts?: CallOptions): Promise<ApproveResult>;
316
324
  /**
317
325
  * Recipient self-claims a SEND with their passkey.
@@ -362,6 +370,35 @@ declare class InvoClient {
362
370
  * throws. Rows include the currency symbol + icon URL (each may be null).
363
371
  */
364
372
  getBalance(opts?: CallOptions): Promise<BalanceResult>;
373
+ /**
374
+ * The signed-in player's loyalty cards in this game: one card per program, each step with
375
+ * its `state` and `progress` (`{ current, target }`, or `null` when the number could not
376
+ * be read this time: render `state` alone then), and the rewards the player unlocked.
377
+ * A card never carries a code; a redeemed reward shows its mask. Your server reads the
378
+ * same cards for any of your players with `InvoServer.getPlayerRewards(playerEmail)`.
379
+ */
380
+ getMyRewards(opts?: CallOptions): Promise<LoyaltyCardsResult>;
381
+ /** Every reward the signed-in player holds or held, newest first. Codes are masked. */
382
+ getMyVault(opts?: CallOptions): Promise<LoyaltyVaultResult>;
383
+ /**
384
+ * Redeem one unlocked reward and return its code. This is the only response that
385
+ * carries a code: show it straight away and never log, cache or store it. Calling again
386
+ * for a reward this player already redeemed shows the code once more while the card's
387
+ * `canRevealAgain` is true (`revealedAgain: true`). Never auto-retried.
388
+ *
389
+ * Refusals: `409 already_redeemed` (`err.isRewardAlreadyRedeemed`), `404
390
+ * vault_entry_not_found` (`err.isRewardNotFound`), `410 vault_entry_expired`
391
+ * (`err.isRewardExpired`), `409 inventory_exhausted` / `409 conflict`
392
+ * (`err.isRewardUnavailable`: no units or codes left, or the reward is reserved or revoked).
393
+ */
394
+ redeemReward(vaultEntryId: string, opts?: CallOptions): Promise<RedeemRewardResult>;
395
+ /**
396
+ * A short-lived link to INVO's hosted "My rewards" page for the signed-in player: their
397
+ * cards, progress and rewards, with a Redeem button. Open `url` in a browser or web view
398
+ * (it cannot be embedded in an iframe). Ask for a fresh link each time the player opens
399
+ * the page; never share or store it.
400
+ */
401
+ getRewardsPageLink(opts?: CallOptions): Promise<RewardsPageLink>;
365
402
  /**
366
403
  * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
367
404
  * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call
@@ -424,4 +461,4 @@ declare class InvoClient {
424
461
  private confirmReceipt;
425
462
  }
426
463
 
427
- export { type ApproveHostedOptions, type ApproveHostedResult, ApproveResult, BalanceResult, CallOptions, CheckoutClient, CheckoutClientConfig, CheckoutMountHandle, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, type EnrollmentDecision, type EnrollmentRespond, EnrollmentVerifyResult, type HostedApprovalStatus, type HostedEnrollment, type HostedEnrollmentInput, type HostedFlow, InvoClient, LinkDeviceResult, MountCheckoutOptions, PendingCollectResult, PlatformCommerceClient, PurchaseCredited, PurchaseExpired, PurchaseRefunded, PurchaseRefused, PurchaseStatusInput, PurchaseStatusResult, RecoveryBeginResult, RecoveryCompleteResult, WaitForPurchaseInput, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, nothingWasCharged };
464
+ export { type ApproveHostedOptions, type ApproveHostedResult, ApproveResult, BalanceResult, CallOptions, CheckoutClient, CheckoutClientConfig, CheckoutMountHandle, ClientConfig, ConfirmReceiptResult, DestinationsQuery, DestinationsResult, EnrollmentBeginResult, type EnrollmentDecision, type EnrollmentRespond, EnrollmentVerifyResult, type HostedApprovalStatus, type HostedEnrollment, type HostedEnrollmentInput, type HostedFlow, InvoClient, LinkDeviceResult, LoyaltyCardsResult, LoyaltyVaultResult, MountCheckoutOptions, PendingCollectResult, PlatformCommerceClient, PurchaseCredited, PurchaseExpired, PurchaseRefunded, PurchaseRefused, PurchaseStatusInput, PurchaseStatusResult, RecoveryBeginResult, RecoveryCompleteResult, RedeemRewardResult, RewardsPageLink, WaitForPurchaseInput, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, nothingWasCharged };
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, receiptFields } from './chunk-YW2PYARQ.js';
2
- export { InvoError } from './chunk-YW2PYARQ.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, receiptFields } from './chunk-7L4O5Q7K.js';
2
+ export { InvoError } from './chunk-7L4O5Q7K.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {
@@ -730,6 +730,7 @@ function nothingWasCharged(r) {
730
730
  }
731
731
 
732
732
  // src/index.ts
733
+ var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
733
734
  function toPendingCollectItem(row) {
734
735
  return {
735
736
  transferId: String(row["transfer_id"] ?? ""),
@@ -769,6 +770,7 @@ function toApproveResult(raw, transactionId) {
769
770
  risk: raw["risk"],
770
771
  guardianApproval: raw["guardian_approval"] ?? void 0,
771
772
  pollEndpoint: raw["poll_endpoint"],
773
+ ...typeof raw["claim_delivery"] === "string" && raw["claim_delivery"] ? { claimDelivery: raw["claim_delivery"] } : {},
772
774
  raw
773
775
  };
774
776
  }
@@ -1130,11 +1132,19 @@ var InvoClient = class {
1130
1132
  };
1131
1133
  return runHostedApproval(opts, api);
1132
1134
  }
1133
- /** Approve a SEND with the player's passkey. */
1135
+ /**
1136
+ * Approve a SEND with the player's passkey.
1137
+ *
1138
+ * Throws 403 `err.isPlayerTokenStale` when the player token predates a change to the
1139
+ * sender's identity (their phone was added on the initiate). Not retried automatically,
1140
+ * because this call moves money: re-mint the player token (or use the `playerToken`
1141
+ * your server got back from `initiateSend`) and retry once.
1142
+ */
1134
1143
  async approveSend(transactionId, opts) {
1135
1144
  return this.approve("send", transactionId, opts);
1136
1145
  }
1137
- /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). */
1146
+ /** Approve a TRANSFER with the player's passkey (returns the sender's claim code). Same
1147
+ * `err.isPlayerTokenStale` handling as {@link approveSend}: re-mint and retry once. */
1138
1148
  async approveTransfer(transactionId, opts) {
1139
1149
  return this.approve("transfers", transactionId, opts);
1140
1150
  }
@@ -1247,6 +1257,72 @@ var InvoClient = class {
1247
1257
  };
1248
1258
  });
1249
1259
  }
1260
+ // ---- Loyalty and rewards (player token) ----
1261
+ /**
1262
+ * The signed-in player's loyalty cards in this game: one card per program, each step with
1263
+ * its `state` and `progress` (`{ current, target }`, or `null` when the number could not
1264
+ * be read this time: render `state` alone then), and the rewards the player unlocked.
1265
+ * A card never carries a code; a redeemed reward shows its mask. Your server reads the
1266
+ * same cards for any of your players with `InvoServer.getPlayerRewards(playerEmail)`.
1267
+ */
1268
+ async getMyRewards(opts) {
1269
+ return this.withTokenRetry(async () => {
1270
+ const raw = await this.get("/api/sdk/loyalty/me/card", opts?.signal);
1271
+ return toLoyaltyCardsResult(raw);
1272
+ });
1273
+ }
1274
+ /** Every reward the signed-in player holds or held, newest first. Codes are masked. */
1275
+ async getMyVault(opts) {
1276
+ return this.withTokenRetry(async () => {
1277
+ const raw = await this.get("/api/sdk/loyalty/me/vault", opts?.signal);
1278
+ return toLoyaltyVaultResult(raw);
1279
+ });
1280
+ }
1281
+ /**
1282
+ * Redeem one unlocked reward and return its code. This is the only response that
1283
+ * carries a code: show it straight away and never log, cache or store it. Calling again
1284
+ * for a reward this player already redeemed shows the code once more while the card's
1285
+ * `canRevealAgain` is true (`revealedAgain: true`). Never auto-retried.
1286
+ *
1287
+ * Refusals: `409 already_redeemed` (`err.isRewardAlreadyRedeemed`), `404
1288
+ * vault_entry_not_found` (`err.isRewardNotFound`), `410 vault_entry_expired`
1289
+ * (`err.isRewardExpired`), `409 inventory_exhausted` / `409 conflict`
1290
+ * (`err.isRewardUnavailable`: no units or codes left, or the reward is reserved or revoked).
1291
+ */
1292
+ async redeemReward(vaultEntryId, opts) {
1293
+ if (typeof vaultEntryId !== "string" || !UUID_RE.test(vaultEntryId.trim())) {
1294
+ throw new InvoError({
1295
+ message: `vaultEntryId must be a reward's vaultEntryId (got ${JSON.stringify(vaultEntryId)}).`,
1296
+ code: "INVALID_INPUT",
1297
+ status: 0
1298
+ });
1299
+ }
1300
+ const id = vaultEntryId.trim();
1301
+ return this.withTokenRetry(async () => {
1302
+ const raw = await this.post(
1303
+ `/api/sdk/loyalty/me/vault/${encodeURIComponent(id)}/redeem`,
1304
+ void 0,
1305
+ opts?.signal
1306
+ );
1307
+ return toRedeemRewardResult(raw, id);
1308
+ });
1309
+ }
1310
+ /**
1311
+ * A short-lived link to INVO's hosted "My rewards" page for the signed-in player: their
1312
+ * cards, progress and rewards, with a Redeem button. Open `url` in a browser or web view
1313
+ * (it cannot be embedded in an iframe). Ask for a fresh link each time the player opens
1314
+ * the page; never share or store it.
1315
+ */
1316
+ async getRewardsPageLink(opts) {
1317
+ return this.withTokenRetry(async () => {
1318
+ const raw = await this.post(
1319
+ "/api/sdk/loyalty/me/rewards-page",
1320
+ void 0,
1321
+ opts?.signal
1322
+ );
1323
+ return toRewardsPageLink(raw);
1324
+ });
1325
+ }
1250
1326
  /**
1251
1327
  * First-enrollment OTP grant (§4.2). When `enrollPasskey()` throws
1252
1328
  * `ENROLLMENT_REQUIRES_AUTHORIZATION` (`err.isEnrollmentAuthorizationRequired`), call