@invonetwork/web-sdk 3.6.0 → 3.8.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,124 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Subscriptions are a first-class server surface, on both rails, with the card capture and the
8
+ sandbox clock tools beside them.
9
+
10
+ New on `InvoServer`:
11
+
12
+ - **`invo.subscriptions`**: `create` (card rail; charges the first period before answering,
13
+ idempotent on `clientRequestId`, a repeat is a typed `idempotentReplay: true` result),
14
+ `get`, `listForPlayer`, `cancel` (an already-terminal row is a 200 `alreadyCanceled`, never
15
+ thrown), `changeAmount` (staged for the next renewal), `setPaymentMethod`, `refund`
16
+ (idempotent; the receipt replays), `steamInit` and `steamFinalize` (Steam rail;
17
+ `alreadyProcessed` is a result, not an error).
18
+ - **`invo.cards`**: `beginSetup` / `confirmSetup` / `list`: the off-session card capture a
19
+ card subscription needs. The hosted checkout does not save a card for subscriptions.
20
+ - **`invo.sandbox.subscriptions`**: `advanceClock` / `forceRenewal` / `forceFailure` /
21
+ `forceAuthChallenge`. These post to `/subscriptions/<id>/...` **relative to the sandbox
22
+ base URL, not under `/api`**, and send `X-Sandbox-Clock-Key` from the new
23
+ `sandboxClockKey` config; a missing key throws before the network.
24
+
25
+ Typed results: `SubscriptionResult` (the subscription object with its TWO clocks,
26
+ `firstCharge` with `paidPeriodSeq`, `card`, `idempotentReplay`), `FirstCharge` (`paid` |
27
+ `requires_action` | `skipped_trial` | `failed` | `pending` | `pending_authorization`),
28
+ `SteamInitResult` (`steamOrderId` for the client callback, `amountCoins`, `pendingReuse`),
29
+ `CancelResult`, `ChangeAmountResult`, `RefundResult`, `CardSetupResult`, `SandboxClockResult`
30
+ (`engineStats`), and typed `data` for all seven `subscription.*` webhook events.
31
+
32
+ Error classifiers: `isActiveSubscriptionExists` (+ `existingSubscriptionId`),
33
+ `isIdempotentReplayMismatch` (+ `mismatchedFields`), `isSteamReauthorizationRequired`,
34
+ `isNotACardSubscription`, `isSteamChannelRequired`, `isSubscriptionTerminal`,
35
+ `isNotAuthorized`, `isSandboxClockUnauthorized`, `isSteamRefundNotSupported`, `isFlowPaused`,
36
+ `isGameNotLive`; `isSteamAuthorizationPending` now also covers the subscription 409.
37
+
38
+ Also: the server `User-Agent` version now derives from the package version (it had read
39
+ `3.0.0` since 3.0.0), pinned by a test.
40
+
41
+ ## 3.7.0
42
+
43
+ ### Minor Changes
44
+
45
+ - Device approval grant (RFC 8628) is now a first-class server surface — including **the
46
+ step that moves the money**.
47
+
48
+ An integrator followed the README, polled a grant to `approved`, and stopped. Nothing
49
+ moved: an approved grant is a _factor_, and the transaction sat at
50
+ `pending_pin_verification` until it expired and was refunded. The README's section ended
51
+ at the poll and neither package had a method for the step after it. Both halves of that
52
+ are fixed here.
53
+
54
+ New on `InvoServer` (all authenticate with the **player token** — on a console the game
55
+ server holds the token it minted, and the game secret is never sent):
56
+
57
+ - `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` → the RFC 8628
58
+ §3.2 grant (`deviceCode`, `userCode`, `verificationUriComplete`, `expiresIn`,
59
+ `interval`, `channel`). `channel: "popup"` is refused before the network — it is
60
+ browser-only (`InvoClient.approveHosted`).
61
+ - `pollDeviceApproval({ playerToken, deviceCode })` → a typed outcome
62
+ (`authorization_pending` / `slow_down` / `approved` / `access_denied` /
63
+ `expired_token`), plus the `enrollment` object while a first-time phone waits on the
64
+ game screen. `invalid_grant` throws.
65
+ - `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` → answers the
66
+ on-screen match-code prompt (`"approve"` | `"deny"`).
67
+ - **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })` — the money
68
+ step.** Routes by flow: `send` → `/api/sdk/send/{id}/approve`, `transfer` →
69
+ `/api/sdk/transfers/{id}/approve`, `send_receipt` →
70
+ `/api/sdk/send/{id}/confirm-receipt`, `transfer_receipt` →
71
+ `/api/sdk/transfers/{id}/confirm-receipt`. Never auto-retried.
72
+ - `completeDeviceApproval(...)` — convenience loop: polls honouring `interval` and
73
+ `slow_down`, surfaces the enrollment prompt, then calls `approveWithDeviceCode`.
74
+
75
+ **`TRANSACTION_NOT_PENDING` is a result, not a throw.** `approveWithDeviceCode` returns
76
+ `{ status: "not_pending", alreadySettled, currentStatus }` so "your earlier attempt
77
+ already landed" is distinguishable from a real refusal **without string-matching** — the
78
+ difference between "the guard worked" and "her currency is stuck". Every other refusal
79
+ stays a typed thrown `InvoError`.
80
+
81
+ `alreadySettled` is **flow-aware and fails closed**. The four endpoints gate on different
82
+ status sets — the sender approves accept `pending_pin_verification` /
83
+ `pending_verification`, the two receipt endpoints accept `pending_claim` / `verified` — so
84
+ a receipt settle landing on `pending_pin_verification` means the SENDER has not approved
85
+ yet (possibly held at a guardian 202). That is _before_ the step, not past it, and calling
86
+ it settled would tell a game to hand over goods for value never credited. It is an
87
+ allow-list per flow rather than a "not expired/failed" deny-list, so a status INVO adds
88
+ later answers `alreadySettled: false` with `currentStatus` set — go read the transaction —
89
+ instead of defaulting to "the money moved" in already-deployed copies of this SDK.
90
+
91
+ Older backend bodies that carried only the message ("Transaction not pending…", "…cannot
92
+ be confirmed…") with no machine code are matched too, but narrowly: HTTP 400, one of those
93
+ two phrases, **and** a readable `(current status: …)` / `(status: …)` clause. "cannot be
94
+ confirmed" is ordinary English, so a phrase match alone can never assert that money moved.
95
+
96
+ New `InvoError` predicates: `isTransactionNotPending`, `currentTransactionStatus`,
97
+ `isDeviceApprovalNotApproved`, `isDeviceApprovalAlreadyPending`,
98
+ `deviceApprovalExpiresAt`, `isSettleFault`, `errorRef`. The RFC 8628 §3.5 tokens are
99
+ promoted onto `err.code`.
100
+
101
+ Two safety fixes in `completeDeviceApproval`: `transactionId` is validated **before** the
102
+ loop (an empty id used to poll for minutes, let the player approve, and only then throw —
103
+ an approved grant with nothing settled), and the `respond` callable handed to
104
+ `onEnrollment` now resolves quietly for every "the prompt is moot" refusal
105
+ (`expired_token`, `invalid_grant`, and the two enrollment 409s) instead of rejecting. A
106
+ prompt on a TV routinely outlives its ten-minute grant, callers fire `respond` without
107
+ awaiting it, and an unhandled rejection exits a Node process.
108
+
109
+ README: the console section is rewritten around begin → show the QR → poll → **call
110
+ `approveWithDeviceCode`** → webhooks, with the supersede-vs-409 begin semantics corrected
111
+ and "consumed when used" replaced by _when_ the code is spent. A new top-level **Sends and
112
+ transfers, stage by stage** section covers both flows and both sides with a
113
+ call-order table, an error table, and a common-mistakes box led by "polling to `approved`
114
+ and stopping". The error tables now also carry the receipt-flow-only refusals a console
115
+ recipient meets (`receiver_not_enrolled_use_claim_code`, `not_intended_receiver`, the
116
+ phone-share 409, `RECIPIENT_IDENTITY_PENDING` / `_DECLINED`) and a warning that a settle
117
+ FAILURE is ambiguous about the money — INVO commits and then reads the transaction back to
118
+ build its 200, so a `*_FAILED` or a timeout can both describe money that already moved:
119
+ read the transaction status before telling the player it failed, and never auto-start a
120
+ replacement. SMS is now confined to a clearly-labelled legacy-fallback subsection.
121
+
3
122
  ## 3.6.0
4
123
 
5
124
  ### Minor Changes