@stripchatdev/create-stripchat-extension 0.1.49 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripchatdev/create-stripchat-extension",
-  "version": "0.1.49",
+  "version": "0.2.2",
   "type": "module",
   "files": [
     "dist",

package/templates/v1/AGENTS.md.ejs

@@ -1,6 +1,6 @@
 # <%= name %>
 Use this file as the primary coding contract for this starter. Use the Stripchat docs to get more details.
-- Category: <%= config.category %>
+- Category: <%= category %>
 - Slots: <%= slotsEntries.map(({ slot }) => slot).join(', ') %>
 - Framework: <%= framework %>
 - Language: <%= language %>
@@ -47,7 +47,7 @@ Use this file as the primary coding contract for this starter. Use the Stripchat
 - 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, paymentHash is required. Obtain it from v1.payment.tokens.spend.succeeded. The model can whisper without paymentHash.
-- Broadcast whispers arrive as v1.ext.whispered
+- Broadcast whispers arrive as v2.ext.whispered with the envelope `{ data, tokenSum }`. Treat `tokenSum` as authoritative actual payment; Validate `tokenSum` against actual activity price. It could be null for free actions, e.g. whispers called by a model.
 - 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.
@@ -65,7 +65,7 @@ Use this file as the primary coding contract for this starter. Use the Stripchat
 - 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.
+- If you use EXTENSION_SLOT_MOVEABLE_OVERLAY, no size configuration is needed in the manifest — the overlay is fixed at 450x685.
 - 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.
@@ -73,10 +73,7 @@ Use this file as the primary coding contract for this starter. Use the Stripchat
 - 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
-- For state shared between a background slot and visual slots, use the slot-state helpers.
-- The background slot owns the state. Visual slots read it and send partial updates.
-- Use the same channel string for the host and every client. Create only one host for each channel.
-- For messages that are not synchronized state, use v1.ext.whisper.local for communication between this extension's frames for the current user. Background should subscribe to events and coordinate it.
+- 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.
@@ -86,14 +83,10 @@ Use this file as the primary coding contract for this starter. Use the Stripchat
 - 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.
+- If you use `EXTENSION_SLOT_MOVEABLE_OVERLAY`, the overlay size is fixed at 450x685 — no manifest size fields are needed. 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.
 
-<% if (framework === 'preact') { -%>
-- Use useSlotState from @stripchatdev/ext-helper/helpers/react in React-compatible visual slots.
-<% } -%>
-
 ## 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
@@ -110,19 +103,12 @@ Use this file as the primary coding contract for this starter. Use the Stripchat
 ## Default Runtime Pattern
 - background owns long-lived state and coordination.
 - Visual slots render UI from current state and forward user actions.
-- Use slot-state helpers when visual slots need a synchronized state snapshot owned by background.
 - 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.
 
-## Shared Slot State helpers
-- Use the same channel value in the host and all clients.
-- The client starts with isLoading: true and state: null until it receives the initial state.
-- Use `setState` for shallow partial updates. Update nested objects explicitly.
-- Unsubscribe clients when visual slots are disposed and unsubscribe the host when background teardown runs.
-
 ## Resolver
 - Start from the generated resolver and extend it only when needed.
 - Keep resolver logic cheap, synchronous, and defensive.
@@ -213,7 +199,6 @@ TV1ExtLoggedInUser:
 - isGuest: false
 - id: number
 - username: string
-- fanClub: TV1UsersFanClub
 - status: 'public' | 'private' | 'exclusivePrivate' | 'groupShow' | 'ticketShow' | 'spy' | 'off'
 - hasTokens: boolean
 - hasPaidBefore: boolean
@@ -222,26 +207,11 @@ TV1ExtLoggedInUser:
 - `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 }
 
-### TV1FanClubTier
-Fan club subscription tier. Ordered from lowest to highest:
-- soldier: first tier with basic benefits
-- lord: second tier with more benefits than soldier
-- prince: third tier with the most benefits
-
-### TV1UsersFanClub
-Discriminated union on `isSubscribed`: TV1UsersFanClubSubscribed | TV1UsersFanClubNotSubscribed.
-
-TV1UsersFanClubSubscribed:
-- isSubscribed: true
-- tier: TV1FanClubTier
-
-TV1UsersFanClubNotSubscribed:
-- isSubscribed: false
-
-### TV1PaymentHash
-- string
-- Payment hash used for authentication. Do not store or reuse it. Use it only once for the request it authorizes.
-
+### TV1PaymentData
+- amount: string
+- paymentToken: string
+- transactionId: string
+- userId: string
 
 ### TV1TipData (payload of v1.tokens.spent)
 - amount: number
@@ -264,7 +234,7 @@ TV1UsersFanClubNotSubscribed:
 - 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 paymentHash from v1.payment.tokens.spend.succeeded.
-- v1.ext.whispered -> receives whispers from v1.ext.whisper.
+- v2.ext.whispered -> receives broadcasts from v1.ext.whisper. The event payload is `{ data, tokenSum }`, where custom fields are in `data`; 
 - 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.
@@ -279,7 +249,6 @@ TV1UsersFanClubNotSubscribed:
 - 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.fanClub.request -> open the fan club subscription modal for the current model. Check `user.fanClub` in context before calling. Params: `{ tier: TV1FanClubTier } | null` — `tier` selects which tab to show in the modal; pass `null` to default to `soldier`. Result null.
 - 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.
@@ -300,97 +269,45 @@ TV1UsersFanClubNotSubscribed:
 - 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 (`paymentHash` param is required and is taken from `paymentHash` in `v1.payment.tokens.spend.succeeded`). If no session is active, this call can create one.
+- v1.session.join.user -> user-only join after payment (`paymentHash` is required and is taken from `paymentHash` 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
-
-### Shared state between background and visual slots
-Use one host in the background slot and a client in each visual slot that needs the same state. Use the same channel in every slot.
-
-Background slot:
-```
-import { createExtHelper } from '@stripchatdev/ext-helper';
-import { createSlotStateHost } from '@stripchatdev/ext-helper/helpers';
-
-const ext = createExtHelper();
-const scoreState = createSlotStateHost({
-  channel: 'score',
-  extHelper: ext,
-  initialState: { score: 0 },
-});
-
-// The background slot owns the shared state.
-const cleanup = () => scoreState.unsubscribe();
-```
-
-<% if (framework === 'preact') { -%>
-Visual slot:
-```
-import { createExtHelper } from '@stripchatdev/ext-helper';
-import { useSlotState } from '@stripchatdev/ext-helper/helpers/react';
-
-type ScoreState = {
-  score: number;
-};
-
-const ext = createExtHelper();
-
-export const App = () => {
-  const { isLoading, state, setState } = useSlotState<ScoreState>({
-    channel: 'score',
-    extHelper: ext,
-  });
-
-  if (isLoading || !state) return <p>Loading score...</p>;
-
-  return (
-    <button onClick={() => void setState({ score: state.score + 1 })}>
-      Score: {state.score}
-    </button>
-  );
+### Validate broadcast payment before acting
+`tokenSum` on `v2.ext.whispered` is the authoritative number of tokens actually paid. In a runtime slot, load the expected action price with `v1.ext.settings.get` (or use a constant for defining a price) and narrow the returned settings value before acting;
+
+```js
+const loadExpectedPrice = async () => {
+  try {
+    const { settings } = await ext.makeRequest('v1.ext.settings.get', null);
+    if (
+      typeof settings !== 'object' ||
+      settings === null ||
+      // priceTokens is an example field, you can name it as you wan't
+      !('priceTokens' in settings) ||
+      !isValidPrice(settings.priceTokens)
+    ) {
+      return null;
+    }
+    return settings.priceTokens;
+  } catch {
+    return null;
+  }
 };
-```
-<% } else { -%>
-Visual slot:
-```
-import { createExtHelper } from '@stripchatdev/ext-helper';
-import { createSlotStateClient } from '@stripchatdev/ext-helper/helpers';
 
-type ScoreState = {
-  score: number;
-};
+const expectedPrice = await loadExpectedPrice();
 
-const ext = createExtHelper();
-const scoreState = createSlotStateClient<ScoreState>({
-  channel: 'score',
-  extHelper: ext,
-});
-const button = document.createElement('button');
-document.body.append(button);
+// later in the background slot
+extHelper.susbcribe('v2.ext.whispered', ({ data, tokenSum }) => {
+  // tokenSum is null for a model or in private shows
+  if (tokenSum !== null && tokenSum !== expectedPrice) return;
+  // otherwise proceed with an action
+})
 
-const render = () => {
-  const { isLoading, state } = scoreState.getSnapshot();
-  button.textContent = isLoading || !state ? 'Loading score...' : `Score: ${state.score}`;
-};
-const addPoint = () => {
-  const state = scoreState.getSnapshot().state;
-  if (state) void scoreState.setState({ score: state.score + 1 });
-};
-
-const unsubscribe = scoreState.subscribe(render);
-button.addEventListener('click', addPoint);
-const cleanup = () => {
-  unsubscribe();
-  button.removeEventListener('click', addPoint);
-  button.remove();
-};
 ```
-<% } -%>
 
-The background host owns the state. Visual slots read it and send partial updates.
+## Canonical Examples and Practices
 
 ### Settings save flow in settings.html
 ```
@@ -511,7 +428,7 @@ const spendForRound = async () => {
   });
 };
 const onTokensSpendSucceeded = (data) => {
-  console.log('Spend confirmed:', data.paymentHash, data.tokensSpendData);
+  console.log('Spend confirmed:', data.paymentData.amount, data.tokensSpendData);
 };
 ext.subscribe('v1.payment.tokens.spend.succeeded', onTokensSpendSucceeded);
 const cleanup = () => {
@@ -549,7 +466,7 @@ const cleanup = () => {
 };
 ```
 
-### User-initiated whisper with payment hash (full flow)
+### User-initiated whisper with payment token (full flow)
 When a user needs to broadcast a whisper during a public show, paymentHash 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 paymentHash.
 
@@ -587,33 +504,43 @@ All clients receiving the broadcast:
 ```
 import { createExtHelper } from '@stripchatdev/ext-helper';
 const ext = createExtHelper();
-const onWhispered = (data) => {
-  if (data.type !== 'SPIN_RESULT') {
+const expectedPrice = 10;
+const onWhispered = async ({ data, tokenSum }) => {
+  if (data.type !== 'SPIN_RESULT' || typeof data.value !== 'number') {
+    return;
+  }
+  // validate that tokenSum is the same as expectedPrice. 
+  if (tokenSum !== null && tokenSum !== expectedPrice) {
     return;
   }
   showResult(data.value);
 };
-ext.subscribe('v1.ext.whispered', onWhispered);
+ext.subscribe('v2.ext.whispered', onWhispered);
 const cleanup = () => {
-  ext.unsubscribe('v1.ext.whispered', onWhispered);
+  ext.unsubscribe('v2.ext.whispered', onWhispered);
 };
 ```
 
 ### Activity request flow
-In rightOverlay or videoDecorativeOverlay (after user-initiated whisper with payment hash):
+In rightOverlay or videoDecorativeOverlay (after user initiated whisper with payment token):
 
 ```
 import { createExtHelper } from '@stripchatdev/ext-helper';
 const ext = createExtHelper();
-
+const expectedPrice = 10;
 const ANIMATION_DURATION = 8_000;
 const ACTIVITY_DURATION = 10_000;
 
-const handleWhispered = async (data) => {
-    if ('type' in data && data.type !== 'SPIN_THE_WHEEL') {
+const handleWhispered = async ({ data, tokenSum }) => {
+    if (data.type !== 'SPIN_RESULT' || typeof data.value !== 'number') {
       return;
     };
 
+    // validate that tokenSum is the same as expectedPrice. 
+    if (tokenSum !== null && tokenSum !== expectedPrice) 
+      return;
+    }
+
     await ext.makeRequest('v1.ext.activity.request', {
       durationMs: ACTIVITY_DURATION,
     });
@@ -631,7 +558,7 @@ const handleWhispered = async (data) => {
     });
 };
 
-ext.subscribe('v1.ext.whispered', handleWhispered);
+ext.subscribe('v2.ext.whispered', handleWhispered);
 ```
 UI blocking should be handled in UI by listening to the activity changes. For example, in mainGameFun slot:
 ```
@@ -765,7 +692,7 @@ void init();
 ### 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.
+3. The overlay is fixed at 450x685 — no size fields needed in the manifest.
 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.
@@ -795,4 +722,3 @@ void init();
 - 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
-- Slots state: https://extensions.stripchat.com/docs/guides/slot-state

package/templates/v1/README.md.ejs

@@ -11,6 +11,11 @@ Read `AGENTS.md` first. It is the project contract for SDK usage, slot lifecycle
 - `public/manifest.json` declares slots, page keys, optional settings entry, and backend actions.
 - `public/resolveSlotPage.js` maps slot types to page keys from `views.pages`.
 - Root HTML files like `<%= slotsEntries[0].slotCamelCased %>.html` and `background.html` are emitted to the archive root.
+<% if (hasSettings) { -%>
+- `settings.html` is the model-facing settings iframe.
+<% } else { -%>
+- To add model-facing settings later, create `settings.html`, add `views.settings`, and add its Vite input.
+<% } -%>
 - Visual slots should stay disposable; keep durable state and coordination in `background`.
 - `vite.config.<%= isTypescript ? 'ts' : 'js' %>` must include every root HTML file in `build.rollupOptions.input`.
 
@@ -32,7 +37,7 @@ Learn more about building Stripchat extensions in the [official documentation](h
 ## Common Changes
 
 - Add a page: create a root HTML file, add it to `public/manifest.json`, return its page key from `public/resolveSlotPage.js`, and include it in `vite.config.<%= isTypescript ? 'ts' : 'js' %>`.
-- Add settings: create `settings.html`, add `views.settings`, add its Vite input, load with `v1.model.ext.settings.get`, and save on `v1.model.ext.settings.set.requested`.
+- Settings are loaded with `v1.model.ext.settings.get` and saved on `v1.model.ext.settings.set.requested` through `v1.model.ext.settings.set`.
 - Add an action: declare it in `public/manifest.json` and call it with `v1.ext.actions.call`.
 
 ## Usage

package/templates/v1/package.json.ejs

@@ -12,7 +12,7 @@
     "preact": "10.25.4"<% } %>
   },
   "devDependencies": {
-    "vite": "6.4.2"<% if (isTypescript) { %>,
+    "vite": "6.4.3"<% if (isTypescript) { %>,
     "typescript": "5.8.2"<% } %><% if (framework === 'preact') { %>,
     "@preact/preset-vite": "2.10.5"<% } %>
   }

package/templates/v1/public/manifest.json.ejs

@@ -1,6 +1,9 @@
 {
   "version": "v2.0",
   "views": {
+<% if (hasSettings) { -%>
+    "settings": "settings.html",
+<% } -%>
     "slots": [<%- slotsEntries.map(({ slot }) => `"${slot}"`).join(', ') %>],
     "pages": {
 <% slotsEntries.forEach(({ slotCamelCased }, i) => { -%>
@@ -8,9 +11,5 @@
 <% }); -%>
     },
     "resolveSlotPageScript": "resolveSlotPage.js"
-  }<% if (slotsEntries.filter(({ slot }) => slot ==='EXTENSION_SLOT_MOVEABLE_OVERLAY').length > 0) { %>,
-  "moveableSlot": {
-    "width": 400,
-    "height": 600
-  }<% } %>
+  }
 }

package/templates/v1/src/slots/background/app.ts.ejs

@@ -6,10 +6,10 @@ import { createExtHelper } from '@stripchatdev/ext-helper';
 const extHelper = createExtHelper();
 
 export const init = () => {
-  const handleWhispered = async (data<%- isTypescript ? ': TEvents["v1.ext.whispered"]' : '' %>) => {
+  const handleWhispered = async (event<%- isTypescript ? ': TEvents["v2.ext.whispered"]' : '' %>) => {
     await extHelper.makeRequest('v1.monitoring.report.log', {
       message: 'background whisper received',
-      data,
+      data: event.data,
     });
   };
 
@@ -20,7 +20,7 @@ export const init = () => {
     });
   };
 
-  extHelper.subscribe('v1.ext.whispered', handleWhispered);
+  extHelper.subscribe('v2.ext.whispered', handleWhispered);
   extHelper.subscribe('v1.ext.context.updated', handleContextUpdated);
 
   extHelper.makeRequest('v1.ext.context.get', null).then((ctx) => {
@@ -31,7 +31,7 @@ export const init = () => {
   });
 
   return () => {
-    extHelper.unsubscribe('v1.ext.whispered', handleWhispered);
+    extHelper.unsubscribe('v2.ext.whispered', handleWhispered);
     extHelper.unsubscribe('v1.ext.context.updated', handleContextUpdated);
   };
 };

package/templates/v1/src/slots/settings/app.ts.ejs

@@ -0,0 +1,84 @@
+import { createExtHelper } from '@stripchatdev/ext-helper';
+
+const extHelper = createExtHelper();
+
+<% if (isTypescript) { -%>
+type TSettings = {
+  viewerMessage: string;
+};
+<% } -%>
+
+const DEFAULT_SETTINGS<%- isTypescript ? ': TSettings' : '' %> = {
+  viewerMessage: '',
+};
+
+const toSettings = (value<%- isTypescript ? ': unknown' : '' %>)<%- isTypescript ? ': TSettings' : '' %> => {
+  if (!value || typeof value !== 'object') {
+    return DEFAULT_SETTINGS;
+  }
+
+  const input<%- isTypescript ? ': Record<string, unknown>' : '' %> = <%- isTypescript ? 'value as Record<string, unknown>' : 'value' %>;
+
+  return {
+    viewerMessage:
+      typeof input.viewerMessage === 'string'
+        ? input.viewerMessage
+        : DEFAULT_SETTINGS.viewerMessage,
+  };
+};
+
+export const init = () => {
+  const viewerMessageInput = document.getElementById('viewer-message')<%- isTypescript ? ' as HTMLInputElement' : '' %>;
+  const errorMessage = document.getElementById('settings-error')<%- isTypescript ? ' as HTMLParagraphElement' : '' %>;
+  let settingsLoaded = false;
+
+  const renderValidation = (message<%- isTypescript ? ': string' : '' %>) => {
+    errorMessage.textContent = message;
+    viewerMessageInput.setAttribute('aria-invalid', String(message.length > 0));
+  };
+
+  const applySettings = (settings<%- isTypescript ? ': TSettings' : '' %>) => {
+    viewerMessageInput.value = settings.viewerMessage;
+  };
+
+  const readSettings = ()<%- isTypescript ? ': TSettings' : '' %> => ({
+    viewerMessage: viewerMessageInput.value,
+  });
+
+  const loadSettings = async () => {
+    try {
+      const response = await extHelper.makeRequest('v1.model.ext.settings.get', null);
+      applySettings(toSettings(response.settings));
+    } catch {
+      applySettings(DEFAULT_SETTINGS);
+    } finally {
+      settingsLoaded = true;
+      viewerMessageInput.removeAttribute('disabled');
+    }
+  };
+
+  const onSettingsSaveRequested = async () => {
+    const settings = readSettings();
+    const isError = !settingsLoaded || settings.viewerMessage.trim().length === 0;
+
+    renderValidation(
+      !settingsLoaded
+        ? 'Settings are still loading.'
+        : isError
+          ? 'Enter a viewer message.'
+          : '',
+    );
+
+    await extHelper.makeRequest('v1.model.ext.settings.set', {
+      settings,
+      isError,
+    });
+  };
+
+  extHelper.subscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+  void loadSettings();
+
+  return () => {
+    extHelper.unsubscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+  };
+};

package/templates/v1/src/slots/settings/app.tsx.ejs

@@ -0,0 +1,112 @@
+import { createExtHelper } from '@stripchatdev/ext-helper';
+import { useEffect, useState } from 'preact/hooks';
+
+const extHelper = createExtHelper();
+
+<% if (isTypescript) { -%>
+type TSettings = {
+  viewerMessage: string;
+};
+<% } -%>
+
+const DEFAULT_SETTINGS<%- isTypescript ? ': TSettings' : '' %> = {
+  viewerMessage: '',
+};
+
+const toSettings = (value<%- isTypescript ? ': unknown' : '' %>)<%- isTypescript ? ': TSettings' : '' %> => {
+  if (!value || typeof value !== 'object') {
+    return DEFAULT_SETTINGS;
+  }
+
+  const input<%- isTypescript ? ': Record<string, unknown>' : '' %> = <%- isTypescript ? 'value as Record<string, unknown>' : 'value' %>;
+
+  return {
+    viewerMessage:
+      typeof input.viewerMessage === 'string'
+        ? input.viewerMessage
+        : DEFAULT_SETTINGS.viewerMessage,
+  };
+};
+
+export const App = () => {
+  const [settings, setSettings] = useState<%- isTypescript ? '<TSettings>' : '' %>(DEFAULT_SETTINGS);
+  const [settingsLoaded, setSettingsLoaded] = useState(false);
+  const [validationMessage, setValidationMessage] = useState('');
+
+  useEffect(() => {
+    let isMounted = true;
+
+    const loadSettings = async () => {
+      try {
+        const response = await extHelper.makeRequest('v1.model.ext.settings.get', null);
+
+        if (isMounted) {
+          setSettings(toSettings(response.settings));
+        }
+      } catch {
+        if (isMounted) {
+          setSettings(DEFAULT_SETTINGS);
+        }
+      } finally {
+        if (isMounted) {
+          setSettingsLoaded(true);
+        }
+      }
+    };
+
+    void loadSettings();
+
+    return () => {
+      isMounted = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    const onSettingsSaveRequested = async () => {
+      const isError = !settingsLoaded || settings.viewerMessage.trim().length === 0;
+
+      setValidationMessage(
+        !settingsLoaded
+          ? 'Settings are still loading.'
+          : isError
+            ? 'Enter a viewer message.'
+            : '',
+      );
+
+      await extHelper.makeRequest('v1.model.ext.settings.set', {
+        settings,
+        isError,
+      });
+    };
+
+    extHelper.subscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+
+    return () => {
+      extHelper.unsubscribe('v1.model.ext.settings.set.requested', onSettingsSaveRequested);
+    };
+  }, [settings, settingsLoaded]);
+
+  return (
+    <main>
+      <h1>Extension settings</h1>
+      <form>
+        <label className="message-field" for="viewer-message">
+          Viewer message
+          <input
+            className="input"
+            id="viewer-message"
+            type="text"
+            aria-invalid={validationMessage.length > 0}
+            value={settings.viewerMessage}
+            disabled={!settingsLoaded}
+            onInput={(event) => {
+              const target = event.currentTarget<%- isTypescript ? ' as HTMLInputElement' : '' %>;
+              setSettings({ ...settings, viewerMessage: target.value });
+            }}
+          />
+        </label>
+        <p className="error" role="alert" aria-live="polite">{validationMessage}</p>
+      </form>
+    </main>
+  );
+};