@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/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