@animated-waffle/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narya.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# `@animated-waffle/client`
+
+Framework-independent browser SDK for embedding a published Narya talking
+Agent: connection lifecycle, microphone input, text input, state, and
+transcripts. React applications should use
+[`@animated-waffle/react`](../waffle-react), which re-exports this entire API
+and adds the Avatar renderer.
+
+The Agent owns its avatar, voice, and prompt. Pipecat, Daily, API routes, and
+avatar asset URLs are SDK implementation details. Production is the default
+API origin; tests and non-production integrations may pass `apiOrigin`.
+
+## Connect
+
+Keep the permanent workspace API key on your server. Exchange it for a
+short-lived Agent session token and give the browser a callback that obtains
+one for each connection:
+
+```ts
+import { WaffleClient } from '@animated-waffle/client'
+
+const agentId = '22222222-2222-4222-8222-222222222222'
+const endUserId = '55555555-5555-4555-8555-555555555555'
+const waffle = new WaffleClient({
+  agentId,
+  sessionToken: async () => {
+    const response = await fetch('/api/narya-session-token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentId, endUserId }),
+    })
+    const body = await response.json()
+    return body.token
+  },
+})
+
+waffle.on('transcript', ({ role, text, final }) => {
+  if (final) console.log(role, text)
+})
+
+await waffle.connect({ inputMode: 'push-to-talk' })
+```
+
+`endUserId` is one stable bare UUID per end user. An anonymous application can
+generate it once with `crypto.randomUUID()` and persist it on that device.
+
+To target a non-production environment:
+
+```ts
+const waffle = new WaffleClient({
+  agentId,
+  sessionToken: () => getSessionToken(agentId),
+  apiOrigin: 'https://animated-waffle-dev.narya.ai',
+})
+```
+
+## API surface
+
+- `connect({ inputMode? })` — `'push-to-talk'` (default) or `'automatic'`.
+- `disconnect()`, `sendText(text)`.
+- `startPushToTalk()` / `stopPushToTalk()` / `cancelPushToTalk()`.
+- `on('status' | 'session' | 'transcript' | 'agentSpeaking' | 'error', fn)` —
+  returns the unsubscribe function.
+- `status`, `session` getters; failures throw `WaffleError` with `code`.
+
+`./internal` is a private contract consumed by `@animated-waffle/react`; it is
+not part of the public API and may change without notice.
+
+See the [SDK documentation](https://animated-waffle.narya.ai/docs/sdk) for the
+complete integration guide.

package/dist/chunk-BXRNROI7.js

@@ -0,0 +1 @@
+var o=new WeakMap;function s(n,t,a){let e=o.get(n)??new Map,r=e.get(t)??new Set;return r.add(a),e.set(t,r),o.set(n,e),()=>r.delete(a)}function i(n,t,a){o.get(n)?.get(t)?.forEach(e=>{e(a)})}export{s as a,i as b};

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+type WaffleStatus = 'disconnected' | 'connecting' | 'connected' | 'disconnecting';
+type WaffleInputMode = 'automatic' | 'push-to-talk';
+interface WaffleSession {
+    id: string;
+    agentId: string;
+    avatarId: string;
+    inputMode: WaffleInputMode;
+}
+interface WaffleTranscript {
+    role: 'user' | 'assistant';
+    text: string;
+    final: boolean;
+    timestamp?: string;
+}
+interface WaffleClientEvents {
+    status: WaffleStatus;
+    session: WaffleSession | null;
+    error: Error;
+    agentSpeaking: boolean;
+    transcript: WaffleTranscript;
+}
+type WaffleSessionToken = () => string | Promise<string>;
+interface WaffleClientOptions {
+    /** The published Agent to connect to. */
+    agentId: string;
+    /** A short-lived token minted for this Agent by the Narya API. */
+    sessionToken: WaffleSessionToken;
+    /** Override the Narya API origin for a non-production environment. */
+    apiOrigin?: string;
+}
+interface WaffleConnectOptions {
+    inputMode?: WaffleInputMode;
+}
+type Listener<K extends keyof WaffleClientEvents> = (payload: WaffleClientEvents[K]) => void;
+declare class WaffleError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+declare class WaffleClient {
+    private readonly realtime;
+    private readonly listeners;
+    private readonly options;
+    private readonly apiOrigin;
+    private currentStatus;
+    private currentSession;
+    private startPromise;
+    private stopPromise;
+    private requestAbort;
+    private audio;
+    private activeInputMode;
+    private turnId;
+    private nextTurnId;
+    private lifecycleVersion;
+    constructor(options: WaffleClientOptions);
+    get status(): WaffleStatus;
+    get session(): WaffleSession | null;
+    on<K extends keyof WaffleClientEvents>(event: K, listener: Listener<K>): () => void;
+    connect(options?: WaffleConnectOptions): Promise<WaffleSession>;
+    disconnect(): Promise<void>;
+    sendText(text: string): Promise<void>;
+    startPushToTalk(): void;
+    stopPushToTalk(): void;
+    cancelPushToTalk(): void;
+    private startInternal;
+    private stopInternal;
+    private sendInputControl;
+    private assertConnected;
+    private handleUserTranscript;
+    private handleBotOutput;
+    private handleTransportState;
+    private handleReady;
+    private handleDisconnected;
+    private setAudioTrack;
+    private stopAudio;
+    private setStatus;
+    private fail;
+    private resolveSessionToken;
+    private withTimeout;
+    private emit;
+}
+
+export { WaffleClient, type WaffleClientEvents, type WaffleClientOptions, type WaffleConnectOptions, WaffleError, type WaffleInputMode, type WaffleSession, type WaffleSessionToken, type WaffleStatus, type WaffleTranscript };

package/dist/index.js

@@ -0,0 +1 @@
+import{b as d}from"./chunk-BXRNROI7.js";import{PipecatClient as g}from"@pipecat-ai/client-js";import{DailyTransport as S}from"@pipecat-ai/daily-transport";var w=15e3,T=3e4,y="https://animated-waffle.narya.ai",k=/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,I=/^sha256:[a-f0-9]{64}$/,s=class extends Error{constructor(e,n,o){super(e);this.status=n;this.code=o;this.name="WaffleError"}status;code};function p(i){return i!==null&&typeof i=="object"&&!Array.isArray(i)?i:null}function b(i=y){let t;try{t=new URL(i)}catch{throw new s("apiOrigin must be a valid URL.",void 0,"invalid_api_origin")}let e=t.hostname==="localhost"||t.hostname==="127.0.0.1"||t.hostname==="[::1]";if(t.protocol!=="https:"&&!(t.protocol==="http:"&&e)||t.username||t.password||t.pathname!=="/"&&t.pathname!==""||t.search||t.hash)throw new s("apiOrigin must be an HTTPS origin or an HTTP loopback origin.",void 0,"invalid_api_origin");return t.origin}function u(i,t){if(typeof i!="string"||i.trim().length===0)throw new s(`Session response is missing ${t}.`);return i}function _(i){let t=u(i,"avatar.asset_hash");if(!I.test(t))throw new s("Session response contains an invalid Avatar asset hash.");return t}function m(i){return typeof i=="number"&&Number.isFinite(i)?i:void 0}function h(i){return typeof i=="string"&&i.length>0?i:void 0}function A(i,t){let e=p(i);if(!e)throw new s("Session response must be a JSON object.");if(e.protocol_version!==1)throw new s("Session response has an unsupported protocol version.");let n=p(e.connection);if(!n||n.transport!=="webrtc")throw new s("Session response is missing a WebRTC connection.");let o=u(n.url,"connection.url");try{if(new URL(o).protocol!=="https:")throw new Error}catch{throw new s("Session response contains an invalid connection URL.")}let c=u(e.avatar_id,"avatar_id"),a=p(e.avatar);if(!a||u(a.id,"avatar.id")!==c)throw new s("Session response contains mismatched Avatar metadata.");let r=u(a.engine,"avatar.engine");if(r!=="vrm")throw new s("Session response contains an unsupported Avatar engine.");let l=u(a.model_url,"avatar.model_url");try{if(new URL(l).protocol!=="https:")throw new Error}catch{throw new s("Session response contains an invalid Avatar model URL.")}return{id:u(e.session_id,"session_id"),agentId:u(e.agent_id,"agent_id"),avatarId:c,avatar:{id:c,name:u(a.name,"avatar.name"),engine:r,modelUrl:l,assetHash:_(a.asset_hash),runtimeProfile:u(a.runtime_profile,"avatar.runtime_profile")},inputMode:t,room:o,token:u(n.token,"connection.token")}}function C(i){let t=p(i);if(!t||typeof t.type!="string")return null;let e={contextId:h(t.contextId)??null,segmentId:h(t.segmentId),occurrence:m(t.occurrence),audioTime:m(t.audioTime),offset:m(t.offset)};if(t.type==="avatar-emotion"){let n=h(t.emotion);return n?{phase:"emotion",emotion:n,...e}:null}if(t.type==="avatar-vocal-action"){let n=h(t.action);return n?{phase:"vocal-action",action:n,...e}:null}return null}function f(i){let{avatar:t,room:e,token:n,...o}=i;return o}var v=class{realtime;listeners=new Map;options;apiOrigin;currentStatus="disconnected";currentSession=null;startPromise=null;stopPromise=null;requestAbort=null;audio=null;activeInputMode="push-to-talk";turnId=null;nextTurnId=0;lifecycleVersion=0;constructor(t){if(this.options=t,this.apiOrigin=b(t.apiOrigin),!k.test(t.agentId))throw new s("agentId must be a UUID.",void 0,"invalid_agent_id");if(typeof t.sessionToken!="function")throw new s("sessionToken must be a function.",void 0,"invalid_session_token");let e=new S({bufferLocalAudioUntilBotReady:!0,inputSettings:{audio:{processor:{type:"noise-cancellation"}}}}),n={onTransportStateChanged:o=>this.handleTransportState(o),onBotReady:()=>this.handleReady(),onDisconnected:()=>this.handleDisconnected(),onBotStartedSpeaking:()=>this.emit("agentSpeaking",!0),onBotStoppedSpeaking:()=>this.emit("agentSpeaking",!1),onUserTranscript:o=>this.handleUserTranscript(o),onBotOutput:o=>this.handleBotOutput(o),onServerMessage:o=>{let c=C(o);c&&d(this,"avatar",c)},onTrackStarted:(o,c)=>{o.kind==="audio"&&c?.local===!1&&this.setAudioTrack(o)},onTrackStopped:(o,c)=>{o.kind==="audio"&&c?.local===!1&&this.setAudioTrack(null)},onError:o=>this.fail(new s(p(o)?.message?.toString()??"Realtime connection failed."))};this.realtime=new g({transport:e,enableCam:!1,enableMic:!1,disconnectOnBotDisconnect:!0,callbacks:n})}get status(){return this.currentStatus}get session(){return this.currentSession?f(this.currentSession):null}on(t,e){let n=this.listeners.get(t)??new Set;return n.add(e),this.listeners.set(t,n),()=>n.delete(e)}connect(t={}){if(this.currentSession&&this.status==="connected")return Promise.resolve(f(this.currentSession));if(this.startPromise)return this.startPromise;let e=++this.lifecycleVersion,n=this.startInternal(t,e).finally(()=>{this.startPromise===n&&(this.startPromise=null)});return this.startPromise=n,n}disconnect(){if(this.stopPromise)return this.stopPromise;let t=this.stopInternal().finally(()=>{this.stopPromise===t&&(this.stopPromise=null)});return this.stopPromise=t,t}async sendText(t){let e=t.trim();e&&(this.assertConnected(),await this.realtime.sendText(e,{audio_response:!0,run_immediately:!0}))}startPushToTalk(){if(this.turnId===null){this.nextTurnId+=1,this.turnId=this.nextTurnId;try{this.realtime.enableMic(!0),this.sendInputControl("start",this.turnId)}catch(t){throw this.turnId=null,t}}}stopPushToTalk(){this.turnId!==null&&(this.sendInputControl("stop",this.turnId),this.turnId=null)}cancelPushToTalk(){this.turnId!==null&&(this.sendInputControl("cancel",this.turnId),this.turnId=null)}async startInternal(t,e){this.activeInputMode=t.inputMode??"push-to-talk",this.setStatus("connecting");let n=new AbortController;this.requestAbort=n;let o;try{let r=await this.resolveSessionToken();o=await this.withTimeout(fetch(`${this.apiOrigin}/v1/agents/${encodeURIComponent(this.options.agentId)}/sessions`,{method:"POST",headers:{Accept:"application/json","Content-Type":"application/json",Authorization:`Bearer ${r}`},signal:n.signal,body:JSON.stringify({input_mode:this.activeInputMode==="push-to-talk"?"push_to_talk":"automatic"})}),w,"Timed out creating the Waffle session.",()=>n.abort())}catch(r){let l=r instanceof Error?r:new s("Could not create session.");throw e!==this.lifecycleVersion?new s("The connection attempt was cancelled."):(this.fail(l),l)}finally{this.requestAbort===n&&(this.requestAbort=null)}if(e!==this.lifecycleVersion)throw new s("The connection attempt was cancelled.");let c=await o.json().catch(()=>null);if(!o.ok){let r=p(c),l=new s(h(r?.detail)??"Could not create session.",o.status,h(r?.code));throw this.fail(l),l}let a;try{a=A(c,this.activeInputMode)}catch(r){let l=r instanceof Error?r:new s("Could not parse the Waffle session.");throw this.fail(l),l}this.currentSession=a,this.emit("session",f(a)),d(this,"presentation",a.avatar),this.setStatus("connecting");try{await this.withTimeout(this.realtime.connect({url:a.room,token:a.token}).then(()=>{}),T,"Timed out waiting for the Waffle Agent.",()=>{this.realtime.disconnect().catch(()=>{})})}catch(r){this.currentSession=null,this.emit("session",null),d(this,"presentation",null),await this.realtime.disconnect().catch(()=>{});let l=r instanceof Error?r:new s("Could not connect.");throw e!==this.lifecycleVersion?new s("The connection attempt was cancelled."):(this.fail(l),l)}return this.activeInputMode==="automatic"&&this.realtime.enableMic(!0),this.setStatus("connected"),this.setAudioTrack(this.realtime.tracks().bot?.audio??null),f(a)}async stopInternal(){if(this.lifecycleVersion+=1,this.requestAbort?.abort(),this.turnId=null,this.stopAudio(),this.currentStatus!=="disconnected"){this.setStatus("disconnecting");try{await this.realtime.disconnect()}finally{this.currentSession=null,this.emit("session",null),d(this,"presentation",null),this.emit("agentSpeaking",!1),this.setStatus("disconnected")}}}sendInputControl(t,e){if(this.activeInputMode!=="push-to-talk")throw new s('Push-to-talk controls require inputMode: "push-to-talk".');this.assertConnected(),this.realtime.sendClientMessage("voice.input_control",{mode:"push_to_talk",state:t,turnId:e})}assertConnected(){if(this.status!=="connected")throw new s("Start the Waffle session before sending input.")}handleUserTranscript(t){this.emit("transcript",{role:"user",text:t.text,final:t.final,timestamp:t.timestamp})}handleBotOutput(t){this.emit("transcript",{role:"assistant",text:t.text,final:!0})}handleTransportState(t){t==="ready"?this.handleReady():t==="disconnecting"?this.setStatus("disconnecting"):t==="disconnected"?this.handleDisconnected():this.currentSession&&this.currentStatus!=="connected"&&this.setStatus("connecting")}handleReady(){this.setStatus("connected")}handleDisconnected(){this.currentSession=null,this.emit("session",null),d(this,"presentation",null),this.stopAudio(),this.emit("agentSpeaking",!1),this.setStatus("disconnected")}setAudioTrack(t){if(d(this,"audioTrack",t),this.stopAudio(!1),!t||typeof document>"u")return;let e=document.createElement("audio");e.autoplay=!0,e.setAttribute("playsinline",""),e.srcObject=new MediaStream([t]),this.audio=e,e.play().catch(n=>{this.emit("error",n instanceof Error?n:new s("Browser blocked agent audio."))})}stopAudio(t=!0){this.audio&&(this.audio.pause(),this.audio.srcObject=null,this.audio=null),t&&d(this,"audioTrack",null)}setStatus(t){this.currentStatus!==t&&(this.currentStatus=t,this.emit("status",t))}fail(t){this.setStatus("disconnected"),this.emit("error",t)}async resolveSessionToken(){let t=await this.options.sessionToken();if(!t.trim())throw new s("sessionToken must not be empty.",void 0,"invalid_session_token");return t}withTimeout(t,e,n,o){return new Promise((c,a)=>{let r=setTimeout(()=>{o?.(),a(new s(n))},e);t.then(l=>{clearTimeout(r),c(l)},l=>{clearTimeout(r),a(l)})})}emit(t,e){this.listeners.get(t)?.forEach(n=>{n(e)})}};export{v as WaffleClient,s as WaffleError};

package/dist/internal.d.ts

@@ -0,0 +1,28 @@
+interface InternalAvatarEvent {
+    phase: 'emotion' | 'vocal-action';
+    contextId?: string | null;
+    emotion?: string;
+    action?: string;
+    segmentId?: string;
+    occurrence?: number;
+    audioTime?: number;
+    offset?: number;
+}
+interface InternalAvatarPresentation {
+    id: string;
+    name: string;
+    engine: 'vrm';
+    modelUrl: string;
+    assetHash: string;
+    runtimeProfile: string;
+}
+interface InternalWaffleEvents {
+    avatar: InternalAvatarEvent;
+    audioTrack: MediaStreamTrack | null;
+    presentation: InternalAvatarPresentation | null;
+}
+type InternalListener<K extends keyof InternalWaffleEvents> = (payload: InternalWaffleEvents[K]) => void;
+declare function subscribeInternal<K extends keyof InternalWaffleEvents>(owner: object, event: K, listener: InternalListener<K>): () => void;
+declare function emitInternal<K extends keyof InternalWaffleEvents>(owner: object, event: K, payload: InternalWaffleEvents[K]): void;
+
+export { type InternalAvatarEvent, type InternalAvatarPresentation, type InternalWaffleEvents, emitInternal, subscribeInternal };

package/dist/internal.js

@@ -0,0 +1 @@
+import{a,b}from"./chunk-BXRNROI7.js";export{b as emitInternal,a as subscribeInternal};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@animated-waffle/client",
+  "version": "0.1.0",
+  "description": "Framework-independent browser SDK for Narya Animated Waffle talking Agents.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "homepage": "https://animated-waffle.narya.ai/docs/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NaryaAI/animated-waffle.git",
+    "directory": "packages/waffle-client"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pipecat-ai/client-js": "1.12.0",
+    "@pipecat-ai/daily-transport": "1.6.7"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}