@invonetwork/web-sdk 3.26.0 → 3.27.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 +1369 -1350
- package/README.md +119 -1
- package/dist/chunk-2DYTV74W.js +3681 -0
- package/dist/chunk-3YDO7GSH.js +6 -0
- package/dist/chunk-6CN236QH.js +473 -0
- package/dist/{chunk-7BYAUHTA.js → chunk-VP3OK4J4.js} +56 -459
- package/dist/game-server.cjs +5933 -0
- package/dist/game-server.d.cts +185 -0
- package/dist/game-server.d.ts +185 -0
- package/dist/game-server.js +716 -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 +98 -1
- package/dist/server.d.cts +28 -10
- package/dist/server.d.ts +28 -10
- package/dist/server.js +4 -3649
- 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-BXFwI0-s.d.cts +8 -0
- package/dist/version-BXFwI0-s.d.ts +8 -0
- package/package.json +91 -77
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
|
|
@@ -2481,7 +2599,7 @@ const { payout } = await invo.payouts.requestPayout({
|
|
|
2481
2599
|
|
|
2482
2600
|
The first payout to a creator registered with the game key carries `owner_confirmation_required: true`: INVO approves it only after your account owner confirms it in the console. A creator payout still `requested` can be cancelled with `invo.payouts.cancelPayout(payout.id)` (a payout to your own bank: `NOT_FOUND`). Remove a creator from your program with `invo.payouts.removePayee(payeeId)` (status `closed`; refused with `PAYEE_HAS_PAYOUTS_IN_FLIGHT` while a payout is in progress).
|
|
2483
2601
|
|
|
2484
|
-
Refusals carry `err.code`: `PAYEE_NOT_FOUND`, `PAYEE_NOT_VERIFIED` (not `verified` right now: check the status), `PAYEE_VERIFICATION_EXPIRED`, `PAYEE_BANK_NOT_VERIFIED`, `PAYEE_CLOSED`, `PAYEE_NOT_PAYABLE` (the creator can't be paid right now; no action is needed from you or the creator; try again later), `INSUFFICIENT_OWED_BALANCE`, `IDEMPOTENCY_KEY_REUSED`, `PAYOUT_NOT_CANCELLABLE`. Registering: `PARTNER_REFERENCE_CONFLICT`, `COUNTRY_NOT_SUPPORTED`, `GAME_HAS_NO_OWNER`. Resending an invite: `INVITE_NOT_NEEDED`, `PAYEE_ERASED`, `INVITE_RATE_LIMITED` (wait `retry_after_seconds`). A completed payout the bank sends back reads `returned` with `return_reason_code` (always `"returned"` on a creator payout). `partner_message` is a note INVO wrote for you.
|
|
2602
|
+
Refusals carry `err.code`: `PAYEE_NOT_FOUND`, `PAYEE_NOT_VERIFIED` (not `verified` right now: check the status), `PAYEE_VERIFICATION_EXPIRED`, `PAYEE_BANK_NOT_VERIFIED`, `PAYEE_CLOSED`, `PAYEE_TERMS_NOT_ACCEPTED` (the creator hasn't accepted INVO's current Payee Terms yet), `PAYEE_NOT_PAYABLE` (the creator can't be paid right now; no action is needed from you or the creator; try again later), `INSUFFICIENT_OWED_BALANCE`, `IDEMPOTENCY_KEY_REUSED`, `PAYOUT_NOT_CANCELLABLE`. Registering: `PARTNER_REFERENCE_CONFLICT`, `COUNTRY_NOT_SUPPORTED`, `GAME_HAS_NO_OWNER`. Resending an invite: `INVITE_NOT_NEEDED`, `PAYEE_ERASED`, `INVITE_RATE_LIMITED` (wait `retry_after_seconds`). A completed payout the bank sends back reads `returned` with `return_reason_code` (always `"returned"` on a creator payout). `partner_message` is a note INVO wrote for you. Each creator carries `payable` and `payable_blockers` (`erased`, `closed`, `not_verified`, `verification_expired`, `terms_not_accepted`, `bank_not_verified`, `not_payable_now`): check `payable` before offering a payout. Removing a creator with a payout still being processed is refused with `PAYEE_HAS_PAYOUTS_IN_FLIGHT` (`payouts_in_flight_by_status` counts them; a `requested` one can be cancelled).
|
|
2485
2603
|
|
|
2486
2604
|
## Webhooks
|
|
2487
2605
|
|