@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/smarticoGlobal.md

@@ -0,0 +1,62 @@
+# _smartico — global SDK surface (non-`.api.*`)
+
+> The `window._smartico` control surface: init/identify, events, deep links, widgets, visitor-mode `vapi`, push, and utilities — everything that is NOT `_smartico.api.*` (those have their own capability pages).
+> Import: typed via `SmarticoGlobal` from '@smartico/public-api'; at runtime the object is on `window._smartico` (no import).
+> Search terms: api, vapi, checkSuccessfullyIdentify, init, initVisitorMode, identify, online, login, logout, clear, changeLanguage, on, off, dp, showWidget, miniGame, showBanner, sendDataToBanner, gamificationBlock, getPublicProps, updatePublicTags, setUTMs, setLoginEntry, setAvatar, setNickname, setSkin, requestPushPermissions, registerNativePushToken, event, action, sendServerError, sendServerDebug, suspendPopups, suspendInbox, suspendMiniGames, showVisitorGame, convertVisitorGame, startLpAnalytics, sendAnalytics, isMobile, parseUrl, parseUrlHash, _smartico, global, window._smartico, SmarticoGlobal, visitor mode, callbacks, events, onWin, onReady, deep link, getWidgetParams, IWidgetParams, widget params, readiness, lifecycle, push
+
+## Readiness gate
+Call `window._smartico?.checkSuccessfullyIdentify()` (synchronous) before any `_smartico.api.*` — `true` once init + identify completed. Or subscribe `_smartico.on('identify', cb)` (see the callbacks page).
+
+## Methods
+- `_smartico.api: WSAPI` — The authenticated WebSocket API surface (`_smartico.api.*`). Available once the SDK has initialized and identified the user — gate calls on `SmarticoGlobal.checkSuccessfullyIdentify`.
+- `_smartico.vapi(language: string): WSAPI` — Visitor-mode (unauthenticated) API surface for the given language. Returns a `WSAPI` scoped to anonymous visitors.
+- `_smartico.checkSuccessfullyIdentify(): boolean` — `true` once the SDK is initialized **and** the user has been successfully identified. Use as a synchronous gate before calling any `api.*` method.
+- `_smartico.init(labelApiKey: string, params?: SmarticoInitParams): void` — Initialize the SDK for an identified integration.
+- `_smartico.initVisitorMode(labelApiKey: string, params?: SmarticoInitParams): void` — Initialize the SDK in visitor (anonymous) mode.
+- `_smartico.identify(extUserId: string, hash: string, payload?: Record<string, unknown>): Promise<void>` — Identify the current user against the label.
+- `_smartico.online(extUserId: string, language: string, userHash: string, payload?: Record<string, unknown>): Promise<void>` — Mark an identified user as online for the given language.
+- `_smartico.login(language?: string, payload?: Record<string, unknown>): void` — Re-run the login flow for the current session.
+- `_smartico.logout(payload?: Record<string, unknown>): void` — Log the current user out of the SDK session.
+- `_smartico.clear(params?: Record<string, unknown>): void` — Clear SDK state/cookies.
+- `_smartico.changeLanguage(language: string): void` — Switch the active UI language.
+- `_smartico.on(event: string, cb: null | ((...args: any[]) => void), params?: Record<string, unknown>): void` — Subscribe to a lifecycle/engagement callback. Pass `null` as the handler to unsubscribe. See the callbacks reference for available keys.
+- `_smartico.off(event: string, cb: null | ((...args: any[]) => void)): void` — Remove a previously registered callback.
+- `_smartico.dp(deepLink: string): void` — Trigger a Smartico deep link.
+- `_smartico.showWidget(widgetType: SmarticoWidgetType, params?: SmarticoWidgetParams): void` — Open a Smartico widget overlay/inline.
+- `_smartico.miniGame(sawTemplateId: string, params: SmarticoWidgetParams, pendingMessageId?: string | number): void` — Open a mini-game widget for the given template.
+- `_smartico.showBanner(params: { dom_id: string; placement_key: string }): void` — Render a banner into a host element.
+- `_smartico.sendDataToBanner(params: { placement_key: string; data: Record<string, unknown> }): void` — Push data into an already-rendered banner.
+- `_smartico.gamificationBlock(params: { dom_id: string; url: string; fit?: 'content' | 'fill' }): void` — Embed the gamification block into a host element.
+- `_smartico.getPublicProps(): PublicProperties` — Snapshot of the user's public gamification properties.
+- `_smartico.updatePublicTags(operation: 'add' | 'remove' | 'replace' | 'clear', tags?: string[]): void` — Add/remove/replace/clear the user's public tags.
+- `_smartico.setUTMs(source: string, campaign: string): void` — Set UTM attribution for the session.
+- `_smartico.setLoginEntry(entry: string): void` — Record the last login entry point.
+- `_smartico.setAvatar(avatarId: string): void` — Set the user's avatar.
+- `_smartico.setNickname(nickname: string): void` — Set the user's nickname.
+- `_smartico.setSkin(skinName: string): void` — Set the active UI skin.
+- `_smartico.requestPushPermissions(): void` — Prompt the browser for web-push permission.
+- `_smartico.registerNativePushToken(token: string, platform?: number, appPackageId?: string): void` — Register a native push token (mobile webviews).
+- `_smartico.event(eventType: string, payload?: Record<string, unknown>): void` — Send a client event.
+- `_smartico.action(actionValue: unknown, extraPayload?: Record<string, unknown>): void` — Send a client action.
+- `_smartico.sendServerError(message: string): void` — Report a client-side error to the server.
+- `_smartico.sendServerDebug(message: string): void` — Send a client-side debug message to the server.
+- `_smartico.suspendPopups(flag: boolean): void` — Temporarily suspend/resume automatic popups.
+- `_smartico.suspendInbox(flag: boolean): void` — Temporarily suspend/resume the inbox.
+- `_smartico.suspendMiniGames(flag: boolean): void` — Temporarily suspend/resume mini-games.
+- `_smartico.showVisitorGame(params: Record<string, unknown>): void` — Show a visitor-mode game.
+- `_smartico.convertVisitorGame(visitorWinUuid: string): void` — Convert a visitor-mode win into an identified reward.
+- `_smartico.startLpAnalytics(params: { lp_template_uuid: string; shadow_root?: ShadowRoot | null }): void` — Start landing-page analytics for a template.
+- `_smartico.sendAnalytics(activityId: number, viewTimeSec?: number): void` — Send a landing-page analytics activity.
+- `_smartico.isMobile(): boolean` — `true` on mobile viewports.
+- `_smartico.parseUrl(): Record<string, string>` — Parse the current URL query into a map.
+- `_smartico.parseUrlHash(): Record<string, string>` — Parse the current URL hash into a map.
+
+## Visitor mode (`vapi`)
+`_smartico.vapi(language)` returns a `WSAPI` scoped to anonymous visitors — same method shapes as `_smartico.api.*`, for unidentified users (pre-login surfaces).
+
+## Reading widget params
+A widget embedded via `showWidget` / `miniGame` receives `IWidgetParams` (theme, height, inline, …). Read them from the embedding snippet / `window.__SMARTICO_LP_PARAMS__`, not from an API call.
+
+## Related
+- `_smartico.on — events & callbacks` (the callbacks capability page)
+- Full prose reference: the SmarticoObject doc (search source `api-raw`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.402",
+	"version": "0.0.404",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -24,7 +24,8 @@
 		"bump-ach": "cd ../tracker/ach && npm install @smartico/public-api@latest --legacy-peer-deps",
 		"bump-bo-server": "cd ../bo_server/server && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
 		"bump-bo-client": "cd ../bo_server/client && source ~/.nvm/nvm.sh && nvm use v13.13.0 && npm install @smartico/public-api@latest",
-		"doc": "typedoc && node scripts/postdoc-cleanup.js"
+		"doc": "typedoc && node scripts/postdoc-cleanup.js",
+		"gen-capabilities": "node scripts/gen-capabilities.js"
 	},
 	"author": "",
 	"license": "ISC",

