@dartsee/plugin-sdk 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @dartsee/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK for **Dartsee Game Controller plugins**. A plugin is your own website, opened by the Game Controller on
+the lane tablet in a sandboxed iframe. This package is the only channel to the host.
+
+```ts
+import { connect, DartseeError } from '@dartsee/plugin-sdk'
+
+const dartsee = await connect()
+const session = await dartsee.session.get()
+const off = dartsee.on('gameEnd', (game) => { /* ... */ })
+```
+
+## Your page runs with an opaque origin
+
+The iframe is `sandbox="allow-scripts allow-forms"`, without `allow-same-origin`. That means:
+
+- **Your own assets and API are cross-origin to your page.** Serve scripts, fonts and API responses with
+  `Access-Control-Allow-Origin: *` (or `null`); accept `Origin: null` on your API. A default Vite build
+  (`<script type="module" crossorigin>`) won't load without it.
+- **No device storage.** `localStorage`, `sessionStorage`, IndexedDB, cookies throw `SecurityError`; libraries
+  that touch them at startup will crash. Authenticate your backend with the bearer token from
+  `auth.getToken()`.
+- **No popups, no top-level navigation**, so no OAuth redirect/popup login.
+- Allow framing: `Content-Security-Policy: frame-ancestors http://127.0.0.1:8080 https://*.dartsee.com`,
+  and no `X-Frame-Options`.
+- Target **Chromium 116**, touch only.
+
+## Errors
+
+Every call rejects with `DartseeError`, `code` one of `TIMEOUT`, `PERMISSION_DENIED`, `UNSUPPORTED`
+(older host — check `dartsee.context.capabilities`), `OFFLINE`, `INVALID_ARGS`, `HOST_ERROR`.

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { Context, EventMap, EventName, GameInfo, SessionInfo } from './protocol';
+export interface CallOptions {
+    /** ms */
+    timeout?: number;
+}
+export interface Dartsee {
+    readonly context: Context;
+    session: {
+        get(opts?: CallOptions): Promise<SessionInfo>;
+    };
+    game: {
+        get(opts?: CallOptions): Promise<GameInfo>;
+    };
+    auth: {
+        getToken(opts?: CallOptions): Promise<string>;
+    };
+    on<E extends EventName>(event: E, fn: (payload: EventMap[E]) => void): () => void;
+}
+export declare function connect({ timeout }?: CallOptions): Promise<Dartsee>;

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export type ErrorCode = 'TIMEOUT' | 'PERMISSION_DENIED' | 'UNSUPPORTED' | 'OFFLINE' | 'INVALID_ARGS' | 'HOST_ERROR';
+export declare class DartseeError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { connect } from './client';
+export type { CallOptions, Dartsee } from './client';
+export { DartseeError } from './errors';
+export type { ErrorCode } from './errors';
+export { validateManifest, SIZES } from './manifest';
+export type { ConfigField, Manifest, Size } from './manifest';
+export * from './protocol';

package/dist/manifest.d.ts

@@ -0,0 +1,29 @@
+export type Size = 'dialog' | 'side' | 'full';
+export declare const SIZES: readonly Size[];
+export interface ConfigField {
+    key: string;
+    label: string;
+    secret?: boolean;
+}
+export interface Manifest {
+    id: string;
+    name: string;
+    description: string;
+    icon: string;
+    label: {
+        en: string;
+    } & Record<string, string>;
+    entryUrl: string;
+    scopes: string[];
+    /** iframe `allow=` features */
+    allow?: string[];
+    size: Size;
+    config?: ConfigField[];
+    /** runs from session start, hidden while the overlay is closed */
+    background?: boolean;
+    /** link-code ownership check at opt-in */
+    verifyUrl?: string;
+    support: string;
+    privacyUrl: string;
+}
+export declare function validateManifest(input: unknown): Manifest;

package/dist/plugin-sdk.es.js

