@smartico/public-api 0.0.402 → 0.0.404

package/scripts/gen-capabilities.js

@@ -0,0 +1,368 @@
+/* eslint-disable */
+/**
+ * gen-capabilities.js — deterministic capability-page generator.
+ *
+ * Stitches the existing single-source-of-truth doc inputs into one
+ * self-contained "API capability page" per public WSAPI method:
+ *
+ *   method TSDoc (summary / @remarks contract / @param / @example / {@link})
+ *   + the return TYPE's own field comments (annotate the response shape)
+ *   + captured REAL response (docs/capabilities/_responses/<method>.json)
+ *   ────────────────────────────────────────────────────────────────────────
+ *   → docs/capabilities/<method>.md
+ *
+ * The capture step (run_public_api → _responses/<method>.json) is a SEPARATE
+ * skill-driven step; this script is pure, deterministic assembly.
+ *
+ *   node scripts/gen-capabilities.js
+ */
+const fs = require('fs');
+const path = require('path');
+const ts = require('typescript');
+
+const ROOT = path.join(__dirname, '..');
+const SRC = path.join(ROOT, 'src');
+const WSAPI_DIR = path.join(SRC, 'WSAPI');
+const OUT_DIR = path.join(ROOT, 'docs', 'capabilities');
+const RESP_DIR = path.join(OUT_DIR, '_responses');
+
+const SKIP_METHODS = new Set(['clearCaches']);
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function listFiles(dir, ext, acc = []) {
+	if (!fs.existsSync(dir)) return acc;
+	for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, e.name);
+		if (e.isDirectory()) listFiles(p, ext, acc);
+		else if (e.name.endsWith(ext)) acc.push(p);
+	}
+	return acc;
+}
+
+const parse = (file) =>
+	ts.createSourceFile(file, fs.readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true);
+
+const LINK_KINDS = new Set([
+	ts.SyntaxKind.JSDocLink, ts.SyntaxKind.JSDocLinkCode, ts.SyntaxKind.JSDocLinkPlain,
+]);
+
+/** Stringify a JSDoc comment (string | NodeArray), rendering {@link X} as `X`. */
+function tagText(comment) {
+	if (!comment) return '';
+	if (typeof comment === 'string') return comment.trim();
+	return comment.map(c => {
+		if (typeof c === 'string') return c;
+		if (LINK_KINDS.has(c.kind)) {
+			const nm = c.name ? c.name.getText() : '';
+			const tail = (c.text || '').trim();
+			return '`' + (nm || tail) + '`' + (nm && tail ? ' ' + tail : '');
+		}
+		return c.text ?? '';
+	}).join('').replace(/[ \t]+/g, ' ').trim();
+}
+
+// Example-response trimming so a method returning a huge map/array (e.g.
+// getTranslations → ~800 keys) doesn't dump a 900-line page. Long strings are
+// clipped; arrays show 2 items; "dictionary-sized" objects (> OBJ_CAP keys, i.e.
+// a key→value map rather than a struct) are truncated to a representative sample.
+// Example-response trimming. NO depth collapse (the real nested shape is the point
+// — e.g. gamePickGetGameInfo.sawTemplate / allRounds). Only bound the pathological
+// cases: long strings, wide arrays, and dictionary-sized maps (getTranslations → 800
+// keys). The full structural definition lives in the type-driven Returns section.
+const EX_ARR = 1, EX_OBJ_CAP = 40, EX_OBJ_KEEP = 12;
+// Noise keys collapsed in the example payload: irrelevant-to-consumer config and
+// keyed duplicates. They're the size driver on the biggest pages and add no signal.
+const NOISE_KEYS = {
+	labelInfo: '…(label config — typed `any`, omitted)',
+	prizesMap: '…(keyed duplicate of `prizes[]`)',
+};
+function trimVal(v) {
+	if (typeof v === 'string') return v.length > 160 ? v.slice(0, 157) + '…' : v;
+	if (Array.isArray(v)) return v.slice(0, EX_ARR).map(trimVal);
+	if (v && typeof v === 'object') {
+		const keys = Object.keys(v);
+		const capped = keys.length > EX_OBJ_CAP;
+		const o = {};
+		for (const k of keys.slice(0, capped ? EX_OBJ_KEEP : keys.length)) {
+			o[k] = (NOISE_KEYS[k] && v[k] && typeof v[k] === 'object') ? NOISE_KEYS[k] : trimVal(v[k]);
+		}
+		if (capped) o['…'] = `(+${keys.length - EX_OBJ_KEEP} more keys)`;
+		return o;
+	}
+	return v;
+}
+
+/** First capitalized type identifier in a type-text (the base of `TX[]`, `TX | null`, …). */
+const baseTypeName = (txt) =>
+	((txt || '').match(/[A-Z][A-Za-z0-9_]+/g) || [])
+		.find(n => !['Promise', 'Partial', 'Array', 'Record', 'GamesApiResponse', 'Date'].includes(n)) || '';
+
+// ── type registry: name → { ext:[names], fields:{ name:{comment,typeText} } } ─
+
+function buildTypeRegistry() {
+	const reg = {};
+	const trailing = (sf, node) => {
+		const tr = ts.getTrailingCommentRanges(sf.text, node.end) || [];
+		return tr.length ? sf.text.slice(tr[0].pos, tr[0].end).replace(/^\/\/\s?/, '').trim() : '';
+	};
+	for (const file of listFiles(SRC, '.ts')) {
+		const sf = parse(file);
+		const visit = (node) => {
+			if (ts.isInterfaceDeclaration(node) && node.name) {
+				const name = node.name.text;
+				const ext = (node.heritageClauses || [])
+					.flatMap(h => h.types.map(t => baseTypeName(t.expression.getText(sf)))).filter(Boolean);
+				const fields = {};
+				for (const m of node.members) {
+					if (!ts.isPropertySignature(m) || !m.name) continue;
+					const fname = m.name.getText(sf);
+					const comment = ts.getJSDocCommentsAndTags(m).map(d => tagText(d.comment)).filter(Boolean).join(' ')
+						|| trailing(sf, m);
+					fields[fname] = { comment: comment.replace(/\s+/g, ' ').trim(), typeText: m.type ? m.type.getText(sf) : '' };
+				}
+				reg[name] = { ext, fields };
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sf);
+	}
+	return reg;
+}
+
+/** Merge a type's own fields over its inherited fields. */
+function resolveFields(name, reg, seen = new Set()) {
+	if (!name || !reg[name] || seen.has(name)) return {};
+	seen.add(name);
+	const acc = {};
+	for (const e of reg[name].ext) Object.assign(acc, resolveFields(e, reg, seen));
+	Object.assign(acc, reg[name].fields);
+	return acc;
+}
+
+// ── method extraction ───────────────────────────────────────────────────────
+
+function extractMethods() {
+	const methods = [];
+	for (const file of listFiles(WSAPI_DIR, '.ts')) {
+		const base = path.basename(file);
+		if (base === 'WSAPITypes.ts' || base === 'WSAPIBase.ts') continue;
+		const domain = base.replace(/^WSAPI/, '').replace(/\.ts$/, '').toLowerCase();
+		const sf = parse(file);
+		const visit = (node) => {
+			if (ts.isMethodDeclaration(node) && node.name) {
+				const isPublic = !node.modifiers?.some(m =>
+					m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword);
+				const name = node.name.getText(sf);
+				if (isPublic && !SKIP_METHODS.has(name) && !name.startsWith('_')) methods.push({ name, domain, node, sf });
+			}
+			ts.forEachChild(node, visit);
+		};
+		visit(sf);
+	}
+	return methods;
+}
+
+function readJSDoc(node, sf) {
+	const docs = ts.getJSDocCommentsAndTags(node);
+	const out = { description: '', remarks: '', params: [], example: '', returns: '', links: [] };
+	for (const d of docs) {
+		if (ts.isJSDoc(d)) out.description = tagText(d.comment) || out.description;
+		for (const t of d.tags || (ts.isJSDoc(d) ? [] : [d])) {
+			const tag = t.tagName?.text, txt = tagText(t.comment);
+			if (tag === 'remarks') out.remarks += (out.remarks ? '\n\n' : '') + txt;
+			else if (tag === 'param') out.params.push({ name: t.name?.getText(sf) ?? '', text: txt });
+			else if (tag === 'example') out.example += (out.example ? '\n\n' : '') + txt;
+			else if (tag === 'returns') out.returns = txt;
+		}
+	}
+	const raw = docs.map(d => d.getText(sf)).join('\n');
+	let m; const re = /\{@link\s+([A-Za-z0-9_.]+)/g;
+	while ((m = re.exec(raw))) if (!out.links.includes(m[1])) out.links.push(m[1]);
+	return out;
+}
+
+// ── page assembly ───────────────────────────────────────────────────────────
+
+function splitRemarks(remarks) {
+	const m = remarks.match(/\*\*Error codes[\s\S]*?(?=\n\s*\*\*[A-Z]|$)/);
+	return m ? { contract: remarks.replace(m[0], '').trim(), errors: m[0].trim() } : { contract: remarks, errors: '' };
+}
+
+// Recursively render a type's fields from the registry, expanding nested object /
+// array field types (bounded by depth + a per-branch cycle guard) so the full
+// structure is described, not collapsed.
+const RT_MAX_DEPTH = 4;
+function renderType(typeName, reg, seen, depth) {
+	const out = [];
+	const pad = '  '.repeat(depth);
+	for (const [k, info] of Object.entries(resolveFields(typeName, reg))) {
+		const tt = info.typeText || '';
+		out.push(`${pad}- \`${k}\` (${tt})${info.comment ? ` — ${info.comment}` : ''}`);
+		const base = baseTypeName(tt);
+		if (base && reg[base] && !seen.has(base) && depth < RT_MAX_DEPTH) {
+			out.push(...renderType(base, reg, new Set([...seen, base]), depth + 1));
+		}
+	}
+	return out;
+}
+
+// The full RETURN TYPE definition — unwraps Promise<…> and GamesApiResponse<…> so
+// the page describes the actual payload type (e.g. GamePickGameInfo), not just the
+// wrapper, with nested types expanded.
+function returnsSection(ret, reg) {
+	if (!ret || ret === 'void') return '_No return value._';
+	let inner = ret.replace(/^Promise\s*<([\s\S]*)>\s*$/, '$1').trim();
+	let prefix = '';
+	const gm = inner.match(/^GamesApiResponse\s*<([\s\S]*)>\s*$/);
+	if (gm) {
+		prefix = 'Wrapped in `GamesApiResponse`: `errCode` (number — `0` = success), `errMessage?` (string), `data?` — the payload:\n\n';
+		inner = gm[1].trim();
+	}
+	const isArr = /\[\]\s*$/.test(inner) || /^Array\s*</.test(inner);
+	const base = baseTypeName(inner);
+	if (!base || !reg[base]) return prefix + `Resolves to \`${inner}\`.`;
+	const lines = [prefix + (isArr ? `Array of \`${base}\`. Each item:` : `\`${base}\`:`)];
+	lines.push(...renderType(base, reg, new Set([base]), 0));
+	return lines.join('\n');
+}
+
+// Renamed / shorthand / guessed names the IDE agent actually searched (from a
+// 48h live-session analysis) → added to the page's Search-terms so the search
+// lands first-shot. doSAWAcknowledge (8 hits) was the biggest single miss.
+const ALIASES = {
+	miniGameWinAcknowledgeRequest: ['doSAWAcknowledge', 'SAWAcknowledge', 'acknowledge', 'SAWAcknowledgeType'],
+	getTournamentsList: ['getTournaments'],
+	getTournamentInstanceInfo: ['getTournament'],
+	getLeaderBoard: ['getLeaderboard', 'leaderboard'],
+	getLeaderBoards: ['getLeaderboards'],
+	getAvatarsList: ['getAvatars'],
+	getMiniGames: ['getSAW', 'spins', 'minigames', 'wheel', 'SAWPrizeType'],
+	playMiniGame: ['doSAWSpin', 'SAWSpin', 'spin'],
+	playMiniGameBatch: ['doSAWSpinBatch'],
+	getMiniGamesHistory: ['getSAWHistory'],
+	getCurrentLevel: ['getUserLevel'],
+	getLevels: ['getUserLevels'],
+	getMissions: ['getUserMissions', 'achievements'],
+	getBadges: ['getUserBadges'],
+	getUserProfile: ['getPublicProps', 'getProfile', 'balance', 'points'],
+};
+
+/** Enum / sub-type names referenced by a return type's fields (1 level deep) —
+ * so a search by a cross-cutting enum name (SAWAcknowledgeType, PointChangeSourceType,
+ * GamePickResolutionType, …) lands on the page that owns it. */
+function collectFieldTypeNames(typeName, reg, seen = new Set(), depth = 0) {
+	const out = new Set();
+	if (!typeName || depth > 1) return out;
+	for (const info of Object.values(resolveFields(typeName, reg))) {
+		for (const n of (info.typeText || '').match(/[A-Z][A-Za-z0-9_]+/g) || []) {
+			if (n.length < 4 || ['Array', 'Record', 'Date', 'Partial', 'Promise', 'This', 'The', 'URL', 'JSON'].includes(n)) continue;
+			out.add(n);
+			if (reg[n] && !seen.has(n)) { seen.add(n); for (const x of collectFieldTypeNames(n, reg, seen, depth + 1)) out.add(x); }
+		}
+	}
+	return out;
+}
+
+function buildPage(method, reg) {
+	const { name, domain, node, sf } = method;
+	const doc = readJSDoc(node, sf);
+	const params = node.parameters.map(p => p.getText(sf)).join(', ');
+	const ret = node.type ? node.type.getText(sf) : 'void';
+	const typeNames = [...new Set((ret.match(/[A-Z][A-Za-z0-9_]+/g) || [])
+		.filter(n => !['Promise', 'Partial', 'Array', 'Record', 'GamesApiResponse'].includes(n)))];
+	const typeName = typeNames[0] || '';
+	const summary = (doc.description.split(/(?<=[.!?])\s/)[0] || doc.description || name).replace(/\s+/g, ' ').trim();
+
+	const respPath = path.join(RESP_DIR, `${name}.json`);
+	const respJson = fs.existsSync(respPath) ? JSON.parse(fs.readFileSync(respPath, 'utf8')) : null;
+	const { contract, errors } = splitRemarks(doc.remarks);
+
+	const sampleKeys = respJson ? Object.keys((Array.isArray(respJson) ? respJson[0] : respJson) || {}).slice(0, 8) : [];
+	const onUpd = /\bonUpdate\b/.test(params) ? ['onUpdate', 'subscription'] : [];
+	const fieldTypes = [...collectFieldTypeNames(typeName, reg)].slice(0, 12);
+	const searchTerms = [name, domain, ...(ALIASES[name] || []), ...typeNames, ...fieldTypes, ...onUpd, ...sampleKeys]
+		.filter((v, i, a) => v && a.indexOf(v) === i).join(', ');
+
+	const o = [];
+	o.push(`# ${name} — API${typeName ? ` (${typeName})` : ''}`, '');
+	o.push(`> ${summary}`);
+	o.push(`> Import: \`import { ${typeNames.join(', ') || '/* types */'} } from '@smartico/public-api'\``);
+	o.push(`> Search terms: ${searchTerms}`, '');
+	o.push('## Signature', '```ts', `_smartico.api.${name}(${params}): ${ret}`, '```', '');
+	o.push('## Parameters', doc.params.length
+		? doc.params.map(p => `- ${p.name ? `\`${p.name}\` — ` : ''}${p.text}`.replace(/\s+/g, ' ').trim()).join('\n')
+		: '_None._', '');
+	o.push(`## Returns${typeName ? ` — \`${ret}\`` : ''}`, returnsSection(ret, reg), '');
+	o.push('## Behavioral contract', contract || `See the [UI guide](../ui/${domain}/UIGuide_${name}.md) if present.`, '');
+	if (doc.example) o.push('## Example', doc.example.trim(), '');
+	if (respJson) o.push('### Example response (REAL shape)',
+		'> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.',
+		'```json',
+		JSON.stringify(Array.isArray(respJson) ? [trimVal(respJson[0])] : trimVal(respJson), null, 2), '```', '');
+	o.push('## Errors', errors || "See this method's TSDoc / the mutation pages for `err_code` handling.", '');
+	if (doc.links.length) o.push('## Related', doc.links.filter(l => l !== name).map(l => `- \`${l}\``).join('\n'), '');
+	return o.join('\n');
+}
+
+// ── global `_smartico.*` surface + callbacks (non-.api.* — the live-session
+//    analysis showed these were unreachable in the `api` lane and live-probed) ──
+
+function buildGlobalSurfacePage() {
+	const file = path.join(SRC, 'SmarticoGlobal.ts');
+	if (!fs.existsSync(file)) return null;
+	const sf = parse(file);
+	let iface = null;
+	const find = (n) => { if (ts.isInterfaceDeclaration(n) && n.name.text === 'SmarticoGlobal') iface = n; ts.forEachChild(n, find); };
+	find(sf);
+	if (!iface) return null;
+	const members = iface.members.filter(m => m.name).map(m => ({
+		name: m.name.getText(sf),
+		sig: m.getText(sf).replace(/;$/, '').replace(/\s+/g, ' ').trim(),
+		one: ts.getJSDocCommentsAndTags(m).map(d => tagText(d.comment)).filter(Boolean).join(' ').replace(/\s+/g, ' ').trim(),
+	}));
+	const extra = ['_smartico', 'global', 'window._smartico', 'SmarticoGlobal', 'visitor mode', 'callbacks', 'events',
+		'onWin', 'onReady', 'deep link', 'getWidgetParams', 'IWidgetParams', 'widget params', 'readiness', 'lifecycle', 'push'];
+	const terms = [...new Set([...members.map(m => m.name), ...extra])].join(', ');
+	const o = [];
+	o.push('# _smartico — global SDK surface (non-`.api.*`)', '');
+	o.push('> 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).');
+	o.push("> Import: typed via `SmarticoGlobal` from '@smartico/public-api'; at runtime the object is on `window._smartico` (no import).");
+	o.push(`> Search terms: ${terms}`, '');
+	o.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).', '');
+	o.push('## Methods');
+	for (const m of members) o.push(`- \`_smartico.${m.sig}\`${m.one ? ` — ${m.one}` : ''}`);
+	o.push('');
+	o.push('## 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).', '');
+	o.push('## 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.', '');
+	o.push('## Related', '- `_smartico.on — events & callbacks` (the callbacks capability page)', '- Full prose reference: the SmarticoObject doc (search source `api-raw`).');
+	return o.join('\n');
+}
+
+function buildConceptPage(srcRel, title, terms) {
+	const p = path.join(ROOT, srcRel);
+	if (!fs.existsSync(p)) return null;
+	const body = fs.readFileSync(p, 'utf8').replace(/^#\s+.*\r?\n/, '').trim();
+	return [`# ${title}`, '', `> ${title}.`, `> Search terms: ${terms}`, '', body].join('\n');
+}
+
+function main() {
+	if (!fs.existsSync(OUT_DIR)) fs.mkdirSync(OUT_DIR, { recursive: true });
+	const reg = buildTypeRegistry();
+	const methods = extractMethods();
+	let written = 0, withResp = 0;
+	for (const method of methods) {
+		fs.writeFileSync(path.join(OUT_DIR, `${method.name}.md`), buildPage(method, reg));
+		written++;
+		if (fs.existsSync(path.join(RESP_DIR, `${method.name}.json`))) withResp++;
+	}
+	let extra = 0;
+	const g = buildGlobalSurfacePage();
+	if (g) { fs.writeFileSync(path.join(OUT_DIR, 'smarticoGlobal.md'), g); extra++; }
+	const cb = buildConceptPage('docs/Callbacks.md', '_smartico.on — events & callbacks',
+		'on, off, callbacks, events, subscribe, subscribeUpdate, onWin, onReady, props_change, identify, EXTERNAL_CALLBACK, lifecycle, _smartico.on');
+	if (cb) { fs.writeFileSync(path.join(OUT_DIR, 'smarticoCallbacks.md'), cb); extra++; }
+	console.log(`[gen-capabilities] wrote ${written} method pages + ${extra} global/concept pages (${withResp} with captured response); type registry: ${Object.keys(reg).length} interfaces`);
+}
+
+main();

package/scripts/run-public-api.mjs

@@ -0,0 +1,105 @@
+/* eslint-disable */
+/**
+ * run-public-api.mjs — run arbitrary public-API code as a REAL identified user, headless.
+ *
+ * A reusable test harness for verifying SDK behaviour against a live env (e.g.
+ * a new server field that's only deployed on one env). It loads the real
+ * smartico.js tracker bundle, init + identify as the given player, then evaluates
+ * SM_CODE inside the page against `window._smartico` and prints the JSON result.
+ *
+ * Unlike the server-side `run_public_api` MCP tool (which runs the PUBLISHED SDK
+ * in visitor mode), this runs the real browser SDK as an identified user, and can
+ * reach the raw protocol via `_smartico.api.api.*` — so it surfaces server fields
+ * the published transform/types don't yet map (e.g. SAW spin-expiration).
+ *
+ * Setup (one-time): npm i -D playwright && npx playwright install chromium
+ *
+ * Run the default test (SAW spin-expiration on env8 DEMO):
+ *   node scripts/run-public-api.mjs
+ *
+ * Run your own snippet (async-function body; `_smartico` + `window._smartico_user_id` in scope):
+ *   SM_CODE='return await _smartico.api.getMissions();' node scripts/run-public-api.mjs
+ *   SM_CODE="$(cat my-test.js)" node scripts/run-public-api.mjs
+ *
+ * Point at another env/label/user:
+ *   SM_LABEL=<label-key ending in env digit> SM_BRAND=<hex> SM_USER=<ext id> \
+ *   SM_SALT=<label salt | 'null'> node scripts/run-public-api.mjs
+ */
+import { chromium } from 'playwright';
+import crypto from 'crypto';
+
+// Defaults: env8 DEMO label (SpaceX brand) with a test player that HAS expirable
+// SAW spins — running bare validates SMR-48946 (mini-game spin expiration).
+const LABEL = process.env.SM_LABEL || 'd78934f3-1d8b-461b-9e8f-287aae43c860-8';
+const BRAND = process.env.SM_BRAND || 'c24a284e';
+const USER  = process.env.SM_USER  || 'test98681514';
+const SALT  = process.env.SM_SALT  || 'null';
+const ORIGIN = process.env.SM_ORIGIN || 'https://app.smartico.ai/';
+const SCRIPT_URL = process.env.SM_SCRIPT_URL || 'https://libs.smartico.ai/smartico.js';
+
+// Default snippet: dump every SAW template that has spin-expiration set for this
+// user, via the RAW command-700 response (the published transform drops the fields).
+const DEFAULT_CODE = `
+  const ext = window._smartico_user_id;
+  const resp = await window._smartico.api.api.sawGetTemplates(ext);
+  const list = (resp && resp.templates) || [];
+  return {
+    user_ext_id: ext,
+    total_templates: list.length,
+    templates_with_spin_expiration: list
+      .filter(t => t.earliest_expiration_dt != null || t.latest_expiration_dt != null)
+      .map(t => ({ saw_template_id: t.saw_template_id, spin_count: t.spin_count,
+                   earliest_expiration_dt: t.earliest_expiration_dt, latest_expiration_dt: t.latest_expiration_dt })),
+  };
+`;
+const CODE = process.env.SM_CODE || DEFAULT_CODE;
+
+function userHash(user, salt) {
+	const ts = Math.floor(Date.now() / 1000) * 1000 + 24 * 3600 * 1000;
+	return crypto.createHash('md5').update(`${user.toLowerCase()}:${salt}:${ts}`.toLowerCase()).digest('hex') + ':' + ts;
+}
+
+(async () => {
+	const hash = userHash(USER, SALT);
+	const browser = await chromium.launch({ headless: true });
+	const ctx = 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 ctx.newPage();
+	page.on('console', m => { if (m.type() === 'error') console.error('  [page error]', m.text().slice(0, 200)); });
+
+	// Self-served CSP-free origin (libs.smartico.ai 403s headless + CSP-blocks injection).
+	await page.route(ORIGIN + '**', r => r.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html><html><head></head><body></body></html>' }));
+	await page.goto(ORIGIN, { waitUntil: 'domcontentloaded' }).catch(() => {});
+
+	await page.evaluate((u) => new Promise((res) => {
+		const s = document.createElement('script'); s.src = u; s.onload = () => res('loaded'); s.onerror = () => res('error'); document.head.appendChild(s);
+	}), SCRIPT_URL);
+	await page.waitForFunction(() => typeof window._smartico !== 'undefined', { timeout: 15000 });
+
+	await page.evaluate(({ LABEL, BRAND, USER, hash }) => {
+		window._smartico_user_id = USER;
+		window._smartico.init(LABEL, { brand_key: BRAND });
+		window._smartico.identify(USER, hash, {});
+	}, { LABEL, BRAND, USER, hash });
+
+	const ok = await page.waitForFunction(() => window._smartico?.checkSuccessfullyIdentify?.() === true, { timeout: 40000 }).then(() => true).catch(() => false);
+	if (!ok) { console.error(`[run] identify failed for ${USER} on ${LABEL} (check SM_SALT / allowed origin).`); await browser.close(); process.exit(3); }
+	console.error(`[run] identified ${USER} on ${LABEL} ✓`);
+
+	// Execute the operator-supplied snippet against window._smartico. SM_CODE is
+	// TRUSTED — the same trust model as `node -e`, `npx`, or the run_public_api MCP
+	// tool: it is the test author's own code, not external/untrusted input. There is
+	// no privilege boundary here (a "malicious SM_CODE" is the operator attacking
+	// their own dev machine). Do NOT feed untrusted/remote strings into SM_CODE.
+	const result = await page.evaluate(async (code) => {
+		const _smartico = window._smartico; // in scope for the snippet
+		try { return { ok: true, value: await (new Function('_smartico', `return (async () => { ${code} })()`))(_smartico) }; }
+		catch (e) { return { ok: false, error: String(e && e.message || e) }; }
+	}, CODE);
+
+	console.log(JSON.stringify(result.ok ? result.value : { ERROR: result.error }, null, 2));
+	await browser.close();
+	process.exit(result.ok ? 0 : 1);
+})().catch(e => { console.error('[run] fatal:', e.message); process.exit(1); });

package/src/MiniGames/SAWGetTemplatesResponse.ts

@@ -44,6 +44,8 @@ export const SAWTemplatesTransform = (items: SAWTemplate[]): TMiniGameTemplate[]
 			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,

package/src/MiniGames/SAWTemplate.ts

@@ -31,6 +31,11 @@ export interface SAWTemplate {
 
 	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/src/NodeCache.ts

@@ -39,6 +39,14 @@ class NodeCache {
 		}
 	}
 
+	public removeByPrefix(prefix: string) {
+		for (const key in this.cache) {
+			if (this.cache.hasOwnProperty(key) && key.indexOf(prefix) === 0) {
+				delete this.cache[key];
+			}
+		}
+	}
+
 	public flushAll() {
 		this.cache = {};
 		if (this.ttlChecker) {

package/src/OCache.ts

@@ -56,6 +56,23 @@ export class OCache {
 		}
 	}
 
+	/**
+	 * Remove every entry whose string key starts with `oKeyBase` — the bare key
+	 * AND all per-parameter composite variants (`${oKeyBase}:…` / `${oKeyBase}<id>`).
+	 * Use when a cache is keyed per parameter (paginated, per-template, per-window):
+	 * an exact-key `clear(oKeyBase)` would miss every variant. `oKeyBase` must be a string.
+	 */
+	public static async clearByPrefix(cacheContext: ECacheContext, oKeyBase: string) {
+		// `set`/`get` build keys as `<context>_<JSON.stringify(oKey)>`; JSON.stringify
+		// wraps a string in quotes, so dropping the trailing quote yields a prefix that
+		// matches both the bare `"base"` key and every `"base…"` composite key.
+		const prefix = cacheContext.toString() + '_' + JSON.stringify(oKeyBase).slice(0, -1);
+
+		if (this.cache[cacheContext]) {
+			this.cache[cacheContext].removeByPrefix(prefix);
+		}
+	}
+
 	public static async clearContext(cacheContext: ECacheContext) {
 		if (this.cache[cacheContext]) {
 			this.cache[cacheContext].flushAll();

package/src/SmarticoGlobal.ts

@@ -192,13 +192,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/src/WSAPI/WSAPI.ts

@@ -34,11 +34,11 @@ export class WSAPI extends WSAPIInbox {
 			on(ClassId.SAW_SHOW_SPIN_PUSH, () => this.reloadMiniGameTemplate());
 			on(ClassId.SAW_AKNOWLEDGE_RESPONSE, () => {
 				this.reloadMiniGameTemplate();
-				OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+				OCache.clearByPrefix(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
 			});
 			on(ClassId.SAW_DO_SPIN_RESPONSE, () => {
 				this.reloadMiniGameTemplate();
-				OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+				OCache.clearByPrefix(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
 			});
 			on(ClassId.MISSION_OPTIN_RESPONSE, () => this.updateMissions());
 			on(ClassId.ACHIEVEMENT_CLAIM_PRIZE_RESPONSE, () => this.updateMissions());
@@ -57,7 +57,7 @@ export class WSAPI extends WSAPIInbox {
 			on(ClassId.CLAIM_BONUS_RESPONSE, () => this.updateBonuses());
 			on(ClassId.SAW_DO_SPIN_BATCH_RESPONSE, () => {
 				this.reloadMiniGameTemplate();
-				OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
+				OCache.clearByPrefix(ECacheContext.WSAPI, onUpdateContextKey.SAWHistory);
 			});
 			on(ClassId.RAF_CLAIM_PRIZE_RESPONSE, () => this.updateRaffles());
 			on(ClassId.GET_INBOX_MESSAGES_RESPONSE, (res) => {

package/src/WSAPI/WSAPIJackpots.ts

@@ -25,7 +25,10 @@ export class WSAPIJackpots extends WSAPIClans {
 	protected async jackpotClearCache() {
 		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Jackpots);
 		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.Pots);
-		OCache.clear(ECacheContext.WSAPI, onUpdateContextKey.JackpotWinners);
+		// Winners + eligible-games are cached per jp_template_id (composite keys),
+		// so a bare clear misses every variant — clear by prefix.
+		OCache.clearByPrefix(ECacheContext.WSAPI, onUpdateContextKey.JackpotWinners);
+		OCache.clearByPrefix(ECacheContext.WSAPI, onUpdateContextKey.JackpotEligibleGames);
 	}
 
 	/**

package/src/WSAPI/WSAPIMiniGames.ts

@@ -198,7 +198,7 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 		saw_template_id?: number;
 	}): Promise<TSawHistory[]> {
 		return OCache.use(
-			onUpdateContextKey.SAWHistory,
+			`${onUpdateContextKey.SAWHistory}:${saw_template_id ?? ''}:${limit ?? ''}:${offset ?? ''}`,
 			ECacheContext.WSAPI,
 			() => this.api.getSawWinningHistoryT(this.userExtId, limit, offset, saw_template_id),
 			CACHE_DATA_SEC,

package/src/WSAPI/WSAPITypes.ts

@@ -171,6 +171,16 @@ export interface TMiniGameTemplate {
 	 * */
 	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. */
@@ -261,6 +271,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;
 }
 
 /**