@stripchatdev/create-stripchat-extension 0.1.46 → 0.1.48

package/templates/v2/AGENTS.md.ejs

@@ -0,0 +1,712 @@
+<!-- AUTO-GENERATED SECTION START -->
+# <%= name %>
+Use this file as the primary coding contract for this starter. Use the Stripchat docs to get more details.
+- Category: <%= category %>
+- Slots: <%= slotsEntries.map(({ slot }) => slot).join(', ') %>
+- Framework: <%= framework %>
+- Language: <%= language %>
+
+## Starter Map
+- public/manifest.json declares slots, page keys, optional settings entry, and backend actions.
+- public/resolveSlotPage.js is the runtime resolver. It returns a page key from views.pages or null.
+- Root HTML files like <%= slotsEntries[0].slotCamelCased %>.html and background.html are emitted into the final archive root.
+- Visual slot entry modules live in src/slots/<slot>/main.<%= isJsxFramework ? jsxExt : ext %>.
+- Visual slot page code lives in src/slots/<slot>/app.<%= isJsxFramework ? jsxExt : ext %>.
+- Background entry module lives in src/slots/background/main.<%= ext %>.
+- Background page code lives in src/slots/background/app.<%= ext %>.
+- If you add settings.html, it is also a root HTML file and must have its own entry module.
+- vite.config.<%= isTypescript ? 'ts' : 'js' %> must include every root HTML file in build.rollupOptions.input.
+
+## Template-managed Files
+These files are generated and managed by the CLI tooling and template generation scripts. Changes may be overwritten by
+future template updates or may cause update conflicts.
+
+- `.project-config.json` — main project configuration.
+- `AGENTS.md` — the section between `<!-- AUTO-GENERATED SECTION START -->` and `<!-- AUTO-GENERATED SECTION END -->`.
+
+These files can be changed, but large structural updates may break future template updates via CLI:
+- `vite.config.ts` — build project configuration.
+- `package.json` — project scripts and dependencies.
+
+This file can be overwritten safely:
+- `README.md` — your project readme information.
+
+## Template CLI Commands
+Available in `package.json` for updating and managing the extension template.
+
+Updating the template keeps your project aligned with the latest starter version, including:
+
+- SDK updates
+- Documentation updates
+- Improvements to generated files
+- Updates to `AGENTS.md`
+
+```bash
+# Update template-managed files and SDK dependencies
+npm run template:update
+```
+
+## Minimal views shape:
+```json
+{
+  "version": "v2.0",
+  "views": {
+    "slots": ["EXTENSION_SLOT_MAIN_GAME_FUN", "EXTENSION_SLOT_BACKGROUND"],
+    "pages": {
+      "mainGameFun": "mainGameFun.html",
+      "background": "background.html"
+    },
+    "resolveSlotPageScript": "resolveSlotPage.js"
+  }
+}
+```
+## Hard Rules
+- Call createExtHelper() exactly once in the first executed module of every page before any other SDK logic.
+- In this starter, keep createExtHelper() in each page's app.* file.
+- If you add settings.html, call createExtHelper() there too.
+- Keep public/resolveSlotPage.js as plain synchronous JS. Do not bundle it, make it async, or import app code into it.
+- public/resolveSlotPage.js must return only a key from public/manifest.json views.pages or null.
+- settings.html does not go through public/resolveSlotPage.js.
+- Every views.pages key must map to a real root HTML file.
+- Every root HTML file must be included in vite.config.<%= isTypescript ? 'ts' : 'js' %> build.rollupOptions.input.
+- Non-background slots can unmount at any time. Do not keep durable state, timers, polling, or coordination logic in them.
+- Keep durable state, timers, polling, and cross-slot coordination in background.
+- If you subscribe to SDK events, DOM events, or timers, clean them up on unmount or teardown.
+- Use named handler functions when subscribing so you can unsubscribe the same reference.
+- Slots can unmount, so you should always unsubscribe from sdk events and browser apis correctly.
+- Use v1.ext.whisper.local for communication between this extension's frames for the current user.
+- Use v1.ext.whisper only when every loaded client in the room should receive the message.
+- When a user sends v1.ext.whisper during a public show, paymentData is required. Obtain it from v1.payment.tokens.spend.succeeded. The model can whisper without paymentData.
+- Broadcast whispers arrive as v1.ext.whispered
+- Local whispers arrive as v1.ext.whispered.local
+- Always include a stable type field in whisper payloads.
+- Do not send sensitive data in whisper payloads, including usernames or user IDs.
+- Use v1.payment.tokens.spend.succeeded to confirm a spend in the paying client's iframe.
+- Use v1.tokens.spent in the model/background iframe to react to the room-side tip.
+- Always pass isAnonymous to v1.chat.message.send.
+- Preserve anonymity in chat messages: use isAnonymous from v1.payment.tokens.spend.succeeded or tipData.isAnonymous, and never infer, override, or de-anonymize users.
+- If isAnonymous is true, do not expose username, user ID, or sender identity in chat text, whispers, monitoring data, or backend action params.
+- Do not add Save or Cancel buttons inside settings.html. The platform renders them outside the iframe.
+- Do not use viewport @media queries. The iframe viewport is the slot container, not the browser window.
+- Do not manage iframe scrolling with overflow: auto or overflow: scroll on html or body.
+- Set background styles on <html>, not <body>.
+- Use CSS variables with html[data-theme='dark'] and html[data-theme='light'] selectors for theming.
+- The SDK sets html[data-theme] when createExtHelper() runs.
+- Do not access the parent DOM.
+- Do not rely on host cookies.
+- Actions are strictly reviewed before publishing. Use it only when necessary (e.g. third-party API calls with secrets).
+- If you use EXTENSION_SLOT_MOVEABLE_OVERLAY, define moveableSlot.width and moveableSlot.height in the manifest. Max size is 450x740.
+- Do not invent new slot names or slot type constants. Use capitalized SNAKE_CASE in view.slots in manifest.
+- Do not invent SDK request names, event names, method names, manifest field names, or payload keys. Use only documented names from the Stripchat docs and this starter.
+- Prefer extending the generated wiring over replacing it.
+- In TypeScript, treat settings and ad-hoc payloads as unknown until narrowed.
+- Keep public/manifest.json valid JSON with no trailing commas.
+- In TypeScript, import types from @stripchatdev/ext-helper and use them
+- ALWAYS USE background slot to handle long-running orchestration logic — timers, polling, state machines, centralized state management, events, whispers
+- The flow should be: visual slot -> whisper.local to background -> background handles logic. Background should subscribe to events and coordinate it
+- Create background slot for each actor (model, viewer). Do not put model-only and viewer-only logic in the same background.
+- Chatbot extensions have no UI — only a background slot handles all logic (receiving messages and sending chatbot messages).
+- Do not create visual slots, HTML pages, or resolver entries for chatbot extensions.
+- Use v1.chatbot.message.send to send messages as bot or model from background. Messages are delivered locally to each user.
+- Use v1.chat.message.received to listen for incoming chat messages in background.
+- The message param in v1.chatbot.message.send supports a {username} placeholder, replaced with the receiving user's name (empty string for anonymous, "Guest" for guests).
+- Do not call v1.chatbot.message.send unconditionally inside v1.chat.message.received handlers for every message — chat rooms can have hundreds of messages per second. Use event-driven triggers (context changes, timers, tips) instead or add strict filters on message content or sender properties.
+- Broadcast Tools are rendered only for the model of the current room.
+- For Broadcast Tools, do not add explicit `context.user?.id === context.model?.id` guards in `public/resolveSlotPage.js` — the platform enforces model-only visibility automatically.
+- If you use `EXTENSION_SLOT_MOVEABLE_OVERLAY`, define `moveableSlot.width` and `moveableSlot.height` in the manifest (max 450x740). Only the user controls expand/collapse; update status/content via SDK, not host UI takeover.
+- videoDecorativeOverlay is not interactive. Do not put buttons or interactive elements in it. Use it only for animations, visualizations etc. after calling `v1.ext.activity.request`.
+- When using `v1.ext.activity.request`, ALWAYS make sure that the actual animation is shorter then the activity duration in order to avoid immidiate slot closing after the animation ends.
+
+## Slot Guardrails
+- Generated slot sets for this starter:
+- Games & Fun: EXTENSION_SLOT_MAIN_GAME_FUN, EXTENSION_SLOT_BACKGROUND,  either one of EXTENSION_SLOT_RIGHT_OVERLAY or EXTENSION_SLOT_VIDEO_DECORATIVE_OVERLAY
+- Sex Toys: EXTENSION_SLOT_MAIN_SEX_TOY, EXTENSION_SLOT_BACKGROUND, EXTENSION_SLOT_MOVEABLE_OVERLAY, optional EXTENSION_SLOT_RIGHT_OVERLAY and EXTENSION_SLOT_VIDEO_DECORATIVE_OVERLAY
+- Chat Bots: EXTENSION_SLOT_BACKGROUND (no visual slots), optional EXTENSION_SLOT_VIDEO_DECORATIVE_OVERLAY
+- Broadcast Tools: EXTENSION_SLOT_BACKGROUND, optional EXTENSION_SLOT_MOVEABLE_OVERLAY
+- Resolver slotType constants:
+- mainGameFun -> EXTENSION_SLOT_MAIN_GAME_FUN
+- mainSexToy -> EXTENSION_SLOT_MAIN_SEX_TOY
+- rightOverlay -> EXTENSION_SLOT_RIGHT_OVERLAY
+- moveableOverlay -> EXTENSION_SLOT_MOVEABLE_OVERLAY
+- background -> EXTENSION_SLOT_BACKGROUND
+
+## Default Runtime Pattern
+- background owns long-lived state and coordination.
+- Visual slots render UI from current state and forward user actions.
+- Load initial context once with v1.ext.context.get.
+- Keep context fresh with v1.ext.context.updated. Payload is { context: TV1ExtContext }.
+- Send state updates to every frame of the current user with v1.ext.whisper.local.
+- If all loaded clients need the event, use v1.ext.whisper.
+- Assume every visual slot can mount, unmount, and remount without notice.
+
+## Resolver
+- Start from the generated resolver and extend it only when needed.
+- Keep resolver logic cheap, synchronous, and defensive.
+- context.user may be missing when the visitor is anonymous.
+- extSettings may be missing or partial.
+- Return null when a slot should not render.
+- If you add model, viewer, or guest variants, add new page keys and branch here.
+- Every returned string must be a key in manifest.json views.pages.
+
+### Generated resolver for this project:
+```
+export default function resolveSlotPage(slotType, context, extSettings) {
+  switch (slotType) {
+<% slotsEntries.forEach(({ slotCamelCased, slot }) => { -%>
+    case '<%= slot %>':
+      return '<%= slotCamelCased %>';
+<% }); -%>
+    default:
+      return null;
+  }
+}
+```
+
+### Example of context-aware branching:
+
+```
+export default function resolveSlotPage(slotType, context, extSettings) {
+  const isBroadcaster = context.user?.id === context.model?.id;
+  const isAnotherModel = context.user?.isModel && !isBroadcaster;
+  if (slotType === 'EXTENSION_SLOT_MAIN_GAME_FUN') {
+    if (isBroadcaster) return 'mainGameFunModel';
+    if (isAnotherModel) return 'mainGameFunVisitingModel'
+    if (context.user?.isGuest) return 'mainGameFunGuest';
+    return 'mainGameFunViewer';
+  }
+  if (slotType === 'EXTENSION_SLOT_BACKGROUND') {
+    return 'background';
+  }
+  return null;
+}
+```
+
+
+## Runtime Context
+- context.model is the broadcaster for the current room.
+- context.user is the current user running the extension.
+- If context.user?.isGuest is true, the current user is a guest (TV1ExtGuestUser). The only field available is isGuest. Fields like id, username, status, hasTokens do not exist on guests.
+- If context.user?.id === context.model?.id, the current user is the broadcaster of the current room.
+- If context.user?.isModel is true, the current logged-in user has a model account. This can also be true for another model visiting the broadcast.
+- Common model statuses: public, private, exclusivePrivate, groupShow, ticketShow, idle, off.
+- Common user statuses: public, private, exclusivePrivate, groupShow, ticketShow, spy, off.
+- High-value branching fields:
+- context.model?.id
+- context.model?.status
+- context.user?.id
+- context.user?.isModel
+- Use `context.user?.id === context.model?.id` to determine that current user is a broadcasting model
+- Use `context.user?.isModel` && !isBroadcaster to determine that visiting user is a model
+- context.user?.status
+- context.user?.hasTokens
+
+## Entity Shapes
+
+### TV1ExtContext
+- model?: TV1ExtModel
+- user?: TV1ExtUser
+
+### TV1ExtModel
+- id: number
+- username: string
+- name: string
+- avatarUrlThumb: string
+- gender: 'male' | 'female' | 'group' | 'tranny'
+- status: 'public' | 'private' | 'exclusivePrivate' | 'groupShow' | 'ticketShow' | 'idle' | 'off'
+- isPrivateEnabled: boolean
+- isSpyEnabled: boolean
+- isExclusivePrivateEnabled: boolean
+- isNonNude: boolean
+
+### TV1ExtUser
+Discriminated union on `isGuest`: TV1ExtGuestUser | TV1ExtLoggedInUser.
+
+TV1ExtGuestUser:
+- isGuest: true
+- guestHash: string;
+
+TV1ExtLoggedInUser:
+- isGuest: false
+- id: number
+- username: string
+- status: 'public' | 'private' | 'exclusivePrivate' | 'groupShow' | 'ticketShow' | 'spy' | 'off'
+- hasTokens: boolean
+- hasPaidBefore: boolean
+- hasUltimateSubscription: boolean
+- isModel: boolean
+- `isModel` means the logged-in user has a model account. It does not mean they are the broadcaster of the current room.
+- userRanking?: { league: 'grey' | 'bronze' | 'silver' | 'gold' | 'diamond' | 'royal' | 'legend'; level: number }
+
+### TV1PaymentData
+- amount: string
+- paymentToken: string
+- transactionId: string
+- userId: string
+
+### TV1TipData (payload of v1.tokens.spent)
+- amount: number
+- isAnonymous: boolean
+- isFromTheCurrentUser: boolean
+- isOriginalSource: boolean
+- message: string | undefined
+- source: 'console' | 'tipMenu' | 'goal' | 'epicGoal' | 'fullscreen' | 'interactiveToy' | 'publicChat' | 'privateChat' | 'extension' | 'sendTipButton' | 'feed'
+- type: 'private' | 'public'
+- user: TV1ExtUser | null | undefined
+
+### TV1GoalData
+- description: string
+- isCompleted: boolean
+- tokensTarget: number
+- tokensCollected: number
+
+## Common SDK Calls
+- v1.ext.context.get -> load initial room context.
+- v1.ext.context.updated -> react to context changes. Event payload is { context: TV1ExtContext }.
+- v1.ext.whisper.local -> send a message to every frame of the current user.
+- v1.ext.whisper -> broadcast to all loaded clients in the room. Users in public shows must include paymentData from v1.payment.tokens.spend.succeeded.
+- v1.ext.whispered -> receives whispers from v1.ext.whisper.
+- v1.ext.whispered.local -> receives whisper.local messages.
+- v1.chat.message.send -> send a chat message on behalf of the extension. The message is sent locally to each user. Always pass isAnonymous from the payment/tip source and preserve the user's anonymity. It can include a {username} placeholder. You can highlight part of the text by using {#accent}Accent text{/accent} and {#fade}Faded text{/fade}. ALWAYS use it to notify a user about game results, e.g. after v1.ext.activity.request timeout.
+- v1.chatbot.message.send -> send a chat message as bot or model. Message is delivered locally to each user. Supports {username} placeholder in message text. Params: from ('bot' | 'model'), message (string). Use it only in chatbot extensions.
+- v1.chat.message.received -> triggered on every new chat message. Payload: messageText (string), sender (TV1ExtUser), type ('private' | 'public').
+- v1.ext.settings.get -> read saved settings in slot pages and background.
+- v1.model.ext.settings.get -> load saved settings inside settings.html.
+- v1.model.ext.settings.set.requested -> platform save event for settings.html.
+- v1.model.ext.settings.set -> persist settings from settings.html.
+- v1.ext.actions.call -> call backend actions declared in the manifest.
+- v1.payment.tokens.spend -> request token spend from the current user. Result is null; confirmation arrives via event.
+- v1.payment.tokens.spend.succeeded -> confirm successful token spend on the paying client. Payload includes isAnonymous and paymentData (TV1PaymentData) needed for v1.ext.whisper in public shows. Prefer it over v1.tokens.spent for any games or interactions that require payment confirmation.
+- v1.payment.tokens.topup -> open the token purchase modal directly for an explicit "Buy tokens" CTA. Params null, result null. It does not confirm a spend; use v1.payment.tokens.spend when you need a confirmed payment for a game or interaction.
+- v1.tokens.spent -> receive room-side tip events. Should be used in background to react on tips (e.g. to send a message in chat).
+- v1.private.request -> request a private show with the broadcaster.
+- v1.ext.signup.open -> open sign-up for anonymous users.
+- v1.ext.activity.request -> Reserves exclusive access to shared activity slots (`EXTENSION_SLOT_RIGHT_OVERLAY`, `EXTENSION_SLOT_VIDEO_DECORATIVE_OVERLAY`) for a short visual action (for example: reactions, wheel-of-fortune spin, or a brief action indicator). The call waits until the slot is available, then starts the reservation for `durationMs` (max `30000` ms) and returns `{ activityId: string }`. Reservation is ephemeral (not persisted across reboots and not restored for newly joined users); for long-lived, persistent flows use `v1.session.*`.
+- v1.ext.movableOverlay.update -> update moveableOverlay status pill (status + message). Sex Toys and Broadcast Tools only.
+- v1.monitoring.report.error -> report meaningful failures.
+- v1.monitoring.report.log -> report important lifecycle events or fallback decisions.
+- v1.storage.string.set -> store a string value by key. Optional ttlSeconds for auto-expiry.
+- v1.storage.string.get -> read a string value by key.
+- v1.storage.string.append -> append text to a string value. If key does not exist, behaves like set.
+- v1.storage.int.get -> read an integer counter value by key.
+- v1.storage.int.increment -> add delta to an integer counter. Negative delta subtracts.
+- v1.storage.int.reset -> reset an integer counter to 0.
+- v1.storage.mutex.lock -> acquire an exclusive lock. Optional ttlSeconds for auto-release.
+- v1.storage.mutex.unlock -> release a previously acquired mutex.
+- v1.storage.mutex.getState -> check whether a mutex is currently locked.
+- v1.storage.top.get -> read a top counter: top-N users by total within a sliding window.
+- v1.storage.top.increment -> append an increment to a top counter for a user.
+- v1.storage.top.reset -> clear all increments for a top counter key.
+- v1.goal.get -> load the current active regular goal. Returns `{ goal: TV1GoalData | null }`. `goal` is `null` when no regular goal is active.
+- v1.goal.updated -> fires when any field of the active goal changes (description, isCompleted, tokensTarget, tokensCollected) or the active goal is removed. Payload: `{ goal: TV1GoalData | null }`. Use it in background to keep the cached goal in sync and broadcast updates to visual slots via v1.ext.whisper.local.
+- v1.session.join.model -> model-only create/start of a long-term session when none exists. If a session is already active, this call does not recreate/replace it.
+- v1.session.join.user -> user-only join after payment (`payment` param is required and is taken from `paymentData` in `v1.payment.tokens.spend.succeeded`). If no session is active, this call can create one.
+- v1.session.get -> returns the current long-term session. Before enabling Start/Join UI, check `v1.session.get`: if `session.owner === 'other'`, keep controls blocked because another extension owns the active session. TTL is applied from whoever created the active session first (model or user).
+- v1.session.finish.model -> clear the current long-term session from the model side.
+- v1.session.whisper.user -> send a custom action payload within the current long-term session from the user to the model.
+
+## Canonical Examples and Practices
+
+### Settings save flow in settings.html
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const DEFAULT_SETTINGS = {
+  isEnabled: true,
+  viewerMessage: 'Welcome to the game',
+};
+
+const toSettings = (value) => {
+  if (!value || typeof value !== 'object') {
+    return DEFAULT_SETTINGS;
+  }
+  const input = /** @type {Record<string, unknown>} */ (value);
+  return {
+    isEnabled:
+      typeof input.isEnabled === 'boolean' ? input.isEnabled : DEFAULT_SETTINGS.isEnabled,
+    viewerMessage:
+      typeof input.viewerMessage === 'string'
+        ? input.viewerMessage
+        : DEFAULT_SETTINGS.viewerMessage,
+  };
+};
+const init = async () => {
+  const res = await ext.makeRequest('v1.model.ext.settings.get', null);
+  const savedSettings = toSettings(res.settings);
+  // populate form fields from savedSettings here
+  const onSettingsSaveRequested = async () => {
+    // read current values from your form fields here
+    const settings = {
+      isEnabled: true,
+      viewerMessage: 'Hello',
+    };
+    const isError =
+      typeof settings.viewerMessage !== 'string' ||
+      settings.viewerMessage.trim().length === 0;
+    await ext.makeRequest('v1.model.ext.settings.set', {
+      settings,
+      isError,
+    });
+  };
+  ext.subscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+  const cleanup = () => {
+    ext.unsubscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+  };
+};
+void init();
+```
+
+### Backend action manifest and call
+Manifest snippet:
+```
+{
+  "actions": [
+    {
+      "name": "createToken",
+      "type": "externalCall",
+      "config": {
+        "action": "https://example.com/api/token",
+        "method": "POST"
+      }
+    }
+  ]
+}
+```
+
+Call from extension code
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+const init = async () => {
+  const result = await ext.makeRequest('v1.ext.actions.call', {
+    actionName: 'createToken',
+    params: {},
+  });
+  if (result.code !== 200) {
+    await ext.makeRequest('v1.monitoring.report.error', {
+      message: 'createToken action failed',
+      data: { code: result.code, body: result.body },
+    });
+    return;
+  }
+  if (!result.body || typeof result.body !== 'object') {
+    await ext.makeRequest('v1.monitoring.report.error', {
+      message: 'createToken returned invalid body',
+      data: { body: result.body },
+    });
+    return;
+  }
+  const body = /** @type {Record<string, unknown>} */ (result.body);
+  if (typeof body.token !== 'string') {
+    await ext.makeRequest('v1.monitoring.report.error', {
+      message: 'createToken returned invalid token',
+      data: { body: result.body },
+    });
+    return;
+  }
+  const token = body.token;
+  console.log('Received token:', token);
+};
+void init();
+```
+
+### Token spend in user iframe, model background reacts via v1.tokens.spent
+User EXTENSION_SLOT_MAIN_GAME_FUN slot:
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+const spendForRound = async () => {
+  await ext.makeRequest('v1.payment.tokens.spend', {
+    tokensAmount: 10,
+    tokensSpendData: {
+      type: 'ROUND_JOIN',
+      roundId: 'round-1',
+    },
+  });
+};
+const onTokensSpendSucceeded = (data) => {
+  console.log('Spend confirmed:', data.paymentData.amount, data.tokensSpendData);
+};
+ext.subscribe('v1.payment.tokens.spend.succeeded', onTokensSpendSucceeded);
+const cleanup = () => {
+  ext.unsubscribe('v1.payment.tokens.spend.succeeded', onTokensSpendSucceeded);
+};
+
+void spendForRound();
+```
+
+Model background slot (reacts to tip with an API call):
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+const onTokensSpent = async ({ tipData }) => {
+  if (!tipData.isOriginalSource) {
+    return;
+  }
+  const result = await ext.makeRequest('v1.ext.actions.call', {
+    actionName: 'recordPayment',
+    params: {
+      amount: tipData.amount,
+      userId: tipData.user?.id,
+    },
+  });
+  if (result.code !== 200) {
+    await ext.makeRequest('v1.monitoring.report.error', {
+      message: 'recordPayment action failed',
+      data: { code: result.code, body: result.body },
+    });
+  }
+};
+ext.subscribe('v1.tokens.spent', onTokensSpent);
+const cleanup = () => {
+  ext.unsubscribe('v1.tokens.spent', onTokensSpent);
+};
+```
+
+### User-initiated whisper with payment token (full flow)
+When a user needs to broadcast a whisper during a public show, paymentData is required.
+Flow: visual slot calls v1.payment.tokens.spend -> user background listens to v1.payment.tokens.spend.succeeded -> user background sends v1.ext.whisper with paymentData.
+
+User visual slot (initiates spend on user action):
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const spinWheel = async () => {
+  await ext.makeRequest('v1.payment.tokens.spend', {
+    tokensAmount: 10,
+    tokensSpendData: { action: 'spin_wheel' },
+  });
+};
+```
+
+User background slot (listens for payment confirmation, whispers with paymentData):
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const onSpendSucceeded = async (data) => {
+  await ext.makeRequest('v1.ext.whisper', {
+    data: { type: 'SPIN_RESULT', value: 7, isAnonymous: data.isAnonymous },
+    paymentData: data.paymentData,
+  });
+};
+ext.subscribe('v1.payment.tokens.spend.succeeded', onSpendSucceeded);
+const cleanup = () => {
+  ext.unsubscribe('v1.payment.tokens.spend.succeeded', onSpendSucceeded);
+};
+```
+
+All clients receiving the broadcast:
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+const onWhispered = (data) => {
+  if (data.type !== 'SPIN_RESULT') {
+    return;
+  }
+  showResult(data.value);
+};
+ext.subscribe('v1.ext.whispered', onWhispered);
+const cleanup = () => {
+  ext.unsubscribe('v1.ext.whispered', onWhispered);
+};
+```
+
+### Activity request flow
+In rightOverlay or videoDecorativeOverlay (after user initiated whisper with payment token):
+
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const ANIMATION_DURATION = 8_000;
+const ACTIVITY_DURATION = 10_000;
+
+const handleWhispered = async (data) => {
+    if ('type' in data && data.type !== 'SPIN_THE_WHEEL') {
+      return;
+    };
+
+    await ext.makeRequest('v1.ext.activity.request', {
+      durationMs: ACTIVITY_DURATION,
+    });
+
+    // do some work here, for example show an animation in rightOverlay or videoDecorativeOverlay for {ANIMATION_DURATION}. Make sure that animation duration < activity duration.
+
+    const isAnonymous = data.isAnonymous === true;
+
+    // after the activity ends, send a message in chat with the result
+    void ext.makeRequest('v1.chat.message.send', {
+      isAnonymous,
+      // where X is the result of the activity
+      message: isAnonymous ? 'An anonymous user won the X' : 'A viewer won the X',
+      user: null,
+    });
+};
+
+ext.subscribe('v1.ext.whispered', handleWhispered);
+```
+UI blocking should be handled in UI by listening to the activity changes. For example, in mainGameFun slot:
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+// sync initial state
+const init = async () => {
+  const { status } = await ext.makeRequest('v1.ext.activity.status', null);
+
+  if (status === 'busy') {
+    // disable button
+  };
+};
+
+// change the UI state on activity updates
+ext.subscribe('v1.ext.activity.busy', () => {
+  // disable button
+});
+ext.subscribe('v1.ext.activity.available', () => {
+  // enable button
+});
+
+await init()
+
+```
+
+### Welcome bot (chatbot background slot)
+Loads context, subscribes to updates, and sends a welcome message after 30 seconds only to Ultimate subscribers in background slot.
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const init = async () => {
+  const { context } = await ext.makeRequest('v1.ext.context.get', null);
+  let currentContext = context;
+
+  const onContextUpdated = (data) => {
+    currentContext = data.context;
+  };
+  ext.subscribe('v1.ext.context.updated', onContextUpdated);
+
+  const welcomeTimer = setTimeout(async () => {
+    if (!currentContext.user?.hasUltimateSubscription) {
+      return;
+    }
+    await ext.makeRequest('v1.chatbot.message.send', {
+      from: 'bot',
+      message: 'Welcome to the room, {username}!',
+    });
+  }, 30_000);
+
+  const cleanup = () => {
+    clearTimeout(welcomeTimer);
+    ext.unsubscribe('v1.ext.context.updated', onContextUpdated);
+  };
+};
+void init();
+```
+
+### Buy tokens CTA (open the top-up modal)
+Use v1.payment.tokens.topup for an explicit "Buy tokens" button. It opens the purchase modal directly and returns null — it does not confirm a spend. For paid game actions that need a confirmed payment, use v1.payment.tokens.spend with v1.payment.tokens.spend.succeeded instead.
+
+Visual slot:
+```
+import { createExtHelper } from '@stripchatdev/ext-helper';
+const ext = createExtHelper();
+
+const onBuyTokensClick = () => {
+  // opens the purchase modal directly; no result and no confirmation event
+  void ext.makeRequest('v1.payment.tokens.topup', null);
+};
+// wire onBuyTokensClick to your "Buy tokens" button
+
+const init = async () => {
+  const { context } = await ext.makeRequest('v1.ext.context.get', null);
+  // show the CTA only to logged-in users who are out of tokens
+  const showBuyCta =
+    !!context.user && !context.user.isGuest && !context.user.hasTokens;
+  // render or hide the "Buy tokens" button based on showBuyCta here
+};
+void init();
+```
+
+## Layout And Theme
+- Width is controlled by the parent slot container.
+- Build layouts with flexbox, grid, %, fr, min(), max(), and clamp().
+- Set html { height: 100% }.
+- Let body grow naturally with content.
+- Put the page background on <html>.
+- Do not rely on viewport-based responsive logic.
+- Assume slot width can change at any time.
+- Use html[data-theme='dark'] and html[data-theme='light'] for theme-specific tokens.
+- Read [design guidelines](https://extensions.stripchat.com/docs/style-guide/guidelines) for recommended UI patterns and practices. Use recommended colors and fonts.
+
+## Monitoring
+- Use monitoring for meaningful failures and important lifecycle events.
+- Keep monitoring messages short and stable.
+- Put variable details in data.
+- Do not spam monitoring for routine events.
+
+## Common Changes
+
+### Add a page variant
+1. Create a new root HTML file at the project root.
+2. Add its page key to public/manifest.json views.pages.
+3. Update public/resolveSlotPage.js to return that page key or null.
+4. Add the new HTML file to vite.config.<%= isTypescript ? 'ts' : 'js' %> input.
+5. Create or reuse the page entry module and page code.
+6. Keep manifest, resolver, HTML, and Vite input in sync.
+### Add model, viewer, or guest variants
+1. Keep the slot name the same.
+2. Add separate page keys in views.pages.
+3. Branch in public/resolveSlotPage.js using context.user, context.model, and context.user.isGuest. For custom broadcaster-only variants outside Broadcast Tools defaults, check `context.user?.id === context.model?.id`. Use `context.user?.isModel` only when behavior should differ for other models visiting your stream.
+4. Return null when that actor should not render the slot.
+5. Keep shared state in background.
+### Add a settings page
+1. Create settings.html as a root HTML file.
+2. Create a page entry module for it and call createExtHelper() there.
+3. Add views.settings to public/manifest.json.
+4. Add settings.html to vite.config.<%= isTypescript ? 'ts' : 'js' %> input.
+5. Load with v1.model.ext.settings.get.
+6. Save in response to v1.model.ext.settings.set.requested.
+7. Persist with v1.model.ext.settings.set.
+### Add a backend action
+1. Declare the action in public/manifest.json actions[].
+2. Use externalCall for HTTP requests. Use delayedEvent only for deferred follow-up work.
+3. Call the action with v1.ext.actions.call, passing all required params.
+4. Handle non-success result.code explicitly.
+5. Do not hardcode secrets in slot code.
+### Add moveable overlay
+1. Add EXTENSION_SLOT_MOVEABLE_OVERLAY to the slot configuration.
+2. Add a page key and root HTML file for it.
+3. Add moveableSlot to the manifest with width and height. Max size is 450x740.
+4. Keep public/icon.svg in the archive root.
+5. Add the HTML file to Vite input.
+6. Update the resolver to return the page key only when appropriate.
+### Final Check Before Finishing
+- createExtHelper() is called once per page.
+- public/resolveSlotPage.js is sync and returns only valid page keys or null.
+- Every page key in views.pages points to a real root HTML file.
+- Every root HTML file is included in Vite input.
+- Subscriptions, timers, and DOM listeners are cleaned up.
+- Durable logic lives in background.
+- Theme styles are based on html[data-theme].
+- Layout uses flexible CSS without viewport @media queries.
+- manifest.json is valid JSON.
+
+### References
+- Overview: https://extensions.stripchat.com/docs/overview/how-extensions-work
+- Manifest: https://extensions.stripchat.com/docs/getting-started/manifest
+- Resolve slot page: https://extensions.stripchat.com/docs/getting-started/resolve-slot-page
+- Slots: https://extensions.stripchat.com/docs/getting-started/slots
+- Slots communication: https://extensions.stripchat.com/docs/getting-started/slots-communication
+- Slots layout: https://extensions.stripchat.com/docs/getting-started/slots-layout
+- Theming: https://extensions.stripchat.com/docs/getting-started/theming
+- Settings: https://extensions.stripchat.com/docs/getting-started/settings
+- Backend actions: https://extensions.stripchat.com/docs/getting-started/backend-actions
+- Monitoring: https://extensions.stripchat.com/docs/getting-started/monitoring
+- Requests: https://extensions.stripchat.com/docs/api/requests
+- Events: https://extensions.stripchat.com/docs/api/events
+- Entities: https://extensions.stripchat.com/docs/api/entities
+- Session guide: https://extensions.stripchat.com/docs/guides/session-extension
+<!-- AUTO-GENERATED SECTION END -->