@smartico/public-api 0.0.403 → 0.0.405

package/.claude/skills/api-tsdoc-final/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: api-tsdoc-final
+description: Run the FULL Smartico public-api documentation-refresh batch in one pass — actualize the `_smartico.on` callback list, refresh the `_smartico` object reference, extend the native WebSocket protocol doc, enrich WSAPI method TSDocs (via the api-tsdoc skill), keep the transforms concept + doc-build wiring current, and finish by preparing a commit message for human review. Use when the user types `/api-tsdoc-final`, or asks to "do the full docs batch", "refresh all SDK docs", or "actualize the public-api docs".
+---
+
+# api-tsdoc-final
+
+The end-to-end documentation refresh for the Smartico **public-api** SDK
+(`/Users/aa/Desktop/SM/public-api/`). It orchestrates every documentation
+action performed per release into one ordered batch, then stops at a prepared
+commit message for a human to review.
+
+This skill **wraps** the per-method [`api-tsdoc`](../api-tsdoc/SKILL.md) skill —
+it does not replace it. `api-tsdoc` enriches one domain/method (hive extraction,
+validation, UI guides, spillover, README + doc-todo housekeeping). This skill
+adds the surrounding documentation surfaces that aren't tied to a single WSAPI
+method: callbacks, the `_smartico` object, the native protocol, the transforms
+concept, and the doc-build wiring — and ties it all off with a review-ready
+commit message.
+
+## Hard rules (same spirit as api-tsdoc)
+
+- **NEVER commit, stage, or push.** This skill ENDS by *preparing* a commit
+  message for human review (step 7). Do not run `git commit` / `git push`.
+- **NEVER run `npm run doc`.** It is human-triggered. The skill leaves a
+  verification checklist for the human to run it and confirm a clean build.
+- **Edit only:**
+  - `.ts` under `public-api/src/` (domain classes, `WSAPITypes.ts`, and the
+    vendored `SmarticoLib/index.ts` enum — see step 1 caveat),
+  - UI guides under `public-api/docs/ui/<domain>/`,
+  - the hand-authored concept docs `public-api/docs/{Callbacks,SmarticoObject,Transforms}.md`,
+  - the native protocol `public-api/docs/native/PROTOCOL.md` (+ `ADDING_METHODS.md`),
+  - `public-api/tsconfig.json` (only `typedocOptions.entryPoints` and `projectDocuments`),
+  - `public-api/README.md`, `public-api/doc-todo.md`.
+- **NEVER edit `public-api/docs/api/**`** — TypeDoc output, wiped by
+  `cleanOutputDir: true` on every `npm run doc`. To add an interface page,
+  add its source `.ts` to `tsconfig` `entryPoints` (never hand-create the `.md`).
+- **`server/llm-sources/` is a read-only RAG mirror and off-limits by default.**
+  Canonical sources are the tracker repo and the live help site
+  (`help.smartico.ai`). If the help-page narrative is needed, ask the user to
+  point at the canonical help repo, or proceed only on explicit user override.
+- Keep all `/** */` and concept-doc content **consumer-facing** — no internal
+  class/file refs, ClassId values (except in PROTOCOL.md, which is the raw
+  protocol spec), DB schemas, or Jira refs. Reference the in-tracker UI as
+  "the default Smartico UI".
+
+## Sources of truth
+
+| Artifact | Edit | Canonical source(s) to read |
+|---|---|---|
+| Callback list (`docs/Callbacks.md`) | `public-api/docs/Callbacks.md` | `tracker/submodule/client-common-libs/src/lib-common/enum/ExternalCallbackKey.ts` (the 18-key enum) + trigger sites: `tracker/src/tracker/{Tracker,Gamification,Smartico,TrackerVisitor}.ts` (grep `triggerExternalCallBack`) + iframe-origin emitters in `tracker/ach/src/core/engine/{SawEngine,UserEngine}.ts` |
+| Vendored callback enum | `public-api/src/SmarticoLib/index.ts` (`declare enum EXTERNAL_CALLBACK_KEY`) | Same `ExternalCallbackKey.ts` (keep in sync; it's a generated bundle — see step 1) |
+| `_smartico` object (`docs/SmarticoObject.md`) | `public-api/docs/SmarticoObject.md` | `tracker/src/tracker/Smartico.ts` (grep `public static`); deep-link values from `DpType` + widget types from `EWidgetType` (verify against `public-api/src/SmarticoLib/index.ts` / `tracker/src/shared/Enums.ts`) |
+| Native protocol (`docs/native/PROTOCOL.md`) | `public-api/docs/native/PROTOCOL.md` | Concept in `public-api/docs/native/ADDING_METHODS.md`; ClassIds from `public-api/src/Base/ClassId.ts`; raw request/response shapes from `public-api/src/SmarticoAPI.ts` + the per-domain `*Request.ts` / `*Response.ts` |
+| WSAPI method TSDocs + UI guides | `public-api/src/WSAPI/*.ts`, `docs/ui/<domain>/` | Delegated to the `api-tsdoc` skill |
+| Transforms concept (`docs/Transforms.md`) | `public-api/docs/Transforms.md` | `grep -rn "export const .*Transform" src/` + `*T` methods in `public-api/src/SmarticoAPI.ts` |
+| Build wiring | `public-api/tsconfig.json`, `public-api/scripts/postdoc-cleanup.js` | — |
+
+## Workflow
+
+Run the steps in order. Each step is idempotent — it reconciles the doc against
+the current code, so re-running the skill just picks up the delta. Track
+progress with TaskCreate/TaskUpdate (one task per step).
+
+### Step 1 — Actualize callbacks (`_smartico.on`)
+
+1. Read the canonical enum `ExternalCallbackKey.ts`. Diff its keys against:
+   - the events documented in `docs/Callbacks.md`, and
+   - the `declare enum EXTERNAL_CALLBACK_KEY` in `src/SmarticoLib/index.ts`.
+2. For each **new** key: grep the tracker for its `triggerExternalCallBack(EXTERNAL_CALLBACK_KEY.X, ...)`
+   site(s) to capture the exact handler arguments; for iframe-origin events
+   (`MNIGAME_WIN`, `ACH_GAME_OPENING`, `GF_UX`) read the ach emit sites. Add a
+   row to the Callbacks.md event table (grouped: Lifecycle / User state / Widget
+   lifecycle / Wins & launches / Errors) with when-it-fires + handler args.
+3. For **removed/renamed** keys: remove/adjust the row.
+4. Sync `src/SmarticoLib/index.ts`'s enum to match canonical (keep canonical
+   order). **Caveat:** that file is `// Generated by dts-bundle-generator` — there
+   is no regen script in this repo, so it's a committed vendored artifact;
+   editing it aligns the committed copy with canonical, but flag in the return
+   summary that the upstream smartico.js `.d.ts` bundle should be regenerated so
+   it doesn't drift back.
+5. Keep Callbacks.md links plain-text (no relative `.md` links — see step 6
+   "media-copy" note).
+
+### Step 2 — Update the `_smartico` object reference
+
+1. Read `Smartico.ts`; list `public static` methods + the `api` / `vapi`
+   members. Diff against `docs/SmarticoObject.md`.
+2. Add/adjust method entries (signature, behavior, preconditions, visitor-mode
+   notes). Group: Setup & identity / User profile / Deep links & embedding /
+   Events & analytics / Push / Visitor games / Data API / Utilities.
+3. Verify the deep-link table values against the `DpType` enum and widget types
+   against `EWidgetType`. Cross-reference `on`/`off` to Callbacks.md (plain text).
+4. (Optional) If the user authorizes reading the help page, fold in operator-
+   facing narrative (session/login window, identity-via-globals + hash formula,
+   control-group flag, URL-triggered deep links, localhost flag, IFrame bridge).
+
+### Step 3 — Extend the native protocol doc
+
+Follow the `docs/native/ADDING_METHODS.md` concept for any WSAPI method **not yet
+in PROTOCOL.md**:
+
+1. Determine which methods are missing: compare PROTOCOL.md's API-Methods ToC
+   against the WSAPI surface. **Exclude GamePick** (`gamePick*`) — it's HTTP REST
+   to a separate games server, not the WebSocket protocol.
+
+   **Name-mapping caveat (avoid false positives).** PROTOCOL.md is keyed by
+   **protocol-layer** method names, NOT the WSAPI wrapper names — a naive
+   string-match of WSAPI names against the ToC reports many already-covered
+   methods as "missing". Map before concluding a gap; known aliases:
+   | WSAPI wrapper | PROTOCOL.md name |
+   |---|---|
+   | `jackpotGet` | `getJackpots` |
+   | `getActivityLog` | `getPointsHistory` |
+   | `getUserLevelExtraCounters` / `getCurrentLevel` | `getUserGamificationInfo` (level/counters derived) |
+   | `miniGameWinAcknowledgeRequest` | `miniGameWinAcknowledge` |
+   | `markUnmarkInboxMessageAsFavorite` | `markInboxMessageAsFavorite` |
+   | `checkSegmentMatch` | covered by `checkSegmentListMatch` (shared request) |
+   | `getBadges` | shares `GET_ACHIEVEMENT_MAP` with `getMissions` (no own section) |
+   | `setNickname` | `setCustomUsername` |
+   Confirm a true gap by checking the **request ClassId** isn't already documented
+   (grep the CID in PROTOCOL.md), not just the method name. Client-only derived
+   methods (e.g. `getCurrentLevel`) have no protocol call and are correctly absent.
+2. For each missing WS method: find request/response ClassId (numeric) in
+   `Base/ClassId.ts`; document the **raw** wire shape (NOT the friendly `T`
+   types) as request + response field tables; add `### Error Codes` table when
+   the method has named codes; add a JSON example where helpful.
+3. Link complex array/object types to `../api/interfaces/<Type>.md`. If that page
+   doesn't exist, **add the interface's source `.ts` to `tsconfig` `entryPoints`**
+   (do NOT hand-create the `.md` in `docs/api/`). Or inline a compact field table.
+4. Add ToC entries (new `####` categories as needed); GitHub auto-slugs anchors.
+5. Note: a method that shares a request with another (e.g. `getBadges` reuses
+   `GET_ACHIEVEMENT_MAP_REQUEST` from `getMissions`) needs no new section —
+   just confirm the shared section documents the distinction.
+
+### Step 4 — Enrich WSAPI method TSDocs (delegate to `api-tsdoc`)
+
+Run the `api-tsdoc` skill for the target domain(s)/method(s) the user named (or,
+with no target, scan `src/WSAPI/WSAPI<Domain>.ts` for thin TSDocs and propose a
+list). `api-tsdoc` owns: hive extraction + mandatory validation pass, the
+TSDoc/UI-guide contract, UI guides under `docs/ui/<domain>/`, spillover into
+`WSAPITypes.ts`, and the README "UI Guides" column + `doc-todo.md` tally + SDK
+gaps list. Do not duplicate that work here — invoke the skill.
+
+### Step 5 — Refresh the transforms concept doc
+
+Re-survey `grep -rnE "export const [A-Za-z]+[Tt]ransform" src/` and the `*T`
+methods in `SmarticoAPI.ts`. If new domains/transforms appeared, update
+`docs/Transforms.md` (the three naming conventions table, the "what a transform
+does" categories, and the before/after example stay accurate). Keep its links
+plain-text.
+
+### Step 6 — Build hygiene (NO `npm run doc`)
+
+Reconcile the doc-build wiring so the next human `npm run doc` is clean:
+
+- **Entry points**: every interface `.md` linked from PROTOCOL.md (or a `{@link Type}`
+  that should resolve) must have its source `.ts` in `tsconfig` `entryPoints`.
+- **projectDocuments**: every hand-authored concept doc
+  (`Callbacks.md`, `SmarticoObject.md`, `Transforms.md`, + any new one) must be
+  listed in `tsconfig` `typedocOptions.projectDocuments`, AND linked from README.
+- **No relative `.md` links inside concept docs / project documents.** TypeDoc
+  media-copies resolvable relative `.md` links into `docs/api/_media/`; use
+  plain-text references (e.g. "see `docs/native/PROTOCOL.md`") instead.
+- **`@param` warnings**: a destructured object param **without** a `= {}` default
+  makes TypeDoc warn on `@param params.*` ("not used"). Fix by moving the
+  descriptions onto the inline type-literal properties as `/** */` comments and
+  removing the `@param params.*` tags (do NOT add `= {}` to params that have
+  required fields). Methods with `= {}` defaults are fine as-is.
+- **Unresolved `{@link}` warnings**: a `{@link method}` to a method defined
+  *later* in the WSAPI inheritance chain won't resolve → convert to backtick
+  code (`` `method` ``). For an enum/type (e.g. `JoinClanErrorCode`), prefer
+  adding its source to `entryPoints` so the link resolves.
+- Leave the human a checklist (step 8) to run `npm run doc` and confirm zero new
+  warnings + that `docs/api/documents/<concept>.md` generated.
+
+### Step 7 — Prepare the commit message (DO NOT COMMIT)
+
+1. Run `git status` and `git diff --stat` from `public-api/`.
+2. Draft a single review-ready commit message grouped by area
+   (callbacks / `_smartico` object / native protocol / WSAPI TSDocs / transforms /
+   build wiring). Conventional-commit style, e.g.:
+
+   ```
+   docs(public-api): refresh SDK docs — callbacks, _smartico object, native protocol, <domains>
+
+   - callbacks: add <N> events to Callbacks.md; sync EXTERNAL_CALLBACK_KEY vendored enum
+   - _smartico object: <added/updated methods>
+   - native protocol: document <methods> (ClassIds <…>); +<N> interface entry points
+   - WSAPI TSDoc: enrich <domain> (<N> methods, <N> UI guides) via api-tsdoc
+   - transforms: <delta or "verified current">
+   - build: projectDocuments/entryPoints wiring; fixed <N> typedoc warnings
+   ```
+3. **Present it for review. Do not run `git commit`.** Surface, separately: the
+   SmarticoLib enum regen caveat (step 1), any hive-sourced claims not directly
+   verified, and any links pending the next `npm run doc`.
+
+### Step 8 — Verification checklist (for the human)
+
+Output these for the human to run after review:
+
+```sh
+cd /Users/aa/Desktop/SM/public-api
+# tsconfig is valid + concept docs wired
+node -e "const o=require('./tsconfig.json'); console.log(o.typedocOptions.projectDocuments)"
+# concept docs have no relative .md links (media-copy safe)
+grep -nE "\]\([a-z][^)]*\.md" docs/Callbacks.md docs/SmarticoObject.md docs/Transforms.md || echo OK
+# every PROTOCOL.md interface link has a target after npm run doc
+npm run doc            # human-run; confirm ZERO new warnings
+grep -rn "../../docs/ui/" docs/api/classes/ && echo BROKEN || echo OK
+```
+
+## Output (return summary)
+
+- **Per-step delta**: what changed in each surface (callbacks added, `_smartico`
+  methods touched, native methods documented, domains enriched, transforms delta,
+  build wiring).
+- **Files edited** (paths).
+- **The prepared commit message** (for review — not committed).
+- **Open items / caveats**: SmarticoLib enum regen, links pending `npm run doc`,
+  any unverified hive claims, the help-page (llm-sources) source caveat.
+- **Cost**: hive totals from the `api-tsdoc` sub-run.
+
+Then **stop**. No commit, no push, no `npm run doc`.
+
+## Notes / scope reminders
+
+- GamePick is HTTP REST (separate `r-games-server`), excluded from PROTOCOL.md.
+- `getBadges` shares `GET_ACHIEVEMENT_MAP_REQUEST` with `getMissions` — no
+  separate native section.
+- `doc-todo.md` (running tally + numbered SDK-gaps list) is maintained by the
+  `api-tsdoc` sub-run in step 4; the batch just confirms it's updated.
+
+## Step 6.5 — Capability pages (RAG ingestion lane)
+
+After the method TSDocs are enriched (step 4) and before the verification
+checklist, refresh the **capability pages** — the docs the IDE coding agent
+actually retrieves (`docs/capabilities/<method>.md`, generated by the public-api
+repo's `scripts/gen-capabilities.js`). The IDE's `api` search lane is wired to
+read **only** these (bo_server `LLMSourceTypeId.PUBLIC_API_CAPABILITY`), not the
+raw source — so a method with no capability page is invisible to the agent.
+
+Two sub-steps (see the `api-tsdoc` skill's "Capability pages" section for the full
+recipe — capture conventions, anonymization, the `run_public_api` creds, the
+`getUserProfile`/tracker-state browser fallback):
+
+1. **Capture missing/stale responses.** For every method enriched this batch (and
+   any with no `docs/capabilities/_responses/<method>.json` yet), capture a real
+   response via `mcp__hive__run_public_api`, anonymize, and write the JSON. Track
+   coverage: `ls docs/capabilities/_responses/ | wc -l` vs the method count.
+2. **Regenerate.** `npm run gen-capabilities` → rewrites all
+   `docs/capabilities/*.md`. Spot-check a handful (right per-domain field
+   comments, real example response present, no internal-name leaks surfaced from a
+   field comment — fix any leak at the source type, then re-run).
+
+Add a line to the verification checklist for the human:
+
+```sh
+npm run gen-capabilities   # regenerate capability pages
+# every capability page that should have a real response payload has one:
+for m in getMissions getStoreItems getTournamentsList getMiniGames getInboxMessages; do
+  test -f docs/capabilities/_responses/$m.json && echo "OK   $m" || echo "MISS $m"; done
+```
+
+**Never hand-edit `docs/capabilities/*.md`** (generated, overwritten). Do not
+commit; this is part of the review-ready batch like everything else.

package/.claude/skills/api-tsdoc-howto/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: api-tsdoc-howto
+description: Inspect the Smartico public-api working tree (uncommitted changes + recent commits), determine which docs / capability pages / captured responses are now stale, and output the EXACT ordered commands to bring the docs + RAG pipeline back in sync. Read-only — never edits, never runs the build/capture/commit steps itself. Use when the user types /api-tsdoc-howto, or asks "what docs need updating", "how do I sync the SDK docs", "what's stale", "what do I run to finish the docs".
+---
+
+# api-tsdoc-howto
+
+A **read-only diagnostic** for the `@smartico/public-api` docs + RAG pipeline.
+It looks at what changed (uncommitted + recent commits), works out what is now
+out of date, and prints a **copy-pasteable, ordered command plan** to complete
+the full flow. It does NOT make edits or run any build/capture/commit step — it
+tells the human exactly what to run.
+
+Full background: `/Users/aa/Desktop/SM/public-api/readme-smartico-dev.md`.
+
+## Hard rules
+
+- **Read-only.** Only run inspection commands (`git status`, `git diff`,
+  `git log`, `ls`, `grep`, `node -e` for counting). NEVER run
+  `npm run gen-capabilities`, `npm run doc`, the capture scripts,
+  `git commit`, `npm publish`, or `bump-tracker`. NEVER edit files.
+- **Output = a plan, not actions.** End with an ordered list of exact commands
+  the human runs, plus a one-paragraph "what's stale and why".
+- Work in `/Users/aa/Desktop/SM/public-api` (the `PUB` dir below).
+
+## The pipeline (what feeds what)
+
+```
+SOURCE (edit)                                  → REGEN STEP            → ARTIFACT (don't edit)
+src/WSAPI/WSAPI<Domain>.ts (method TSDoc)       ┐
+src/WSAPI/WSAPITypes.ts + src/<Domain>/*.ts     ├ npm run gen-capabilities → docs/capabilities/<method>.md
+docs/ui/<domain>/UIGuide_<method>.md            │
+docs/capabilities/_responses/<method>.json      ┘
+src/**.ts (TSDoc) + tsconfig entryPoints        → npm run doc              → docs/api/**
+docs/capabilities/**                            → JobLLM2 (env2 cron, auto) → RAG (PUBLIC_API_CAPABILITY)
+```
+
+## Step 1 — gather state
+
+```sh
+PUB=/Users/aa/Desktop/SM/public-api
+git -C "$PUB" status --porcelain
+git -C "$PUB" --no-pager diff --stat HEAD
+git -C "$PUB" --no-pager log --oneline -10
+# coverage
+echo "pages: $(ls "$PUB"/docs/capabilities/*.md 2>/dev/null | wc -l | tr -d ' ') | responses: $(ls "$PUB"/docs/capabilities/_responses/*.json 2>/dev/null | wc -l | tr -d ' ')"
+```
+
+Consider BOTH uncommitted changes and the last few commits — a method enriched
+in a recent commit may still be missing its regenerated page or captured
+response if the author stopped early.
+
+## Step 2 — classify each changed path → impact
+
+| Changed path | What it means | Needs |
+|---|---|---|
+| `src/WSAPI/WSAPI<Domain>.ts` | method TSDoc/signature/return changed | `gen-capabilities`; `doc` |
+| `src/WSAPI/WSAPITypes.ts`, `src/<Domain>/*.ts` (types) | field shapes/comments changed | `gen-capabilities`; `doc`; maybe **re-capture** if the wire shape changed |
+| `docs/ui/<domain>/UIGuide_<method>.md` | behavioral contract changed | `gen-capabilities` |
+| `docs/capabilities/_responses/<method>.json` | new/updated real response | `gen-capabilities` |
+| `scripts/gen-capabilities.js` | generator logic changed | `gen-capabilities` (all pages) |
+| `tsconfig.json` (`entryPoints`/`projectDocuments`) | new public type/doc | `doc` |
+| **`docs/capabilities/*.md`** edited by hand | ⚠️ generated file hand-edited | WARN — will be overwritten; move the change to the source + regenerate |
+| **`docs/api/**`** edited by hand | ⚠️ TypeDoc output hand-edited | WARN — overwritten by `doc` |
+| a **new public method** in `WSAPI<Domain>.ts` | brand-new surface | full flow: TSDoc → capture → `gen-capabilities` → entryPoints/`doc` |
+
+## Step 3 — concrete staleness checks (run these)
+
+```sh
+PUB=/Users/aa/Desktop/SM/public-api
+
+# (a) Inputs changed but capability pages NOT regenerated → pages are STALE.
+#     If any of these appear in `git status` while docs/capabilities/*.md do NOT,
+#     gen-capabilities must run.
+git -C "$PUB" status --porcelain -- src/WSAPI docs/ui docs/capabilities/_responses scripts/gen-capabilities.js
+git -C "$PUB" status --porcelain -- docs/capabilities/'*.md'   # empty here = not yet regenerated
+
+# (b) Public methods with NO capability page (new methods) or NO captured response.
+node -e '
+const fs=require("fs"),path=require("path");
+const W=path.join("'"$PUB"'","src/WSAPI"), C=path.join("'"$PUB"'","docs/capabilities"), R=path.join(C,"_responses");
+const methods=new Set();
+for(const f of fs.readdirSync(W)){ if(!/^WSAPI.*\.ts$/.test(f)||f==="WSAPITypes.ts"||f==="WSAPIBase.ts")continue;
+  for(const m of fs.readFileSync(path.join(W,f),"utf8").matchAll(/^\tpublic (?:async )?([a-zA-Z][A-Za-z0-9]*)\s*[(<]/gm)) methods.add(m[1]); }
+const pages=new Set(fs.existsSync(C)?fs.readdirSync(C).filter(f=>f.endsWith(".md")).map(f=>f.slice(0,-3)):[]);
+const resp=new Set(fs.existsSync(R)?fs.readdirSync(R).filter(f=>f.endsWith(".json")).map(f=>f.slice(0,-5)):[]);
+const noPage=[...methods].filter(m=>!pages.has(m));
+const noResp=[...methods].filter(m=>!resp.has(m));
+console.log("methods:",methods.size,"| no capability page:",noPage.join(", ")||"none","| no captured response:",noResp.join(", ")||"none");
+'
+
+# (c) New exported public types not yet in TypeDoc entryPoints.
+grep -oE "export (interface|class|enum|type) [A-Z][A-Za-z0-9_]+" "$PUB"/src/WSAPI/WSAPITypes.ts | awk '{print $3}' | sort -u > /tmp/_types.txt
+node -e 'const o=require("'"$PUB"'/tsconfig.json");console.log("entryPoints:",(o.typedocOptions.entryPoints||[]).join(" "))'
+```
+
+Interpretation:
+- **(a)** source/ui/response changed AND `docs/capabilities/*.md` unchanged → **run gen-capabilities**.
+- **(b)** `no capability page` → a new method; needs TSDoc + capture + gen. `no captured response` → page exists but only type-fallback Returns (no real example) → capture if reachable.
+- **(c)** a new public type referenced by a method but absent from `entryPoints`/`docs/api` → add it + run `doc`.
+
+## Step 4 — emit the ordered command plan
+
+Print ONLY the steps that apply, in order. Template:
+
+```
+Docs sync plan (run from /Users/aa/Desktop/SM/public-api):
+
+# 1. capture real responses (only if new/changed methods need a real example)
+#    visitor-reachable methods — fastest, no browser:
+#      use the mcp__hive__run_public_api tool (see readme §4a)
+#    auth-only (getUserProfile / gamePick* / getInboxMessageBody) or a full refresh:
+SM_MUTATIONS=1 node scripts/capture-responses-browser.mjs   # omit SM_MUTATIONS for read-only
+#    (one-time: npm i -D playwright && npx playwright install chromium)
+
+# 2. regenerate capability pages   (REQUIRED whenever any source/type/ui/response changed)
+npm run gen-capabilities
+
+# 3. regenerate the TypeDoc reference   (only if TSDoc or tsconfig entryPoints changed)
+npm run doc
+
+# 4. verify
+ls docs/capabilities/_responses/*.json | wc -l   # coverage vs method count
+git status
+
+# 5. ship
+git add -A && git commit -m "<message>"
+npm version patch && npm publish          # so run_public_api + consumers see new methods
+npm run bump-tracker                       # flow into live _smartico.api
+#    RAG re-indexes automatically (JobLLM2, env2 cron) — no manual step.
+```
+
+Drop steps that don't apply (e.g. no entryPoints change → skip `npm run doc`;
+no method change → skip capture). If hand-edited generated files were found,
+lead with a ⚠️ telling the human to move the edit into the source first.
+
+## Output format
+
+1. **Changed (uncommitted + recent commits)** — short bullet list, grouped by impact.
+2. **Stale / missing** — what's out of date and why (pages not regenerated, methods with no captured response, types missing from entryPoints, hand-edited generated files).
+3. **Run this** — the ordered, trimmed command plan from Step 4.
+
+Then stop. No edits, no execution beyond read-only inspection.

package/dist/MiniGames/SAWTemplate.d.ts

@@ -21,6 +21,10 @@ export interface SAWTemplate {
     maxSpinsCount: number;
     maxSpinsPediodMs: number;
     next_available_spin_ts?: number;
+    /** Soonest-expiring spin's expiration time for this user (epoch ms); `null`/absent when no expirable spins. */
+    earliest_expiration_dt?: number | null;
+    /** Latest-expiring spin's expiration time for this user (epoch ms); `null`/absent when no expirable spins. */
+    latest_expiration_dt?: number | null;
     saw_skin_key: string;
     saw_skin_ui_definition: {
         skin_folder: string;

package/dist/MiniGames/SAWTemplateUI.d.ts

@@ -365,8 +365,12 @@ export interface SAWTemplateUI {
     game_difficulty?: SAWGameDifficultyType;
     /**
      * URL of the operator-hosted custom mini-game, loaded inside an iframe by
-     * the widget for `SAWGameType.CustomMinigame`.  The operator is trusted, so
-     * the iframe is rendered without a sandbox.
+     * the widget for `SAWGameType.CustomMinigame`.  The operator is trusted
+     * (the URL resolves to the operator's own published Web Studio game), but
+     * the iframe is still rendered with a restrictive sandbox as defence in
+     * depth: `sandbox="allow-scripts allow-forms allow-same-origin allow-popups
+     * allow-pointer-lock"`. Top-level navigation is intentionally not allowed,
+     * so the game cannot redirect the host page.
      * Back-Office label: _"Game URL"_.
      */
     custom_game_url?: string;

package/dist/SmarticoGlobal.d.ts

@@ -174,12 +174,6 @@ export interface SmarticoGlobal {
 }
 declare global {
     interface Window {
-        /**
-         * Params injected by the Smartico widget runtime (`widget.js`) when a widget
-         * is embedded via `_smartico.showWidget` / a widget script tag. Keys mirror
-         * the params passed in the embedding snippet (e.g. `id`).
-         */
-        __SMARTICO_LP_PARAMS__?: Record<string, string | number>;
         /**
          * The global Smartico SDK object, present once the embed snippet has loaded.
          * Optional because it is `undefined` until the script initializes — guard

package/dist/WSAPI/WSAPITypes.d.ts

@@ -160,6 +160,15 @@ export interface TMiniGameTemplate {
      * Important: this field will not be populated if “Max number of attempts a user can do” is set to value different from 1
      * */
     next_available_spin_ts: number;
+    /** Soonest-expiring spin's expiration time for the current user, as an epoch-ms timestamp.
+     * `null` when the user has no expirable spins for this template — spins only expire when the
+     * template defines a spin-expiration rule (Wheel of Fortune, Loot Boxes, etc.). Pair with
+     * `latest_expiration_dt` to render a "spins expire between X and Y" window. */
+    earliest_expiration_dt?: number | null;
+    /** Latest-expiring spin's expiration time for the current user, as an epoch-ms timestamp.
+     * `null` when the user has no expirable spins; equals `earliest_expiration_dt` when a single
+     * expiration applies. */
+    latest_expiration_dt?: number | null;
     /** The message that should be shown to the user when he cannot play the game, server rejected attempt with error code SAWSpinErrorCode.SAW_FAILED_MAX_SPINS_REACHED */
     over_limit_message: string;
     /** The message that should be shown to the user when he cannot play the game because he doesn't have spin attempts or points. */
@@ -242,6 +251,40 @@ export interface TUserProfile {
     /** AI-recommended casino bet amount for this user. Undefined when no
      * recommendation is currently available. */
     core_recommended_casino_bet_amount?: number;
+    /** Display name of the user's current level (e.g. `"Silver"`); resolve the id via `getCurrentLevel()`. */
+    ach_level_current?: string;
+    /** `true` when the user is in the gamification A/B control group (gamification UI suppressed). */
+    ach_gamification_in_control_group?: boolean;
+    /** Smartico-internal numeric user id. */
+    user_id?: number;
+    /** ISO country code of the user (e.g. `"BG"`). */
+    user_country?: string;
+    /** Wallet currency code (e.g. `"EUR"`). */
+    core_wallet_currency?: string;
+    /** Registration timestamp (epoch ms); `0` when unknown. */
+    core_registration_date?: number;
+    /** Last-session browser push-permission state (e.g. `"BLOCKED"`, `"GRANTED"`). */
+    user_last_session_push_state?: string;
+    /** `true` when the account is flagged as a bonus abuser. */
+    acc_bonus_abuser?: boolean;
+    /** Selected avatar id (catalogue avatar or AI-variant base). */
+    avatar_id?: string;
+    /** `avatar_real_id` of the selected avatar; `0` when none. */
+    avatar_real_id?: number;
+    /** `avatar_real_id` of the user's core avatar; null when unset. */
+    core_avatar_real_id?: number | null;
+    /** Current clan id (string); empty/null when not in a clan. */
+    core_clan_id?: string;
+    /** `true` when the user was kicked from their clan; null when not applicable. */
+    core_clan_is_kicked?: boolean | null;
+    /** Id of the clan the user was kicked from; null when not applicable. */
+    core_clan_kicked_out_id?: number | null;
+    /** ext_user_id of the friend who referred this user; null when none. */
+    aff_referred_by_friend_ext_user_id?: string | null;
+    /** Refer-a-friend share URL; null when the feature is disabled. */
+    aff_refer_friend_url?: string | null;
+    /** Count of friends this user has referred. */
+    aff_refered_friends_count?: number;
 }
 /**
  * TLevel describes one level in the label's level ladder.

package/dist/index.js

@@ -510,6 +510,8 @@ var SAWTemplatesTransform = function SAWTemplatesTransform(items) {
       activeFromDate: r.activeFromDate,
       activeTillDate: r.activeTillDate,
       next_available_spin_ts: r.next_available_spin_ts,
+      earliest_expiration_dt: r.earliest_expiration_dt,
+      latest_expiration_dt: r.latest_expiration_dt,
       steps_to_finish_game: r.saw_template_ui_definition.steps_to_finish_game,
       custom_section_id: r.saw_template_ui_definition.custom_section_id,
       saw_template_ui_definition: r.saw_template_ui_definition