package/readme-smartico-dev.md

@@ -0,0 +1,208 @@
+# Smartico public-api — docs & RAG pipeline (developer guide)
+
+How the `@smartico/public-api` documentation is produced, how the IDE coding
+agent retrieves it, and **how to keep it all up to date**. Read this before
+touching TSDoc, the capability pages, the capture scripts, or the bo_server
+ingestion.
+
+---
+
+## 1. The big picture
+
+```
+ SOURCE OF TRUTH (you edit)                 GENERATED (never edit)            CONSUMED BY
+ ─────────────────────────                  ──────────────────────           ───────────
+ src/WSAPI/WSAPI<Domain>.ts  ─┐
+   method TSDoc (usage)        │
+ src/WSAPI/WSAPITypes.ts +     │   npm run gen-capabilities
+   domain types (field docs)   ├──────────────────────────►  docs/capabilities/<method>.md ─┐
+ docs/ui/<domain>/UIGuide_*.md │   (scripts/gen-capabilities.js)   (one self-contained       │
+   (behavioral contract)       │                                    "API capability page")   │
+ docs/capabilities/_responses/ │                                                              │
+   <method>.json (REAL shapes)─┘                                                              │
+                                                                                              │   JobLLM2 (env2 cron)
+ src/**.ts (TSDoc)  ──────────────►  docs/api/**  (TypeDoc reference) ───┐                    ├──► llm.docs2 (Postgres, GAMES db)
+   npm run doc                        (scripts/postdoc-cleanup.js)        │  ingested as        │     + embeddings (llm.chunks2)
+                                                                          │  PUBLIC_API_DOCS    │
+                                                                          │  ("api-raw" lane)   ▼
+                                                                          └──────────────►  IDE coding agent
+ docs/capabilities/** ────────────────────────────────────────────────────► ingested as PUBLIC_API_CAPABILITY
+                                                                             (the PRIMARY "api" retrieval lane)
+```
+
+**The IDE agent retrieves capability pages, not raw source.** Each page is one
+task-completable unit: signature + full inline return shape + behavioral
+contract + a **real example response** + errors + related links. Design rules
+live in `../bo_server/server/src/ide/SMARTICO_DOC_STRUCTURE_GUIDE.md`.
+
+---
+
+## 2. Source of truth — what to edit where
+
+| Edit | For | Owned by |
+|---|---|---|
+| `src/WSAPI/WSAPI<Domain>.ts` method TSDoc | narrative usage: preconditions, error tables, refresh/cache, idempotency, `@example`, `{@link}` | `api-tsdoc` skill |
+| `src/WSAPI/WSAPITypes.ts` + `src/<Domain>/*.ts` field comments | terse one-line field definitions (what + type/units + null semantics) | `api-tsdoc` skill |
+| `docs/ui/<domain>/UIGuide_<method>.md` | UI/behavioral contract prose | `api-tsdoc` skill |
+| `docs/capabilities/_responses/<method>.json` | the **captured real response** (anonymized) | capture scripts (§4) |
+| `tsconfig.json` `typedocOptions.entryPoints` | add new public types/classes so they appear in `docs/api` | manual |
+
+**NEVER hand-edit** (regenerated, overwritten):
+- `docs/api/**` — TypeDoc output (`cleanOutputDir: true`).
+- `docs/capabilities/*.md` — generated by `gen-capabilities.js`.
+
+---
+
+## 3. Keeping docs updated — the per-release workflow
+
+Run after any change to a method's signature, behavior, or types.
+
+1. **Enrich the source** — TSDoc + field comments + UI guide. Use `/api-tsdoc <method>` (one method) or `/api-tsdoc-final` (whole release batch). These never commit and never run the build steps below.
+2. **Capture / refresh the real response** for the method → `docs/capabilities/_responses/<method>.json` (§4).
+3. **Generate capability pages**: `npm run gen-capabilities`. Rewrites all `docs/capabilities/*.md` from TSDoc + types + the captured responses.
+4. **(Reference site)** `npm run doc` — TypeDoc → `docs/api/**` (+ `postdoc-cleanup.js`). Human-triggered; confirm zero new warnings.
+5. **Ship**: commit; publish (`npm version patch && npm publish`) so the npm package + `run_public_api` see new methods; `npm run bump-tracker` to flow into the live `_smartico.api`.
+6. **RAG ingest is automatic**: `JobLLM2` (bo_server, env2 cron, every 60s) clones `public-api`, re-indexes changed `docs/capabilities/**` under `PUBLIC_API_CAPABILITY`. No manual step. It emails `MAIL_TO_AI_PRODUCT` when done.
+
+**Coverage check:** `ls docs/capabilities/_responses/*.json | wc -l` vs `ls docs/capabilities/*.md | wc -l`. Methods without a `_responses` file still get a complete Returns shape from the type registry (fallback), just no real example payload.
+
+---
+
+## 4. Capturing real response shapes
+
+Two mechanisms. **Prefer `run_public_api`** for everything it can reach; use the browser script only for the auth-only gaps.
+
+### 4a. Server-side — `mcp__hive__run_public_api` (visitor mode, no browser)
+
+Runs the real published WSAPI bound to label+brand+user, returns `JSON.stringify(result)`. No user-hash, no CORS, no SDK loader.
+
+- **Captures:** almost all `getX()` fetch methods.
+- **Cannot capture** (runs in *visitor / no-tracker* mode): `getUserProfile`, `getInboxMessageBody` (read tracker state), all `gamePick*` ("not available in visitor mode").
+- **Caveat:** runs the **published npm** SDK → lags local `main`. Newly-added methods aren't there until `npm publish`.
+
+### 4b. Headless real-user — `scripts/capture-responses-browser.mjs`
+
+Loads the real `smartico.js` tracker bundle, `init` + `identify` as a real player, then sweeps every `_smartico.api.*` and writes anonymized `_responses/<method>.json`. Covers the auth-only gaps.
+
+```sh
+npm i -D playwright && npx playwright install chromium    # one-time
+node scripts/capture-responses-browser.mjs                # read-only sweep
+SM_MUTATIONS=1 node scripts/capture-responses-browser.mjs # + execute mutations (test acct only)
+SM_DEBUG=1     node scripts/capture-responses-browser.mjs # full console + per-WS-frame trace
+npm run gen-capabilities                                  # rebuild pages after capture
+```
+
+Progress/diagnostics stream to **`/tmp/sm-capture.log`** (stdout is buffered in background).
+
+**Env overrides** (defaults = the env4 ICE **test** label):
+
+| Var | Default | Meaning |
+|---|---|---|
+| `SM_LABEL` | `a6e7ac26-…-4` | label key (last char = env) |
+| `SM_BRAND` | `f86271e6` | brand key |
+| `SM_USER` | `4579cace-…c45b` | player ext id |
+| `SM_SALT` | `null` | label hash salt (env4 ICE = literal `'null'`) |
+| `SM_ORIGIN` | `https://app.smartico.ai/` | self-served CSP-free page origin |
+| `SM_SCRIPT_URL` | `https://libs.smartico.ai/smartico.js` | tracker bundle |
+| `SM_UA` | desktop Chrome | user-agent |
+| `SM_MUTATIONS` | off | run the mutation pass |
+| `SM_DEBUG` | off | verbose console + WS frames |
+
+**How identify works (hard-won):**
+- `smartico.js` builds `_smartico`; identify is the **method form** `_smartico.identify(user, hash, {})` — the queue form `_smartico('identify', …)` silently no-ops after load.
+- hash = `md5( lower(`${user}:${salt}:${ts}`) ) + ':' + ts`, `ts = floor(now/1000)*1000 + 24h`. Server accepts it when the label salt matches (`'null'` for env4 ICE).
+- realtime WS = `wss://api{ENV}.smartico.ai/websocket/services`.
+- **Why a self-served origin:** `libs.smartico.ai` 403s headless clients and its error page's CSP blocks injected scripts; the script routes a blank CSP-free page on `app.smartico.ai` and fetches `smartico.js` cross-origin with a realistic UA.
+
+**Dynamic ids + richest sampling:** the sweep fetches list methods first and harvests every param id (tournament instance, clan, jp_template, raffle/draw/run, inbox guid, gamepick matchx/quiz template) — **no hardcoded ids**. For list methods it stores the *most-populated* item so the captured shape isn't a degenerate first element.
+
+**Anonymization (automatic):** CDN hosts (`cloudfront.net`/`smartico.ai`/`smr.vc`) → `cdn.example`; any UUID → zeros; `clean_ext_user_id` → `0`. Keep product config (names, prize tables) — only the field *shape* matters.
+
+### 4c. Mutations (`SM_MUTATIONS=1`)
+
+Executes write methods on the **test account** to capture result shapes; reversibles are restored. Captured: jackpot opt in/out, inbox mark-read/favorite/mark-all, setAvatar (restored), mission opt-in, claimBonus, registerInTournament, buyStoreItem, playMiniGame + acknowledge + batch. Skipped by guards when no suitable entity exists (claim-reward, raffle-optin, joinClan). **Never runs `deleteAllInboxMessages` / single delete** (destructive) or the gamepick submit (charges buy-in). Real error codes are valuable too (e.g. `buyStoreItem → 11002`).
+
+---
+
+## 5. The generator — `scripts/gen-capabilities.js`
+
+Pure, deterministic Node + the `typescript` compiler API (no extra deps). Per public WSAPI method it emits `docs/capabilities/<method>.md`:
+
+- **facts header** (title, one-line summary, import, Search-terms) — high retrieval weight.
+- **Signature / Parameters** — from the method node + `@param`.
+- **Returns** — annotates the **captured response** fields with the **return type's own** comments (per-type resolved, inheritance-aware, nested via the property's element type). No captured response → falls back to the resolved **type** shape (still complete).
+- **Behavioral contract** — the method's `@remarks` (with an Error-codes block split out into `## Errors`).
+- **Example** + **Example response (REAL shape)** — the `@example` + the captured JSON.
+- **Related** — from `{@link}` targets.
+
+Run: `npm run gen-capabilities`. Reads `_responses/<method>.json` if present. Never commits.
+
+---
+
+## 6. RAG ingestion (bo_server)
+
+| Piece | File | What |
+|---|---|---|
+| Source-type enum | `server/src/Managers/LLMManager.ts` | `LLMSourceTypeId.PUBLIC_API_CAPABILITY = 8` |
+| Ingest job | `server/src/Jobs/JobLLM2.ts` → `processPublicAPI()` | indexes `docs/capabilities/**` under the new type; the raw walk skips `capabilities`/`_responses` (`LLM_SKIP_DIRS`). env2 only, 60s refresh. |
+| IDE routing | `server/src/ide/ideSmarticoTools.ts` | `SOURCE_TYPE_MAP.api → [PUBLIC_API_CAPABILITY]` (primary); `api-raw → [PUBLIC_API_DOCS]` (raw source fallback) |
+| IDE tools | `ideSmarticoTools.ts` | `search_smartico_reference` (semantic + Cohere rerank → top distinct docs), `read_smartico_reference` (one doc by id), `list_smartico_reference` |
+| Design rules | `server/src/ide/SMARTICO_DOC_STRUCTURE_GUIDE.md` | the capability-page spec |
+
+The IDE `api` lane reads **only** capability pages. A method with no capability page is invisible to the agent — always run `gen-capabilities` after enriching.
+
+---
+
+## 7. Skills
+
+- **`/api-tsdoc <method>`** — enrich one method end-to-end (TSDoc + UI guide + capture a response + regenerate the page). Never commits / never runs `npm run doc`.
+- **`/api-tsdoc-final`** — the whole release doc batch (callbacks, `_smartico` object, native protocol, all method TSDocs, capability capture + generation), stops at a prepared commit message.
+
+Skill files: `~/.claude/skills/api-tsdoc/SKILL.md`, `~/.claude/skills/api-tsdoc-final/SKILL.md`.
+
+---
+
+## 8. Adding a NEW method — checklist
+
+1. Implement the method in `src/WSAPI/WSAPI<Domain>.ts`; add return/types to `WSAPITypes.ts` (or a domain types file).
+2. Add new public types to `tsconfig.json` `typedocOptions.entryPoints`.
+3. `/api-tsdoc <method>` → TSDoc + field comments + UI guide.
+4. Capture a real response (§4) → `_responses/<method>.json`.
+5. `npm run gen-capabilities` → new `docs/capabilities/<method>.md`. Spot-check Returns has the right per-domain field comments + a real example.
+6. Commit; `npm publish`; `npm run bump-tracker`. RAG re-indexes automatically.
+
+---
+
+## 9. Field-type facts (server-determined; verified via `run_public_api`)
+
+- `*_ts` / `*_date_ts` → **epoch-ms number**. Round/event/store/raffle timestamps → number ms.
+- Plain Java date strings (`complete_date`, `unlock_date`, `sent_date`, bonus `create_date`/`redeem_date`) → **`"dd/MM/yyyy HH:mm:ss"` string, NOT ISO-8601** (`new Date()` won't parse them).
+- GamePick (Node `r-games-server`) date strings → real ISO-8601; `match_date` / `event_resolution_date` / `last_wallet_sync_time` are **strings**, not numbers.
+- `TActivityLog.create_date` → epoch **seconds** (the lone outlier).
+- Avatar `dt_created` → epoch-ms number.
+- GamePick request params `ext_user_id` / `smartico_ext_user_id` are SDK-injected (optional for consumers).
+
+---
+
+## 10. Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `run_public_api`: "Tracker is not initialized" | tracker-state method (`getUserProfile`). Use the browser script. |
+| `run_public_api`: "not available in visitor mode" | auth-only (`gamePick*`). Use the browser script. |
+| `run_public_api`: method "is not a function" | published SDK lags local `main`. `npm publish` first. |
+| Browser: `smartico.js → error` / never loads | origin blocked/CSP. Set `SM_ORIGIN` to an allowlisted origin; ensure realistic `SM_UA`. |
+| Browser: `NOT identified (timeout)` | wrong hash/salt, or identify called the queue form. Confirm `SM_SALT`; identify must be method form (already is). Inspect with `SM_DEBUG=1` (`/tmp/sm-capture.log`). |
+| Capture hangs | per-call 8s + stage caps already bound it; check `/tmp/sm-capture.log`. |
+| `undefined.filter`/`.map` from a getter | SDK robustness bug on empty data (`getBonuses`, `getJackpotEligibleGames`) — capture once a relevant entity exists, or fix the SDK guard. |
+| Capability page shows another domain's field comment | the return type is missing that field → add it to the type (don't edit the page). |
+| Internal leak in a page (DB table, ClassId) | a source **field comment** leaked it → fix the comment (public-contract rule). |
+
+---
+
+## 11. Reference
+
+**npm scripts:** `gen-capabilities`, `doc` (TypeDoc), `build`, `bump-tracker`.
+**Scripts:** `scripts/gen-capabilities.js`, `scripts/capture-responses-browser.mjs`, `scripts/postdoc-cleanup.js`.
+**Test creds (env4 ICE — dev/test label only):** label `a6e7ac26-c368-4892-9380-96e7ff82cf3e-4`, brand `f86271e6`, user `4579cace-9069-4d65-93ff-9b8b6c83c45b`, salt `null`.
+**Current coverage:** 52 / 70 methods have a real captured response; the rest use the type-fallback Returns.

