@invonetwork/web-sdk 3.6.0 → 3.7.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 CHANGED
@@ -1,5 +1,86 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Device approval grant (RFC 8628) is now a first-class server surface — including **the
8
+ step that moves the money**.
9
+
10
+ An integrator followed the README, polled a grant to `approved`, and stopped. Nothing
11
+ moved: an approved grant is a _factor_, and the transaction sat at
12
+ `pending_pin_verification` until it expired and was refunded. The README's section ended
13
+ at the poll and neither package had a method for the step after it. Both halves of that
14
+ are fixed here.
15
+
16
+ New on `InvoServer` (all authenticate with the **player token** — on a console the game
17
+ server holds the token it minted, and the game secret is never sent):
18
+
19
+ - `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` → the RFC 8628
20
+ §3.2 grant (`deviceCode`, `userCode`, `verificationUriComplete`, `expiresIn`,
21
+ `interval`, `channel`). `channel: "popup"` is refused before the network — it is
22
+ browser-only (`InvoClient.approveHosted`).
23
+ - `pollDeviceApproval({ playerToken, deviceCode })` → a typed outcome
24
+ (`authorization_pending` / `slow_down` / `approved` / `access_denied` /
25
+ `expired_token`), plus the `enrollment` object while a first-time phone waits on the
26
+ game screen. `invalid_grant` throws.
27
+ - `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` → answers the
28
+ on-screen match-code prompt (`"approve"` | `"deny"`).
29
+ - **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })` — the money
30
+ step.** Routes by flow: `send` → `/api/sdk/send/{id}/approve`, `transfer` →
31
+ `/api/sdk/transfers/{id}/approve`, `send_receipt` →
32
+ `/api/sdk/send/{id}/confirm-receipt`, `transfer_receipt` →
33
+ `/api/sdk/transfers/{id}/confirm-receipt`. Never auto-retried.
34
+ - `completeDeviceApproval(...)` — convenience loop: polls honouring `interval` and
35
+ `slow_down`, surfaces the enrollment prompt, then calls `approveWithDeviceCode`.
36
+
37
+ **`TRANSACTION_NOT_PENDING` is a result, not a throw.** `approveWithDeviceCode` returns
38
+ `{ status: "not_pending", alreadySettled, currentStatus }` so "your earlier attempt
39
+ already landed" is distinguishable from a real refusal **without string-matching** — the
40
+ difference between "the guard worked" and "her currency is stuck". Every other refusal
41
+ stays a typed thrown `InvoError`.
42
+
43
+ `alreadySettled` is **flow-aware and fails closed**. The four endpoints gate on different
44
+ status sets — the sender approves accept `pending_pin_verification` /
45
+ `pending_verification`, the two receipt endpoints accept `pending_claim` / `verified` — so
46
+ a receipt settle landing on `pending_pin_verification` means the SENDER has not approved
47
+ yet (possibly held at a guardian 202). That is _before_ the step, not past it, and calling
48
+ it settled would tell a game to hand over goods for value never credited. It is an
49
+ allow-list per flow rather than a "not expired/failed" deny-list, so a status INVO adds
50
+ later answers `alreadySettled: false` with `currentStatus` set — go read the transaction —
51
+ instead of defaulting to "the money moved" in already-deployed copies of this SDK.
52
+
53
+ Older backend bodies that carried only the message ("Transaction not pending…", "…cannot
54
+ be confirmed…") with no machine code are matched too, but narrowly: HTTP 400, one of those
55
+ two phrases, **and** a readable `(current status: …)` / `(status: …)` clause. "cannot be
56
+ confirmed" is ordinary English, so a phrase match alone can never assert that money moved.
57
+
58
+ New `InvoError` predicates: `isTransactionNotPending`, `currentTransactionStatus`,
59
+ `isDeviceApprovalNotApproved`, `isDeviceApprovalAlreadyPending`,
60
+ `deviceApprovalExpiresAt`, `isSettleFault`, `errorRef`. The RFC 8628 §3.5 tokens are
61
+ promoted onto `err.code`.
62
+
63
+ Two safety fixes in `completeDeviceApproval`: `transactionId` is validated **before** the
64
+ loop (an empty id used to poll for minutes, let the player approve, and only then throw —
65
+ an approved grant with nothing settled), and the `respond` callable handed to
66
+ `onEnrollment` now resolves quietly for every "the prompt is moot" refusal
67
+ (`expired_token`, `invalid_grant`, and the two enrollment 409s) instead of rejecting. A
68
+ prompt on a TV routinely outlives its ten-minute grant, callers fire `respond` without
69
+ awaiting it, and an unhandled rejection exits a Node process.
70
+
71
+ README: the console section is rewritten around begin → show the QR → poll → **call
72
+ `approveWithDeviceCode`** → webhooks, with the supersede-vs-409 begin semantics corrected
73
+ and "consumed when used" replaced by _when_ the code is spent. A new top-level **Sends and
74
+ transfers, stage by stage** section covers both flows and both sides with a
75
+ call-order table, an error table, and a common-mistakes box led by "polling to `approved`
76
+ and stopping". The error tables now also carry the receipt-flow-only refusals a console
77
+ recipient meets (`receiver_not_enrolled_use_claim_code`, `not_intended_receiver`, the
78
+ phone-share 409, `RECIPIENT_IDENTITY_PENDING` / `_DECLINED`) and a warning that a settle
79
+ FAILURE is ambiguous about the money — INVO commits and then reads the transaction back to
80
+ build its 200, so a `*_FAILED` or a timeout can both describe money that already moved:
81
+ read the transaction status before telling the player it failed, and never auto-start a
82
+ replacement. SMS is now confined to a clearly-labelled legacy-fallback subsection.
83
+
3
84
  ## 3.6.0
4
85
 
5
86
  ### Minor Changes