@@ -0,0 +1,118 @@
+class g extends Error {
+  constructor(e, i) {
+    super(i), this.code = e, this.name = "DartseeError";
+  }
+}
+const N = "CONNECT", b = "READY", A = "EVENT", m = {
+  SESSION_GET: "SESSION_GET",
+  GAME_GET: "GAME_GET",
+  AUTH_GET_TOKEN: "AUTH_GET_TOKEN"
+}, M = Object.values(m), $ = (r, e) => `${r}_RESPONSE_${e}`, k = (r, e) => `${r}_ERROR_${e}`, _ = 1e4, G = 3e4;
+function I({ timeout: r = _ } = {}) {
+  const e = window.parent;
+  if (e === window)
+    return Promise.reject(new g("HOST_ERROR", "Not inside the Dartsee host (no parent frame)"));
+  const i = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map();
+  let E = 0;
+  const o = (n, d, s = {}) => {
+    if (!d.capabilities.includes(n))
+      return Promise.reject(new g("UNSUPPORTED", `Host ${d.hostVersion} does not support ${n}`));
+    const u = s.timeout ?? _, c = String(++E), p = $(n, c), a = k(n, c);
+    return new Promise((T, y) => {
+      const f = () => {
+        clearTimeout(h), i.delete(p), i.delete(a);
+      }, h = setTimeout(() => {
+        f(), y(new g("TIMEOUT", `${n} timed out after ${u} ms`));
+      }, u);
+      i.set(p, (R) => {
+        f(), T(R.data);
+      }), i.set(a, (R) => {
+        f();
+        const S = R.data;
+        y(new g(S?.code ?? "HOST_ERROR", S?.message ?? `${n} failed`));
+      }), e.postMessage({ id: n, nonce: c }, "*");
+    });
+  }, v = (n) => {
+    let d;
+    return {
+      context: n,
+      session: { get: (s) => o(m.SESSION_GET, n, s) },
+      game: { get: (s) => o(m.GAME_GET, n, s) },
+      auth: {
+        async getToken(s) {
+          return (!d || d.expiresAt - Date.now() < G) && (d = await o(m.AUTH_GET_TOKEN, n, s)), d.token;
+        }
+      },
+      on(s, u) {
+        const c = t.get(s) ?? /* @__PURE__ */ new Set();
+        return t.set(s, c), c.add(u), () => c.delete(u);
+      }
+    };
+  };
+  return new Promise((n, d) => {
+    let s = !1;
+    const u = setTimeout(() => {
+      window.removeEventListener("message", c), d(new g("TIMEOUT", `Host did not answer within ${r} ms`));
+    }, r);
+    function c(p) {
+      if (p.source !== e)
+        return;
+      const a = p.data;
+      if (!(!a || typeof a.id != "string")) {
+        if (!s) {
+          if (a.id !== b)
+            return;
+          s = !0, clearTimeout(u), n(v(a.data));
+          return;
+        }
+        if (a.id === A) {
+          const { name: T, payload: y } = a.data ?? {};
+          t.get(T)?.forEach((f) => {
+            try {
+              f(y);
+            } catch (h) {
+              console.error(`[dartsee] ${T} listener threw`, h);
+            }
+          });
+          return;
+        }
+        i.get(a.id)?.(a);
+      }
+    }
+    window.addEventListener("message", c), e.postMessage({ id: N }, "*");
+  });
+}
+const O = ["dialog", "side", "full"], l = (r) => typeof r == "string" && r.trim() !== "", w = (r) => {
+  try {
+    return l(r) && new URL(r).protocol === "https:";
+  } catch {
+    return !1;
+  }
+}, U = (r) => Array.isArray(r) && r.every(l);
+function D(r) {
+  const e = r ?? {}, i = [], t = (E, o) => E || i.push(o);
+  if (t(l(e.id) && /^[a-z0-9][a-z0-9-]*$/.test(e.id), "id: lowercase letters, digits and dashes"), t(l(e.name), "name: required"), t(l(e.description), "description: required"), t(w(e.icon), "icon: https URL"), t(l(e.label?.en), "label.en: required"), t(e.label == null || Object.values(e.label).every(l), "label: every value a non-empty string"), t(w(e.entryUrl), "entryUrl: https URL"), t(U(e.scopes), "scopes: array of strings"), t(e.allow === void 0 || U(e.allow), "allow: array of strings"), t(O.includes(e.size), `size: one of ${O.join(", ")}`), t(e.background === void 0 || typeof e.background == "boolean", "background: boolean"), t(e.verifyUrl === void 0 || w(e.verifyUrl), "verifyUrl: https URL"), t(l(e.support), "support: required"), t(w(e.privacyUrl), "privacyUrl: https URL"), e.config !== void 0) {
+    const E = Array.isArray(e.config) && e.config.every(
+      (o) => l(o?.key) && l(o?.label) && (o.secret === void 0 || typeof o.secret == "boolean")
+    );
+    t(E, "config: array of { key, label, secret? }"), t(E && new Set(e.config.map((o) => o.key)).size === e.config.length, "config: duplicate key");
+  }
+  if (i.length)
+    throw new Error(`Invalid manifest:
+- ${i.join(`
+- `)}`);
+  return e;
+}
+export {
+  N as CONNECT,
+  g as DartseeError,
+  A as EVENT,
+  b as READY,
+  m as RPC,
+  M as RPC_IDS,
+  O as SIZES,
+  I as connect,
+  k as errorId,
+  $ as responseId,
+  D as validateManifest
+};