package/scripts/capture-responses-browser.mjs

@@ -0,0 +1,301 @@
+/* eslint-disable */
+/**
+ * capture-responses-browser.mjs — REAL-USER response-shape capture (headless).
+ *
+ * Loads the real Smartico tracker bundle (smartico.js) in a headless browser,
+ * does `init` + `identify` as an actual identified player, then calls every
+ * `_smartico.api.*` GET method and writes one anonymized sample per method to
+ * `docs/capabilities/_responses/<method>.json` (the generator inputs for
+ * gen-capabilities.js).
+ *
+ * Why a browser (vs the server-side `run_public_api`): methods that read tracker
+ * state — `getUserProfile`, `getInboxMessageBody` — and the auth-only GamePick
+ * methods are NOT available in the server's visitor mode. Real identify fills
+ * those gaps and gives shapes identical to what a browser consumer sees.
+ *
+ * Setup + run:
+ *   npm i -D playwright && npx playwright install chromium
+ *   node scripts/capture-responses-browser.mjs
+ *
+ * Creds default to the env4 ICE test label (salt_key 'null' → the user-hash is
+ * computable client-side; no server secret needed). Override via env:
+ *   SM_LABEL, SM_BRAND, SM_USER, SM_SALT, SM_SCRIPT_URL
+ */
+import { chromium } from 'playwright';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RESP_DIR = path.join(__dirname, '..', 'docs', 'capabilities', '_responses');
+
+const LABEL = process.env.SM_LABEL || 'a6e7ac26-c368-4892-9380-96e7ff82cf3e-4';
+const BRAND = process.env.SM_BRAND || 'f86271e6';
+const USER  = process.env.SM_USER  || '4579cace-9069-4d65-93ff-9b8b6c83c45b';
+const SALT  = process.env.SM_SALT  || 'null';
+const SCRIPT_URL = process.env.SM_SCRIPT_URL || 'https://libs.smartico.ai/smartico.js';
+
+// hash = md5(lower(`user:salt:ts`)) + ':' + ts ; ts = now + 24h, ms (matches the
+// tracker's expo/public/index.html harness exactly).
+function userHash(user, salt) {
+	const ts = Math.floor(Date.now() / 1000) * 1000 + 24 * 3600 * 1000;
+	const input = `${user.toLowerCase()}:${salt}:${ts}`.toLowerCase();
+	return crypto.createHash('md5').update(input).digest('hex') + ':' + ts;
+}
+
+const anon = (v) => {
+	if (typeof v === 'string') return v
+		.replace(/https?:\/\/[a-z0-9.\-]+\.(cloudfront\.net|smartico\.ai|smrcdn\.cloud|smr\.vc)/gi, 'https://cdn.example')
+		.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '00000000-0000-0000-0000-000000000000');
+	if (Array.isArray(v)) return v.map(anon);
+	if (v && typeof v === 'object') { const o = {}; for (const k of Object.keys(v)) o[k] = (k === 'clean_ext_user_id') ? '0' : anon(v[k]); return o; }
+	return v;
+};
+
+// Bound a captured value so a method returning a huge map/array (e.g.
+// getTranslations → ~800 keys) doesn't produce an 800-line input file. A bit more
+// generous than the page generator (which re-trims to depth 3 / 1 item): keeps a
+// representative sample. strings→200 · arrays→2 · dictionary objects (>50 keys)→20
+// · nesting beyond depth 5 collapses.
+const bound = (v) => {
+	if (typeof v === 'string') return v.length > 200 ? v.slice(0, 197) + '…' : v;
+	if (Array.isArray(v)) return v.slice(0, 2).map(bound);   // no depth collapse — keep the real nested shape
+	if (v && typeof v === 'object') {
+		const keys = Object.keys(v);
+		const cap = keys.length > 50;   // only dictionary-sized maps (getTranslations) are capped
+		const o = {};
+		for (const k of keys.slice(0, cap ? 20 : keys.length)) o[k] = bound(v[k]);
+		if (cap) o['…'] = `(+${keys.length - 20} more keys)`;
+		return o;
+	}
+	return v;
+};
+
+(async () => {
+	const LOG = '/tmp/sm-capture.log';
+	const log = (m) => { const line = '[capture] ' + m; console.log(line); try { fs.appendFileSync(LOG, line + '\n'); } catch {} };
+	try { fs.writeFileSync(LOG, ''); } catch {}
+	const DEBUG = !!process.env.SM_DEBUG; // SM_DEBUG=1 → full console + per-frame WS trace
+	const nodeTimeout = (p, ms, label) => Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error('node-timeout ' + ms + 'ms @ ' + label)), ms))]);
+
+	const hash = userHash(USER, SALT);
+	log('launching chromium…');
+	const browser = await chromium.launch({ headless: true });
+	const context = await browser.newContext({
+		userAgent: process.env.SM_UA || 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+		viewport: { width: 1280, height: 800 }, locale: 'en-US',
+	});
+	const page = await context.newPage();
+	page.on('console', m => { if (DEBUG || ['error', 'warning'].includes(m.type())) log('  [console:' + m.type() + '] ' + m.text().slice(0, 260)); });
+	page.on('requestfailed', r => log('  [requestfailed] ' + r.url().slice(0, 120) + ' — ' + (r.failure()?.errorText || '')));
+	page.on('pageerror', e => log('  [pageerror] ' + String(e.message || e).slice(0, 240)));
+	let wsFrames = 0;
+	page.on('websocket', ws => {
+		log('  [ws OPEN] ' + ws.url().slice(0, 140));
+		ws.on('socketerror', e => log('  [ws ERROR] ' + String(e).slice(0, 200)));
+		ws.on('close', () => log('  [ws CLOSE] ' + ws.url().slice(0, 80)));
+		ws.on('framesent', f => { if (DEBUG && wsFrames++ < 40) log('  [ws →] ' + String(f.payload).slice(0, 160)); });
+		ws.on('framereceived', f => { if (DEBUG && wsFrames++ < 40) log('  [ws ←] ' + String(f.payload).slice(0, 160)); });
+	});
+
+	// Serve a blank, CSP-free page on a stable https origin. libs.smartico.ai 403s
+	// the headless client and its error page carries a CSP that blocks injected
+	// scripts; a self-served origin sidesteps both. smartico.js is still fetched
+	// over the real network with the realistic UA above. Override origin via SM_ORIGIN.
+	const ORIGIN = process.env.SM_ORIGIN || 'https://app.smartico.ai/';
+	await page.route(ORIGIN + '**', r => r.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html><html><head></head><body></body></html>' }));
+	log('goto sandbox origin ' + ORIGIN + ' …');
+	await nodeTimeout(page.goto(ORIGIN, { waitUntil: 'domcontentloaded' }), 20000, 'goto').catch(e => log('goto: ' + e.message));
+
+	log('injecting smartico.js …');
+	const loadState = await nodeTimeout(page.evaluate((SCRIPT_URL) => new Promise((resolve) => {
+		window._smartico_script_location = SCRIPT_URL;
+		const s = document.createElement('script');
+		s.src = SCRIPT_URL;
+		s.onload = () => resolve('loaded');
+		s.onerror = () => resolve('error');
+		document.head.appendChild(s);
+	}), SCRIPT_URL), 25000, 'inject').catch(e => 'timeout:' + e.message);
+	log('smartico.js → ' + loadState);
+
+	await page.waitForFunction(() => typeof window._smartico !== 'undefined', { timeout: 10000 }).catch(() => {});
+	log('init + identify …');
+	const idDiag = await page.evaluate(({ LABEL, BRAND, USER, hash }) => {
+		if (typeof window._smartico === 'undefined') return { reason: 'no _smartico' };
+		const t = { smartico: typeof window._smartico, identify: typeof window._smartico.identify, api: typeof window._smartico.api };
+		try {
+			window._smartico_user_id = USER;
+			window._smartico_user_hash = hash;
+			window._smartico.init(LABEL, { brand_key: BRAND, debug: true });
+			if (typeof window._smartico.identify === 'function') { window._smartico.identify(USER, hash, {}); t.call = 'identify()'; }
+			else { window._smartico('identify', USER, hash, {}); t.call = 'queue'; }
+		} catch (e) { t.error = e.message; }
+		return t;
+	}, { LABEL, BRAND, USER, hash }).catch(e => ({ evalError: e.message }));
+	log('identify diag: ' + JSON.stringify(idDiag));
+
+	const identified = await page.waitForFunction(() => window._smartico?.checkSuccessfullyIdentify?.() === true, { timeout: 35000 })
+		.then(() => true).catch(() => false);
+	log(identified ? 'identified ✓ — calling api methods' : 'NOT identified (timeout) — calling anyway (auth methods will error)');
+	if (await page.evaluate(() => typeof window._smartico) === 'undefined') { log('FATAL: _smartico never loaded (smartico.js blocked). Run from an allowed origin/network.'); await browser.close(); process.exit(2); }
+	if (!identified) {
+		log('identify did not complete — skipping the api sweep (auth-only methods need a live identified session).');
+		log('likely cause: WS backend unreachable from here, origin not allowlisted for the label, or hash/salt rejected. Run from an allowed origin/network, or set SM_SALT / a precomputed hash.');
+		await browser.close();
+		process.exit(3);
+	}
+
+	const results = await nodeTimeout(page.evaluate(async ({ MUTATE }) => {
+		const api = window._smartico.api;
+		const clip = (v) => {
+			if (typeof v === 'string') return v.length > 200 ? v.slice(0, 197) + '…' : v;
+			if (Array.isArray(v)) return v.map(clip);
+			if (v && typeof v === 'object') { const o = {}; for (const k of Object.keys(v)) o[k] = clip(v[k]); return o; }
+			return v;
+		};
+		// "richness" = count of populated (non-null/non-empty) fields — pick the most
+		// complete item so the captured shape isn't a degenerate first element.
+		const score = (o) => (o && typeof o === 'object' && !Array.isArray(o))
+			? Object.values(o).filter(v => v !== null && v !== '' && !(Array.isArray(v) && v.length === 0)).length : 0;
+		const rich = (arr, n = 2) => Array.isArray(arr) ? arr.slice().sort((a, b) => score(b) - score(a)).slice(0, n).map(clip) : clip(arr);
+		const one = (r) => clip(Array.isArray(r) ? r.slice(0, 1) : r);
+		const out = {};
+		const withTimeout = (p, ms = 8000) => Promise.race([
+			Promise.resolve().then(() => p),
+			new Promise((_, rej) => setTimeout(() => rej(new Error('timeout ' + ms + 'ms')), ms)),
+		]);
+		const safe = async (n, fn, post) => { try { const r = await withTimeout(Promise.resolve().then(fn)); out[n] = (post || (Array.isArray(r) ? rich : clip))(r); } catch (e) { out[n] = 'ERR: ' + (e && e.message || String(e)); } };
+		const raw = async (fn) => { try { return await withTimeout(Promise.resolve().then(fn)); } catch (e) { return null; } };
+		const now = Math.floor(Date.now() / 1000);
+
+		// ---- profile (tracker-state, browser-only) ----
+		try { out.getUserProfile = clip(api.getUserProfile()); } catch (e) { out.getUserProfile = 'ERR: ' + e.message; }
+
+		// ---- list fetches (raw kept for id-harvesting; richest sample stored) ----
+		const missions = await raw(() => api.getMissions()); out.getMissions = rich(missions);
+		const badges = await raw(() => api.getBadges()); out.getBadges = rich(badges);
+		await safe('getAchCategories', () => api.getAchCategories());
+		const bonuses = await raw(() => api.getBonuses()); out.getBonuses = rich(bonuses);
+		const store = await raw(() => api.getStoreItems()); out.getStoreItems = rich(store);
+		await safe('getStoreCategories', () => api.getStoreCategories());
+		await safe('getStorePurchasedItems', () => api.getStorePurchasedItems({ limit: 3 }));
+		const tours = await raw(() => api.getTournamentsList()); out.getTournamentsList = rich(tours);
+		const clans = await raw(() => api.getClans()); out.getClans = clip(clans);
+		const jackpot = await raw(() => api.jackpotGet()); out.jackpotGet = clip(jackpot);
+		const raffles = await raw(() => api.getRaffles()); out.getRaffles = rich(raffles);
+		const minigames = await raw(() => api.getMiniGames()); out.getMiniGames = rich(minigames);
+		await safe('getMiniGamesHistory', () => api.getMiniGamesHistory({ limit: 3 }));
+		const avatars = await raw(() => api.getAvatarsList()); out.getAvatarsList = rich(avatars);
+		await safe('getAvatarsCustomized', () => api.getAvatarsCustomized());
+		await safe('getAvatarPrompts', () => api.getAvatarPrompts());
+		const inbox = await raw(() => api.getInboxMessages()); out.getInboxMessages = rich(inbox);
+		await safe('getInboxUnreadCount', () => api.getInboxUnreadCount(), clip);
+		await safe('getCustomSections', () => api.getCustomSections());
+		await safe('getTranslations', () => api.getTranslations('EN'), clip);
+		await safe('getCurrentLevel', () => api.getCurrentLevel(), clip);
+		await safe('getLevels', () => api.getLevels());
+		await safe('getUserLevelExtraCounters', () => api.getUserLevelExtraCounters(), clip);
+		await safe('getActivityLog', () => api.getActivityLog({ startTimeSeconds: now - 2592000, endTimeSeconds: now, from: 0, to: 20 }));
+
+		// ---- detail / param methods — every id harvested from the lists above (no hardcodes) ----
+		const ids = {};
+		ids.tournamentInstance = tours?.[0]?.instance_id;
+		if (ids.tournamentInstance != null) out.getTournamentInstanceInfo = clip(await raw(() => api.getTournamentInstanceInfo(ids.tournamentInstance)));
+		ids.clanId = clans?.clans?.[0]?.clan_id;
+		if (ids.clanId != null) out.getClanInfo = clip(await raw(() => api.getClanInfo(ids.clanId)));
+		ids.jpTemplate = Array.isArray(jackpot) ? jackpot?.[0]?.jp_template_id : jackpot?.jp_template_id;
+		if (ids.jpTemplate != null) {
+			await safe('getJackpotWinners', () => api.getJackpotWinners({ jp_template_id: ids.jpTemplate }));
+			await safe('getJackpotEligibleGames', () => api.getJackpotEligibleGames({ jp_template_id: ids.jpTemplate }));
+		}
+		ids.inboxGuid = inbox?.[0]?.message_guid;
+		if (ids.inboxGuid) await safe('getInboxMessageBody', () => api.getInboxMessageBody(ids.inboxGuid), clip);
+		const raffle0 = raffles?.[0]; const draw0 = raffle0?.draws?.[0];
+		if (raffle0 && draw0) {
+			await safe('getRaffleDrawRun', () => api.getRaffleDrawRun({ raffle_id: raffle0.id, run_id: draw0.run_id }), clip);
+			await safe('getRaffleDrawRunsHistory', () => api.getRaffleDrawRunsHistory({ raffle_id: raffle0.id }));
+		}
+		await safe('getLeaderBoard', () => api.getLeaderBoard(1), clip);
+
+		// ---- GamePick: find a usable MatchX/Quiz template from the minigame list ----
+		const gpGames = (minigames || []).filter(g => g.saw_game_type === 'matchx' || g.saw_game_type === 'quiz');
+		for (const g of gpGames) {
+			const info = await raw(() => api.gamePickGetGameInfo({ saw_template_id: g.id }));
+			if (info && info.errCode === 0) {
+				out.gamePickGetGameInfo = clip(info);
+				const rounds = await raw(() => api.gamePickGetActiveRounds({ saw_template_id: g.id }));
+				out.gamePickGetActiveRounds = one(rounds);
+				const roundId = rounds?.data?.[0]?.round_id;
+				ids.gpTemplate = g.id; ids.gpRound = roundId;
+				if (roundId) {
+					out.gamePickGetActiveRound = one(await raw(() => api.gamePickGetActiveRound({ saw_template_id: g.id, round_id: roundId })));
+					out.gamePickGetBoard = one(await raw(() => api.gamePickGetBoard({ saw_template_id: g.id, round_id: roundId })));
+				}
+				out.gamePickGetHistory = one(await raw(() => api.gamePickGetHistory({ saw_template_id: g.id })));
+				out.gamePickGetUserInfo = one(await raw(() => api.gamePickGetUserInfo({ saw_template_id: g.id })));
+				break;
+			}
+		}
+
+		if (!MUTATE) return out;
+
+		// =================== MUTATIONS (opt-in via SM_MUTATIONS=1) ===================
+		// TEST ACCOUNT ONLY. Reversible mutations are restored; one-shot/consuming ones
+		// (claim/buy/register/play) intentionally change state to capture the result shape.
+		const prof = (() => { try { return api.getUserProfile() || {}; } catch { return {}; } })();
+
+		if (ids.jpTemplate != null) { // jackpot opt in → out (net opted-out)
+			await safe('jackpotOptIn', () => api.jackpotOptIn({ jp_template_id: ids.jpTemplate }), clip);
+			await safe('jackpotOptOut', () => api.jackpotOptOut({ jp_template_id: ids.jpTemplate }), clip);
+		}
+		if (ids.inboxGuid) { // inbox mark read + favorite toggle (favorite restored)
+			await safe('markInboxMessageAsRead', () => api.markInboxMessageAsRead(ids.inboxGuid), clip);
+			await safe('markUnmarkInboxMessageAsFavorite', () => api.markUnmarkInboxMessageAsFavorite(ids.inboxGuid, true), clip);
+			await raw(() => api.markUnmarkInboxMessageAsFavorite(ids.inboxGuid, false));
+			await safe('markAllInboxMessagesAsRead', () => api.markAllInboxMessagesAsRead(), clip);
+		}
+		const av = (avatars || [])[0]; // setAvatar (restore original)
+		const newUrl = av?.avatar_url || av?.public_meta?.image_url;
+		const newReal = av?.avatar_real_id ?? av?.id;
+		if (newUrl && newReal != null) {
+			await safe('setAvatar', () => api.setAvatar({ avatar_url: newUrl, avatar_real_id: newReal }), clip);
+			if (prof.avatar_url && prof.avatar_real_id != null) await raw(() => api.setAvatar({ avatar_url: prof.avatar_url, avatar_real_id: prof.avatar_real_id }));
+		}
+		const optMission = (missions || []).find(m => m.is_requires_optin && !m.is_opted_in && !m.is_locked);
+		if (optMission) await safe('requestMissionOptIn', () => api.requestMissionOptIn(optMission.id), clip);
+		const claimMission = (missions || []).find(m => m.requires_prize_claim && m.ach_completed_id);
+		if (claimMission) await safe('requestMissionClaimReward', () => api.requestMissionClaimReward(claimMission.id, claimMission.ach_completed_id), clip);
+		let rOpt = null; // raffle opt-in (a draw that requires it, not yet opted-in)
+		for (const rf of (raffles || [])) { const d = (rf.draws || []).find(d => d.requires_optin && !d.user_opted_in && d.is_active); if (d) { rOpt = { raffle_id: rf.id, draw_id: d.id, raffle_run_id: d.run_id }; break; } }
+		if (rOpt) await safe('requestRaffleOptin', () => api.requestRaffleOptin(rOpt), clip);
+		const bonus = (bonuses || []).find(b => b.is_redeemable ?? b.redeemable) || (bonuses || [])[0];
+		if (bonus) await safe('claimBonus', () => api.claimBonus(bonus.id), clip); // consumes a bonus
+		const regT = (tours || []).find(t => t.is_can_register) || (tours || [])[0];
+		if (regT) await safe('registerInTournament', () => api.registerInTournament(regT.instance_id), clip); // success or insufficient-funds shape
+		const buyItem = (store || []).filter(s => s.purchase_type === 'points').sort((a, b) => (a.price || 0) - (b.price || 0))[0] || (store || [])[0];
+		if (buyItem) await safe('buyStoreItem', () => api.buyStoreItem(buyItem.id), clip); // success or insufficient-balance shape
+		const myClan = prof.core_clan_id ? Number(prof.core_clan_id) : null;
+		if (myClan) await safe('joinClan', () => api.joinClan(myClan), clip); // re-join current clan = harmless, still returns the shape
+		const freeGame = (minigames || []).find(g => g.saw_buyin_type === 'free' && Number(g.spin_count) !== 0) || (minigames || []).find(g => g.saw_buyin_type === 'free');
+		if (freeGame) { // play a FREE minigame (no currency) without auto-ack, then acknowledge
+			const play = await raw(() => api.playMiniGame(freeGame.id, { acknowledge: false }));
+			if (play) out.playMiniGame = clip(play);
+			if (play && play.request_id) await safe('miniGameWinAcknowledgeRequest', () => api.miniGameWinAcknowledgeRequest(play.request_id), clip);
+			await safe('playMiniGameBatch', () => api.playMiniGameBatch(freeGame.id, 1), clip);
+		}
+
+		return out;
+	}, { MUTATE: !!process.env.SM_MUTATIONS }), 240000, 'sweep');
+
+	let ok = 0, skip = [];
+	for (const [name, val] of Object.entries(results)) {
+		if (typeof val === 'string' && val.startsWith('ERR')) { skip.push(`${name}: ${val.slice(0, 70)}`); continue; }
+		fs.writeFileSync(path.join(RESP_DIR, `${name}.json`), JSON.stringify(bound(anon(val)), null, 2));
+		ok++;
+	}
+	log(`wrote ${ok} response files`);
+	if (skip.length) log('skipped (errors):\n  ' + skip.join('\n  '));
+	log('now run: npm run gen-capabilities');
+	await browser.close();
+})().catch(e => { try { fs.appendFileSync('/tmp/sm-capture.log', '[capture] fatal: ' + e.message + '\n'); } catch {} console.error('[capture] fatal:', e.message); process.exit(1); });