@memberjunction/realtime-widget 0.0.0 → 5.45.1

package/dist/voice/voice-abuse-guard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Client-side voice abuse ceilings. Voice is the biggest cost/abuse
+ * surface on a PUBLIC endpoint (plan W4 §"Voice abuse controls"), so the widget caps
+ * each session locally as defense-in-depth — the authoritative limits are also
+ * enforced server-side (SessionJanitor TTL + model-cost ceiling). This guard is pure
+ * and unit-tested; the controller polls it and aborts when it trips.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Configurable ceilings for one voice session. */
+export interface VoiceAbuseLimits {
+    /** Hard cap on a single voice session's wall-clock duration (minutes). */
+    maxSessionMinutes: number;
+    /** Optional cap on total output tokens (a proxy for model spend) before aborting. */
+    maxOutputTokens?: number;
+}
+/** Why a voice session was aborted by the guard. */
+export type VoiceAbortReason = 'max-minutes' | 'max-cost';
+/** Default limits used when a widget instance doesn't specify its own. */
+export declare const DEFAULT_VOICE_LIMITS: VoiceAbuseLimits;
+/**
+ * Tracks elapsed time + accumulated usage for one voice session and decides when to
+ * abort. Stateful but trivially testable (inject `now`/usage; no timers inside).
+ */
+export declare class VoiceAbuseGuard {
+    private readonly limits;
+    private startedAtMs;
+    private outputTokens;
+    constructor(limits?: VoiceAbuseLimits);
+    /** Marks the session start. */
+    Start(nowMs: number): void;
+    /** Accumulates reported output-token usage. */
+    AddUsage(outputTokens: number | undefined): void;
+    /** Returns an abort reason if a ceiling has been crossed, else null. */
+    ShouldAbort(nowMs: number): VoiceAbortReason | null;
+    /** A user-facing message for an abort reason. */
+    static MessageFor(reason: VoiceAbortReason): string;
+}
+//# sourceMappingURL=voice-abuse-guard.d.ts.map

package/dist/voice/voice-abuse-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-abuse-guard.d.ts","sourceRoot":"","sources":["../../src/voice/voice-abuse-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC7B,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,EAAE,gBAGlC,CAAC;AAEF;;;GAGG;AACH,qBAAa,eAAe;IAIZ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,YAAY,CAAK;gBAEI,MAAM,GAAE,gBAAuC;IAE5E,+BAA+B;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,+CAA+C;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAMvD,wEAAwE;IACjE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAc1D,iDAAiD;WACnC,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CAK7D"}

package/dist/voice/voice-abuse-guard.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Client-side voice abuse ceilings. Voice is the biggest cost/abuse
+ * surface on a PUBLIC endpoint (plan W4 §"Voice abuse controls"), so the widget caps
+ * each session locally as defense-in-depth — the authoritative limits are also
+ * enforced server-side (SessionJanitor TTL + model-cost ceiling). This guard is pure
+ * and unit-tested; the controller polls it and aborts when it trips.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Default limits used when a widget instance doesn't specify its own. */
+export const DEFAULT_VOICE_LIMITS = {
+    maxSessionMinutes: 10,
+    maxOutputTokens: 50_000,
+};
+/**
+ * Tracks elapsed time + accumulated usage for one voice session and decides when to
+ * abort. Stateful but trivially testable (inject `now`/usage; no timers inside).
+ */
+export class VoiceAbuseGuard {
+    constructor(limits = DEFAULT_VOICE_LIMITS) {
+        this.limits = limits;
+        this.startedAtMs = null;
+        this.outputTokens = 0;
+    }
+    /** Marks the session start. */
+    Start(nowMs) {
+        this.startedAtMs = nowMs;
+        this.outputTokens = 0;
+    }
+    /** Accumulates reported output-token usage. */
+    AddUsage(outputTokens) {
+        if (outputTokens && outputTokens > 0) {
+            this.outputTokens += outputTokens;
+        }
+    }
+    /** Returns an abort reason if a ceiling has been crossed, else null. */
+    ShouldAbort(nowMs) {
+        if (this.startedAtMs === null) {
+            return null;
+        }
+        const elapsedMin = (nowMs - this.startedAtMs) / 60_000;
+        if (elapsedMin >= this.limits.maxSessionMinutes) {
+            return 'max-minutes';
+        }
+        if (this.limits.maxOutputTokens != null && this.outputTokens >= this.limits.maxOutputTokens) {
+            return 'max-cost';
+        }
+        return null;
+    }
+    /** A user-facing message for an abort reason. */
+    static MessageFor(reason) {
+        return reason === 'max-minutes'
+            ? 'Voice session time limit reached. Please start a new session or continue by text.'
+            : 'Voice session usage limit reached. Please continue by text.';
+    }
+}
+//# sourceMappingURL=voice-abuse-guard.js.map