package/dist/plugin-sdk.iife.js

@@ -0,0 +1,3 @@
+var DartseeSDK=function(s){"use strict";class f extends Error{constructor(e,a){super(a),this.code=e,this.name="DartseeError"}}const _="CONNECT",v="READY",U="EVENT",g={SESSION_GET:"SESSION_GET",GAME_GET:"GAME_GET",AUTH_GET_TOKEN:"AUTH_GET_TOKEN"},D=Object.values(g),N=(r,e)=>`${r}_RESPONSE_${e}`,b=(r,e)=>`${r}_ERROR_${e}`,A=1e4,$=3e4;function k({timeout:r=A}={}){const e=window.parent;if(e===window)return Promise.reject(new f("HOST_ERROR","Not inside the Dartsee host (no parent frame)"));const a=new Map,t=new Map;let T=0;const i=(n,E,o={})=>{if(!E.capabilities.includes(n))return Promise.reject(new f("UNSUPPORTED",`Host ${E.hostVersion} does not support ${n}`));const u=o.timeout??A,d=String(++T),y=N(n,d),c=b(n,d);return new Promise((p,S)=>{const w=()=>{clearTimeout(h),a.delete(y),a.delete(c)},h=setTimeout(()=>{w(),S(new f("TIMEOUT",`${n} timed out after ${u} ms`))},u);a.set(y,O=>{w(),p(O.data)}),a.set(c,O=>{w();const M=O.data;S(new f(M?.code??"HOST_ERROR",M?.message??`${n} failed`))}),e.postMessage({id:n,nonce:d},"*")})},P=n=>{let E;return{context:n,session:{get:o=>i(g.SESSION_GET,n,o)},game:{get:o=>i(g.GAME_GET,n,o)},auth:{async getToken(o){return(!E||E.expiresAt-Date.now()<$)&&(E=await i(g.AUTH_GET_TOKEN,n,o)),E.token}},on(o,u){const d=t.get(o)??new Set;return t.set(o,d),d.add(u),()=>d.delete(u)}}};return new Promise((n,E)=>{let o=!1;const u=setTimeout(()=>{window.removeEventListener("message",d),E(new f("TIMEOUT",`Host did not answer within ${r} ms`))},r);function d(y){if(y.source!==e)return;const c=y.data;if(!(!c||typeof c.id!="string")){if(!o){if(c.id!==v)return;o=!0,clearTimeout(u),n(P(c.data));return}if(c.id===U){const{name:p,payload:S}=c.data??{};t.get(p)?.forEach(w=>{try{w(S)}catch(h){console.error(`[dartsee] ${p} listener threw`,h)}});return}a.get(c.id)?.(c)}}window.addEventListener("message",d),e.postMessage({id:_},"*")})}const R=["dialog","side","full"],l=r=>typeof r=="string"&&r.trim()!=="",m=r=>{try{return l(r)&&new URL(r).protocol==="https:"}catch{return!1}},I=r=>Array.isArray(r)&&r.every(l);function G(r){const e=r??{},a=[],t=(T,i)=>T||a.push(i);if(t(l(e.id)&&/^[a-z0-9][a-z0-9-]*$/.test(e.id),"id: lowercase letters, digits and dashes"),t(l(e.name),"name: required"),t(l(e.description),"description: required"),t(m(e.icon),"icon: https URL"),t(l(e.label?.en),"label.en: required"),t(e.label==null||Object.values(e.label).every(l),"label: every value a non-empty string"),t(m(e.entryUrl),"entryUrl: https URL"),t(I(e.scopes),"scopes: array of strings"),t(e.allow===void 0||I(e.allow),"allow: array of strings"),t(R.includes(e.size),`size: one of ${R.join(", ")}`),t(e.background===void 0||typeof e.background=="boolean","background: boolean"),t(e.verifyUrl===void 0||m(e.verifyUrl),"verifyUrl: https URL"),t(l(e.support),"support: required"),t(m(e.privacyUrl),"privacyUrl: https URL"),e.config!==void 0){const T=Array.isArray(e.config)&&e.config.every(i=>l(i?.key)&&l(i?.label)&&(i.secret===void 0||typeof i.secret=="boolean"));t(T,"config: array of { key, label, secret? }"),t(T&&new Set(e.config.map(i=>i.key)).size===e.config.length,"config: duplicate key")}if(a.length)throw new Error(`Invalid manifest:
+- ${a.join(`
+- `)}`);return e}return s.CONNECT=_,s.DartseeError=f,s.EVENT=U,s.READY=v,s.RPC=g,s.RPC_IDS=D,s.SIZES=R,s.connect=k,s.errorId=b,s.responseId=N,s.validateManifest=G,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"}),s}({});

package/dist/protocol.d.ts

@@ -0,0 +1,61 @@
+import type { ErrorCode } from './errors';
+import type { Size } from './manifest';
+export interface Message<T = unknown> {
+    id: string;
+    data?: T;
+    nonce?: string;
+}
+export declare const CONNECT = "CONNECT";
+export declare const READY = "READY";
+export declare const EVENT = "EVENT";
+export declare const RPC: {
+    readonly SESSION_GET: "SESSION_GET";
+    readonly GAME_GET: "GAME_GET";
+    readonly AUTH_GET_TOKEN: "AUTH_GET_TOKEN";
+};
+export type RpcId = (typeof RPC)[keyof typeof RPC];
+export declare const RPC_IDS: readonly RpcId[];
+export declare const responseId: (id: string, nonce: string) => string;
+export declare const errorId: (id: string, nonce: string) => string;
+export interface ErrorPayload {
+    code: ErrorCode;
+    message: string;
+}
+export interface Context {
+    pluginId: string;
+    venueId: string;
+    machineId: string;
+    language: string;
+    size: Size;
+    scopes: string[];
+    hostVersion: string;
+    capabilities: string[];
+}
+export interface SessionInfo {
+    active: boolean;
+    controlMode: string;
+    endsAt?: number;
+    playerCount: number;
+}
+export interface GameInfo {
+    status: 'no_game' | 'in_game' | 'finished';
+    gameType?: string;
+}
+export interface TokenInfo {
+    token: string;
+    expiresAt: number;
+}
+export interface EventMap {
+    gameStart: GameInfo;
+    gameEnd: GameInfo;
+    sessionStart: SessionInfo;
+    sessionEnd: SessionInfo;
+    languageChange: {
+        language: string;
+    };
+}
+export type EventName = keyof EventMap;
+export interface EventMessage<E extends EventName = EventName> {
+    name: E;
+    payload: EventMap[E];
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@dartsee/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3",
+  "description": "SDK for Dartsee Game Controller plugins",
+  "license": "MIT",
+  "homepage": "https://apidocs.dartsee.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/dartsee/games-monorepo.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "type": "module",
+  "main": "./dist/plugin-sdk.es.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/plugin-sdk.iife.js",
+  "jsdelivr": "./dist/plugin-sdk.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/plugin-sdk.es.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "coverage": "vitest run"
+  },
+  "publishConfig": {
+    "@dartsee:registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "devDependencies": {
+    "vite-plugin-dts": "^2.3.0"
+  }
+}