@invonetwork/web-sdk 3.26.1 → 3.28.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 +20 -0
- package/README.md +118 -0
- package/dist/chunk-3DRWLDDF.js +6 -0
- package/dist/chunk-4YKTKXC5.js +3735 -0
- package/dist/chunk-6CN236QH.js +473 -0
- package/dist/{chunk-7BYAUHTA.js → chunk-VP3OK4J4.js} +56 -459
- package/dist/game-server.cjs +6025 -0
- package/dist/game-server.d.cts +193 -0
- package/dist/game-server.d.ts +193 -0
- package/dist/game-server.js +746 -0
- package/dist/game.cjs +2172 -0
- package/dist/game.d.cts +197 -0
- package/dist/game.d.ts +197 -0
- package/dist/game.js +1034 -0
- package/dist/index.cjs +87 -0
- package/dist/index.d.cts +19 -3
- package/dist/index.d.ts +19 -3
- package/dist/index.js +26 -2
- package/dist/server.cjs +158 -1
- package/dist/server.d.cts +50 -7
- package/dist/server.d.ts +50 -7
- package/dist/server.js +4 -3650
- package/dist/types-CoW9LopI.d.cts +143 -0
- package/dist/types-CoW9LopI.d.ts +143 -0
- package/dist/{types-Cjd4SAR8.d.cts → types-_lIm74kd.d.cts} +40 -1
- package/dist/{types-Cjd4SAR8.d.ts → types-_lIm74kd.d.ts} +40 -1
- package/dist/version-iWmcxjYu.d.cts +8 -0
- package/dist/version-iWmcxjYu.d.ts +8 -0
- package/package.json +91 -77
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.28.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Going live is swapping the key. `invoGameServerFromEnv` now picks the environment from `INVO_GAME_SECRET`: the public demo key (`ivsdk_demo_...`, baked into INVO's game templates) is the sandbox; any other key is looked up once with `GET /api/sdk/key-environment` (production first, then the sandbox) and cached. `INVO_ENV` and `INVO_BASE_URL` still override it.
|
|
8
|
+
- `X-Invo-Project-Id` is now sent on every call in both environments, so the first live call after go-live links the template project to your INVO account. `INVO_PROJECT_ID` is read when `projectId` is not passed. The id format is `proj_` + a 26-character uppercase Crockford ULID; `newProjectId()` (game-server entry) makes one.
|
|
9
|
+
- New exports (server and game-server entries): `resolveEnvironment`, `baseUrlForKey`, `isDemoKey`, `EnvironmentUnknownError`, `PRODUCTION_BASE_URL`, `SANDBOX_BASE_URL`, `DEMO_KEY_PREFIX`.
|
|
10
|
+
- Nothing removed or renamed.
|
|
11
|
+
|
|
12
|
+
## 3.27.0
|
|
13
|
+
|
|
14
|
+
### Minor Changes
|
|
15
|
+
|
|
16
|
+
- Loyalty: `InvoServer.reportGameEvent({ playerEmail, eventType, eventId?, occurredAt?, payload? })` (`POST /api/sdk/loyalty/server-events`, game secret, trusted for rewards) and `InvoClient.reportGameEvent(...)` (`POST /api/sdk/loyalty/events`, player token). `eventId` is generated when omitted and returned; the server call retries with it. Types `GameEventType`, `ReportGameEventInput`, `ReportServerGameEventInput`, `ReportGameEventResult`.
|
|
17
|
+
- New entry `@invonetwork/web-sdk/game-server`: the server half of a browser game's economy. `invoGameServerFromEnv` / `createInvoGameServer` serve sessions, the premium wallet (read from INVO), a soft-currency ledger, hosted checkout, signed-webhook crediting processed exactly once, idempotent item purchases (premium through `purchaseItem`, soft through the ledger), rate-limited earnings, loyalty events and rewards, under `/api/invo`. `createFileGameStore` (atomic JSON file) and `createMemoryGameStore`; `toNodeListener` adapts it to `node:http`. With secrets missing it answers `503 INVO_SETUP_REQUIRED` and keeps `/health` and `/catalog` up.
|
|
18
|
+
- New entry `@invonetwork/web-sdk/game`: `InvoGameEconomy` (the browser client for that server: sign-in, wallet events, `buyItem`, `buyPremium` with popup or redirect checkout, batched `earn`, `reportEvent`) and `mountInvoUI`, a framework-free DOM kit (balance HUD, buy-currency modal, shop grid, sign-in, toasts) in the INVO palette, themeable by CSS variables. Holds no secret. Used by `@invonetwork/phaser` and `@invonetwork/three`.
|
|
19
|
+
- `invoGameServerFromEnv` accepts `projectId` (sent to the sandbox as `X-Invo-Project-Id` on every call, never in production) and `fetch`. `InvoGameEconomy.checkSetup()` re-asks the server whether its INVO secrets are set; the UI kit's developer setup guide uses it to notice when the keys arrive.
|
|
20
|
+
- The UI kit ships the INVO design: a glass wallet HUD with animated balance changes, a tabbed shop with lit item cards, ownership chips and stack pips, premium packs with a best-value ribbon, sign-in with field icons, a step-by-step developer setup guide, toasts, and bottom sheets on phones. It respects `prefers-reduced-motion`.
|
|
21
|
+
- Nothing removed or renamed; the `.` and `./server` entries are unchanged apart from the two new methods.
|
|
22
|
+
|
|
3
23
|
## 3.26.1
|
|
4
24
|
|
|
5
25
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -120,7 +120,9 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
120
120
|
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
121
121
|
- [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
|
|
122
122
|
- [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
|
|
123
|
+
- [Browser games: the game economy layer](#browser-games-the-game-economy-layer)
|
|
123
124
|
- [Loyalty and rewards](#loyalty-and-rewards)
|
|
125
|
+
- [Reporting game events](#reporting-game-events)
|
|
124
126
|
- [Webhooks](#webhooks)
|
|
125
127
|
- [Resilience & observability](#resilience--observability)
|
|
126
128
|
- [Errors](#errors)
|
|
@@ -2366,6 +2368,91 @@ const done = await server.completeDeviceApproval({
|
|
|
2366
2368
|
|
|
2367
2369
|
---
|
|
2368
2370
|
|
|
2371
|
+
## Browser games: the game economy layer
|
|
2372
|
+
|
|
2373
|
+
New in 3.27.0. Two more entry points give a browser game a complete INVO economy without
|
|
2374
|
+
writing the money plumbing yourself. `@invonetwork/phaser` and `@invonetwork/three` build on them.
|
|
2375
|
+
|
|
2376
|
+
| Entry | Runs on | What it is |
|
|
2377
|
+
|---|---|---|
|
|
2378
|
+
| `@invonetwork/web-sdk/game-server` | your Node server | sessions, the premium wallet (read from INVO), a soft-currency ledger, hosted checkout, signed-webhook crediting (exactly once), the item shop, loyalty events |
|
|
2379
|
+
| `@invonetwork/web-sdk/game` | the browser | `InvoGameEconomy` (talks only to your game server) and `mountInvoUI`, a DOM kit: balance HUD, buy-currency modal, shop grid, sign-in |
|
|
2380
|
+
|
|
2381
|
+
**Two currencies.** PREMIUM is your game's INVO currency: bought with real money through INVO's
|
|
2382
|
+
hosted checkout, held and debited by INVO. SOFT is earned by playing and held by your game
|
|
2383
|
+
server's ledger. Shop items are priced in one or the other.
|
|
2384
|
+
|
|
2385
|
+
**Server.** Secrets come from the environment; with them missing the server still runs and every
|
|
2386
|
+
INVO route answers `503 INVO_SETUP_REQUIRED` naming what to add.
|
|
2387
|
+
|
|
2388
|
+
```ts
|
|
2389
|
+
import http from "node:http";
|
|
2390
|
+
import { invoGameServerFromEnv, createFileGameStore, toNodeListener } from "@invonetwork/web-sdk/game-server";
|
|
2391
|
+
|
|
2392
|
+
const economy = {
|
|
2393
|
+
premium: { name: "Gems", packs: [{ id: "gems_small", name: "Pouch of Gems", usdAmount: "4.99", amount: 50 }] },
|
|
2394
|
+
soft: { name: "Coins", startingBalance: 100 },
|
|
2395
|
+
items: [
|
|
2396
|
+
{ id: "golden_aura", name: "Golden Aura", category: "cosmetic", currency: "premium", price: 30 },
|
|
2397
|
+
{ id: "pickaxe_2", name: "Sharper Pickaxe", category: "upgrade", currency: "soft", price: 80, maxOwned: 5 },
|
|
2398
|
+
],
|
|
2399
|
+
};
|
|
2400
|
+
|
|
2401
|
+
// INVO_GAME_SECRET, INVO_WEBHOOK_SECRET, INVO_ENV (sandbox | production), PUBLIC_URL
|
|
2402
|
+
const { server, missing } = invoGameServerFromEnv({
|
|
2403
|
+
economy,
|
|
2404
|
+
env: process.env,
|
|
2405
|
+
store: createFileGameStore({ file: ".data/invo-game.json" }),
|
|
2406
|
+
});
|
|
2407
|
+
http.createServer(toNodeListener(server, serveYourStaticFiles)).listen(3000);
|
|
2408
|
+
```
|
|
2409
|
+
|
|
2410
|
+
Point your INVO webhook at `https://<your-host>/api/invo/webhook`.
|
|
2411
|
+
|
|
2412
|
+
**Browser.**
|
|
2413
|
+
|
|
2414
|
+
```ts
|
|
2415
|
+
import { InvoGameEconomy, mountInvoUI } from "@invonetwork/web-sdk/game";
|
|
2416
|
+
|
|
2417
|
+
const economy = new InvoGameEconomy(); // routes under /api/invo on the same origin
|
|
2418
|
+
await economy.init(); // catalog, saved session, returning checkout
|
|
2419
|
+
const ui = mountInvoUI(document.getElementById("game")!, economy, {
|
|
2420
|
+
onModalChange: (open) => game.setPaused(open),
|
|
2421
|
+
});
|
|
2422
|
+
|
|
2423
|
+
economy.earn(5, "ore mined"); // batched, rate-limited on the server
|
|
2424
|
+
if (economy.owns("golden_aura")) player.showAura();
|
|
2425
|
+
economy.on("wallet", (w) => hud.setCoins(w.soft.balance));
|
|
2426
|
+
await economy.reportEvent("game.milestone.reached", { milestone_key: "level_5" });
|
|
2427
|
+
```
|
|
2428
|
+
|
|
2429
|
+
**Money rules the layer enforces.**
|
|
2430
|
+
|
|
2431
|
+
- Premium currency is credited only by a verified `purchase.completed` webhook (`metadata.purchase_ref`
|
|
2432
|
+
links it to the checkout), never because the browser says a checkout finished. Each webhook is
|
|
2433
|
+
processed once by its idempotency key and each ledger line is written once by a unique ref, so
|
|
2434
|
+
a redelivered event cannot credit twice.
|
|
2435
|
+
- Item purchases are idempotent on the browser's `clientRequestId`; a retry replays the first
|
|
2436
|
+
answer. Premium items are debited by INVO (`purchaseItem`; the standard item split applies). If
|
|
2437
|
+
the route dies after INVO debited the player, the signed `item.purchased` webhook still grants
|
|
2438
|
+
the item.
|
|
2439
|
+
- Soft-currency purchases check and debit the balance in one serialized step: concurrent taps
|
|
2440
|
+
cannot overdraw.
|
|
2441
|
+
- `earn` is capped per request and per rolling minute. Compute valuable rewards on your server;
|
|
2442
|
+
`earn` is for casual play loops.
|
|
2443
|
+
- Sessions are random server-side tokens; the browser never holds the game secret or an INVO token.
|
|
2444
|
+
|
|
2445
|
+
**Routes** (all under `/api/invo`): `GET /health`, `GET /catalog`, `POST /session`,
|
|
2446
|
+
`POST /session/end`, `GET /wallet`, `POST /checkout`, `GET /purchases/{ref}`, `POST /webhook`,
|
|
2447
|
+
`POST /items/{id}/buy`, `POST /earn`, `POST /events`, `GET /rewards`. Errors are
|
|
2448
|
+
`{ "error": { "code", "message" } }` with the HTTP status.
|
|
2449
|
+
|
|
2450
|
+
**Storage.** `createFileGameStore` writes one JSON file atomically and is right for a template or
|
|
2451
|
+
a single-instance game. Running several instances? Implement `GameStore` (`read` + `transact`)
|
|
2452
|
+
over your database.
|
|
2453
|
+
|
|
2454
|
+
---
|
|
2455
|
+
|
|
2369
2456
|
## Loyalty and rewards
|
|
2370
2457
|
|
|
2371
2458
|
Show a player their loyalty programs, how far they are through each step, and the rewards they
|
|
@@ -2448,6 +2535,37 @@ the client uses `getMyRewards()` with the player token instead.
|
|
|
2448
2535
|
A blank email, or a `vaultEntryId` that is not a reward's id, throws `INVALID_INPUT` (status 0)
|
|
2449
2536
|
before the network. `redeemReward` is never auto-retried.
|
|
2450
2537
|
|
|
2538
|
+
### Reporting game events
|
|
2539
|
+
|
|
2540
|
+
New in 3.27.0. Gameplay steps (sessions, level milestones, custom events registered in the
|
|
2541
|
+
console) are reported by your game; currency steps are seen by INVO and are never reported.
|
|
2542
|
+
Report from your SERVER when a reward depends on the event: server events are the trusted ones.
|
|
2543
|
+
|
|
2544
|
+
```ts
|
|
2545
|
+
// Server (game secret): trusted for rewards.
|
|
2546
|
+
const { eventId } = await server.reportGameEvent({
|
|
2547
|
+
playerEmail: "player@example.com",
|
|
2548
|
+
eventType: "game.milestone.reached",
|
|
2549
|
+
payload: { milestone_key: "level_10" },
|
|
2550
|
+
});
|
|
2551
|
+
|
|
2552
|
+
// Browser (player token).
|
|
2553
|
+
await invo.reportGameEvent({ eventType: "game.session.started", payload: { session_ref: sessionRef } });
|
|
2554
|
+
```
|
|
2555
|
+
|
|
2556
|
+
| `eventType` | `payload` |
|
|
2557
|
+
|---|---|
|
|
2558
|
+
| `game.session.started` / `game.session.heartbeat` | `session_ref` |
|
|
2559
|
+
| `game.session.ended` | `session_ref`, `duration_seconds` |
|
|
2560
|
+
| `game.milestone.reached` | `milestone_key`, optional `value`, `session_ref` |
|
|
2561
|
+
| `game.custom.recorded` | `event_name` (registered in the console), optional `value` |
|
|
2562
|
+
|
|
2563
|
+
`eventId` (a UUID) is the idempotency key: the SDK generates one when you leave it out and returns
|
|
2564
|
+
it; reuse it on a retry. `occurredAt` takes ISO 8601 with a timezone, or a `Date`. Bad input
|
|
2565
|
+
throws `INVALID_INPUT` before the network; INVO refuses with `400 RESERVED_EVENT_TYPE` /
|
|
2566
|
+
`EVENT_TYPE_NOT_ALLOWED`, `404 PLAYER_NOT_FOUND` or `422 validation_failed` (an unregistered
|
|
2567
|
+
`event_name`).
|
|
2568
|
+
|
|
2451
2569
|
---
|
|
2452
2570
|
|
|
2453
2571
|
## Partner and creator payouts
|