@sonatel-os/strapi-plugin-tcg 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @sonatel-os/strapi-plugin-tcg
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A complete trading-card-game module for **Strapi v5**. Drop it into any Strapi install and you get the whole game backend plus the admin screens to run it: seasons, card catalog, packs with QR codes, pulls with a deterministic engine, peer-to-peer trades, redemptions validated at a booth, players, audit, dashboard. Everything is gated by Strapi's own RBAC.
+
+It was built to move **Jambaar** (the Dakar 2026 Youth Olympics card game) off its standalone API and into the central CMS, but nothing in it is Jambaar-specific: a season carries its own rarity table, limits, rank ladder and card pool, so the same install can run several games or several editions of one game.
+
+---
+
+## What you get
+
+| Area              | In the admin                                                                                                                                                                                                                                                                      | For the mini-program (`/api/tcg`)                                                                                          |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| **Seasons**       | Create, edit, activate, archive. Rarity table with live 100 % check, limits, pity rules, rank ladder, editions.                                                                                                                                                                   | `GET /season`                                                                                                              |
+| **Cards**         | Grid with filters, create/edit modal, lore and artist, **supply cap** and mint counter, "only at…" exclusivity badge.                                                                                                                                                             | `GET /cards`, `GET /cards/:id`                                                                                             |
+| **Packs & drops** | A pack is a place or a booster; each pack has **drops**: one QR each, **static (printed poster)** or **rotating (booth screen)**, with open/close window, scan caps, cooldown, and its own cards that can be **exclusive to that QR**. Effective-pool preview, dry-run simulator. | `GET /packs`, `GET /packs/:slug` (with drops)                                                                              |
+| **Live**          | **Boosts**: multiply the odds of any rarity for a time window, season-wide or on one pack; presets like "Golden hour". Open/sold-out drops, rewards running low.                                                                                                                  | `GET /live`                                                                                                                |
+| **Pulls**         | Dashboard rarity split vs target, audit log with seed, roll, **odds snapshot**, **pity** flag and **mint number**.                                                                                                                                                                | `POST /pulls/scan`, `GET /pulls/history`, `GET /pulls/cooldowns`                                                           |
+| **Collection**    | Per-player view with completion, rank, sets, badges, mint numbers.                                                                                                                                                                                                                | `GET /collection`, `GET /collection/stats`                                                                                 |
+| **Trades**        | Counts on the dashboard.                                                                                                                                                                                                                                                          | `POST /trades/offer`, `POST /trades/scan`, `…/accept`, `…/reject`, `…/cancel`, `GET /trades/active`, `GET /trades/history` |
+| **Rewards**       | **Catalog** with tiers, stock, per-player limit, booth, availability window and a **cost builder**: N cards of a rarity (or at least a rarity), a specific card, a complete set (owned or handed in).                                                                             | `GET /rewards`, `GET /rewards/eligibility`                                                                                 |
+| **Booth**         | Type or scan a redemption code, see the cards and the reward, hand it over or cancel and give the cards back (stock released).                                                                                                                                                    | `POST /redemptions`, `GET /redemptions/:id`, `GET /redemptions/history`                                                    |
+| **Sets & badges** | **Sets** are collection goals and reward costs. **Badges** are achievements with rules (pulls, rarity pulls, packs visited, streak, completion, mint ≤ N, scanned a drop, set complete…), secret or visible; nine starters seeded per season.                                     | `GET /sets`, `GET /badges`                                                                                                 |
+| **Players**       | Search by code, external id, phone or name; detail with badges, sets, mint numbers; deactivate; grant a card.                                                                                                                                                                     | `GET /me`, `PATCH /me`                                                                                                     |
+
+All plugin tables are prefixed `tcg_` and hidden from the Content Manager — the module owns its UI.
+
+### How a pull works
+
+1. The player scans a drop QR. Static tokens are verified by signature; rotating tokens also burn a nonce (single use, survives restarts and pods).
+2. Window, scan caps, cooldown (printed codes default to a 24 h per-player cooldown), daily limits and collection size are checked.
+3. The effective pool is built: pack pool, drop pool or both; cards flagged **exclusive** anywhere only drop where flagged; **sold-out** cards (supply cap reached) are removed.
+4. Live **boosts** reshape the rarity table; **pity** clamps the minimum rarity after too many low pulls.
+5. The engine draws (seeded, reproducible); the copy is **minted** with a conditional increment so two concurrent pulls never overshoot a cap; drop scans are counted the same way.
+6. The pull is recorded with its odds snapshot; **badges** are evaluated and newly earned ones come back in the response (`unlocked`), as they do after trades and redemptions.
+
+## Install
+
+```bash
+yarn add @sonatel-os/strapi-plugin-tcg
+```
+
+```js
+// config/plugins.js — everything is optional
+tcg: {
+  enabled: true,
+  config: {
+    playerCodePrefix: 'JMB',                        // the JMB in JMB-A7K2 (2–6 uppercase letters/digits)
+    qr: { globalSecret: env('TCG_QR_SECRET') },     // signs trade QR codes and packs without their own secret
+    players: {
+      idHeader: 'x-player-id',                      // how the caller names the player (any stable id it owns)
+      nameHeader: 'x-player-name',                  // optional display-name hint
+      avatarHeader: 'x-player-avatar',              // optional avatar URL hint
+      autoProvision: true,                          // unknown ids create a player; false → 404 PLAYER_NOT_FOUND
+    },
+  },
+},
+```
+
+Rebuild the admin (`yarn build`), restart, then give roles the **TCG** permissions under _Settings → Roles → Plugins_.
+
+## Protecting the API
+
+The plugin has no authentication of its own. Its player routes under `/api/tcg` are ordinary Strapi **content-API** routes, so they are governed exactly like the rest of your API:
+
+- **API tokens** (_Settings → API Tokens_): create a token, tick the TCG actions it may call (`game.scan`, `game.collection`, …), and have your backend or host app send it as `Authorization: Bearer <token>`.
+- **Users & Permissions roles**: tick the same actions on a role, and callers authenticate with a users-permissions JWT instead.
+
+Any Strapi can install the plugin; any host (a mini-program through its gateway, a mobile app's backend, a kiosk) can drive it with the credential you hand it.
+
+## How players are identified
+
+The caller names the player with a header on every player route:
+
+```http
+POST /api/tcg/pulls/scan
+Authorization: Bearer <strapi api token>
+x-player-id: 221770000001          # any stable id the host owns: phone, Max It user id, username…
+x-player-name: Awa Diop            # optional, refreshes the profile
+x-player-avatar: https://…         # optional
+
+{ "qrToken": "p.…" }
+```
+
+The first time an id is seen a player is created with a code (`JMB-A7K2`) that they show at the booth; later calls reuse it. `GET /me` returns the player (`isNew` is true on the call that created it). Catalog routes (`/season`, `/packs`, `/cards`, `/live`, `/rewards`) need no player header. Missing header → `400 PLAYER_REQUIRED`; unknown id with `autoProvision: false` → `404 PLAYER_NOT_FOUND`; deactivated in the admin → `403 PLAYER_INACTIVE`.
+
+Who the person is behind the id is the host's business: Jambaar, for instance, identifies players through the Max It host SDK in the mini-program and lets its gateway attach the header.
+
+## Error envelope
+
+```json
+{
+  "error": {
+    "status": 422,
+    "code": "COOLDOWN_ACTIVE",
+    "message": "Patientez encore 231 s.",
+    "details": { "remainingSeconds": 231 }
+  }
+}
+```
+
+Clients branch on `code` (see `server/src/constants.js`), never on the French message.
+
+## The engine
+
+Pulls are deterministic and auditable: `sha256(player:pack:pullNumber:timestamp)` seeds a Mulberry32 PRNG; the first roll picks the rarity from the season's cumulative table, the second picks a card by weight inside that rarity (falling back to the whole pool). Seed, roll, rarity and a verification hash are stored on every pull, and the Audit screen shows them. The Simulate tab runs the same engine 2 000 times against a pack without writing anything.
+
+QR tokens are HMAC-signed (`p.<pack>.<nonce>.<exp>.<sig>` / `t.<offer>.<player>.<nonce>.<exp>.<sig>`), expire, and are single-use: consumed nonces are written to `tcg_nonces` so replay protection works across restarts and pods. Expired nonces and trade offers are swept every minute.
+
+## Permissions
+
+| Action                                                       | Lets a role…                             |
+| ------------------------------------------------------------ | ---------------------------------------- |
+| `access`                                                     | see the TCG menu entry                   |
+| `dashboard.read`, `audit.read`                               | read the dashboard, the pull log         |
+| `seasons.read/write`, `cards.read/write`, `packs.read/write` | manage the catalog                       |
+| `packs.qr`                                                   | generate booth QR codes                  |
+| `players.read/write`                                         | look players up, deactivate, grant cards |
+| `redemptions.read/fulfill`                                   | run the booth                            |
+| `settings.read/write`                                        | see the configuration page               |
+
+## Development
+
+```bash
+yarn install
+yarn test            # jest, pure logic (engine, QR, identity, season rules)
+yarn build           # dist/ for admin + server
+yarn watch:link      # live-reload inside a host app (strapi-plugin watch:link)
+```
+
+In a host app, point at your checkout while iterating:
+
+```js
+tcg: { enabled: true, resolve: '../strapi-plugin-tcg', config: { /* … */ } }
+```
+
+Layout: `server/src` (content-types, services, controllers, routes, policies, utils), `admin/src` (pages, components, RTK Query slice, translations EN/FR).
+
+## Roadmap
+
+- Card image upload from the Cards screen (today: set `image` through the Media Library relation or the API).
+- Duplicate economy (melt copies into a craft), public live feed, geofenced scans, CSV import, printable sheet of every drop QR.
+- Excel export of pulls / redemptions through `@sonatel/strapi-plugin-excel-export`.
+- Webhooks on `pull.completed`, `trade.accepted`, `redemption.fulfilled`.
+- Per-season leaderboard endpoint for the mini-program.