@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 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; $500 by default in sandbox and production, adjustable by INVO). 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
+ 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 $500 daily limit applies in sandbox too, and a refund over it answers `pending_approval`); and create one with `trialDays: 7` to see `skipped_trial` convert.
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.0";
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 ($500 per UTC day
2216
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
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.0";
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 ($500 per UTC day
704
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
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.0";
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 ($500 per UTC day
704
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
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.0";
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 ($500 per UTC day
1231
- * by default), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@invonetwork/web-sdk",
3
- "version": "3.12.0",
3
+ "version": "3.12.1",
4
4
  "description": "INVO Web SDK — currency purchase + passkey (WebAuthn) verification for partner web platforms.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "private": false,