@stripchatdev/create-stripchat-extension 0.1.49 → 0.2.1

package/templates/v1/src/slots/settings/main.css.ejs

@@ -0,0 +1,117 @@
+:root {
+  font-family: Inter, 'Helvetica Neue', Roboto, Arial, Helvetica, sans-serif;
+}
+
+html {
+  height: 100%;
+  font-size: 13px;
+  color: var(--text-color);
+}
+
+html[data-theme='light'] {
+  --text-color: #101010;
+  --input-error-color: #f14b57;
+  --input-error-active: #de5b64;
+  --input-error-hover: #d5444e;
+  --input-error-box-shadow-focused: inset 0 1px 1px rgb(0 0 0 / 7.5%), 0 0 6px rgb(213 68 78 / 75%);
+  --input-color: #141414;
+  --input-background-color: #fff;
+  --input-background-color-focused: #fff;
+  --input-border-color: rgb(20 20 20 / 20%);
+  --input-border-color-focused: rgb(20 20 20 / 40%);
+  --input-box-shadow-focused: inset 0 1px 1px rgb(0 0 0 / 7.5%), 0 0 5px rgb(20 20 20 / 15%);
+  --input-placeholder-color: rgb(20 20 20 / 40%);
+}
+
+html[data-theme='dark'] {
+  --text-color: #f8f8f8;
+  --input-error-color: #de5b64;
+  --input-error-active: #d5444e;
+  --input-error-hover: #d5444e;
+  --input-error-box-shadow-focused: inset 0 1px 1px rgb(0 0 0 / 7.5%), 0 0 6px rgb(213 68 78 / 75%);
+  --input-color: #f8f8f8;
+  --input-background-color: #000;
+  --input-background-color-focused: #000;
+  --input-border-color: #000;
+  --input-border-color-focused: rgb(255 255 255 / 30%);
+  --input-box-shadow-focused: inset 0 1px 1px rgb(0 0 0 / 7.5%), 0 0 5px rgb(255 255 255 / 25%);
+  --input-placeholder-color: rgb(248 248 248 / 33%);
+}
+
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+
+body {
+  font-feature-settings:
+    'liga' off,
+    'clig' off;
+}
+
+main {
+  margin: 0 auto;
+  height: 100%;
+}
+
+h1 {
+  margin-bottom: 0.5rem;
+}
+
+form {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.message-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+}
+
+.input {
+  display: inline-block;
+  height: 40px;
+  padding: 10px 20px;
+  border: 1px solid var(--input-border-color);
+  border-radius: 20px;
+  background-color: var(--input-background-color);
+  color: var(--input-color);
+  font-size: 12px;
+  line-height: 20px;
+  transition: all 0.15s ease-in-out;
+}
+
+.input::placeholder {
+  color: var(--input-placeholder-color);
+}
+
+.input:focus {
+  border-color: var(--input-border-color-focused);
+  background-color: var(--input-background-color-focused);
+  box-shadow: var(--input-box-shadow-focused);
+  outline: none;
+}
+
+.input:disabled {
+  cursor: default;
+  opacity: 0.33;
+}
+
+input::-ms-clear {
+  display: none;
+}
+
+input[type='number']::-webkit-outer-spin-button,
+input[type='number']::-webkit-inner-spin-button {
+  margin: 0;
+  appearance: none;
+}
+
+.error {
+  color: var(--input-error-color);
+  font-size: 0.75rem;
+  line-height: 1.2;
+}

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

@@ -0,0 +1,3 @@
+import { init } from './app';
+
+init();

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

@@ -0,0 +1,9 @@
+import { render } from 'preact';
+
+import { App } from './app';
+
+const root = document.getElementById('app');
+
+if (root) {
+  render(<App />, root);
+}

package/templates/v1/src/slots/settings/settings.html.ejs

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Extension settings</title>
+
+  <link rel="stylesheet" href="<%= stylePath %>" />
+</head>
+
+<body>
+  <% if (framework==='preact' ) { -%>
+    <div id="app"></div>
+    <% } else { -%>
+      <main>
+        <h1>Extension settings</h1>
+        <form>
+          <label class="message-field" for="viewer-message">
+            Viewer message
+            <input id="viewer-message" class="input" type="text" aria-invalid="false" disabled />
+          </label>
+          <p id="settings-error" class="error" role="alert" aria-live="polite"></p>
+        </form>
+      </main>
+      <% } -%>
+        <script type="module" src="<%= entryModulePath %>"></script>
+</body>
+
+</html>

package/templates/v1/vite.config.ts.ejs

@@ -15,6 +15,9 @@ export default defineConfig({
     outDir: 'dist',
     rollupOptions: {
       input: {
+<% if (hasSettings) { -%>
+        'settings': resolve(__dirname, 'settings.html'),
+<% } -%>
 <%  slotsEntries.forEach(({ slotCamelCased }, i) => { -%>
         '<%= slotCamelCased %>': resolve(__dirname, '<%= slotCamelCased %>.html')<%= i < slotsEntries.length - 1 ? ',' : '' %>
 <% }); -%>

package/templates/v2/AGENTS.md.ejs

@@ -76,8 +76,8 @@ npm run template:update
 - 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
+- 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 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.
@@ -263,8 +263,8 @@ TV1ExtLoggedInUser:
 - 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.whisper -> broadcast to all loaded clients in the room. Users in public shows must include paymentHash from v1.payment.tokens.spend.succeeded.
+- 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.
@@ -275,7 +275,7 @@ TV1ExtLoggedInUser:
 - 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.spend.succeeded -> confirm successful token spend on the paying client. Payload includes isAnonymous and paymentHash (TV1PaymentHash) 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.
@@ -299,11 +299,44 @@ TV1ExtLoggedInUser:
 - 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.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.
 
+### 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;
+  }
+};
+
+const expectedPrice = await loadExpectedPrice();
+
+// 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
+})
+
+```
+
 ## Canonical Examples and Practices
 
 ### Settings save flow in settings.html
@@ -464,8 +497,8 @@ const cleanup = () => {
 ```
 
 ### 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.
+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.
 
 User visual slot (initiates spend on user action):
 ```
@@ -480,7 +513,7 @@ const spinWheel = async () => {
 };
 ```
 
-User background slot (listens for payment confirmation, whispers with paymentData):
+User background slot (listens for payment confirmation, whispers with paymentHash):
 ```
 import { createExtHelper } from '@stripchatdev/ext-helper';
 const ext = createExtHelper();
@@ -488,7 +521,7 @@ 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,
+    paymentHash: data.paymentHash,
   });
 };
 ext.subscribe('v1.payment.tokens.spend.succeeded', onSpendSucceeded);
@@ -501,15 +534,20 @@ 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);
 };
 ```
 
@@ -519,15 +557,20 @@ In rightOverlay or videoDecorativeOverlay (after user initiated whisper with pay
 ```
 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,
     });
@@ -545,7 +588,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:
 ```

package/templates/v2/vite.config.ts.ejs

@@ -17,6 +17,9 @@ export default defineConfig({
     assetsInlineLimit: 0,
     rollupOptions: {
       input: {
+<% if (hasSettings) { -%>
+        'settings': resolve(__dirname, 'settings.html'),
+<% } -%>
 <%  slotsEntries.forEach(({ slotCamelCased }, i) => { -%>
         '<%= slotCamelCased %>': resolve(__dirname, '<%= slotCamelCased %>.html')<%= i < slotsEntries.length - 1 ? ',' : '' %>
 <% }); -%>