@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/CHANGELOG.md +32 -0
- package/README.md +168 -14
- package/dist/{chunk-YW2PYARQ.js → chunk-7L4O5Q7K.js} +181 -5
- package/dist/index.cjs +261 -9
- package/dist/index.d.cts +42 -5
- package/dist/index.d.ts +42 -5
- package/dist/index.js +80 -4
- package/dist/server.cjs +297 -25
- package/dist/server.d.cts +64 -19
- package/dist/server.d.ts +64 -19
- package/dist/server.js +146 -16
- package/dist/{types-CCqgVhzf.d.cts → types-BXcPz6Xw.d.cts} +272 -2
- package/dist/{types-CCqgVhzf.d.ts → types-BXcPz6Xw.d.ts} +272 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.21.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 0238b53: Player registration, phone changes and identity re-key. Server: `mintPlayerToken` takes optional
|
|
8
|
+
`playerPhone` and `playerName`; with a phone, a player new to your title is created, and the
|
|
9
|
+
result now carries `created` and `phoneMismatch` (previously dropped). New
|
|
10
|
+
`registerPlayer({ playerEmail, playerPhone, playerName? })` (`POST /api/sdk/players`) and
|
|
11
|
+
`updatePlayerPhone({ playerEmail, newPhone })` (`POST /api/sdk/players/phone`, never
|
|
12
|
+
auto-retried). `initiateSend` / `initiateTransfer` results expose `identityRekeyed`,
|
|
13
|
+
`playerToken`, `playerTokenExpiresAt`, `identityId` and `claimDeliveryPlanned`; approve results
|
|
14
|
+
expose `claimDelivery`. New error predicates `isPlayerTokenStale`,
|
|
15
|
+
`isPhoneChangeRequiresVerification`, `isPhoneMismatch`, `isPhoneShareRefused`;
|
|
16
|
+
`isPlayerNotFound` also recognises the codeless `player_not_found` 404. A 403
|
|
17
|
+
`PLAYER_TOKEN_STALE` on approve is surfaced, never auto-retried: re-mint and retry once.
|
|
18
|
+
Additive only. README section "Registering players and changing their phone".
|
|
19
|
+
|
|
20
|
+
## 3.20.0
|
|
21
|
+
|
|
22
|
+
### Minor Changes
|
|
23
|
+
|
|
24
|
+
- 1dc07df: Loyalty and rewards. Server: `InvoServer.getPlayerRewards(playerEmail)` reads one player's
|
|
25
|
+
loyalty cards with the game secret (`GET /api/sdk/loyalty/players/rewards`). Browser, with the
|
|
26
|
+
player token: `InvoClient.getMyRewards()` (the player's cards), `getMyVault()`,
|
|
27
|
+
`redeemReward(vaultEntryId)` (the only response with a code; never auto-retried) and
|
|
28
|
+
`getRewardsPageLink()` (INVO's hosted "My rewards" page). Every card step carries `progress`,
|
|
29
|
+
`{ current, target }`, or `null` when unavailable; `state` decides completion. New error
|
|
30
|
+
predicates `isRewardAlreadyRedeemed`, `isRewardNotFound`, `isRewardExpired`,
|
|
31
|
+
`isRewardUnavailable` (`inventory_exhausted` / `conflict`); the server read's
|
|
32
|
+
`PLAYER_NOT_FOUND` and `INVALID_PLAYER_EMAIL` use the existing `isPlayerNotFound` and
|
|
33
|
+
`isInvalidPlayerEmail`. Additive only. README section "Loyalty and rewards".
|
|
34
|
+
|
|
3
35
|
## 3.19.0
|
|
4
36
|
|
|
5
37
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -93,6 +93,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
93
93
|
- [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
|
|
94
94
|
- [Install](#install)
|
|
95
95
|
- [Architecture & the two entry points](#architecture--the-two-entry-points)
|
|
96
|
+
- [Registering players and changing their phone](#registering-players-and-changing-their-phone)
|
|
96
97
|
- [Before you go live](#before-you-go-live)
|
|
97
98
|
- [Configuration](#configuration)
|
|
98
99
|
- [Tiers](#tiers)
|
|
@@ -117,6 +118,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
117
118
|
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
118
119
|
- [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
|
|
119
120
|
- [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
|
|
121
|
+
- [Loyalty and rewards](#loyalty-and-rewards)
|
|
120
122
|
- [Webhooks](#webhooks)
|
|
121
123
|
- [Resilience & observability](#resilience--observability)
|
|
122
124
|
- [Errors](#errors)
|
|
@@ -172,28 +174,86 @@ Build and test against the **dev console + sandbox** first, then switch to the *
|
|
|
172
174
|
|
|
173
175
|
### Player token (session mint for an existing player)
|
|
174
176
|
|
|
175
|
-
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player
|
|
176
|
-
**already exists**
|
|
177
|
-
|
|
178
|
-
such player exists). It only needs `playerEmail`:
|
|
177
|
+
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player. For a
|
|
178
|
+
player who **already exists** in your title it looks them up by `playerEmail` and returns a
|
|
179
|
+
token for their identity; it only needs `playerEmail`:
|
|
179
180
|
|
|
180
181
|
```ts
|
|
181
182
|
// your backend
|
|
182
183
|
const { token } = await invo.mintPlayerToken({ playerEmail: "player@example.com" });
|
|
183
184
|
```
|
|
184
185
|
|
|
185
|
-
|
|
186
|
-
|
|
186
|
+
For a player who is **not in your title yet**, the answer depends on `playerPhone`:
|
|
187
|
+
|
|
188
|
+
- without `playerPhone`: `404`, `err.isPlayerNotFound` (unchanged behaviour);
|
|
189
|
+
- with `playerPhone` (E.164) and optionally `playerName`: INVO **creates** the player and
|
|
190
|
+
the result carries `created: true`. A first-time receiver can then collect in-game without
|
|
191
|
+
buying first.
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
const t = await invo.mintPlayerToken({
|
|
195
|
+
playerEmail: "player@example.com",
|
|
196
|
+
playerPhone: "+15555550100",
|
|
197
|
+
playerName: "Pat",
|
|
198
|
+
});
|
|
199
|
+
if (t.created) { /* the player was new to your title */ }
|
|
200
|
+
if (t.phoneMismatch) { /* they exist with a different phone; see updatePlayerPhone */ }
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
An existing player's phone is **never changed** by this call. When it differs from the
|
|
204
|
+
`playerPhone` you passed, the token is still minted for that player and the result carries
|
|
205
|
+
`phoneMismatch: true`. A phone that already belongs to another email is a `409`
|
|
206
|
+
(`err.isPhoneShareRefused`).
|
|
187
207
|
|
|
188
208
|
**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
|
|
189
|
-
money routing keys off it
|
|
209
|
+
money routing keys off it:
|
|
190
210
|
|
|
191
211
|
- **`initiateSend` / `initiateTransfer`** require the **sender's** phone (E.164), and take the
|
|
192
|
-
**recipient's** phone. You can send by the recipient's **phone alone
|
|
212
|
+
**recipient's** phone. You can send by the recipient's **phone alone**; they supply their
|
|
193
213
|
email when they claim.
|
|
194
214
|
- An account with no phone can't receive cross-game money and can't take part in the
|
|
195
|
-
account-linking consent
|
|
196
|
-
(
|
|
215
|
+
account-linking consent, so make sure players have a phone at **creation / enrollment**
|
|
216
|
+
(`registerPlayer`, or `mintPlayerToken` with `playerPhone`), before they transact.
|
|
217
|
+
|
|
218
|
+
### Registering players and changing their phone
|
|
219
|
+
|
|
220
|
+
Two server calls, both authenticated with your game secret, neither moves money nor sends the
|
|
221
|
+
player a message.
|
|
222
|
+
|
|
223
|
+
**`registerPlayer({ playerEmail, playerPhone, playerName? })`** creates the player in your
|
|
224
|
+
title. It returns `status: "created"` (new) or `status: "exists"` (already in your title with
|
|
225
|
+
that phone), the `identityId`, and a `playerToken` / `playerTokenExpiresAt` when INVO can issue
|
|
226
|
+
one for your title, so you can hand the browser a token straight away.
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
const reg = await invo.registerPlayer({
|
|
230
|
+
playerEmail: "player@example.com",
|
|
231
|
+
playerPhone: "+15555550100",
|
|
232
|
+
playerName: "Pat",
|
|
233
|
+
});
|
|
234
|
+
// reg.status: "created" | "exists"; reg.playerToken may be present
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
**`updatePlayerPhone({ playerEmail, newPhone })`** sets the phone of a player already in your
|
|
238
|
+
title. It returns `status: "updated"` or `status: "unchanged"`, and `identityRekeyed`. A phone
|
|
239
|
+
change can give the player a **new INVO identity**: when `identityRekeyed` is `true`, every
|
|
240
|
+
player token minted before the change is out of date, so use the `playerToken` in the result
|
|
241
|
+
(or mint a new one). This call is never retried automatically.
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
const upd = await invo.updatePlayerPhone({ playerEmail: "player@example.com", newPhone: "+15555550111" });
|
|
245
|
+
if (upd.identityRekeyed && upd.playerToken) handTokenToBrowser(upd.playerToken);
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
| Refusal | HTTP | Means | Do |
|
|
249
|
+
|---|---|---|---|
|
|
250
|
+
| `err.isPhoneMismatch` (`PHONE_MISMATCH`) | 409 | `registerPlayer`: the player is already in your title with a **different** phone. Nothing changed. | Call `updatePlayerPhone` if the change is genuine. |
|
|
251
|
+
| `err.isPhoneShareRefused` (`PHONE_SHARE_APPROVAL_REQUIRED`) | 409 | The phone belongs to another email. Nothing was created or changed. Same code as `err.isPhoneShareApprovalRequired`. | Show `err.message`; ask the player to check the number. |
|
|
252
|
+
| `err.isPhoneChangeRequiresVerification` (`PHONE_CHANGE_REQUIRES_VERIFICATION`) | 409 | `updatePlayerPhone`: the player has secured this account, so the change needs the player's own confirmation. Nothing changed. | Until that flow is available, contact INVO support to change it. |
|
|
253
|
+
| `err.isPlayerNotFound` | 404 | `updatePlayerPhone` (or `mintPlayerToken` without `playerPhone`): no player with that email in your title. | Create the player first (`registerPlayer`). |
|
|
254
|
+
| `INVALID_INPUT` / `INVALID_PHONE` | 400 | A missing email or phone, or a phone INVO does not accept. | Fix the input. The SDK also refuses a non-E.164 phone before the network (`status === 0`). |
|
|
255
|
+
| rate limited | 429 | Too many registrations or phone changes for this player. | Back off by `err.retryAfter`. |
|
|
256
|
+
| `PHONE_UPDATE_UNAVAILABLE` | 503 | `updatePlayerPhone` could not be checked right now. Nothing changed. | Try again shortly. |
|
|
197
257
|
|
|
198
258
|
### Token bootstrap (both modes)
|
|
199
259
|
|
|
@@ -1586,6 +1646,7 @@ the same one: a grant approved for `transfer` settles nothing else.
|
|
|
1586
1646
|
| `TRANSACTION_NOT_PENDING` | 400 | The transaction is not at this step. Three different situations: your earlier attempt **already landed**; the transaction is **dead** (expired / refunded); or — on a receipt flow — it has **not got here yet**, because the sender's own approval is still pending or held at a guardian. | **Not thrown by `approveWithDeviceCode`** — it comes back as `{ status: "not_pending", alreadySettled, currentStatus }`. `alreadySettled` separates the first case from the other two. When it is `false`, go read `getTransferStatus` / `getSendStatus` rather than assuming; never retry-loop. |
|
|
1587
1647
|
| `DEVICE_APPROVAL_NOT_APPROVED` | 400 | The `device_code` was unknown, another player's, bound to a different transaction, bound to a different **flow**, or the player has not approved yet. One answer for all five, deliberately — distinguishing them would leak which transactions have a live approval. | `err.isDeviceApprovalNotApproved`. Check the `flow` matches the `begin`, and that the poll actually said `approved`. |
|
|
1588
1648
|
| `DEVICE_APPROVAL_ALREADY_PENDING` | 409 | An **approved** grant for this transaction and flow is still inside its window. The player already approved. | `err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`. You are missing stage 4, not a new code — call `approveWithDeviceCode` with the code you have. (A merely *pending* earlier grant does **not** 409; `begin` supersedes it.) |
|
|
1649
|
+
| `PLAYER_TOKEN_STALE` | 403 | The player token predates a change to the sender's identity: their phone was added (often on this very initiate), which gives them a new identity. Nothing moved; the old token stays refused. | `err.isPlayerTokenStale`. The SDK does not retry money calls itself: re-mint the player token (or use `playerToken` from the initiate result, present when `identityRekeyed` is `true`) and retry the approve **once**. |
|
|
1589
1650
|
| `PASSKEY_RECOVERY_COOLDOWN` | 403 | Money **out** is paused for 24 h after a passkey recovery (SIM-swap protection). Receiving and collecting are unaffected. | `err.isPasskeyRecoveryCooldown`, `err.retryAfterAt` (ISO; the body also carries `retry_after_seconds`). Expect a fresh initiate later — do not retry-loop. |
|
|
1590
1651
|
| `SEND_APPROVE_FAILED`, `TRANSFER_APPROVE_FAILED`, `CONFIRM_RECEIPT_FAILED` | 400 | A **fault** on INVO's side, not a rule. `err.isSettleFault`; the body carries **`error_ref`** (`err.errorRef`). | Never retryable. See the ambiguity note below — do **not** tell the player it failed until you have read the transaction. Quote `errorRef` to INVO support; it names the exact server log line. |
|
|
1591
1652
|
| guardian hold | 202 | A minor's transaction is waiting on a guardian. **The money is held, not refused.** | Returned as a result with `holdReason`; poll `getGuardianApprovalStatus`. Terminal outcomes (`GUARDIAN_APPROVAL_REJECTED` / `_EXPIRED`) throw as 410. |
|
|
@@ -2126,6 +2187,90 @@ const done = await server.completeDeviceApproval({
|
|
|
2126
2187
|
|
|
2127
2188
|
---
|
|
2128
2189
|
|
|
2190
|
+
## Loyalty and rewards
|
|
2191
|
+
|
|
2192
|
+
Show a player their loyalty programs, how far they are through each step, and the rewards they
|
|
2193
|
+
unlocked. Programs are built in the INVO console; the SDK only reads them and redeems rewards.
|
|
2194
|
+
Currency steps (purchases, transfers, sends, item spends, subscriptions) count on their own.
|
|
2195
|
+
|
|
2196
|
+
**Browser (player token).** The token names the player; no email or id is sent.
|
|
2197
|
+
|
|
2198
|
+
```ts
|
|
2199
|
+
import { InvoClient } from "@invonetwork/web-sdk";
|
|
2200
|
+
|
|
2201
|
+
const invo = new InvoClient({ token: playerToken, baseUrl: "https://invo.network" });
|
|
2202
|
+
|
|
2203
|
+
const { cards } = await invo.getMyRewards(); // GET /api/sdk/loyalty/me/card
|
|
2204
|
+
for (const card of cards) {
|
|
2205
|
+
console.log(card.title, `${card.stepsComplete} of ${card.stepsRequired} steps`);
|
|
2206
|
+
for (const step of card.steps) {
|
|
2207
|
+
const label =
|
|
2208
|
+
step.state === "complete" ? "Done"
|
|
2209
|
+
: step.state === "locked" ? "Locked"
|
|
2210
|
+
: step.progress ? `${step.progress.current} / ${step.progress.target}` // "3 / 5"
|
|
2211
|
+
: "Open";
|
|
2212
|
+
console.log(step.summary, label);
|
|
2213
|
+
}
|
|
2214
|
+
}
|
|
2215
|
+
|
|
2216
|
+
const { items } = await invo.getMyVault(); // every reward the player holds or held, newest first
|
|
2217
|
+
const redeemed = await invo.redeemReward(items[0].vaultEntryId);
|
|
2218
|
+
showToPlayer(redeemed.code); // the ONLY place a code appears: never log, cache or store it
|
|
2219
|
+
|
|
2220
|
+
const { url } = await invo.getRewardsPageLink(); // INVO's hosted "My rewards" page, short-lived
|
|
2221
|
+
window.open(url);
|
|
2222
|
+
```
|
|
2223
|
+
|
|
2224
|
+
**Server (game secret).** Read the same cards for any of your players by email, for example to
|
|
2225
|
+
render loyalty UI server-side or send your own "2 matches to go" notification:
|
|
2226
|
+
|
|
2227
|
+
```ts
|
|
2228
|
+
import { InvoServer } from "@invonetwork/web-sdk/server";
|
|
2229
|
+
|
|
2230
|
+
const server = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET!, baseUrl: "https://invo.network" });
|
|
2231
|
+
const { cards } = await server.getPlayerRewards("player@example.com");
|
|
2232
|
+
```
|
|
2233
|
+
|
|
2234
|
+
`getPlayerRewards` takes the game's server secret only. Never ship the secret in a game client;
|
|
2235
|
+
the client uses `getMyRewards()` with the player token instead.
|
|
2236
|
+
|
|
2237
|
+
**Reading a card.**
|
|
2238
|
+
|
|
2239
|
+
- `step.state` is the authority on whether a step is done: `complete`, `open` (the player can
|
|
2240
|
+
work on it now) or `locked` (in an ordered program, a step after the first unfinished one).
|
|
2241
|
+
- `step.progress` is `{ current, target }` on a live card. `target` is the step's count (1
|
|
2242
|
+
unless the program set one), and `current` reaches `target` only when `state` is `complete`.
|
|
2243
|
+
It is `null` in a preview and when the number could not be read this time: render `state`
|
|
2244
|
+
alone then. Do not recompute progress yourself.
|
|
2245
|
+
- `card.status` is `available`, `in_progress`, `completed`, `expired` or `in_review`.
|
|
2246
|
+
- A card never carries a code. A redeemed reward shows `codeMasked` (for example `••••ABCD`).
|
|
2247
|
+
`redeemReward` returns the code; calling it again for a reward the player already redeemed
|
|
2248
|
+
shows the code once more while the card's `canRevealAgain` is true (`revealedAgain: true`).
|
|
2249
|
+
- Mint a fresh rewards page link each time the player opens the page; never share or store it.
|
|
2250
|
+
The page cannot be embedded in an iframe.
|
|
2251
|
+
|
|
2252
|
+
**Errors.**
|
|
2253
|
+
|
|
2254
|
+
| Call | Status | `err.code` | Predicate |
|
|
2255
|
+
|---|---|---|---|
|
|
2256
|
+
| `getPlayerRewards` | 400 | `INVALID_PLAYER_EMAIL` | `err.isInvalidPlayerEmail` |
|
|
2257
|
+
| `getPlayerRewards` | 401 | `INVALID_GAME_SECRET` (missing or wrong key, or a per-channel key: this read takes the server secret only) | |
|
|
2258
|
+
| `getPlayerRewards` | 404 | `PLAYER_NOT_FOUND` (no player with this email in this game) | `err.isPlayerNotFound` |
|
|
2259
|
+
| any | 429 | (do not match on a code) | treat any 429 as retryable after a pause; `err.retryAfter` (reads are retried automatically first) |
|
|
2260
|
+
| `redeemReward` | 409 | `already_redeemed` | `err.isRewardAlreadyRedeemed` |
|
|
2261
|
+
| `redeemReward` | 404 | `vault_entry_not_found` | `err.isRewardNotFound` |
|
|
2262
|
+
| `redeemReward` | 410 | `vault_entry_expired` | `err.isRewardExpired` |
|
|
2263
|
+
| `redeemReward` | 409 | `inventory_exhausted` (no units or codes left for this reward) | `err.isRewardUnavailable` |
|
|
2264
|
+
| `redeemReward` | 409 | `conflict` (the reward is reserved or revoked) | `err.isRewardUnavailable` |
|
|
2265
|
+
| `getPlayerRewards` | 409 | `NO_TENANT` (the game is not set up for loyalty) | |
|
|
2266
|
+
| any | 503 | temporarily unavailable | retry later |
|
|
2267
|
+
| any | 502 / 504 | the loyalty service could not be reached, or timed out | retry later |
|
|
2268
|
+
|
|
2269
|
+
A blank email, or a `vaultEntryId` that is not a reward's id, throws `INVALID_INPUT` (status 0)
|
|
2270
|
+
before the network. `redeemReward` is never auto-retried.
|
|
2271
|
+
|
|
2272
|
+
---
|
|
2273
|
+
|
|
2129
2274
|
## Webhooks
|
|
2130
2275
|
|
|
2131
2276
|
The synchronous responses are for UX; **reconcile and grant value off webhooks.** They're HMAC-signed; **dedupe on the `X-Invo-Idempotency-Key` header** (stable across retries/replays — *not* `X-Invo-Event-Id`, which changes per delivery).
|
|
@@ -2285,6 +2430,8 @@ Helpers:
|
|
|
2285
2430
|
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
2286
2431
|
| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
|
|
2287
2432
|
| `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
|
|
2433
|
+
| `.isPhoneShareRefused` / `.isPhoneMismatch` / `.isPhoneChangeRequiresVerification` | `mintPlayerToken` / `registerPlayer` / `updatePlayerPhone` refusals (409); see [Registering players and changing their phone](#registering-players-and-changing-their-phone) |
|
|
2434
|
+
| `.isPlayerTokenStale` | approve refused (403 `PLAYER_TOKEN_STALE`): the token predates the sender's phone being added. Re-mint (or use the initiate's `playerToken`) and retry once; never auto-retried |
|
|
2288
2435
|
| `.isSteamValueNonTransferable` | initiate blocked (409): would move more than the non-Steam balance to a non-Steam destination → show `.message`, cap input at `.steamTransferableMax` (`.steamOriginAmount` = Steam-locked portion) |
|
|
2289
2436
|
| `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
|
|
2290
2437
|
| `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
|
|
@@ -2314,9 +2461,11 @@ try {
|
|
|
2314
2461
|
|
|
2315
2462
|
| Method | Returns |
|
|
2316
2463
|
|---|---|
|
|
2317
|
-
| `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }
|
|
2318
|
-
| `
|
|
2319
|
-
| `
|
|
2464
|
+
| `mintPlayerToken({ playerEmail, playerPhone?, playerName? })` | `{ token, expiresAt, identityId, created?, phoneMismatch? }`: session mint; an unknown player is a 404 without `playerPhone` and is created with it (`created: true`); an existing player's phone is never changed (`phoneMismatch: true` when it differs). See [Player token](#player-token-session-mint-for-an-existing-player) |
|
|
2465
|
+
| `registerPlayer({ playerEmail, playerPhone, playerName? })` | `{ status: "created" \| "exists", identityId, playerToken?, playerTokenExpiresAt?, raw }`; moves no money. `isPhoneMismatch` / `isPhoneShareRefused` |
|
|
2466
|
+
| `updatePlayerPhone({ playerEmail, newPhone })` | `{ status: "updated" \| "unchanged", identityRekeyed, identityId, playerToken?, playerTokenExpiresAt?, raw }`; never auto-retried. `isPhoneChangeRequiresVerification` / `isPhoneShareRefused` / `isPlayerNotFound` |
|
|
2467
|
+
| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, identityRekeyed?, playerToken?, playerTokenExpiresAt?, identityId?, claimDeliveryPlanned?, raw }`; when `identityRekeyed` is `true`, hand the browser `playerToken` before it approves |
|
|
2468
|
+
| `initiateTransfer(input)` | same as `initiateSend` |
|
|
2320
2469
|
| `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, minPurchaseWarning?, raw }` (`minPurchaseWarning` while an amount under INVO's minimum card purchase is still accepted), where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
|
|
2321
2470
|
| `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, partnerFeeUsd?, internationalCardFeeUsd?, feeTakenFrom?, minPurchaseWarning?, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
|
|
2322
2471
|
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only |
|
|
@@ -2343,6 +2492,7 @@ try {
|
|
|
2343
2492
|
| `cards.list(playerEmail)` | `{ cards: SavedCard[], raw }` — unexpired cards, newest first; `card.id` is the `playerCardId` |
|
|
2344
2493
|
| `sandbox.subscriptions.advanceClock(id, intervals?)` / `forceRenewal(id)` / `forceFailure(id, outcome?, { failureCode?, failureMessage? })` / `forceAuthChallenge(id, { failureMessage? })` | `SandboxClockResult` — `{ status, action, subscription, before?, after?, engineStats?, retryScheduleDays?, retriesRemaining?, authChallengesUsed?, …, raw }`; **sandbox only**, posts to `/subscriptions/<id>/...` relative to the sandbox base (not `/api`), needs `sandboxClockKey`; never auto-retried |
|
|
2345
2494
|
| `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
|
|
2495
|
+
| `getPlayerRewards(playerEmail)` | `LoyaltyCardsResult`: `{ cardVersion, cards, raw }`, the player's loyalty cards in your game (the same cards as `InvoClient.getMyRewards()`); each step carries `state` and `progress` (`{ current, target }` or `null`); rewards carry `codeMasked` only. Server secret only. `isPlayerNotFound` / `isInvalidPlayerEmail`. See [Loyalty and rewards](#loyalty-and-rewards) |
|
|
2346
2496
|
| `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
|
|
2347
2497
|
| `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
|
|
2348
2498
|
| ~~`verifySmsTransfer(txnId, smsPin)`~~ / ~~`verifySmsSend(txnId, smsPin)`~~ | **Deprecated (3.1.0), removal at a future major.** `SmsVerifyResult` — completes the SMS-PIN path when `verificationMethod: "sms"`. Prefer passkey enrollment + `approveTransfer`/`approveSend`; keep this only for users who can't enroll. Still fully functional. |
|
|
@@ -2370,12 +2520,16 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
|
|
|
2370
2520
|
| `enrollPasskey()` | `{ status, device, raw }` |
|
|
2371
2521
|
| `enrollmentBegin()` / `enrollmentVerify(code)` | OTP grant for `ENROLLMENT_REQUIRES_AUTHORIZATION` (then retry `enrollPasskey`) |
|
|
2372
2522
|
| `recoveryBegin()` / `recoveryComplete(code)` | passkey recovery for `ENROLLMENT_REQUIRES_PROOF` when the passkey was lost/deleted (then retry `enrollPasskey`) — recovered keys can't move money OUT for 24h (`PASSKEY_RECOVERY_COOLDOWN`) |
|
|
2373
|
-
| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
|
|
2523
|
+
| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, claimDelivery?, raw }`; `claimDelivery` is `"email"`, `"none"` or legacy `"sms"`. 403 `err.isPlayerTokenStale`: re-mint and retry once (never auto-retried) |
|
|
2374
2524
|
| `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
|
|
2375
2525
|
| `linkDevice()` | `{ status, raw }` — call with no arguments; the server mints the link id (a value passed by 3.10-era code is still accepted and ignored) |
|
|
2376
2526
|
| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
|
|
2377
2527
|
| `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
|
|
2378
2528
|
| `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
|
|
2529
|
+
| `getMyRewards()` | `LoyaltyCardsResult`: `{ cardVersion, cards, raw }`, the signed-in player's loyalty cards with per-step `state` and `progress` |
|
|
2530
|
+
| `getMyVault()` | `{ items, raw }`: every reward the player holds or held, newest first, codes masked |
|
|
2531
|
+
| `redeemReward(vaultEntryId)` | `{ vaultEntryId, rewardRef, state, redeemedAt, code, codeMasked, revealedAgain, revealUntil, raw }`: the only response with a code; never auto-retried |
|
|
2532
|
+
| `getRewardsPageLink()` | `{ url, expiresAt, raw }`: a short-lived link to INVO's hosted "My rewards" page |
|
|
2379
2533
|
| `approveHosted({ transactionId, flow, platformOrigin?, onEnrollment?, renderPrompt?, popupBlocked?, popup?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "closed" \| "blocked" \| "redirected", popupBlocked, message?, approval? }` — runs the whole RFC 8628 device-approval grant from the browser on INVO's hosted page (begin `channel:"popup"` → popup → poll → match-code prompt → confirm-enrollment → approve with the `device_code`, which the SDK holds and never exposes); `approval` is the `ApproveResult` / `ConfirmReceiptResult` of the flow's approve endpoint |
|
|
2380
2534
|
| `checkout.getPurchaseStatus({ sessionId, sessionToken })` | `{ status, terminal, orderId, sessionId, coinsCredited, transactionId, newBalance, reasonCode, message, amountChargedUsd, listedUsd, currencyName, raw }`: what happened to a hosted-checkout purchase. Authenticated by the SESSION token, not the player token |
|
|
2381
2535
|
| `checkout.waitForPurchase({ sessionId, sessionToken, intervalMs?, timeoutMs?, maxAttempts?, signal?, onUpdate? })` | the same result, polled until INVO's `terminal` is true (never re-derived from `status`); on the cap it returns the last result rather than throwing. Also available standalone: `new CheckoutClient({ baseUrl })` |
|
|
@@ -817,9 +817,47 @@ var InvoError = class _InvoError extends Error {
|
|
|
817
817
|
* The same code comes back from `cards.beginSetup` and from `mintPlayerToken` for the
|
|
818
818
|
* same reason; those two never create players, so create the member first (for
|
|
819
819
|
* example with `createSetupSession` and a `playerName`, or a currency purchase).
|
|
820
|
+
* `getPlayerRewards` answers it when no player has that email in this game.
|
|
820
821
|
*/
|
|
821
822
|
get isPlayerNotFound() {
|
|
822
|
-
|
|
823
|
+
if (this.code === "PLAYER_NOT_FOUND") return true;
|
|
824
|
+
return this.status === 404 && this.bodyObject()["error"] === "player_not_found";
|
|
825
|
+
}
|
|
826
|
+
// ---- Player registration, phone changes, identity re-key ----
|
|
827
|
+
/**
|
|
828
|
+
* True when an approve was refused because the player token predates a change to the
|
|
829
|
+
* sender's identity (`PLAYER_TOKEN_STALE`, 403): their phone was added (for example on
|
|
830
|
+
* the initiate), which gives them a new identity. Nothing moved and the token stays
|
|
831
|
+
* refused. Re-mint the player token (or use the `playerToken` from the initiate result)
|
|
832
|
+
* and retry once. The SDK never retries a money call on its own.
|
|
833
|
+
*/
|
|
834
|
+
get isPlayerTokenStale() {
|
|
835
|
+
return this.code === "PLAYER_TOKEN_STALE";
|
|
836
|
+
}
|
|
837
|
+
/**
|
|
838
|
+
* True when `updatePlayerPhone` was refused because the player has secured this account,
|
|
839
|
+
* so the change needs the player's own confirmation (`PHONE_CHANGE_REQUIRES_VERIFICATION`,
|
|
840
|
+
* 409). Nothing changed. Until that confirmation flow is available, contact INVO support.
|
|
841
|
+
*/
|
|
842
|
+
get isPhoneChangeRequiresVerification() {
|
|
843
|
+
return this.code === "PHONE_CHANGE_REQUIRES_VERIFICATION";
|
|
844
|
+
}
|
|
845
|
+
/**
|
|
846
|
+
* True when `registerPlayer` found the player already in your game with a DIFFERENT
|
|
847
|
+
* phone (`PHONE_MISMATCH`, 409). Nothing changed; use `updatePlayerPhone` to change it.
|
|
848
|
+
* (`mintPlayerToken` reports the same situation as `phoneMismatch: true` on success.)
|
|
849
|
+
*/
|
|
850
|
+
get isPhoneMismatch() {
|
|
851
|
+
return this.code === "PHONE_MISMATCH";
|
|
852
|
+
}
|
|
853
|
+
/**
|
|
854
|
+
* True when the phone you supplied belongs to another email
|
|
855
|
+
* (`PHONE_SHARE_APPROVAL_REQUIRED`, 409) on `mintPlayerToken`, `registerPlayer` or
|
|
856
|
+
* `updatePlayerPhone`. Nothing was created or changed. The same condition as
|
|
857
|
+
* {@link isPhoneShareApprovalRequired}, named for these registration calls.
|
|
858
|
+
*/
|
|
859
|
+
get isPhoneShareRefused() {
|
|
860
|
+
return this.isPhoneShareApprovalRequired;
|
|
823
861
|
}
|
|
824
862
|
/**
|
|
825
863
|
* True when `cards.createSetupSession` was asked to create a new member (`playerName`
|
|
@@ -831,7 +869,8 @@ var InvoError = class _InvoError extends Error {
|
|
|
831
869
|
}
|
|
832
870
|
/**
|
|
833
871
|
* True when `cards.createSetupSession` was refused because `playerEmail` was missing or
|
|
834
|
-
* is not an email address (`INVALID_PLAYER_EMAIL`, 400).
|
|
872
|
+
* is not an email address (`INVALID_PLAYER_EMAIL`, 400). `getPlayerRewards` answers it
|
|
873
|
+
* for an email that is not an email address (a blank one never leaves the SDK).
|
|
835
874
|
*/
|
|
836
875
|
get isInvalidPlayerEmail() {
|
|
837
876
|
return this.code === "INVALID_PLAYER_EMAIL";
|
|
@@ -882,6 +921,26 @@ var InvoError = class _InvoError extends Error {
|
|
|
882
921
|
get isIdentityCheckUnavailable() {
|
|
883
922
|
return this.code === "IDENTITY_CHECK_UNAVAILABLE";
|
|
884
923
|
}
|
|
924
|
+
// ---- Loyalty rewards (InvoClient.redeemReward) ----
|
|
925
|
+
/** True when a reward was already redeemed and its code can no longer be shown (`already_redeemed`, 409). */
|
|
926
|
+
get isRewardAlreadyRedeemed() {
|
|
927
|
+
return this.code === "already_redeemed";
|
|
928
|
+
}
|
|
929
|
+
/** True when the player has no such reward (`vault_entry_not_found`, 404). */
|
|
930
|
+
get isRewardNotFound() {
|
|
931
|
+
return this.code === "vault_entry_not_found";
|
|
932
|
+
}
|
|
933
|
+
/**
|
|
934
|
+
* True when the reward cannot be redeemed right now (409): `inventory_exhausted` (no units or
|
|
935
|
+
* codes are left for it) or `conflict` (the reward is reserved or revoked).
|
|
936
|
+
*/
|
|
937
|
+
get isRewardUnavailable() {
|
|
938
|
+
return this.code === "inventory_exhausted" || this.code === "conflict";
|
|
939
|
+
}
|
|
940
|
+
/** True when the reward expired before it was redeemed (`vault_entry_expired`, 410). */
|
|
941
|
+
get isRewardExpired() {
|
|
942
|
+
return this.code === "vault_entry_expired";
|
|
943
|
+
}
|
|
885
944
|
/** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
|
|
886
945
|
get retryAfter() {
|
|
887
946
|
const v = this.bodyObject()["retry_after"];
|
|
@@ -1181,6 +1240,123 @@ function receiptFields(raw) {
|
|
|
1181
1240
|
return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
|
|
1182
1241
|
}
|
|
1183
1242
|
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1243
|
+
// src/shared/loyalty.ts
|
|
1244
|
+
var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
|
|
1245
|
+
var rows = (v) => Array.isArray(v) ? v.filter((r) => r && typeof r === "object" && !Array.isArray(r)) : [];
|
|
1246
|
+
var str = (v) => v === void 0 || v === null ? "" : String(v);
|
|
1247
|
+
var strOrNull = (v) => v === void 0 || v === null ? null : String(v);
|
|
1248
|
+
var numOrNull = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
|
|
1249
|
+
var int = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
|
|
1250
|
+
var passThrough = (v) => v;
|
|
1251
|
+
function toLoyaltyStepProgress(value) {
|
|
1252
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
|
|
1253
|
+
const v = value;
|
|
1254
|
+
const current = v["current"];
|
|
1255
|
+
const target = v["target"];
|
|
1256
|
+
if (!Number.isInteger(current) || !Number.isInteger(target)) return null;
|
|
1257
|
+
return { current, target };
|
|
1258
|
+
}
|
|
1259
|
+
function toStep(row) {
|
|
1260
|
+
return {
|
|
1261
|
+
stepId: strOrNull(row["step_id"]),
|
|
1262
|
+
index: int(row["index"]),
|
|
1263
|
+
action: str(row["action"]),
|
|
1264
|
+
label: str(row["label"]),
|
|
1265
|
+
summary: str(row["summary"]),
|
|
1266
|
+
windowHours: numOrNull(row["window_hours"]),
|
|
1267
|
+
state: str(row["state"]),
|
|
1268
|
+
progress: toLoyaltyStepProgress(row["progress"]),
|
|
1269
|
+
raw: row
|
|
1270
|
+
};
|
|
1271
|
+
}
|
|
1272
|
+
function toCardReward(row) {
|
|
1273
|
+
return {
|
|
1274
|
+
vaultEntryId: str(row["vault_entry_id"]),
|
|
1275
|
+
rewardId: str(row["reward_id"]),
|
|
1276
|
+
state: str(row["state"]),
|
|
1277
|
+
unlockedAt: str(row["unlocked_at"]),
|
|
1278
|
+
expiresAt: str(row["expires_at"]),
|
|
1279
|
+
redeemedAt: strOrNull(row["redeemed_at"]),
|
|
1280
|
+
codeMasked: strOrNull(row["code_masked"]),
|
|
1281
|
+
canRedeem: row["can_redeem"] === true,
|
|
1282
|
+
canRevealAgain: row["can_reveal_again"] === true,
|
|
1283
|
+
revealUntil: strOrNull(row["reveal_until"]),
|
|
1284
|
+
raw: row
|
|
1285
|
+
};
|
|
1286
|
+
}
|
|
1287
|
+
function toLoyaltyCard(row) {
|
|
1288
|
+
const brand = obj(row["brand"]);
|
|
1289
|
+
const reward = obj(row["reward"]);
|
|
1290
|
+
const steps = rows(row["steps"]).map(toStep);
|
|
1291
|
+
return {
|
|
1292
|
+
cardVersion: passThrough(row["card_version"]),
|
|
1293
|
+
mode: str(row["mode"]),
|
|
1294
|
+
programId: strOrNull(row["program_id"]),
|
|
1295
|
+
questId: strOrNull(row["quest_id"]),
|
|
1296
|
+
questVersion: numOrNull(row["quest_version"]),
|
|
1297
|
+
campaignId: strOrNull(row["campaign_id"]),
|
|
1298
|
+
title: str(row["title"]),
|
|
1299
|
+
description: str(row["description"]),
|
|
1300
|
+
brand: { name: strOrNull(brand["name"]), logoUrl: strOrNull(brand["logo_url"]) },
|
|
1301
|
+
artUrl: strOrNull(row["art_url"]),
|
|
1302
|
+
reward: { rewardId: strOrNull(reward["reward_id"]), name: strOrNull(reward["name"]) },
|
|
1303
|
+
orderMode: str(row["order_mode"]),
|
|
1304
|
+
status: str(row["status"]),
|
|
1305
|
+
startsAt: strOrNull(row["starts_at"]),
|
|
1306
|
+
endsAt: strOrNull(row["ends_at"]),
|
|
1307
|
+
completionHours: numOrNull(row["completion_hours"]),
|
|
1308
|
+
completionNote: strOrNull(row["completion_note"]),
|
|
1309
|
+
windowEndsAt: strOrNull(row["window_ends_at"]),
|
|
1310
|
+
completedAt: strOrNull(row["completed_at"]),
|
|
1311
|
+
stepsRequired: passThrough(row["steps_required"]),
|
|
1312
|
+
stepsComplete: passThrough(row["steps_complete"]),
|
|
1313
|
+
steps,
|
|
1314
|
+
rewards: rows(row["rewards"]).map(toCardReward),
|
|
1315
|
+
raw: row
|
|
1316
|
+
};
|
|
1317
|
+
}
|
|
1318
|
+
function toLoyaltyCardsResult(raw) {
|
|
1319
|
+
return {
|
|
1320
|
+
cardVersion: passThrough(raw["card_version"]),
|
|
1321
|
+
cards: rows(raw["cards"]).map(toLoyaltyCard),
|
|
1322
|
+
raw
|
|
1323
|
+
};
|
|
1324
|
+
}
|
|
1325
|
+
function toVaultEntry(row) {
|
|
1326
|
+
return {
|
|
1327
|
+
vaultEntryId: str(row["vault_entry_id"]),
|
|
1328
|
+
rewardRef: str(row["reward_ref"]),
|
|
1329
|
+
programId: str(row["program_id"]),
|
|
1330
|
+
questId: strOrNull(row["quest_id"]),
|
|
1331
|
+
units: str(row["units"]),
|
|
1332
|
+
state: str(row["state"]),
|
|
1333
|
+
unlockedAt: strOrNull(row["unlocked_at"]),
|
|
1334
|
+
expiresAt: strOrNull(row["expires_at"]),
|
|
1335
|
+
redeemedAt: strOrNull(row["redeemed_at"]),
|
|
1336
|
+
codeMasked: strOrNull(row["code_masked"]),
|
|
1337
|
+
raw: row
|
|
1338
|
+
};
|
|
1339
|
+
}
|
|
1340
|
+
function toLoyaltyVaultResult(raw) {
|
|
1341
|
+
return { items: rows(raw["items"]).map(toVaultEntry), raw };
|
|
1342
|
+
}
|
|
1343
|
+
function toRedeemRewardResult(raw, vaultEntryId) {
|
|
1344
|
+
return {
|
|
1345
|
+
vaultEntryId: str(raw["vault_entry_id"] ?? vaultEntryId),
|
|
1346
|
+
rewardRef: str(raw["reward_ref"]),
|
|
1347
|
+
state: str(raw["state"]),
|
|
1348
|
+
redeemedAt: strOrNull(raw["redeemed_at"]),
|
|
1349
|
+
code: strOrNull(raw["code"]),
|
|
1350
|
+
codeMasked: strOrNull(raw["code_masked"]),
|
|
1351
|
+
revealedAgain: raw["revealed_again"] === true,
|
|
1352
|
+
revealUntil: strOrNull(raw["reveal_until"]),
|
|
1353
|
+
raw
|
|
1354
|
+
};
|
|
1355
|
+
}
|
|
1356
|
+
function toRewardsPageLink(raw) {
|
|
1357
|
+
return { url: str(raw["url"]), expiresAt: str(raw["expires_at"]), raw };
|
|
1358
|
+
}
|
|
1359
|
+
|
|
1360
|
+
export { Http, InvoError, assertSecureBaseUrl, creditFields, receiptFields, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink };
|
|
1361
|
+
//# sourceMappingURL=chunk-7L4O5Q7K.js.map
|
|
1362
|
+
//# sourceMappingURL=chunk-7L4O5Q7K.js.map
|