@invonetwork/web-sdk 3.2.0 → 3.2.1
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 +628 -610
- package/README.md +864 -850
- package/package.json +76 -76
package/CHANGELOG.md
CHANGED
|
@@ -1,610 +1,628 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
|
|
4
|
-
[Semantic Versioning](https://semver.org/). Releases are managed with
|
|
5
|
-
[changesets](https://github.com/changesets/changesets).
|
|
6
|
-
|
|
7
|
-
## [3.2.
|
|
8
|
-
|
|
9
|
-
**
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- **`
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
###
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
-
|
|
101
|
-
|
|
102
|
-
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
###
|
|
163
|
-
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
(
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
-
|
|
203
|
-
`
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
- New `InvoError` classifiers
|
|
238
|
-
`
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
- New
|
|
256
|
-
(
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
## [2.
|
|
265
|
-
|
|
266
|
-
**
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
- **
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
**
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
- `
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
- **
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
the
|
|
360
|
-
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
- **
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
- `
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
`
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
`
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
-
|
|
481
|
-
`
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
## [0.
|
|
520
|
-
|
|
521
|
-
Additive release —
|
|
522
|
-
|
|
523
|
-
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
- **`
|
|
531
|
-
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
- **
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
- `InvoServer` (`/server`): `
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
`
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
-
|
|
591
|
-
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
`
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
-
|
|
604
|
-
|
|
605
|
-
-
|
|
606
|
-
-
|
|
607
|
-
|
|
608
|
-
-
|
|
609
|
-
|
|
610
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@invonetwork/web-sdk` are documented here. This project follows
|
|
4
|
+
[Semantic Versioning](https://semver.org/). Releases are managed with
|
|
5
|
+
[changesets](https://github.com/changesets/changesets).
|
|
6
|
+
|
|
7
|
+
## [3.2.1] - 2026-08-28
|
|
8
|
+
|
|
9
|
+
**Documentation only. No code changes, no API changes.**
|
|
10
|
+
|
|
11
|
+
Documents two things about the Steam rail that the SDK does not change but every
|
|
12
|
+
Steam integration has to handle:
|
|
13
|
+
|
|
14
|
+
- **Currency for a Steam-distributed title must be bought on the `steam` rail.**
|
|
15
|
+
Any other rail is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`. This is a
|
|
16
|
+
platform requirement and it applies across every storefront the title ships on,
|
|
17
|
+
because a player's balance is shared between them.
|
|
18
|
+
- **The player is charged more than the value you request.** Steam's platform
|
|
19
|
+
commission is priced into the charge rather than absorbed, so the Steam
|
|
20
|
+
init-purchase response now carries `charged_usd` alongside `value_usd`. Show
|
|
21
|
+
`charged_usd` in your store. The currency the player receives is unchanged, so a
|
|
22
|
+
pack is worth the same in-game on every rail, and the rate is configuration --
|
|
23
|
+
read the response rather than hard-coding a multiplier.
|
|
24
|
+
|
|
25
|
+
## [3.2.0] — 2026-08-24
|
|
26
|
+
|
|
27
|
+
**Storefront keys.** A game that ships on more than one storefront now gets one SDK
|
|
28
|
+
key per storefront -- `steam`, `ios`, `android`, `web`, `console` -- all valid at the
|
|
29
|
+
same time, and the key determines the payment rail. Construct one client per key and
|
|
30
|
+
use whichever matches where the player is buying. **Additive: no behavior changes, no
|
|
31
|
+
API removals.** A single existing key keeps working exactly as it does today, `rail`
|
|
32
|
+
included, with no deadline and no migration.
|
|
33
|
+
|
|
34
|
+
Three new typed error predicates for refusals this SDK previously surfaced only as a
|
|
35
|
+
raw `code` string:
|
|
36
|
+
|
|
37
|
+
- `InvoError.isRailChannelMismatch` -- the `rail` you sent disagrees with the storefront key
|
|
38
|
+
you authenticated with (400). The fix is to stop sending `rail`; the key already
|
|
39
|
+
determines it. INVO refuses rather than silently overriding, because overriding
|
|
40
|
+
would bill a player through a route you did not ask for.
|
|
41
|
+
- `InvoError.isSteamRailNotEntitled` -- a Steam purchase was attempted for a title INVO has
|
|
42
|
+
not registered as distributed on Steam (403). Holding a `steam` storefront key does
|
|
43
|
+
not by itself register the title.
|
|
44
|
+
- `InvoError.isSteamPurchaseLayerRequired` -- a title distributed on Steam tried to sell currency
|
|
45
|
+
on a non-Steam rail (409). Use the dedicated Steam purchase flow.
|
|
46
|
+
|
|
47
|
+
Also in this release: the 3-D Secure completion method's documentation no longer names
|
|
48
|
+
a payment processor. INVO does not name processors in developer-facing surfaces, and
|
|
49
|
+
this line had been an exception to that for some time.
|
|
50
|
+
|
|
51
|
+
Also in 3.2.0: **provider-neutral error codes.** INVO stamps a neutral alias
|
|
52
|
+
(`error_code_public`) beside any machine code that carries a payment
|
|
53
|
+
processor's name. This SDK previously read only the raw code, so a partner
|
|
54
|
+
branching on `err.code` had to hard-code a vendor name INVO's own public
|
|
55
|
+
documentation is not allowed to print. `err.code` is now the neutral alias when
|
|
56
|
+
one exists (`STRIPE_ERROR` becomes `PROCESSOR_ERROR`), and the literal wire value stays reachable on
|
|
57
|
+
`err.rawCode` for anyone already matching it. Refund reads prefer
|
|
58
|
+
`processor_refund_reference` over the vendor-named field, with a fallback.
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
**Storefront keys are still server-side keys.** A storefront key names where the
|
|
62
|
+
*purchase* came from, not where the key lives. It belongs in your backend exactly like
|
|
63
|
+
your original key -- never in a game client, an app bundle, or browser code.
|
|
64
|
+
|
|
65
|
+
## [3.1.0] — 2026-08-04
|
|
66
|
+
|
|
67
|
+
**Passkeys are the gold standard; the SMS-PIN path is deprecated.** This release makes INVO's
|
|
68
|
+
authentication guidance explicit in the two places developers actually look — the README and IDE
|
|
69
|
+
autocomplete. **No behavior changes, no API removals, no runtime warnings.** Upgrading and
|
|
70
|
+
changing nothing produces byte-identical runtime behavior.
|
|
71
|
+
|
|
72
|
+
A passkey is a phishing-resistant, origin-bound WebAuthn assertion. An SMS PIN is a shared secret
|
|
73
|
+
on a channel exposed to SIM swap and interception. They were documented as interchangeable
|
|
74
|
+
verification options; they are not, and the docs said so in a way that produced PIN-first
|
|
75
|
+
integrations.
|
|
76
|
+
|
|
77
|
+
### Added — error-contract classifiers
|
|
78
|
+
Three 403s that previously arrived as a generic `InvoError` (correct `status`/`code`/`message`,
|
|
79
|
+
but no typed branch) now have classifiers:
|
|
80
|
+
|
|
81
|
+
- **`err.isSourceGameNotLive`** — the caller's OWN game is in testing. Self-serve: switch it to
|
|
82
|
+
Live in the console (Game Settings → Status).
|
|
83
|
+
- **`err.isTargetGameNotLive`** — the DESTINATION game is in testing. Usually another
|
|
84
|
+
developer's game, so the caller **cannot** fix it. **Deliberately distinct** from the source
|
|
85
|
+
case: collapsing them into one "not live" branch yields a "go fix it" CTA that dead-ends half
|
|
86
|
+
the time.
|
|
87
|
+
- **`err.gameStatus`** — the `game_status` field from either refusal (e.g. `"testing"`).
|
|
88
|
+
- **`err.isWebauthnNotEnabledForTenant`** — tenant has no verified WebAuthn RP ID. **This is
|
|
89
|
+
configuration state, not a failure**: fall back to the SMS/in-app path instead of surfacing an
|
|
90
|
+
error. Currently the common case — 4/23 sandbox and **0/3 production** tenants are configured.
|
|
91
|
+
|
|
92
|
+
Note the backend splits field names across these: the `*_GAME_NOT_LIVE` pair uses
|
|
93
|
+
`error_code`/`message`, while `WEBAUTHN_NOT_ENABLED_FOR_TENANT` uses `code`/`error`. The SDK
|
|
94
|
+
already read both, so `err.code` is populated either way — the new tests pin both shapes.
|
|
95
|
+
|
|
96
|
+
### Clarified — the SDK does not, and did not, collapse non-2xx into transport errors
|
|
97
|
+
Following a report of a `403` being debugged as a network outage: verified end-to-end that a
|
|
98
|
+
non-2xx always surfaces with its real `status`, `code`, and `message`, and that `status: 0` is
|
|
99
|
+
reserved for a genuine absence of an HTTP response. **No fix was needed in the SDK** — the loss
|
|
100
|
+
happened in an integration-layer catch-all. Added regression tests pinning the behavior, plus a
|
|
101
|
+
README section (**"`.status === 0` means 'no HTTP response' — and nothing else"**) showing the
|
|
102
|
+
anti-pattern and the correct handler, and a note that `409` is a retryable not-ready state
|
|
103
|
+
rather than a failure.
|
|
104
|
+
|
|
105
|
+
### Deprecated
|
|
106
|
+
- **`InvoServer.verifySmsTransfer` / `InvoServer.verifySmsSend`** — marked `@deprecated`. They
|
|
107
|
+
still work exactly as before and still hit the same endpoints. A **future major version will
|
|
108
|
+
remove them**; no date is committed yet. Keep them only as a genuine last resort for users who
|
|
109
|
+
cannot enroll a passkey (unsupported device, no platform authenticator) or who decline.
|
|
110
|
+
**Migration:** when `initiateSend`/`initiateTransfer` returns `verificationMethod: "sms"`, read
|
|
111
|
+
it as *"this sender has no passkey"* — prompt `InvoClient.enrollPasskey()` and then
|
|
112
|
+
`InvoClient.approveSend` / `approveTransfer`, instead of routing to a PIN pad.
|
|
113
|
+
|
|
114
|
+
### Changed (documentation only)
|
|
115
|
+
- New README section — **"Passkeys are the gold standard — don't build on SMS"** — with the
|
|
116
|
+
do/don't table, the deprecation notice, and an explicit list of the OTP surfaces that are
|
|
117
|
+
**not** discouraged.
|
|
118
|
+
- `VerificationMethod`, `InitiateResult.verificationMethod` and `SmsVerifyResult` doc comments
|
|
119
|
+
reframed: `"in_app"` and `"sms"` are no longer presented as peer options.
|
|
120
|
+
- "Before you go live" now stresses configuring RP ID / origins *before* launch, since an
|
|
121
|
+
unconfigured tenant silently drops every sender onto the deprecated path.
|
|
122
|
+
- **New "Prerequisite: passkeys are dark until your tenant verifies a domain" subsection.**
|
|
123
|
+
Recommending passkeys without saying what unlocks them would send developers straight into a
|
|
124
|
+
`403` on their first `enrollPasskey()` call — with 0/3 prod tenants configured, that is
|
|
125
|
+
currently *everyone*. The deprecation carries no removal date for the same reason.
|
|
126
|
+
- Stability section corrected — it still claimed `2.0.0` was the only major, which `3.0.0`
|
|
127
|
+
made false.
|
|
128
|
+
- Design doc: `docs/features/passkey-first-authentication.md`.
|
|
129
|
+
|
|
130
|
+
### Not affected — still recommended
|
|
131
|
+
`enrollmentBegin`/`enrollmentVerify`, `recoveryBegin`/`recoveryComplete`, and
|
|
132
|
+
`phoneShareInitiate`/`phoneShareApprove` all involve a one-time code but are the on-ramp *to* a
|
|
133
|
+
passkey (or phone-ownership consent), not a substitute for one. They are **not** deprecated.
|
|
134
|
+
|
|
135
|
+
### Upgrade note
|
|
136
|
+
The only way this release can surface in a pipeline is a lint rule that treats `@deprecated`
|
|
137
|
+
usage as an error (e.g. `deprecation/deprecation` with `--max-warnings 0`). That is a lint-level
|
|
138
|
+
signal, not a build or runtime break, and it is the intended notice.
|
|
139
|
+
|
|
140
|
+
## [3.0.0] — 2026-07-20
|
|
141
|
+
|
|
142
|
+
**BREAKING — the Platform Commerce card leg moved to INVO's hosted checkout.** The backend now
|
|
143
|
+
hosts the entire card flow (card fields, Apple Pay / Google Pay, billing-address collection,
|
|
144
|
+
3-D Secure) on its own checkout page, so the browser card-element surface shipped in 2.5.x is
|
|
145
|
+
gone. Card sales are simpler AND safer: server creates → buyer pays on `checkoutUrl` → fulfill
|
|
146
|
+
on the `platform_commerce.purchased` webhook. Note: the card leg is pending final enablement on
|
|
147
|
+
the backend (sandbox payment test) — the balance leg is fully live.
|
|
148
|
+
|
|
149
|
+
### Migration from 2.5.x (card leg only — balance/status/refund/webhooks unchanged)
|
|
150
|
+
- `platformCommerce.purchase({ fundingSource: "card" })`: **remove `billingAddress`** (the type
|
|
151
|
+
is gone; the hosted page collects it) and optionally pass `successUrl` / `cancelUrl` /
|
|
152
|
+
`metadata`. The result now carries `checkoutUrl` / `sessionId` / `expiresAt` (unix seconds) /
|
|
153
|
+
`idempotentReplay` — **`clientSecret` no longer exists.**
|
|
154
|
+
- Browser: **`confirmCardPayment` and `mountCardPayment` are removed** (with all card-element
|
|
155
|
+
types and the `commercePublishableKey` config). Replace with a redirect
|
|
156
|
+
(`location.href = checkoutUrl`) or the new optional embed:
|
|
157
|
+
`invo.platformCommerce.mountCheckout(el, checkoutUrl, { onComplete })` — an iframe plus an
|
|
158
|
+
origin-checked listener for the page's `INVO_CHECKOUT_COMPLETE` message.
|
|
159
|
+
- Card duplicates no longer 409: retrying `purchase` with the same `clientRequestId` **replays
|
|
160
|
+
the same checkout session** (`idempotentReplay: true`), so a lost response is recoverable.
|
|
161
|
+
|
|
162
|
+
### Added
|
|
163
|
+
- `PlatformPurchaseInput.successUrl/cancelUrl/metadata`; result fields
|
|
164
|
+
`sessionId/checkoutUrl/expiresAt/idempotentReplay`.
|
|
165
|
+
- `InvoClient.platformCommerce.mountCheckout(el, checkoutUrl, opts)` → `{ iframe, destroy() }`.
|
|
166
|
+
- `err.isAboveCardMaximum` (`ABOVE_CARD_MAXIMUM`, card > $999.99) + client-side card USD
|
|
167
|
+
bounds fail-fast ($0.50–$999.99).
|
|
168
|
+
- Card `requires_payment` responses without a `checkout_url` fail closed (`INVALID_RESPONSE`).
|
|
169
|
+
|
|
170
|
+
### Removed
|
|
171
|
+
- `confirmCardPayment`, `mountCardPayment`, `commercePublishableKey`, `BillingAddress`, and the
|
|
172
|
+
card-element/processor types + the runtime CDN script loader (no more processor touchpoints
|
|
173
|
+
in this SDK at all).
|
|
174
|
+
|
|
175
|
+
## [2.5.1] — 2026-07-20
|
|
176
|
+
|
|
177
|
+
Hardening patch from a second, independent post-release audit (correctness vs the backend
|
|
178
|
+
blueprint + security red-team) of the 2.5.0 Platform Commerce feature. No API breaks.
|
|
179
|
+
|
|
180
|
+
### Fixed
|
|
181
|
+
- **Card-confirm script loader could hang forever on retry.** After a transient CDN failure
|
|
182
|
+
(or a pre-existing processor `<script>` tag whose events already fired), the next
|
|
183
|
+
`mountCardPayment`/`confirmCardPayment` attached listeners to a dead tag and never settled —
|
|
184
|
+
checkout silently dead until page reload. The loader now removes failed tags and polls
|
|
185
|
+
(bounded, 10s) when a tag pre-exists.
|
|
186
|
+
- **Orphaned card element on submit-lookup failure.** `confirmCardPayment` now destroys the
|
|
187
|
+
mounted Payment Element before rethrowing when the `submit` selector can't be resolved
|
|
188
|
+
(previously a retry stacked a second live card iframe).
|
|
189
|
+
- **Billing-address validation errors no longer echo the submitted values** (cardholder PII
|
|
190
|
+
could otherwise land in logs/Sentry); optional billing fields (`name`/`line2`/`state`) are
|
|
191
|
+
now type-checked.
|
|
192
|
+
- **`playerPhone` on `platformCommerce.purchase` is now E.164-validated** — this endpoint can
|
|
193
|
+
create the player identity, so a national-format phone must never reach the wire.
|
|
194
|
+
- **`err.isInsufficientBalance` now also classifies the zero-balance 400** ("Player has no
|
|
195
|
+
balance in this tenant", which carries only `current_balance`).
|
|
196
|
+
- **Breaker-open 503 keeps its human message** (`err.code === "service_unavailable"`, message
|
|
197
|
+
no longer collapses to the bare token).
|
|
198
|
+
- **Webhook types:** `platform_commerce.refunded` `player_email` is nullable + `identity_id`
|
|
199
|
+
added; (2.5.0 already made card-leg `total_price` optional on `purchased`).
|
|
200
|
+
- **Refund result surfaces `newBalance`** (balance leg) **and `processorRefundId`** (card leg)
|
|
201
|
+
instead of leaving them `raw`-only.
|
|
202
|
+
- Platform-commerce error tests now assert the REAL backend envelopes
|
|
203
|
+
(`{status,error_code,message}` / bare `{message}`), not idealized shapes.
|
|
204
|
+
|
|
205
|
+
### Docs
|
|
206
|
+
- Card-leg lost-response caveat on `purchase` (duplicate 409 can strand a `clientSecret`-less
|
|
207
|
+
pending order — reconcile via webhook/`getStatus`, retry with a NEW `clientRequestId`).
|
|
208
|
+
- `confirmCardPayment`: bank-redirect return-leg guidance + remount-after-decline note;
|
|
209
|
+
`CardPaymentResult.raw` log-redaction note.
|
|
210
|
+
|
|
211
|
+
## [2.5.0] — 2026-07-20
|
|
212
|
+
|
|
213
|
+
**Platform Commerce (ecommerce).** A new flow for **platform** tenants (non-game apps: vertical
|
|
214
|
+
video, creator merch, marketplace) to sell items funded by **INVO balance or a real card**, with
|
|
215
|
+
INVO as merchant of record and full refunds. This is **distinct from item purchase** — that is a
|
|
216
|
+
*game* tenant spending a player's *existing game currency* on an *in-game* item (balance only, no
|
|
217
|
+
card, no refund). Additive; only platform tenants can call it (a game tenant gets `403
|
|
218
|
+
NOT_A_PLATFORM_TENANT`). (Backend handoff: BE-PIP-009 `PLATFORM_COMMERCE_SDK.md`.)
|
|
219
|
+
|
|
220
|
+
- **Server** (`InvoServer.platformCommerce`, mirrored in the Python SDK as
|
|
221
|
+
`server.platform_commerce`):
|
|
222
|
+
- `purchase(input)` — `fundingSource: "balance"` settles synchronously (`status:"success"`);
|
|
223
|
+
`"card"` returns `status:"requires_payment"` + a `clientSecret` and **requires a
|
|
224
|
+
`billingAddress`**. Idempotent on `clientRequestId`.
|
|
225
|
+
- `getStatus(orderId)` — `completed` | `pending_payment` | `refunded`.
|
|
226
|
+
- `refund({ orderId | clientRequestId, reason? })` — INVO retains its fee; a second refund
|
|
227
|
+
throws `409` (`err.isAlreadyRefunded`).
|
|
228
|
+
- **Browser** (`InvoClient.platformCommerce`):
|
|
229
|
+
- `confirmCardPayment(clientSecret, { mount, publishableKey?, returnUrl?, submit? })` — mounts
|
|
230
|
+
the card element and confirms; returns `{ status: "succeeded" | "requires_action" |
|
|
231
|
+
"processing" | "failed" }`. The processor JS is **lazy-loaded from its CDN — no bundled
|
|
232
|
+
dependency**; pass its publishable key (or set `commercePublishableKey` on the client config).
|
|
233
|
+
- `mountCardPayment(clientSecret, opts)` — the primitive: `{ element, confirm(), destroy() }`
|
|
234
|
+
to confirm from your own Pay button.
|
|
235
|
+
- **Webhooks:** new typed `platform_commerce.purchased` / `platform_commerce.refunded` events.
|
|
236
|
+
**Fulfill card orders on `platform_commerce.purchased`, never on the browser confirmation.**
|
|
237
|
+
- **New `InvoError` classifiers:** `isNotPlatformTenant` (403), `isAmountBelowMinimum`,
|
|
238
|
+
`isBelowCardMinimum` (card < $0.50), `isAlreadyRefunded` (409).
|
|
239
|
+
- Docs: README now leads the flow list with an explicit **item purchase vs Platform Commerce**
|
|
240
|
+
contrast; new "Platform Commerce (ecommerce)" section.
|
|
241
|
+
|
|
242
|
+
## [2.4.1] — 2026-07-10
|
|
243
|
+
|
|
244
|
+
Docs only, no code change — corrects stale README prose that the 2.4.0 publish still carried:
|
|
245
|
+
the status line led with an old version, and the Stability section still cited the `2.0.0`
|
|
246
|
+
`playerPhone` requirement as the standing breaking change (2.2.0 relaxed it back to optional).
|
|
247
|
+
Republished so the package-bundled README is accurate.
|
|
248
|
+
|
|
249
|
+
## [2.4.0] — 2026-07-10
|
|
250
|
+
|
|
251
|
+
**Steam transfer policy.** Steam-purchased currency is locked to Steam titles; the backend now
|
|
252
|
+
enforces this at transfer/send initiate and annotates destinations. Additive, and inert until a
|
|
253
|
+
title is flagged Steam-distributed. (Design doc: `docs/features/steam-transfer-policy.md`.)
|
|
254
|
+
|
|
255
|
+
- New `InvoError` classifiers on `initiateSend`/`initiateTransfer` 409s:
|
|
256
|
+
`isSteamValueNonTransferable` (with `steamTransferableMax` / `steamOriginAmount` — decimal
|
|
257
|
+
strings) and `isNonSteamValueIntoSteamBlocked`. Surface `err.message` verbatim.
|
|
258
|
+
- New `DestinationGame.acceptsSteamOriginValue` (maps `accepts_steam_origin_value`; `false` when
|
|
259
|
+
omitted) — disable non-Steam destinations for a player holding Steam value so they never hit
|
|
260
|
+
the 409.
|
|
261
|
+
|
|
262
|
+
No breaking changes.
|
|
263
|
+
|
|
264
|
+
## [2.3.0] — 2026-07-07
|
|
265
|
+
|
|
266
|
+
**Claim-time phone-share approval.** The backend closed a security gap: claiming/collecting a
|
|
267
|
+
phone-routed transfer now authorizes the collecting identity against the receiver phone before
|
|
268
|
+
crediting. So `confirmReceiptSend`/`confirmReceiptTransfer` and `claimTransfer`/`claimCurrency`
|
|
269
|
+
can now return the phone-share `409 PHONE_SHARE_APPROVAL_REQUIRED` (previously only
|
|
270
|
+
registration/mint did). The existing `InvoError.isPhoneShareApprovalRequired` already classifies
|
|
271
|
+
it — no consumer code must change — but:
|
|
272
|
+
|
|
273
|
+
- New **`InvoError.phoneShareLast4`** surfaces the `phone_last4` from the 409 body for the UI
|
|
274
|
+
("we texted the phone ending 1234").
|
|
275
|
+
- `isPhoneShareApprovalRequired` docs + the `confirmReceipt*`/claim method docs + README now
|
|
276
|
+
spell out the claim-time path: it's **not a failure** — the funds are held and the phone owner
|
|
277
|
+
is texted; show `err.message` verbatim, then **retry the same call** once approved (it succeeds
|
|
278
|
+
idempotently); on denial/expiry the sender is refunded.
|
|
279
|
+
|
|
280
|
+
Additive, no breaking changes; affects all rails' claim paths (transfer, currency send, amazon).
|
|
281
|
+
|
|
282
|
+
## [2.2.0] — 2026-07-07
|
|
283
|
+
|
|
284
|
+
**Backend reconciliation** — a full audit of the SDK against the live backend surfaced three
|
|
285
|
+
places the SDK didn't match reality. All changes are backward-compatible (relaxing required
|
|
286
|
+
inputs / adding surface); no working call breaks.
|
|
287
|
+
|
|
288
|
+
- **`mintPlayerToken` no longer requires `playerPhone`.** `/api/sdk/player-token` is a
|
|
289
|
+
session-token mint for an **existing** player (looked up by email) — not a registration call.
|
|
290
|
+
It reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
|
|
291
|
+
a bug: it could **block a valid token mint for an existing email-only player**. `playerPhone`
|
|
292
|
+
is now optional and validated only if provided. Phone stays enforced where it matters — the
|
|
293
|
+
sender's phone on `initiateSend`/`initiateTransfer`, and at player creation.
|
|
294
|
+
- **Send by phone alone.** `receiverPlayerEmail` (send) and `targetPlayerEmail` (transfer) are
|
|
295
|
+
now **optional** — you can send to a recipient's phone; they supply their email at claim
|
|
296
|
+
(claim still requires it, since that's where the recipient establishes identity).
|
|
297
|
+
- **`getPlayerBalance` is by email only.** There is no by-`playerId` balance route on the
|
|
298
|
+
backend, so passing `playerId` threw a confusing 404. It now throws a clear `INVALID_INPUT`
|
|
299
|
+
pointing you to `InvoClient.getBalance()` (client-side) or `playerEmail` (server-side).
|
|
300
|
+
- **New `InvoError.isUserVerificationRequired`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
|
|
301
|
+
failure — re-run the passkey ceremony requiring UV.
|
|
302
|
+
- Fixed `iterateItemPurchaseHistory` to read the backend's `total_count` pagination key (was
|
|
303
|
+
`total`; the loop already terminated via the short-page guard, so behavior is unchanged).
|
|
304
|
+
|
|
305
|
+
**Migration:** none required. If you were passing `playerPhone` to `mintPlayerToken` it still
|
|
306
|
+
works; you can now also omit it. Replace any `getPlayerBalance({ playerId })` with an email
|
|
307
|
+
lookup or `InvoClient.getBalance()`.
|
|
308
|
+
|
|
309
|
+
## [2.1.2] — 2026-07-07
|
|
310
|
+
|
|
311
|
+
**Hosted-checkout reconciliation** (the create-session API contract is unchanged; the hosted
|
|
312
|
+
page was rebuilt). Additive + docs only.
|
|
313
|
+
|
|
314
|
+
- `createCheckout` now surfaces `expiresInSeconds` (the `checkout_url` token TTL, e.g. 900) as
|
|
315
|
+
a first-class field on `CreateCheckoutResult` — previously only on `.raw`.
|
|
316
|
+
- README: the `platform` rail is described as cards + Apple Pay / Google Pay / Link +
|
|
317
|
+
international billing (no app-store commission), and the checkout note now says reloading the
|
|
318
|
+
URL after a completed payment is idempotent (an already-complete success screen), not an
|
|
319
|
+
error. No API/signature changes.
|
|
320
|
+
|
|
321
|
+
## [2.1.1] — 2026-07-06
|
|
322
|
+
|
|
323
|
+
**Security & correctness hardening** from a full audit + red-team of both SDKs. No API changes;
|
|
324
|
+
upgrade recommended.
|
|
325
|
+
|
|
326
|
+
- **Fail closed on HTTP redirects (security).** The transport now sends `redirect:"manual"` and
|
|
327
|
+
throws `UNEXPECTED_REDIRECT` on any 3xx instead of following it. Previously a redirect from
|
|
328
|
+
the API host could cause the game-secret header to be re-sent to an unvalidated URL (matches
|
|
329
|
+
the Python SDK fix, where the leak also covered the player token and an `http://` downgrade).
|
|
330
|
+
- **`retryAfter` no longer treats a blank `retry_after` as `0`.** An empty/whitespace
|
|
331
|
+
`retry_after` string used to become `0` (`Number("")===0`) — an immediate, no-backoff retry.
|
|
332
|
+
It's now correctly `undefined`, in both `InvoError.retryAfter` and the retry layer.
|
|
333
|
+
- **Whitespace OTP codes rejected client-side.** `recoveryComplete`/`enrollmentVerify` now
|
|
334
|
+
reject a whitespace-only `code` before the network call, so it can't burn an attempt against
|
|
335
|
+
the attempt-capped endpoints (parity with the Python SDK).
|
|
336
|
+
- **Webhook verify uses `crypto.timingSafeEqual`** on the sync path (parity with Python's
|
|
337
|
+
`hmac.compare_digest`); the runtime-agnostic async/edge path keeps its string compare.
|
|
338
|
+
- **WebAuthn option mappers fail cleanly.** A malformed `register/begin` body now throws
|
|
339
|
+
`WEBAUTHN_OPTIONS_MALFORMED` (an `InvoError`) instead of a raw `TypeError`.
|
|
340
|
+
|
|
341
|
+
## [2.1.0] — 2026-07-02
|
|
342
|
+
|
|
343
|
+
**Passkey recovery ("lost or replaced my passkey").** Deleting a passkey on the device never
|
|
344
|
+
tells the server the key is gone, so re-enrollment was dead-ended by the anti-takeover gate
|
|
345
|
+
(`ENROLLMENT_REQUIRES_PROOF`) with nothing left to prove possession with. The backend shipped
|
|
346
|
+
a self-serve, possession-proofed recovery flow; this release wires the client side.
|
|
347
|
+
|
|
348
|
+
- `InvoClient.recoveryBegin()` — sends a one-time code to the phone/email on file
|
|
349
|
+
(`{ status: "sent", channels }`); `InvoClient.recoveryComplete(code)` — deactivates the
|
|
350
|
+
stale server-side passkey and authorizes a fresh enrollment
|
|
351
|
+
(`{ status: "recovered", deactivatedCount, next }`). Then retry the same `enrollPasskey()`.
|
|
352
|
+
- New `InvoError` classifiers: `isEnrollmentCodeInvalid`, `isPasskeyRecoveryCooldown`, and
|
|
353
|
+
`retryAfterAt` (the ISO timestamp on the 403 cooldown — distinct from the numeric
|
|
354
|
+
`retryAfter` throttle field). Bare `no_channel_on_file` / `rate_limited` error tokens are
|
|
355
|
+
now promoted to `err.code`.
|
|
356
|
+
- **24-hour money cooldown surfaced:** a recovery-enrolled passkey logs in and collects
|
|
357
|
+
funds immediately, but `approveSend`/`approveTransfer` throw 403
|
|
358
|
+
`PASSKEY_RECOVERY_COOLDOWN` for 24h (SIM-swap protection). Branch on
|
|
359
|
+
`isPasskeyRecoveryCooldown`, show the pause message with `retryAfterAt`, don't retry-loop.
|
|
360
|
+
- README: recovery subsection under Passkeys, incl. the password-manager cleanup tip for
|
|
361
|
+
"there is a problem saving your passkey" (stale orphan entry).
|
|
362
|
+
|
|
363
|
+
Additive, no breaking changes. Routes require SDK verification enabled for the tenant
|
|
364
|
+
(dark 503 otherwise).
|
|
365
|
+
|
|
366
|
+
## [2.0.0] — 2026-07-02
|
|
367
|
+
|
|
368
|
+
**BREAKING — `mintPlayerToken` now requires `playerPhone` (E.164).** Requested by the INVO
|
|
369
|
+
backend after a live incident: a player registered email-only couldn't receive a cross-game
|
|
370
|
+
transfer (incoming transfers are matched by phone) and never got the account-linking consent
|
|
371
|
+
SMS (also phone-triggered). The network identity is derived from **email + phone together**,
|
|
372
|
+
so the phone must be present on the FIRST registration call — attaching it later changes the
|
|
373
|
+
identity and forces device re-enrollment.
|
|
374
|
+
|
|
375
|
+
- `mintPlayerToken({ playerEmail, playerPhone })` — `playerPhone` is required and validated
|
|
376
|
+
as E.164 (`+15555550100`: leading `+`, country code, digits only) before any network call;
|
|
377
|
+
the body now posts `player_phone` alongside `player_email`.
|
|
378
|
+
- **Pending approval is surfaced, not an error to swallow:** minting with a phone that
|
|
379
|
+
already belongs to another INVO account (same person, new email) throws the existing
|
|
380
|
+
`isPhoneShareApprovalRequired` 409 — the phone holder got a consent SMS. New
|
|
381
|
+
`InvoError.phoneShareApprovalId` exposes the `approval_id` from the 409 body for the
|
|
382
|
+
`phoneShareApprove` OTP fallback. Docs updated to cover the registration path (previously
|
|
383
|
+
documented for claims only).
|
|
384
|
+
- README: new "Player registration (email + phone, required)" section; examples updated
|
|
385
|
+
(`proxy-server.ts` token route now rejects a phoneless actor with a clear 400).
|
|
386
|
+
|
|
387
|
+
**Migration:** collect the player's phone in your enrollment UI before the first
|
|
388
|
+
`mintPlayerToken` call and pass it as `playerPhone` in E.164. Handle the
|
|
389
|
+
`isPhoneShareApprovalRequired` error as a "pending approval" UI state.
|
|
390
|
+
|
|
391
|
+
## [1.2.1] — 2026-07-01
|
|
392
|
+
|
|
393
|
+
**Fix — browser "Illegal invocation".** The SDK invoked its fetch as `this.fetchImpl(...)`,
|
|
394
|
+
so the browser's native `fetch` ran with the wrong `this` and threw
|
|
395
|
+
`TypeError: Illegal invocation` — breaking every browser `InvoClient` read
|
|
396
|
+
(balance/destinations/pending) and the passkey ceremonies when using the default global
|
|
397
|
+
`fetch` (retries then made it slow on top). The fetch impl is now bound to `globalThis`
|
|
398
|
+
(harmless for a custom `fetch`). No API change. Node/tests were unaffected, which is why it
|
|
399
|
+
slipped through — added a `this`-sensitive regression test.
|
|
400
|
+
|
|
401
|
+
## [1.2.0] — 2026-07-01
|
|
402
|
+
|
|
403
|
+
Two more server-side capabilities on `InvoServer`.
|
|
404
|
+
|
|
405
|
+
- **Phone-share OTP handshake** — `phoneShareInitiate` / `phoneShareApprove` / `phoneShareStatus`
|
|
406
|
+
resolve a `409 PHONE_SHARE_APPROVAL_REQUIRED`. Unauthenticated (phone-owner-driven — no game
|
|
407
|
+
secret, no player token), relayed by a partner backend; after approve, re-issue the identical
|
|
408
|
+
original request (the grant is server-side + auto-consumed). Adds
|
|
409
|
+
`InvoError.isPhoneShareAlreadyApproved`.
|
|
410
|
+
- **Server-side `getDestinations`** — game-secret variant of the browser
|
|
411
|
+
`InvoClient.getDestinations`; pass `{ sourceGameId, direction }` (default `"transfer"`), rows
|
|
412
|
+
share the same `DestinationGame` shape.
|
|
413
|
+
|
|
414
|
+
## [1.1.0] — 2026-07-01
|
|
415
|
+
|
|
416
|
+
Four additive server-side flows on `InvoServer` (the SMS-PIN / claim-code / status /
|
|
417
|
+
guardian paths partners still need alongside the passkey path).
|
|
418
|
+
|
|
419
|
+
- **SMS-PIN completion** — `verifySmsTransfer` / `verifySmsSend` (for `verificationMethod: "sms"`).
|
|
420
|
+
- **Claim-by-code** — `claimTransfer` / `claimCurrency`, incl. the `needsAccountSelection`
|
|
421
|
+
multi-account disambiguation (a `200` with `candidates`, not an error).
|
|
422
|
+
- **Status reads** — `getTransferStatus` / `getSendStatus` (surface `verificationState`).
|
|
423
|
+
- **Guardian approval-status poll** — `getGuardianApprovalStatus` (poll a hold to `state`).
|
|
424
|
+
- New typed results (`SmsVerifyResult`, `ClaimResult`, `TransactionStatusResult`,
|
|
425
|
+
`GuardianApprovalStatusResult`) + `InvoError.isPhoneShareApprovalRequired`.
|
|
426
|
+
|
|
427
|
+
## [1.0.0] — 2026-07-01
|
|
428
|
+
|
|
429
|
+
**1.0 — stable.** The public API is now covered by a stability commitment: it follows
|
|
430
|
+
semver and no breaking change ships without a major bump + migration note. This is a
|
|
431
|
+
milestone release, **not a breaking change** — code on `0.8.x` continues to work unchanged.
|
|
432
|
+
|
|
433
|
+
Also in this release (docs + DX):
|
|
434
|
+
|
|
435
|
+
- **Integration modes** documented — **browser-direct** (default) and **behind your proxy**
|
|
436
|
+
(keep the INVO player token server-side via a custom `baseUrl`/`fetch`; no CORS or
|
|
437
|
+
security-posture change). Plus a token-bootstrap example and a CORS + RP-ID/origins
|
|
438
|
+
go-live checklist.
|
|
439
|
+
- `linkDevice` called out as the lowest-risk first adoption (additive, no refactor).
|
|
440
|
+
|
|
441
|
+
## [0.8.0] — 2026-07-01
|
|
442
|
+
|
|
443
|
+
Completes the **discovery layer** for send/transfer UIs.
|
|
444
|
+
|
|
445
|
+
- **`InvoClient.getBalance()`** (browser, player-token, `GET /api/sdk/balance`) — the
|
|
446
|
+
player's balances for the token's game: `balances[]` (`currencyId`, `currencyName`,
|
|
447
|
+
`currencySymbol`/`currencySymbolUrl` (nullable), `availableBalance`/`reservedBalance`/
|
|
448
|
+
`totalBalance` as decimal strings) plus `totalValue` / `currencyCount` / `hasFunds`. A
|
|
449
|
+
player who hasn't transacted here yet returns an empty `balances` array (a `200`, not an
|
|
450
|
+
error); `404 GAME_NOT_FOUND` throws.
|
|
451
|
+
- **`InvoServer.getLinkedIdentities({ playerEmail | playerPhone })`** (server-only,
|
|
452
|
+
game-secret) — a player's linked wallet identities (game-scoped). Provide one identifier
|
|
453
|
+
(phone wins if both); no in-game match returns `notFound: true` with empty `emails`
|
|
454
|
+
instead of throwing. **Returns first-party PII — never expose to the browser.**
|
|
455
|
+
|
|
456
|
+
## [0.7.0] — 2026-07-01
|
|
457
|
+
|
|
458
|
+
Start of the **discovery layer** for send/transfer UIs.
|
|
459
|
+
|
|
460
|
+
- **`InvoClient.getDestinations({ direction })`** — one player-token call
|
|
461
|
+
(`GET /api/sdk/destinations`) returns every game the player can send/transfer to, with
|
|
462
|
+
all display metadata **inline** (game name, icon, currency name/symbol, min/max transfer
|
|
463
|
+
limits) — no per-game lookup. Includes source game/currency info and `transferMode`
|
|
464
|
+
(`universal`/`linked` + `linkedGameIds`).
|
|
465
|
+
- _(Coming in 0.7.x: `getBalance` single-game player-token read; `getLinkedIdentities`
|
|
466
|
+
server-side.)_
|
|
467
|
+
|
|
468
|
+
## [0.6.0] — 2026-07-01
|
|
469
|
+
|
|
470
|
+
Three additive browser flows for partner front-ends, built to the live backend contracts.
|
|
471
|
+
|
|
472
|
+
- **`InvoClient.getPendingCollect()`** — the player's own pending-to-collect list
|
|
473
|
+
(player-token `GET /api/sdk/transfers/pending`), PII-free. Each row's `kind`
|
|
474
|
+
(`identity_gate` → `approve*`, `receiving_confirm` → `confirmReceipt*`) tells you the
|
|
475
|
+
action; typed fields incl. `held` / `holdReason` / `stepUpRequired`.
|
|
476
|
+
- **First-enrollment OTP grant** — `enrollmentBegin()` / `enrollmentVerify(code)` for
|
|
477
|
+
`ENROLLMENT_REQUIRES_AUTHORIZATION` (send OTP to phone+email, verify, then retry the
|
|
478
|
+
same `enrollPasskey()` — the server grant is auto-consumed). New `InvoError` helpers
|
|
479
|
+
`isEnrollmentAuthorizationRequired` / `isEnrollmentProofRequired`.
|
|
480
|
+
- **Typed approve/confirm holds** — `approve*`/`confirmReceipt*` now surface a typed
|
|
481
|
+
`holdReason` (from `error_code ?? code`) on HTTP 202 holds, plus `risk` /
|
|
482
|
+
`guardianApproval` / `pollEndpoint` on approve. `RECIPIENT_IDENTITY_PENDING` correctly
|
|
483
|
+
surfaces on confirm-receipt. Success carries no `holdReason`.
|
|
484
|
+
|
|
485
|
+
## [0.5.0] — 2026-07-01
|
|
486
|
+
|
|
487
|
+
Support partner `metadata` end-to-end on the purchase flow (additive, backward-compatible).
|
|
488
|
+
|
|
489
|
+
- **`PurchaseCompletedData.metadata?`** — the `purchase.completed` webhook now echoes your
|
|
490
|
+
metadata back (all rails); `event.data.metadata` is typed.
|
|
491
|
+
- **`purchaseCurrency`** now accepts and forwards `metadata` (the direct `/purchase-currency`
|
|
492
|
+
endpoint accepts it too, matching `createCheckout`).
|
|
493
|
+
|
|
494
|
+
## [0.4.2] — 2026-06-30
|
|
495
|
+
|
|
496
|
+
Fixes from an independent line-by-line audit against the live backend.
|
|
497
|
+
|
|
498
|
+
- **`linkDevice` now works.** `device/link/webauthn/begin` returns a wrapped
|
|
499
|
+
`{ link_id, options }` body (challenge nested under `options`) and binds the
|
|
500
|
+
challenge to a server-generated `link_id`. The client now unwraps `options` and
|
|
501
|
+
echoes the server's `link_id` to `/complete` (it previously threw on an undefined
|
|
502
|
+
challenge and sent the wrong id).
|
|
503
|
+
- **`InvoError.code` is now populated for the direct purchase rail + guardian flows.**
|
|
504
|
+
`errorFromResponse` reads `error_code` (SecureErrorHandler + `/purchase-currency`)
|
|
505
|
+
in addition to `code`, and promotes known no-code tokens (`flow_paused`,
|
|
506
|
+
`spending_limit_exceeded`, `receiver_not_enrolled_use_claim_code`) to `.code`. Fixes
|
|
507
|
+
`isDuplicateRequest` on the direct rail.
|
|
508
|
+
- **Guardian/minor routing.** The 202 guardian body also carries
|
|
509
|
+
`verification_method:"sms"`; the SDK now suppresses it (reports
|
|
510
|
+
`verificationMethod: undefined`) so a guardian-pending minor isn't routed into the
|
|
511
|
+
SMS-PIN UI. README example reordered to branch on `guardianApproval` first.
|
|
512
|
+
|
|
513
|
+
## [0.4.1] — 2026-06-30
|
|
514
|
+
|
|
515
|
+
Docs only — replaced the README's internal-leaking "Deployment prerequisites"
|
|
516
|
+
(backend flag names, DB columns, gating mechanics) with a partner-facing
|
|
517
|
+
"Before you go live"; republished so the npm page README is current.
|
|
518
|
+
|
|
519
|
+
## [0.4.0] — 2026-06-30
|
|
520
|
+
|
|
521
|
+
Additive release — more server reads, edge-ready webhooks, cancellation, and tooling.
|
|
522
|
+
|
|
523
|
+
- **`getInboundPending({ playerEmail | playerPhone })`** — live, unclaimed inbound
|
|
524
|
+
sends/transfers for a player (the source of truth behind the "you have X to collect"
|
|
525
|
+
badge; pairs with `transfer.claim_pending`).
|
|
526
|
+
- **`verifyWebhookAsync`** — Web Crypto variant of `verifyWebhook` that runs on
|
|
527
|
+
Cloudflare Workers / Deno / Vercel+Netlify Edge / Bun / browsers; and
|
|
528
|
+
**`createWebhookHandler`** — a zero-dep Fetch-API `(Request) => Promise<Response>`
|
|
529
|
+
webhook route handler (Next.js App Router, Workers, Deno, Hono, Bun).
|
|
530
|
+
- **`iterateItemPurchaseHistory`** — async iterator that pages through a player's
|
|
531
|
+
full item-purchase history.
|
|
532
|
+
- **Per-call `AbortSignal`** — every method accepts an optional `{ signal }`; an
|
|
533
|
+
aborted call throws `InvoError` code `ABORTED` and is never retried.
|
|
534
|
+
- **Tooling**: ESLint (+ lint in CI), changesets release automation, `SECURITY.md`,
|
|
535
|
+
and `CODEOWNERS`.
|
|
536
|
+
|
|
537
|
+
## [0.3.0] — 2026-06-30
|
|
538
|
+
|
|
539
|
+
Additive release — new server capabilities plus transport resilience/observability.
|
|
540
|
+
|
|
541
|
+
- **Webhook verification** (`/server`): `verifyWebhook(rawBody, signatureHeader, secret | secrets, opts?)`
|
|
542
|
+
— constant-time HMAC-SHA256 over `${t}.${rawBody}`, 5-minute replay window,
|
|
543
|
+
multi-secret rotation; returns a typed `InvoWebhookEvent` discriminated union
|
|
544
|
+
(`purchase.*`, `item.purchased`, `transfer.*`, `payout.status_changed`, `webhook.test`).
|
|
545
|
+
Throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` /
|
|
546
|
+
`WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`). Server-only; the browser bundle
|
|
547
|
+
stays crypto-free. Independently security-audited.
|
|
548
|
+
- **`getPlayerBalance({ playerEmail | playerId })`** (`/server`): typed `player` / `balances` / `summary`.
|
|
549
|
+
- **Automatic retries**: network errors/timeouts, `429` (honoring `retry_after`), and
|
|
550
|
+
`5xx` are retried with exponential backoff + jitter. New config `maxRetries`
|
|
551
|
+
(default 2, `0` disables) and `retryBaseDelayMs` (default 250).
|
|
552
|
+
- **Observability hooks**: optional `onRequest` / `onResponse` / `onError` on both
|
|
553
|
+
entries (best-effort/non-throwing); `InvoError.requestId` carries the backend
|
|
554
|
+
request id for support/tracing.
|
|
555
|
+
- **Typed reads**: `confirmPayment` → `ConfirmPaymentResult`; `getOrderDetails` /
|
|
556
|
+
`getItemOrderDetails` → `OrderDetailsResult`; `getItemPurchaseHistory` →
|
|
557
|
+
`ItemHistoryResult` (previously untyped `Record`). All keep `raw`.
|
|
558
|
+
- **Light validation**: `mintPlayerToken` and `createCheckout` require a non-blank
|
|
559
|
+
`playerEmail` (throws `INVALID_INPUT` before the network call).
|
|
560
|
+
- **License**: `package.json` `license` is now `SEE LICENSE IN LICENSE` (was
|
|
561
|
+
`UNLICENSED`); `LICENSE` rewritten as an explicit install-and-use grant for
|
|
562
|
+
building INVO integrations.
|
|
563
|
+
|
|
564
|
+
## [0.2.1] — 2026-06-30
|
|
565
|
+
|
|
566
|
+
Docs only — no code change (republished so the npm page README is current).
|
|
567
|
+
|
|
568
|
+
- Rewrote the README into a complete integration/deployment guide: capability
|
|
569
|
+
overview, architecture, deployment prerequisites, per-flow sections (currency
|
|
570
|
+
purchase, item purchase, sends, transfers, passkeys), webhooks, errors, and a
|
|
571
|
+
full API reference for both entries.
|
|
572
|
+
- Added INVO console onboarding: `https://console.invo.network` (production) and
|
|
573
|
+
`https://dev.console.invo.network` (testing/sandbox), mapped to their API base URLs.
|
|
574
|
+
|
|
575
|
+
## [0.2.0] — 2026-06-30
|
|
576
|
+
|
|
577
|
+
Adds **item purchase** (spend existing game currency on an in-game item, §4.8) — an
|
|
578
|
+
additive, server-only surface.
|
|
579
|
+
|
|
580
|
+
- `InvoServer` (`/server`): `purchaseItem`, `getItemPurchaseHistory`, `getItemOrderDetails`.
|
|
581
|
+
- Server-side, game-secret auth — no passkey, no real money, no payment rail (it's a
|
|
582
|
+
balance debit). Grant the item off the `item.purchased` webhook.
|
|
583
|
+
- Client-side guards: required fields (trim-checked), `itemQuantity` integer `1..1000`,
|
|
584
|
+
prices `> 0` and `<= 999999.99` (magnitude-safe 2-decimal check), and
|
|
585
|
+
`totalPrice == unitPrice × itemQuantity (±0.01)` compared in integer cents.
|
|
586
|
+
- Load-bearing response fields (`transaction_id`, `order_id`) throw `INVALID_RESPONSE`
|
|
587
|
+
if missing on a 200.
|
|
588
|
+
- `InvoError` helpers: `isInsufficientBalance` (gated to 400; not the `429` throttle),
|
|
589
|
+
`isDuplicateRequest` (409), `retryAfter` (numeric or string `retry_after`); all
|
|
590
|
+
null-safe against non-JSON error bodies.
|
|
591
|
+
- Independently audited (2 agents) against handoff doc §4.8/§6/§8; contract verified,
|
|
592
|
+
error-classification edge cases fixed.
|
|
593
|
+
|
|
594
|
+
## [0.1.0] — 2026-06-30
|
|
595
|
+
|
|
596
|
+
Initial scaffold.
|
|
597
|
+
|
|
598
|
+
- `InvoServer` (`/server`): `mintPlayerToken`, `initiateSend`, `initiateTransfer`,
|
|
599
|
+
`createCheckout`, `purchaseCurrency`, `confirmPayment`, `getOrderDetails`.
|
|
600
|
+
- Client-side purchase guards (§4.7): USD amount `0 < x ≤ 999.99`, required
|
|
601
|
+
`purchaseReference`, and `rail:"steam"` rejected before the network call
|
|
602
|
+
(`INVALID_INPUT` / `MISSING_PURCHASE_REFERENCE` / `WRONG_RAIL_ENDPOINT`).
|
|
603
|
+
- `InvoClient` (browser): `enrollPasskey`, `approveSend`/`approveTransfer`,
|
|
604
|
+
`confirmReceiptSend`/`confirmReceiptTransfer`, and `linkDevice` for the
|
|
605
|
+
interchangeable-methods flow (§4.6).
|
|
606
|
+
- Optional `refreshToken` hook: transparently re-mints and retries once on
|
|
607
|
+
`SDK_TOKEN_EXPIRED` (§11.2).
|
|
608
|
+
- Shared: typed `InvoError`, isomorphic HTTP client, WebAuthn JSON⇄binary helpers.
|
|
609
|
+
- Tests: HTTP layer, server request mapping + purchase guards, browser client
|
|
610
|
+
flows (enroll/approve/link/token-refresh), and WebAuthn serialization.
|
|
611
|
+
- Contracts extracted + auditor-verified against the INVO backend.
|
|
612
|
+
|
|
613
|
+
### Hardening (independent red-team pass)
|
|
614
|
+
|
|
615
|
+
- **Guardian/minor `202` path no longer mismapped to `verificationMethod:"sms"`** —
|
|
616
|
+
`initiateSend`/`initiateTransfer` now return `verificationMethod: undefined` and a
|
|
617
|
+
`guardianApproval` block on the guardian path, so callers don't route into the
|
|
618
|
+
PIN UI by mistake (§4.3).
|
|
619
|
+
- `usdAmount` validation tightened: rejects non-plain-decimal strings
|
|
620
|
+
(`"0x10"`, `"1e2"`, whitespace) and >2 decimal places before any network call.
|
|
621
|
+
- Load-bearing response fields (`token`, `checkout_url`) now throw `INVALID_RESPONSE`
|
|
622
|
+
instead of silently surfacing as empty strings.
|
|
623
|
+
- `getOrderDetails` requires at least one of `orderId`/`transactionId`.
|
|
624
|
+
- Token refresh now re-runs the **whole** passkey ceremony on `SDK_TOKEN_EXPIRED`
|
|
625
|
+
(never replays a single-use assertion) and single-flights concurrent refreshes.
|
|
626
|
+
- `baseUrl` must be `https://` (localhost exempt) so the token/secret can't travel
|
|
627
|
+
in cleartext.
|
|
628
|
+
- Published tarball excludes sourcemaps (no proprietary source shipped).
|