@invonetwork/web-sdk 3.12.0 → 3.12.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 +14 -0
- package/README.md +34 -2
- package/dist/server.cjs +4 -3
- package/dist/server.d.cts +4 -3
- package/dist/server.d.ts +4 -3
- package/dist/server.js +4 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.12.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Docs: subscription packages.
|
|
8
|
+
|
|
9
|
+
The README's Subscriptions section gains a **Subscription packages** part. A package (the API calls it a plan) is what a developer sells: a name, a price, a billing interval and the `item_id` the game checks. Packages are created, edited, closed and reopened in the INVO dashboard with the developer's own sign-in, never with the game secret or a player token, so this SDK does not wrap them and has no `packages` or `plans` namespace. That is deliberate.
|
|
10
|
+
|
|
11
|
+
Nothing about an integration changes. `server.subscriptions.create(...)` and `steamInit(...)` still subscribe a member to an `itemId`, webhooks carry the same payloads, and entitlement still comes from `subscription.renewed`. A package's subscriber counts and monthly revenue are measured per title and `item_id`, so a new package immediately shows the members already subscribed to its item. The section also covers the two counts (`subscriber_count` on basis `active`, `live_subscriber_count` on basis `live`), who a price change applies to, and that closing a package cancels nobody. Full guide: https://docs.invo.network/docs/subscriptions-packages/
|
|
12
|
+
|
|
13
|
+
Doc correction: the subscription refund daily limit. The README and the `subscriptions.refund` JSDoc said a game's daily self-serve refund limit is $500 by default. It no longer is: by default the limit is never lower than the largest single subscription charge (`25000.00` USD today), so any single period can always be refunded on its own, and if INVO raises the per-charge maximum the limit rises with it. INVO can still set a specific limit for one game, which applies as set, even if lower. Everything else about refunds is unchanged: reaching the limit exactly still runs, going over it answers HTTP 202 `pending_approval`, and approved requests do not count toward the day. The sandbox recipe now says how to see a 202 (ask INVO for a low limit on the sandbox game).
|
|
14
|
+
|
|
15
|
+
Documentation only. No export was added, removed, renamed or retyped.
|
|
16
|
+
|
|
3
17
|
## 3.12.0
|
|
4
18
|
|
|
5
19
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -102,6 +102,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
102
102
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
103
103
|
- [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
|
|
104
104
|
- [Cards for subscriptions](#cards-for-subscriptions)
|
|
105
|
+
- [Subscription packages](#subscription-packages)
|
|
105
106
|
- [Player balance](#player-balance)
|
|
106
107
|
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
107
108
|
- [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
|
|
@@ -1025,7 +1026,7 @@ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED"
|
|
|
1025
1026
|
|
|
1026
1027
|
1. **Enabled per game.** On by default for every game; INVO can turn them off for a game (`403 REFUNDS_NOT_ENABLED`, `err.isRefundsNotEnabled`).
|
|
1027
1028
|
2. **30 days.** A period can be refunded for 30 days after it was charged (`409 REFUND_WINDOW_CLOSED`, `err.isRefundWindowClosed`, with `err.periodChargedAt`, `err.refundWindowDays`, `err.refundWindowClosedAt`). A retry of a refund that already ran still returns its receipt.
|
|
1028
|
-
3. **A daily limit per game** (per UTC day
|
|
1029
|
+
3. **A daily limit per game** (per UTC day, in sandbox and production). By default it is never lower than the largest single subscription charge (`25000.00` USD today), so any single period can always be refunded on its own; if INVO raises the per-charge maximum, the limit rises with it. INVO can set a specific limit for your game, which applies as set, even if lower. A refund that would exceed it does **not** run: the call answers HTTP 202 with `status: "pending_approval"` and `requestId` (check with `isRefundPendingApproval(r)`), carrying every receipt field with nothing moved, and INVO reviews the request. Approved: the refund runs as if your call had (the 30 days count from when you asked), you receive `subscription.refunded`, `subscription.refund_approved` and, for a full refund, `subscription.canceled`, sent together and may arrive in any order, and a retry of your key returns the receipt. Rejected: you receive `subscription.refund_rejected` with `decision_reason`, and your key throws `409 REFUND_REQUEST_REJECTED` (`err.isRefundRequestRejected`); use a new key to try again. While a request is pending, other refunds of that period throw `409 REFUND_REQUEST_PENDING` (`err.isRefundRequestPending`, the id on `err.refundRequestId`). The same key returns the same 202 with `idempotentReplay: true`.
|
|
1029
1030
|
4. **A reason.** Recommended now, required after a notice period. Without it the refund still runs (`reason: null`) and `warnings` carries `REASON_RECOMMENDED`; a reason longer than 500 characters is cut, with `REASON_TRUNCATED` (the SDK refuses one over 500 before the network).
|
|
1030
1031
|
|
|
1031
1032
|
Your developer console session can list your refund requests (`GET /api/dev/subscriptions/refund-requests?status=pending|approved|rejected|all`); that console read is not wrapped by this SDK, which authenticates with the game key.
|
|
@@ -1053,7 +1054,7 @@ await sb.forceAuthChallenge(id); // moves it to awaiting_authenticati
|
|
|
1053
1054
|
>
|
|
1054
1055
|
> **Second credential.** Every clock call sends `X-Game-Secret-Key` *and* `X-Sandbox-Clock-Key`, a separate per-game key (`ivclk_...`). Get it from the sandbox console: open the game, **Game Settings**, the **"Sandbox clock key"** card (generated the first time you reveal it; the same card rotates it, with a 7-day grace). Pass it as `sandboxClockKey`; a missing key throws `INVALID_INPUT` before the network, a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`). Keep it out of game clients and source control. None of these calls is auto-retried: each one moves the clock or runs the engine.
|
|
1055
1056
|
|
|
1056
|
-
**Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.createSetupSession` (open `cardSetupUrl` in a browser; the sandbox page runs against the test-mode card processor, so enter a test card there, never a real one; the sandbox recipe on the public docs site is at https://docs.invo.network/docs/subscriptions-sandbox), or, on the processor-bound path, with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period (a full refund cancels the subscription, so refund a partial amount first if you want to keep testing it; the
|
|
1057
|
+
**Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.createSetupSession` (open `cardSetupUrl` in a browser; the sandbox page runs against the test-mode card processor, so enter a test card there, never a real one; the sandbox recipe on the public docs site is at https://docs.invo.network/docs/subscriptions-sandbox), or, on the processor-bound path, with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period (a full refund cancels the subscription, so refund a partial amount first if you want to keep testing it; the daily limit applies in sandbox too, and a refund over it answers `pending_approval`; at the default limit a single period always runs, so to see a `pending_approval` ask INVO to set a low limit for your sandbox game); and create one with `trialDays: 7` to see `skipped_trial` convert.
|
|
1057
1058
|
|
|
1058
1059
|
**Steam recipe.** In sandbox `steamFinalize` **does not call Steam**: it auto-approves a stand-in agreement and runs the real settlement (`fin.sandboxAutoApproved === true`), and `forceRenewal` treats the Steam charge as captured (`engineStats.steam_charged: 1, sandbox_synthetic: 1`). So sandbox proves INVO's currency path (coins, split, events, dunning), not Valve's charge: do one real Steam sandbox authorisation before launch. Credit the wallet above the price (a sandbox purchase), advance + force, and expect `funding.steam_charged_usd: "0.00"`.
|
|
1059
1060
|
|
|
@@ -1114,6 +1115,37 @@ Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.16
|
|
|
1114
1115
|
15. **Steam: finalize is your call**, the member has 24 hours, `web` needs `playerIp` and a top-level window, match the client callback on `steamOrderId`, show `amountCoins` (country-dependent, fixed at init), and `split.total_usd` on a Steam renewal is *not* the price.
|
|
1115
1116
|
16. **Sandbox does not exercise Valve.** `sandboxAutoApproved: true` means the charge was simulated.
|
|
1116
1117
|
|
|
1118
|
+
### Subscription packages
|
|
1119
|
+
|
|
1120
|
+
A package (the API calls it a plan) is what you sell: a name, a price, a billing interval and the
|
|
1121
|
+
`item_id` your game checks. Full guide:
|
|
1122
|
+
[docs.invo.network/docs/subscriptions-packages](https://docs.invo.network/docs/subscriptions-packages/).
|
|
1123
|
+
|
|
1124
|
+
- **Packages are managed in your INVO dashboard, not in this SDK.** Creating, editing, closing and
|
|
1125
|
+
reopening a package is authenticated by your dashboard sign-in, not by your game secret or a
|
|
1126
|
+
player token. This SDK has no `packages` or `plans` namespace, by design: a game secret on your
|
|
1127
|
+
server should never be able to reprice what your members pay.
|
|
1128
|
+
- **Your integration does not change.** `server.subscriptions.create(...)` and `server.subscriptions.steamInit(...)` still subscribe a member to an
|
|
1129
|
+
`itemId` with your game secret. Webhooks carry the same payloads, and entitlement still comes from
|
|
1130
|
+
`subscription.renewed`, keyed on `item_id`.
|
|
1131
|
+
- **The `item_id` is the link.** A package describes one `item_id` in one title, and only one live
|
|
1132
|
+
package may hold a given `item_id` per title (a second is refused with `ITEM_ID_IN_USE`).
|
|
1133
|
+
- **A new package adopts the members already on its item.** Subscriber counts and the monthly
|
|
1134
|
+
revenue figure are measured per title and `item_id`, so a package created over existing members
|
|
1135
|
+
shows them immediately. There is no linking step, and their subscriptions do not change.
|
|
1136
|
+
- **Two counts.** `subscriber_count` (basis `active`) is members being charged.
|
|
1137
|
+
`live_subscriber_count` (basis `live`) is everyone still subscribed, including trials and members
|
|
1138
|
+
cancelling at period end. A package whose members are all in trial shows `0` and `400`. Both are
|
|
1139
|
+
correct.
|
|
1140
|
+
- **A price change must say who it applies to.** New subscribers only is available now, and current
|
|
1141
|
+
members keep the price they are on. Moving existing subscribers too (each at their own next
|
|
1142
|
+
renewal) is not available yet and is refused with a named code rather than half-applied.
|
|
1143
|
+
Renaming a package is not a price change.
|
|
1144
|
+
- **Closing a package cancels nobody.** It stops new subscriptions only. Existing members renew and
|
|
1145
|
+
are billed exactly as before, at their own price. A package with members can be closed but never
|
|
1146
|
+
deleted, and a closed package can be reopened. If a package price and a member's price disagree,
|
|
1147
|
+
the member pays their own price.
|
|
1148
|
+
|
|
1117
1149
|
---
|
|
1118
1150
|
|
|
1119
1151
|
## Player balance
|
package/dist/server.cjs
CHANGED
|
@@ -988,7 +988,7 @@ function toDestinationsResult(raw, direction) {
|
|
|
988
988
|
}
|
|
989
989
|
|
|
990
990
|
// src/version.ts
|
|
991
|
-
var SDK_VERSION = "3.12.
|
|
991
|
+
var SDK_VERSION = "3.12.1";
|
|
992
992
|
|
|
993
993
|
// src/shared/types.ts
|
|
994
994
|
function isRefundPendingApproval(r) {
|
|
@@ -2212,8 +2212,9 @@ var SubscriptionsServer = class {
|
|
|
2212
2212
|
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
2213
2213
|
*
|
|
2214
2214
|
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
2215
|
-
* (HTTP 202): the refund would exceed the game's daily self-serve limit
|
|
2216
|
-
*
|
|
2215
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
|
|
2216
|
+
* default never lower than the largest single subscription charge, so a single period
|
|
2217
|
+
* always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
2217
2218
|
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
2218
2219
|
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
2219
2220
|
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
package/dist/server.d.cts
CHANGED
|
@@ -6,7 +6,7 @@ export { b1 as CardSetupStatus, b2 as CurrencyBalance, p as DestinationGame, b3
|
|
|
6
6
|
* `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
|
|
7
7
|
* Bump it with the changeset flow.
|
|
8
8
|
*/
|
|
9
|
-
declare const SDK_VERSION = "3.12.
|
|
9
|
+
declare const SDK_VERSION = "3.12.1";
|
|
10
10
|
|
|
11
11
|
interface VerifyWebhookOptions {
|
|
12
12
|
/** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
|
|
@@ -700,8 +700,9 @@ declare class SubscriptionsServer {
|
|
|
700
700
|
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
701
701
|
*
|
|
702
702
|
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
703
|
-
* (HTTP 202): the refund would exceed the game's daily self-serve limit
|
|
704
|
-
*
|
|
703
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
|
|
704
|
+
* default never lower than the largest single subscription charge, so a single period
|
|
705
|
+
* always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
705
706
|
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
706
707
|
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
707
708
|
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
package/dist/server.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export { b1 as CardSetupStatus, b2 as CurrencyBalance, p as DestinationGame, b3
|
|
|
6
6
|
* `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
|
|
7
7
|
* Bump it with the changeset flow.
|
|
8
8
|
*/
|
|
9
|
-
declare const SDK_VERSION = "3.12.
|
|
9
|
+
declare const SDK_VERSION = "3.12.1";
|
|
10
10
|
|
|
11
11
|
interface VerifyWebhookOptions {
|
|
12
12
|
/** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
|
|
@@ -700,8 +700,9 @@ declare class SubscriptionsServer {
|
|
|
700
700
|
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
701
701
|
*
|
|
702
702
|
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
703
|
-
* (HTTP 202): the refund would exceed the game's daily self-serve limit
|
|
704
|
-
*
|
|
703
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
|
|
704
|
+
* default never lower than the largest single subscription charge, so a single period
|
|
705
|
+
* always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
705
706
|
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
706
707
|
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
707
708
|
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
package/dist/server.js
CHANGED
|
@@ -3,7 +3,7 @@ export { InvoError } from './chunk-5BMM5ZTW.js';
|
|
|
3
3
|
import { createHmac, timingSafeEqual } from 'crypto';
|
|
4
4
|
|
|
5
5
|
// src/version.ts
|
|
6
|
-
var SDK_VERSION = "3.12.
|
|
6
|
+
var SDK_VERSION = "3.12.1";
|
|
7
7
|
|
|
8
8
|
// src/shared/types.ts
|
|
9
9
|
function isRefundPendingApproval(r) {
|
|
@@ -1227,8 +1227,9 @@ var SubscriptionsServer = class {
|
|
|
1227
1227
|
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
1228
1228
|
*
|
|
1229
1229
|
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
1230
|
-
* (HTTP 202): the refund would exceed the game's daily self-serve limit
|
|
1231
|
-
*
|
|
1230
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
|
|
1231
|
+
* default never lower than the largest single subscription charge, so a single period
|
|
1232
|
+
* always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
1232
1233
|
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
1233
1234
|
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
1234
1235
|
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
package/package.json
CHANGED