package/dist/voice/voice-abuse-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-abuse-guard.js","sourceRoot":"","sources":["../../src/voice/voice-abuse-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAqB;IAClD,iBAAiB,EAAE,EAAE;IACrB,eAAe,EAAE,MAAM;CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,eAAe;IAIxB,YAA6B,SAA2B,oBAAoB;QAA/C,WAAM,GAAN,MAAM,CAAyC;QAHpE,gBAAW,GAAkB,IAAI,CAAC;QAClC,iBAAY,GAAG,CAAC,CAAC;IAEsD,CAAC;IAEhF,+BAA+B;IACxB,KAAK,CAAC,KAAa;QACtB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,+CAA+C;IACxC,QAAQ,CAAC,YAAgC;QAC5C,IAAI,YAAY,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC;QACtC,CAAC;IACL,CAAC;IAED,wEAAwE;IACjE,WAAW,CAAC,KAAa;QAC5B,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,UAAU,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;QACvD,IAAI,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC9C,OAAO,aAAa,CAAC;QACzB,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,IAAI,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YAC1F,OAAO,UAAU,CAAC;QACtB,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,iDAAiD;IAC1C,MAAM,CAAC,UAAU,CAAC,MAAwB;QAC7C,OAAO,MAAM,KAAK,aAAa;YAC3B,CAAC,CAAC,mFAAmF;YACrF,CAAC,CAAC,6DAA6D,CAAC;IACxE,CAAC;CACJ"}

package/dist/voice/voice-controller.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview The voice seam. The UI element depends only on this interface, so the
+ * voice affordance is unit-testable with a mock and decoupled from the realtime client
+ * + mint wiring. The real implementation (`RealtimeVoiceController`) reuses
+ * `@memberjunction/ai-realtime-client` (client-direct topology) — no new driver.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+/** Coarse voice UI state surfaced to the widget. */
+export type WidgetVoiceState = 'idle' | 'connecting' | 'listening' | 'speaking' | 'ended' | 'error';
+/** A transcript line delivered to the widget while voice is active. */
+export interface WidgetVoiceTranscript {
+    role: 'user' | 'agent';
+    text: string;
+    isFinal: boolean;
+}
+/** Callbacks the widget supplies when starting voice. */
+export interface VoiceControllerCallbacks {
+    onState: (state: WidgetVoiceState) => void;
+    onTranscript: (transcript: WidgetVoiceTranscript) => void;
+    /** Called when the session ends (incl. an abuse-ceiling abort), with an optional reason. */
+    onEnded: (reason?: string) => void;
+    /**
+     * Reveals (and returns) the demonstration-surface host element for an interactive channel the agent
+     * just engaged, so the channel can render into it inside the widget's shadow DOM. Called the first
+     * time a channel's tool fires. Omitted when the widget exposes no channel surface.
+     */
+    getChannelSurface?: (channelName: string, title: string) => HTMLElement;
+}
+/** Starts/stops a client-direct voice session with the pinned agent. */
+export interface IVoiceController {
+    /** Begins a voice session (mints, connects, acquires mic, enforces ceilings). */
+    Start(callbacks: VoiceControllerCallbacks): Promise<void>;
+    /** Ends the active voice session. */
+    Stop(): Promise<void>;
+    /** Whether a voice session is currently active. */
+    readonly IsActive: boolean;
+}
+//# sourceMappingURL=voice-controller.d.ts.map

package/dist/voice/voice-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-controller.d.ts","sourceRoot":"","sources":["../../src/voice/voice-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpG,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3C,YAAY,EAAE,CAAC,UAAU,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC1D,4FAA4F;IAC5F,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;CAC3E;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC7B,iFAAiF;IACjF,KAAK,CAAC,SAAS,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,qCAAqC;IACrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC9B"}

package/dist/voice/voice-controller.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview The voice seam. The UI element depends only on this interface, so the
+ * voice affordance is unit-testable with a mock and decoupled from the realtime client
+ * + mint wiring. The real implementation (`RealtimeVoiceController`) reuses
+ * `@memberjunction/ai-realtime-client` (client-direct topology) — no new driver.
+ *
+ * @module @memberjunction/realtime-widget
+ */
+export {};
+//# sourceMappingURL=voice-controller.js.map

package/dist/voice/voice-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-controller.js","sourceRoot":"","sources":["../../src/voice/voice-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -1,10 +1,39 @@
 {
   "name": "@memberjunction/realtime-widget",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @memberjunction/realtime-widget",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.45.1",
+  "description": "MemberJunction: Droppable, embeddable public customer-support widget (text + voice). A shadow-DOM web component that reuses ConversationsRuntime + the realtime client stack against MJAPI with a guest session JWT. No MJ login required.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "bundle": "esbuild dist/embed.js --bundle --splitting --format=esm --platform=browser --outdir=dist/embed --entry-names=mj-widget --chunk-names=chunks/[name]-[hash]",
+    "bundle:min": "esbuild dist/embed.js --bundle --splitting --minify --format=esm --platform=browser --outdir=dist/embed-min --entry-names=mj-widget --chunk-names=chunks/[name]-[hash]",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/global": "5.45.1",
+    "@memberjunction/core": "5.45.1",
+    "@memberjunction/core-entities": "5.45.1",
+    "@memberjunction/conversations-runtime": "5.45.1",
+    "@memberjunction/graphql-dataprovider": "5.45.1",
+    "@memberjunction/ai": "5.45.1",
+    "@memberjunction/ai-realtime-client": "5.45.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.11",
+    "esbuild": "^0.26.0",
+    "jsdom": "^24.0.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }