@stripchatdev/ext-helper 0.0.1

package/README.md

@@ -0,0 +1,67 @@
+# @stripchatdev/ext-helper
+
+SDK for building extensions on the Stripchat Extension Platform. Provides typed methods for context, events, settings,
+whisper messaging, and backend actions — all from inside sandboxed iframes.
+
+## Installation
+
+```bash
+npm install @stripchatdev/ext-helper
+```
+
+## Quick Start
+
+Call `createExtHelper()` once at the entry point of each page:
+
+```ts
+import {createExtHelper} from '@stripchatdev/ext-helper';
+
+const ext = createExtHelper();
+```
+
+### Make requests
+
+```ts
+const ctx = await ext.makeRequest('v1.ext.context.get', null);
+```
+
+### Subscribe to events
+
+```ts
+ext.subscribe('v1.ext.context.updated', ({context}) => {
+  // handle context update
+});
+```
+
+### Send a whisper to other slots
+
+```ts
+await ext.makeRequest('v1.ext.whisper.local', {
+  data: {type: 'READY'},
+});
+```
+
+### Call a backend action
+
+```ts
+const result = await ext.makeRequest('v1.ext.actions.call', {
+  actionName: 'stopDevice',
+  params: {deviceId: 'dev_456', token: 'tok_abc'},
+});
+```
+
+## TypeScript
+
+Full type definitions are included. You get autocompletion and type safety for all methods and events out of the box.
+
+## Documentation
+
+For the full guide — manifest setup, slots, resolver scripts, settings, communication, and more — see
+the [Extension Platform Documentation](https://extensions.stripchat.com/docs/).
+
+## Browser Support
+
+- Chrome 91+
+- Firefox 90+
+- Safari 15+
+- Edge 91+

package/dist/ext-helper.js

@@ -0,0 +1,315 @@
+const M = (r) => !!r && typeof r == "object" && "protocol" in r && r.protocol === "iframe_pubsub" && "version" in r && r.version === "1.0", E = (r, e) => r, g = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var u;
+(function(r) {
+  r.Base32IncorrectEncoding = "B32_ENC_INVALID", r.DecodeTimeInvalidCharacter = "DEC_TIME_CHAR", r.DecodeTimeValueMalformed = "DEC_TIME_MALFORMED", r.EncodeTimeNegative = "ENC_TIME_NEG", r.EncodeTimeSizeExceeded = "ENC_TIME_SIZE_EXCEED", r.EncodeTimeValueMalformed = "ENC_TIME_MALFORMED", r.PRNGDetectFailure = "PRNG_DETECT", r.ULIDInvalid = "ULID_INVALID", r.Unexpected = "UNEXPECTED", r.UUIDInvalid = "UUID_INVALID";
+})(u || (u = {}));
+class l extends Error {
+  constructor(e, t) {
+    super(`${t} (${e})`), this.name = "ULIDError", this.code = e;
+  }
+}
+function R(r) {
+  const e = Math.floor(r() * 32) % 32;
+  return g.charAt(e);
+}
+function m(r) {
+  const e = N(), t = e && (e.crypto || e.msCrypto) || null;
+  if (typeof (t == null ? void 0 : t.getRandomValues) == "function")
+    return () => {
+      const s = new Uint8Array(1);
+      return t.getRandomValues(s), s[0] / 255;
+    };
+  if (typeof (t == null ? void 0 : t.randomBytes) == "function")
+    return () => t.randomBytes(1).readUInt8() / 255;
+  throw new l(u.PRNGDetectFailure, "Failed to find a reliable PRNG");
+}
+function N() {
+  return v() ? self : typeof window < "u" ? window : typeof global < "u" ? global : typeof globalThis < "u" ? globalThis : null;
+}
+function y(r, e) {
+  let t = "";
+  for (; r > 0; r--)
+    t = R(e) + t;
+  return t;
+}
+function I(r, e = 10) {
+  if (isNaN(r))
+    throw new l(u.EncodeTimeValueMalformed, `Time must be a number: ${r}`);
+  if (r > 281474976710655)
+    throw new l(u.EncodeTimeSizeExceeded, `Cannot encode a time larger than ${281474976710655}: ${r}`);
+  if (r < 0)
+    throw new l(u.EncodeTimeNegative, `Time must be positive: ${r}`);
+  if (Number.isInteger(r) === !1)
+    throw new l(u.EncodeTimeValueMalformed, `Time must be an integer: ${r}`);
+  let t, s = "";
+  for (let n = e; n > 0; n--)
+    t = r % 32, s = g.charAt(t) + s, r = (r - t) / 32;
+  return s;
+}
+function v() {
+  return typeof WorkerGlobalScope < "u" && self instanceof WorkerGlobalScope;
+}
+function f(r, e) {
+  const t = m(), s = Date.now();
+  return I(s, 10) + y(16, t);
+}
+const T = ({ seq: r, uniqId: e }) => (t) => ({
+  ...{
+    protocol: "iframe_pubsub",
+    version: "1.0",
+    id: e(),
+    seq: r(),
+    timestamp: Date.now()
+  },
+  ...t
+}), b = T({
+  uniqId: () => f(),
+  seq: () => f()
+});
+class _ {
+  constructor(e) {
+    this.eventHandlerMap = /* @__PURE__ */ new Map(), this.globalMessageHandler = (n, o) => {
+      if (M(n)) {
+        if (n.type === "event") {
+          const { eventName: c } = n, i = this.eventHandlerMap.get(c);
+          if (!i)
+            return;
+          i.forEach((a) => {
+            try {
+              a(n.data, o.id);
+            } catch (d) {
+              console.error("[PubSubSubscriber] globalMessageHandler: failed to handle income message", d);
+            }
+          });
+          return;
+        }
+        console.error("[PubSubSubscriber] globalMessageHandler: unhandled message", n);
+      }
+    };
+    const { brokerId: t, transport: s } = e;
+    this.brokerId = t, this.transport = s, this.transport.onMessage(this.globalMessageHandler);
+  }
+  subscribe(e, t) {
+    const s = E(e);
+    let n = this.eventHandlerMap.get(s);
+    n || (n = /* @__PURE__ */ new Set(), this.eventHandlerMap.set(s, n)), n.add(t);
+    const o = b({
+      type: "subscribe",
+      eventName: e
+    });
+    this.transport.send(this.brokerId, o);
+  }
+  unsubscribe(e, t) {
+    const s = E(e);
+    let n = this.eventHandlerMap.get(s);
+    if (!n)
+      return;
+    t ? n.delete(t) : this.eventHandlerMap.delete(s);
+    const o = b({
+      type: "unsubscribe",
+      eventName: e
+    });
+    this.transport.send(this.brokerId, o);
+  }
+}
+const w = !!Error.captureStackTrace, P = "APP_ERROR";
+class p extends Error {
+  constructor(e, t) {
+    super(e), this.name = new.target.name || P, this.cause = t, w && Error.captureStackTrace(this, this.constructor);
+  }
+  static getChainedMessage(e) {
+    let { message: t } = e;
+    return e instanceof p && e.cause && (t += `
+Caused by: ${p.getChainedMessage(e.cause)}`), t;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      cause: this.cause ? p.getChainedMessage(this.cause) : void 0
+    };
+  }
+}
+const O = {
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+}, C = "RPC_ERROR";
+class D extends p {
+  constructor(e) {
+    super(e.message || "unknown rpc error"), this.name = C, this.code = (e == null ? void 0 : e.code) || O.INTERNAL_ERROR;
+  }
+}
+const A = (r) => !!r && typeof r == "object" && "protocol" in r && r.protocol === "iframe_rpc" && "version" in r && r.version === "1.0", S = ({ uniqId: r }) => (e) => ({
+  ...{
+    protocol: "iframe_rpc",
+    version: "1.0",
+    id: r(),
+    timestamp: Date.now()
+  },
+  ...e
+}), H = S({
+  uniqId: () => f()
+});
+class k {
+  constructor(e) {
+    this.pendingEntryMap = /* @__PURE__ */ new Map(), this.globalMessageHandler = (n) => {
+      if (A(n)) {
+        if (n.type === "response" && n.status === "ok") {
+          const o = n.id, c = this.pendingEntryMap.get(o);
+          if (!c) {
+            console.error("[RpcClient] globalMessageHandler: got success response without pending request", n);
+            return;
+          }
+          this.pendingEntryMap.delete(o), c.resolve(n.result);
+          return;
+        }
+        if (n.type === "response" && n.status === "error") {
+          const o = n.id, c = this.pendingEntryMap.get(o);
+          if (!c) {
+            console.error("[RpcClient] globalMessageHandler: got error response without pending request", n);
+            return;
+          }
+          this.pendingEntryMap.delete(o), c.reject(new D(n.error));
+          return;
+        }
+        console.error("[RpcClient] globalMessageHandler: invalid message schema", n);
+      }
+    };
+    const { serverId: t, transport: s } = e;
+    this.serverId = t, this.transport = s, this.transport.onMessage(this.globalMessageHandler);
+  }
+  makeRequest(e, t) {
+    const s = H({
+      type: "request",
+      method: e,
+      params: t
+    }), n = new Promise((o, c) => {
+      this.pendingEntryMap.set(s.id, {
+        method: e,
+        resolve: (i) => {
+          o(i);
+        },
+        reject: (i) => {
+          c(i);
+        }
+      });
+    });
+    try {
+      this.transport.send(this.serverId, s);
+    } catch (o) {
+      console.error("[RpcClient] makeRequest: failed to send rpc message", o);
+      const c = this.pendingEntryMap.get(s.id);
+      c && (this.pendingEntryMap.delete(s.id), c.reject(o));
+    }
+    return n;
+  }
+}
+class L {
+  constructor(e) {
+    this.peers = /* @__PURE__ */ new Map(), this.onMessage = (s) => {
+      const n = (o) => {
+        const { data: c, origin: i, source: a } = o;
+        if (!a) {
+          console.error("[PostMessageTransport] onMessage: source could not be empty");
+          return;
+        }
+        const d = this.findPeer(a, i);
+        if (d)
+          try {
+            s(c, d);
+          } catch (h) {
+            console.error("[PostMessageTransport] onMessage: failed to call cb on message", h);
+          }
+      };
+      return this.localWindow.addEventListener("message", n), () => {
+        this.localWindow.removeEventListener("message", n);
+      };
+    };
+    const { localWindow: t } = e;
+    this.localWindow = t || window;
+  }
+  send(e, t) {
+    const s = this.peers.get(e);
+    s && s.source.postMessage(t, s.origin);
+  }
+  broadcast(e) {
+    this.peers.forEach((t) => {
+      t.source.postMessage(e, t.origin);
+    });
+  }
+  broadcastGroup(e, t) {
+    e.forEach((s) => {
+      this.send(s, t);
+    });
+  }
+  addPeer(e) {
+    this.peers.set(e.id, e);
+  }
+  removePeer(e) {
+    this.peers.delete(e);
+  }
+  findPeer(e, t) {
+    for (const [s, n] of this.peers)
+      if (n.source === e && n.origin === t)
+        return n;
+    return null;
+  }
+}
+class G {
+  constructor(e) {
+    const {
+      serverId: t,
+      serverOrigin: s,
+      serverSource: n,
+      theme: o
+    } = e, c = {
+      id: t,
+      origin: s,
+      source: n
+    }, i = new L({});
+    i.addPeer(c), this.rpcClient = new k({
+      transport: i,
+      serverId: t
+    }), this.subscriber = new _({
+      transport: i,
+      brokerId: c.id
+    }), document.documentElement.dataset.theme = o;
+  }
+  makeRequest(e, t) {
+    return this.rpcClient.makeRequest(e, t);
+  }
+  subscribe(e, t) {
+    return this.subscriber.subscribe(e, t);
+  }
+  unsubscribe(e, t) {
+    return this.subscriber.unsubscribe(e, t);
+  }
+  bootstrap() {
+    let e = { height: 0, width: 0 };
+    const t = document.documentElement, s = (i, a) => {
+      (e.height !== a || e.width !== i) && (e = { height: a, width: i }, this.makeRequest("v1.system.resize.notify", { height: a, width: i }));
+    }, n = (i) => {
+      for (const a of i) {
+        if (a.target !== t)
+          continue;
+        const { height: d, width: h } = a.contentRect;
+        s(h, d);
+      }
+    };
+    (() => {
+      const { height: i, width: a } = t.getBoundingClientRect();
+      s(a, i);
+    })(), new ResizeObserver(n).observe(document.documentElement);
+  }
+}
+const q = () => {
+  const r = new URL(window.location.href), e = r.searchParams.get("origin") || "", t = r.searchParams.get("theme") || "dark", s = new G({
+    serverId: "server",
+    serverOrigin: e || window.parent.origin,
+    serverSource: window.parent,
+    theme: t
+  });
+  return s.bootstrap(), s;
+};
+export {
+  q as createExtHelper
+};

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+export declare const createExtHelper: () => ExtHelper;
+
+declare class ExtHelper {
+    private rpcClient;
+    private subscriber;
+    constructor(props: TExtHelperProps);
+    makeRequest<M extends Extract<keyof TApiContract['methods'], string>>(method: M, params: TApiContract['methods'][M]['params']): Promise<TV1Methods[M]["result"]>;
+    subscribe<E extends Extract<keyof TApiContract['events'], string>>(eventName: E, handler: TAnyPubSubHandler<TApiContract['events'][E]>): void;
+    unsubscribe<E extends Extract<keyof TApiContract['events'], string>>(eventName: E, handler?: TAnyPubSubHandler<TApiContract['events'][E]>): void;
+    bootstrap(): void;
+}
+
+export declare type IV1ResolveSlotPage = (slotType: string, context: TV1ExtContext, extSettings: TV1ExtSettings) => void;
+
+export declare type TAnyApiEventData<D = unknown> = D;
+
+export declare type TAnyApiEventName = string;
+
+export declare type TAnyApiMethodMeta<P = unknown, R = unknown> = {
+    params: P;
+    result: R;
+};
+
+export declare type TAnyApiMethodName = string;
+
+export declare type TAnyApiSchema<Events extends Record<TAnyApiEventName, TAnyApiEventData> = Record<TAnyApiEventName, TAnyApiEventData>, Methods extends Record<TAnyApiMethodName, TAnyApiMethodMeta> = Record<TAnyApiMethodName, TAnyApiMethodMeta>> = {
+    events: Events;
+    methods: Methods;
+};
+
+declare type TAnyPubSubHandler<D = unknown> = (data: D, peerId: TTransportPeer['id']) => void;
+
+export declare type TApiContract = TApiSchema;
+
+export declare type TApiSchema = TAnyApiSchema<TEvents, TMethods>;
+
+export declare type TEvents = TV1Events;
+
+/** UUID */
+export declare type TExtensionId = string;
+
+declare type TExtHelperProps = {
+    serverId: string;
+    serverOrigin: string;
+    serverSource: Window;
+    theme: TTheme;
+};
+
+export declare type TExtPageResolverMethods = {
+    'page.resolve': {
+        params: {
+            context: unknown;
+            extSettings: unknown;
+            resolvePageScriptUrl: string;
+            slotType: string;
+        };
+        result: {
+            pageName: string | null;
+        };
+    };
+};
+
+export declare type TMethods = TV1Methods;
+
+export declare type TModelId = TUserId;
+
+export declare type TTheme = 'light' | 'dark';
+
+declare type TTransportPeer = {
+    id: string;
+};
+
+declare type TUnknownDictionary = Record<string, unknown>;
+
+export declare type TUserId = number;
+
+export declare type TV1ActionParamValue = string | number | boolean | null | undefined | TV1ActionParamValue[] | {
+    [key: string]: TV1ActionParamValue;
+};
+
+export declare type TV1ActionRequestParams = {
+    actionName: string;
+    params: Record<string, TV1ActionParamValue>;
+};
+
+export declare type TV1ActionResult = {
+    body: unknown;
+    code: number;
+};
+
+export declare type TV1AvailableGenders = 'male' | 'female' | 'tranny' | 'maleFemale' | 'males' | 'females' | 'trannies' | 'maleTranny' | 'femaleTranny';
+
+declare type TV1ChatMethods = {
+    'v1.chat.message.send': {
+        params: {
+            isAnonymous: boolean;
+            message: string;
+            user: TV1ExtUser | null;
+        };
+        result: null;
+    };
+};
+
+export declare type TV1Events = TV1ExtEvents & TV1PaymentEvents & TV1ModelEvents;
+
+export declare type TV1ExtContext = {
+    model?: TV1ExtModel;
+    user?: TV1ExtUser;
+};
+
+declare type TV1ExtEvents = {
+    'v1.ext.context.updated': {
+        context: TV1ExtContext;
+    };
+    'v1.ext.whispered': TV1WhisperData;
+};
+
+declare type TV1ExtMethods = {
+    'v1.ext.actions.call': {
+        params: TV1ActionRequestParams;
+        result: TV1ActionResult;
+    };
+    'v1.ext.activity.request': {
+        params: {
+            durationMs: number;
+        };
+        result: {
+            isGranted: boolean;
+        };
+    };
+    'v1.ext.context.get': {
+        params: null;
+        result: TV1ExtContext;
+    };
+    'v1.ext.movableOverlay.update': {
+        params: {
+            message?: string;
+            status?: 'active' | 'inactive' | 'connecting' | 'error';
+        };
+        result: null;
+    };
+    'v1.ext.settings.get': {
+        params: null;
+        result: {
+            settings: TV1ExtSettings;
+        };
+    };
+    'v1.ext.signup.open': {
+        params: {
+            type: 'user';
+        };
+        result: null;
+    };
+    'v1.ext.whisper': {
+        params: {
+            data: TV1WhisperData;
+        };
+        result: null;
+    };
+    'v1.ext.whisper.local': {
+        params: {
+            data: TV1WhisperData;
+        };
+        result: null;
+    };
+};
+
+export declare type TV1ExtModel = {
+    avatarUrlThumb: string;
+    doP2p: boolean;
+    doPrivate: boolean;
+    doSpy: boolean;
+    gender: TV1AvailableGenders;
+    id: TUserId;
+    isNonNude: boolean;
+    name: string;
+    status: TV1ModelStatus;
+    username: string;
+};
+
+export declare type TV1ExtSettings = unknown;
+
+export declare type TV1ExtUser = {
+    id: TUserId;
+    isExGreen: boolean;
+    isGreen: boolean;
+    isModel: boolean;
+    isRegular: boolean;
+    isStudio: boolean;
+    isUltimate: boolean;
+    status: TV1UserStatus;
+    username: string;
+    userRanking?: {
+        isEx: boolean;
+        league: TV1UserLeague;
+        level: number;
+    } | null;
+};
+
+export declare type TV1Methods = TV1ExtMethods & TV1SystemMethods & TV1PaymentMethods & TV1ModelMethods & TV1ChatMethods & TV1PrivateMethods;
+
+declare type TV1ModelEvents = {
+    'v1.model.ext.settings.set.requested': null;
+};
+
+declare type TV1ModelMethods = {
+    'v1.model.ext.settings.get': {
+        params: null;
+        result: {
+            settings: TV1ExtSettings;
+        };
+    };
+    'v1.model.ext.settings.set': {
+        params: {
+            isError: boolean;
+            settings: TV1ExtSettings;
+        };
+        result: null;
+    };
+};
+
+export declare type TV1ModelStatus = (typeof V1_SHOW_STATUSES)[keyof typeof V1_SHOW_STATUSES];
+
+declare type TV1PaymentEvents = {
+    'v1.payment.tokens.spend.succeeded': {
+        isAnonymous: boolean;
+        tokensAmount: number;
+        tokensSpendData: TV1TokenSpendData;
+    };
+};
+
+declare type TV1PaymentMethods = {
+    'v1.payment.tokens.spend': {
+        params: {
+            tokensAmount: number;
+            tokensSpendData: TV1TokenSpendData;
+        };
+        result: null;
+    };
+};
+
+declare type TV1PrivateMethods = {
+    'v1.private.request': {
+        params: null;
+        result: null;
+    };
+};
+
+declare type TV1SystemMethods = {
+    'v1.system.resize.notify': {
+        params: {
+            height: number;
+            width: number;
+        };
+        result: null;
+    };
+};
+
+export declare type TV1TokenSpendData = TUnknownDictionary;
+
+declare type TV1UserLeague = 'grey' | 'bronze' | 'silver' | 'gold' | 'diamond' | 'royal' | 'legend';
+
+export declare type TV1UserStatus = (typeof V1_SHOW_STATUSES)[keyof typeof V1_SHOW_STATUSES];
+
+export declare type TV1WhisperData = TUnknownDictionary;
+
+export declare const V1_SHOW_STATUSES: {
+    readonly STATUS_TICKET_SHOW: "ticketShow";
+    readonly STATUS_GROUP_SHOW: "groupShow";
+    readonly STATUS_OFF: "off";
+    readonly STATUS_PRIVATE: "private";
+    readonly STATUS_EXCLUSIVE_PRIVATE: "exclusivePrivate";
+    readonly STATUS_PUBLIC: "public";
+    readonly STATUS_IDLE: "idle";
+};
+
+export { }

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@stripchatdev/ext-helper",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "module": "./dist/ext-helper.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build:code": "vite build",
+    "build:clean": "rm -rf ./dist ./dist-types",
+    "build:types": "tsc -b --force && api-extractor run --local",
+    "build:clean-artefacts": "rm -rf ./dist-types",
+    "build": "npm run build:clean && npm run build:code && npm run build:types && npm run build:clean-artefacts"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/ext-helper.js",
+      "default": "./dist/ext-helper.js"
+    }
+  },
+  "dependencies": {
+    "ulid": "*"
+  }
+}