@komaa/standin-sdk 0.1.0

package/dist/handler.d.ts

@@ -0,0 +1,283 @@
+/**
+ * The seam every StandIn plugin implements.
+ *
+ * This is the whole contract between the SDK and an agent framework, and it is
+ * deliberately five methods wide. {@link CallServer} owns everything that is the
+ * same for every framework - the socket StandIn dials, the HMAC handshake and
+ * its replay guard, capacity and draining, the frame loop, sequence numbers and
+ * the outbound audio timeline, and the two watchdogs that end a call nobody
+ * closed. A plugin owns only the part that differs: what to do with a caller's
+ * voice, and where the reply comes from.
+ *
+ * Identical in shape to the Python SDK's `standin.handler`, translated to TS
+ * naming (snake_case becomes camelCase). A plugin ported between the two
+ * changes only its method names.
+ *
+ * Writing one:
+ *
+ * ```ts
+ * import { CallServer, type CallSession } from "@komaa/standin-sdk";
+ *
+ * class EchoHandler {
+ *   #call!: CallSession;
+ *   async onStart(session: CallSession) { this.#call = session; }
+ *   async onCallerAudio(pcm: Buffer) { await this.#call.sendAudio(pcm); }
+ * }
+ *
+ * const server = new CallServer({ handlerFactory: () => new EchoHandler() });
+ * await server.start();
+ * ```
+ *
+ * Every method is optional: the server treats a missing one as a no-op, so a
+ * handler that only wants audio implements only `onCallerAudio`. Nothing extends
+ * anything.
+ */
+import type { Emotion, SpeechMark } from "./avatar.js";
+import type { SessionStart } from "./protocol.js";
+import type { DisplayImageOptions, VideoFrame, VideoSource } from "./vision.js";
+/**
+ * One live Microsoft Teams call, as a handler sees it.
+ *
+ * Handed to {@link CallHandler.onStart} and valid until the call ends. The
+ * server owns the socket; this is the handler's only way to reach it.
+ */
+export interface CallSession {
+    /**
+     * StandIn's id for this call. Authenticated - it is the value the handshake
+     * HMAC signed, not something a caller supplied.
+     */
+    readonly callId: string;
+    /**
+     * The `session.start` that opened the call: caller identity, direction,
+     * thread, recording status.
+     */
+    readonly start: SessionStart;
+    /**
+     * Send the agent's voice to the caller.
+     *
+     * `pcm` is raw PCM16, 16 kHz, mono, little-endian - the same format
+     * {@link CallHandler.onCallerAudio} receives. The server owns the sequence
+     * number and the outbound timeline, so a handler never tracks either, and a
+     * re-published or swapped audio source cannot make timestamps jump backwards.
+     */
+    /**
+     * Whether the Microsoft Teams call is being recorded, right now.
+     *
+     * One flag, kept current by the server: it starts from
+     * `session.start.recordingStatus` and follows every later `recording.status`
+     * change, so a plugin never has to re-derive it from the context sentence it
+     * happens to have seen.
+     *
+     * A reported status WINS over the start snapshot, whichever arrives first.
+     * `session.start` omits the field when the state was unknown at answer time,
+     * and an omitted field is not "not recording": letting the snapshot overwrite
+     * a `recording.status` that landed first would shut every recording-gated
+     * capability for the whole call, silently.
+     *
+     * Gate on it before anything that STORES what the caller said or showed with
+     * a third party. A recorded call is one the caller was told is being kept; an
+     * unrecorded one is not.
+     */
+    readonly recordingActive: boolean;
+    /**
+     * Who is speaking now, when StandIn sends unmixed audio.
+     *
+     * `undefined` on the mixed path, which is most calls, so treat it as a hint
+     * rather than as something to depend on. Use it to attribute a transcript, or
+     * to tell a model who it is answering in a meeting.
+     */
+    readonly speaker: string | undefined;
+    /**
+     * How many people are on the call.
+     *
+     * Zero until StandIn first says, and it says again whenever somebody joins or
+     * leaves. The number behind the "this is a 1:1 call" and "there are N human
+     * participants" context sentences, for a plugin that wants to branch on it
+     * rather than hand a sentence to a model.
+     */
+    readonly participantCount: number;
+    /** Whether anything has actually taken this call yet. */
+    readonly answered: boolean;
+    /**
+     * Say that an agent has taken the call. Stamped once, never re-stamped.
+     *
+     * A plugin that joins a room calls this when the agent's own audio track
+     * appears, not when a participant connects: monitors, recorders and avatar
+     * workers all connect, and none of them is an agent answering. A plugin that
+     * never calls it is still covered, because sending audio counts.
+     */
+    markAnswered(): void;
+    /**
+     * How much outbound data the socket has not yet flushed.
+     *
+     * The number a continuous sender watches to decide whether to drop a frame.
+     * Audio and the avatar tile both push on a timer, and a peer that stops
+     * reading turns "send everything" into an unbounded buffer.
+     *
+     * Zero when the transport cannot report it, so treat a zero as "no evidence
+     * of backpressure" rather than as proof of an idle socket.
+     */
+    readonly bufferedBytes: number;
+    /**
+     * The outbound audio timeline, in milliseconds.
+     *
+     * The same clock this call's `audio.frame` messages are stamped with, which is
+     * what a video frame must be stamped with too. A wall clock keeps ticking
+     * through listening silence while this one does not, so stamping video from a
+     * wall clock makes the audio and video drift apart on paper even when they are
+     * in step.
+     */
+    readonly mediaTimeMs: number;
+    sendAudio(pcm: Buffer): Promise<void>;
+    /**
+     * Drop whatever agent audio StandIn still has buffered.
+     *
+     * The only lever that un-sends audio already handed to the service: it
+     * flushes the platform player, so the caller stops hearing the turn they just
+     * interrupted. Call it the moment your provider reports the caller started
+     * speaking, before you cancel the response upstream - otherwise a barge-in
+     * stops the model but the bot keeps talking for the length of the buffer.
+     */
+    cancelPlayback(): Promise<void>;
+    /**
+     * The most recent frame the caller showed, or `undefined` if they have shown
+     * nothing.
+     *
+     * Synchronous, because it reads a value the frame loop already stored: there
+     * is no waiting for a frame here, and a handler that wants to know the moment
+     * one arrives implements {@link CallHandler.onVideoFrame} instead.
+     *
+     * With no `source` the screen share wins over the camera, because an agent
+     * asked to look is nearly always being asked about what is being shown rather
+     * than who is showing it.
+     */
+    latestVideoFrame(source?: VideoSource): VideoFrame | undefined;
+    /**
+     * Draw an image on the bot's video tile for a few seconds.
+     *
+     * The agent's half of the vision lane: a chart it just computed, a page it is
+     * quoting, a photo it was asked for. Best-effort and additive, so a service
+     * that does not implement it ignores the message rather than failing the call.
+     */
+    displayImage(image: Buffer | string, options?: DisplayImageOptions): Promise<void>;
+    /**
+     * Put one frame of continuous video on the bot's tile.
+     *
+     * The server owns the sequence number and stamps the frame with the outbound
+     * AUDIO timeline, exactly as it does for {@link sendAudio}, so the two streams
+     * cannot disagree about what time it is.
+     *
+     * Latest wins and there is no handshake: the first frames start the stream and
+     * silence ends it. Pace it and drop under backpressure rather than queueing,
+     * which is what `TileStream` is for.
+     */
+    sendTileFrame(jpeg: Buffer, width?: number, height?: number): Promise<void>;
+    /**
+     * Hint the emotion the avatar should wear on the bot's tile.
+     *
+     * Best-effort and video only: an unknown emotion renders as neutral, and
+     * nothing here changes a sample of what the caller hears.
+     */
+    express(emotion: Emotion): Promise<void>;
+    /**
+     * Send the viseme timeline for one utterance, which is what drives lip-sync
+     * on the avatar.
+     *
+     * Real timings from your provider are best. Where there are none, which is
+     * every realtime speech-to-speech model, `lipsync.ts` estimates a timeline
+     * from the text and spreads it over the audio that turn actually sent: a
+     * mouth on a measured clock beats a still one. What is worse than none is a
+     * timeline whose DURATION was guessed, from text length or a words-per-minute
+     * rate, because that one drifts further out of step with the voice the longer
+     * it runs.
+     */
+    sendSpeechMarks(marks: Iterable<SpeechMark>): Promise<void>;
+    /**
+     * Ask for the call to end. Idempotent, and the first reason wins - a cascade
+     * of close causes must not overwrite the one that actually ended it.
+     *
+     * Safe to call from inside {@link CallHandler.onStart} to refuse a call: it
+     * returns immediately there rather than deadlocking against teardown, and the
+     * close runs once onStart unwinds.
+     */
+    end(reason: string): Promise<void>;
+}
+/**
+ * What a plugin implements. One instance per call, built by a
+ * {@link HandlerFactory}.
+ *
+ * Every method is awaited by the server and every one is optional. A rejection
+ * from any of them is logged and ends that call alone - one bad call must never
+ * take the worker with it.
+ */
+export interface CallHandler {
+    /**
+     * The call is live. Join a room, open a realtime socket, build an agent -
+     * whatever this framework needs. Audio does not flow until this resolves, so a
+     * slow start delays the caller rather than dropping frames.
+     */
+    onStart?(session: CallSession): void | Promise<void>;
+    /**
+     * One frame of the caller's voice: PCM16, 16 kHz, mono, little-endian.
+     *
+     * Called on the receive path of a live call, so it must not block. The frame
+     * has already been validated - a truncated or malformed payload is dropped by
+     * the server and never reaches here.
+     */
+    onCallerAudio?(pcm: Buffer): void | Promise<void>;
+    /**
+     * One sampled frame of the caller's camera or screen share.
+     *
+     * Optional, and most handlers never implement it: frames arrive sparsely and
+     * best-effort, and the common shape is to look only when the model asks, which
+     * {@link CallSession.latestVideoFrame} already serves without a callback.
+     * Implement this for ambient vision - narrating a slide deck, watching a
+     * whiteboard, noticing that the share stopped.
+     *
+     * Called on the receive path of a live call, so a slow model call belongs off
+     * the frame loop, exactly as it does in {@link CallHandler.onCallerAudio}.
+     */
+    onVideoFrame?(frame: VideoFrame): void | Promise<void>;
+    /**
+     * A different person started speaking.
+     *
+     * Optional, and only ever called when StandIn sends unmixed audio: most calls
+     * carry mixed audio and never call it at all. Called on CHANGE only, never
+     * per frame. The name rides every inbound audio frame, and a model told forty
+     * times a second who is speaking would hear nothing else.
+     *
+     * Called on the receive path of a live call, so anything slow belongs off the
+     * frame loop, exactly as in {@link CallHandler.onCallerAudio}.
+     */
+    onSpeakerChange?(name: string): void | Promise<void>;
+    /**
+     * Non-interrupting context about the call, as a plain sentence ready to put in
+     * front of a model: participant counts and group-call etiquette, DTMF key
+     * presses, and recording status changes.
+     *
+     * Delivered as it arrives. A framework that cannot accept context before its
+     * agent is ready should queue it here - the server does not, because what
+     * "ready" means is a framework's own business.
+     */
+    onContext?(text: string): void | Promise<void>;
+    /**
+     * StandIn is ending the call and wants this line spoken first.
+     *
+     * The server has already told StandIn to drop whatever agent audio it had
+     * buffered, so this line plays immediately. Interrupt the current turn and say
+     * it: the teardown follows shortly, and a goodbye queued behind a long answer
+     * is a goodbye the caller never hears.
+     */
+    onGoodbye?(text: string): void | Promise<void>;
+    /**
+     * Release everything this call holds. Always called exactly once, on every
+     * path, before the slot is freed.
+     */
+    aclose?(reason: string): void | Promise<void>;
+}
+/**
+ * Builds one {@link CallHandler} per call. Called with no arguments, so a plugin
+ * closes over its own configuration rather than threading it through the server.
+ */
+export type HandlerFactory = () => CallHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"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"}

package/dist/handler.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+export {};
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+BAA+B"}

package/dist/hmac.d.ts

@@ -0,0 +1,32 @@
+export declare const TIMESTAMP_HEADER = "x-standin-timestamp";
+export declare const SIGNATURE_HEADER = "x-standin-signature";
+export declare const SIGNATURE_V2_HEADER = "x-standin-signature-v2";
+/** Handshakes are dialed and answered immediately; anything older is a replay. */
+export declare const REPLAY_WINDOW_MS = 60000;
+/** Chat POSTs allow delayed relay retries; WebSocket upgrades still use 60 s. */
+export declare const CHAT_REPLAY_WINDOW_MS = 300000;
+export declare function nowMs(): number;
+/** Signature for a WebSocket upgrade. */
+export declare function signHandshake(secret: string, timestampMs: number | string, handshakeId: string): string;
+/** Constant-time check of an inbound upgrade. Empty inputs fail CLOSED. */
+export declare function verifyHandshake(secret: string, timestamp: string | undefined, handshakeId: string, signature: string | undefined, currentMs?: number): boolean;
+/** Sign a chat POST's exact transmitted bytes as `{timestampMs}.{rawBody}`.
+ * Strings are UTF-8 encoded. Serialize once and send those same bytes.
+ */
+export declare function signBody(secret: string, timestampMs: number | string, rawBody: string | Uint8Array): string;
+/** Verify a chat POST, allowing 300 s of clock skew by default.
+ * Missing or malformed headers fail closed. The WebSocket chat channel still
+ * signs the channel name and uses the separate 60 s window.
+ */
+export declare function verifyBody(secret: string, timestamp: string | undefined, rawBody: string | Uint8Array, signature: string | undefined, currentMs?: number, windowMs?: number): boolean;
+/** Return `METHOD\npath\nsha256_hex(body)` for a v2 control request.
+ * The path is the HTTP request path, without the origin or query string,
+ * matching the worker verifier. The body covers every field, including tenantId.
+ */
+export declare function canonicalRequest(method: string, path: string, rawBody: string | Uint8Array): string;
+/** Sign an outbound control request for X-StandIn-Signature-V2.
+ * Pass the exact bytes you will transmit. v1 handshakes remain supported for
+ * WebSockets; control requests should send this v2 header.
+ */
+export declare function signRequest(secret: string, timestampMs: number | string, method: string, path: string, rawBody: string | Uint8Array): string;
+//# sourceMappingURL=hmac.d.ts.map

package/dist/hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.d.ts","sourceRoot":"","sources":["../src/hmac.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAE7C,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,yCAAyC;AACzC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAuBT;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,SAAwB,GAC/B,OAAO,CAWT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,MAAM,CAMR"}

package/dist/hmac.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * StandIn signatures for WebSocket handshakes, chat POSTs and control requests.
+ *
+ * WebSocket handshakes use `HMAC-SHA256(secret, "{timestampMs}.{id}")`,
+ * lowercase hex, carried in `X-StandIn-Timestamp` / `X-StandIn-Signature`.
+ *
+ *     inbound   StandIn dials the call listener; `id` is the callId in the URL
+ *               path, and `CallServer` VERIFIES inside a replay window.
+ *     outbound  the worker dials the chat channel; `id` is the channel name,
+ *               and `ChatChannel` SIGNS.
+ *
+ * Chat POSTs sign the exact body bytes with a five-minute replay window.
+ * Control requests use v2, binding the method, path and hash of the whole body.
+ *
+ * Byte-for-byte identical to the Python SDK's `standin/sdk/_hmac.py`; the shared
+ * conformance vectors assert that a signature produced by either verifies in the
+ * other.
+ */
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+export const TIMESTAMP_HEADER = "x-standin-timestamp";
+export const SIGNATURE_HEADER = "x-standin-signature";
+export const SIGNATURE_V2_HEADER = "x-standin-signature-v2";
+/** Handshakes are dialed and answered immediately; anything older is a replay. */
+export const REPLAY_WINDOW_MS = 60_000;
+/** Chat POSTs allow delayed relay retries; WebSocket upgrades still use 60 s. */
+export const CHAT_REPLAY_WINDOW_MS = 300_000;
+export function nowMs() {
+    return Date.now();
+}
+/** Signature for a WebSocket upgrade. */
+export function signHandshake(secret, timestampMs, handshakeId) {
+    return createHmac("sha256", secret)
+        .update(`${timestampMs}.${handshakeId}`, "utf8")
+        .digest("hex");
+}
+/** Constant-time check of an inbound upgrade. Empty inputs fail CLOSED. */
+export function verifyHandshake(secret, timestamp, handshakeId, signature, currentMs) {
+    if (!secret || !timestamp || !signature)
+        return false;
+    // Restrict the timestamp to ASCII decimal, matching the Python SDK.
+    // Number() also accepts empty strings, hexadecimal and exponent notation.
+    if (!/^-?\d+$/.test(timestamp.trim()))
+        return false;
+    const ts = Number(timestamp.trim());
+    if (!Number.isFinite(ts))
+        return false;
+    const now = currentMs ?? nowMs();
+    if (Math.abs(now - ts) > REPLAY_WINDOW_MS)
+        return false;
+    const expected = signHandshake(secret, timestamp, handshakeId);
+    const given = signature.trim().toLowerCase();
+    // timingSafeEqual THROWS on a length mismatch, and this is reachable by anyone
+    // who can open a socket. Unguarded, a short signature header turns an
+    // unauthenticated upgrade into a 500 instead of a 401 - a crash path, and an
+    // oracle that tells "malformed" apart from "wrong".
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(given, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** Sign a chat POST's exact transmitted bytes as `{timestampMs}.{rawBody}`.
+ * Strings are UTF-8 encoded. Serialize once and send those same bytes.
+ */
+export function signBody(secret, timestampMs, rawBody) {
+    return createHmac("sha256", secret)
+        .update(`${timestampMs}.`, "utf8")
+        .update(rawBody)
+        .digest("hex");
+}
+/** Verify a chat POST, allowing 300 s of clock skew by default.
+ * Missing or malformed headers fail closed. The WebSocket chat channel still
+ * signs the channel name and uses the separate 60 s window.
+ */
+export function verifyBody(secret, timestamp, rawBody, signature, currentMs, windowMs = CHAT_REPLAY_WINDOW_MS) {
+    if (!secret || !timestamp || !signature)
+        return false;
+    if (!/^-?\d+$/.test(timestamp.trim()))
+        return false;
+    const ts = Number(timestamp.trim());
+    if (!Number.isFinite(ts))
+        return false;
+    if (Math.abs((currentMs ?? nowMs()) - ts) > windowMs)
+        return false;
+    const expected = Buffer.from(signBody(secret, timestamp, rawBody), "utf8");
+    const given = Buffer.from(signature.trim().toLowerCase(), "utf8");
+    if (expected.length !== given.length)
+        return false;
+    return timingSafeEqual(expected, given);
+}
+/** Return `METHOD\npath\nsha256_hex(body)` for a v2 control request.
+ * The path is the HTTP request path, without the origin or query string,
+ * matching the worker verifier. The body covers every field, including tenantId.
+ */
+export function canonicalRequest(method, path, rawBody) {
+    const bodyHash = createHash("sha256").update(rawBody).digest("hex");
+    return `${method.toUpperCase()}\n${path}\n${bodyHash}`;
+}
+/** Sign an outbound control request for X-StandIn-Signature-V2.
+ * Pass the exact bytes you will transmit. v1 handshakes remain supported for
+ * WebSockets; control requests should send this v2 header.
+ */
+export function signRequest(secret, timestampMs, method, path, rawBody) {
+    return signHandshake(secret, timestampMs, canonicalRequest(method, path, rawBody));
+}
+//# sourceMappingURL=hmac.js.map

package/dist/hmac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../src/hmac.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * StandIn SDK - put your AI agent into a Microsoft Teams call.
+ *
+ * StandIn (https://standin.komaa.com) is the hosted bridge that joins the Microsoft Teams
+ * call: it owns the Microsoft side entirely - the bot registration, Graph, media
+ * negotiation, the avatar tile - and speaks to your worker over one
+ * authenticated socket per call. This package is that socket's other end.
+ *
+ * The Python SDK (`standin-sdk` on PyPI) is the same API, same seam, same wire
+ * protocol. Which one you use is decided by the framework you are integrating,
+ * not by preference.
+ *
+ * This module is the CORE, and it is the whole reason one package works: it
+ * imports nothing from `plugins/`, so `import { CallServer } from
+ * "@komaa/standin-sdk"` succeeds on a machine with no framework installed at
+ * all. A plugin is reached by its own subpath - `@komaa/standin-sdk/echo`,
+ * `@komaa/standin-sdk/openclaw` - and only a caller that already has that
+ * framework ever loads it. Keep it that way: one framework import at the top of
+ * a file reachable from here would break every install that does not use it.
+ *
+ * You do not normally use this directly. Reach for the plugin for your
+ * framework; the root-level examples show a complete deployment of each.
+ *
+ * Writing a plugin is the other direction, and it is deliberately small -
+ * see {@link CallHandler}, or copy `plugins/echo`, which answers a real
+ * call in under 100 lines.
+ */
+export { BYTES_PER_SAMPLE, FRAME_BYTES, FRAME_MS, REALTIME_SAMPLE_RATE_HZ, FrameAligner, frameDurationMs, pcm16Rms, resamplePcm16, } from "./audio.js";
+export { EMOTIONS, ExpressionCue, MAX_EMOTION_CHARS, MAX_VISEME_ID, type Emotion, type InferredEmotion, type SpeechMark, expression, inferEmotion, speechMarks, } from "./avatar.js";
+export { MAX_AUDIO_BUFFER_BYTES, CallServer, type CallServerOptions, } from "./callServer.js";
+export { TROUBLE_ANSWERING, TROUBLE_HEARING, TROUBLE_SPEAKING, VoiceLane, type Answer, type Synthesize, type Transcribe, type VoiceLaneOptions, type VoiceTurn, } from "./lane.js";
+export { SyntheticCall, runSmoke, report as smokeReport, type SmokeCheck, type SmokeResult, } from "./smoke.js";
+export { LiveCalls, TENANT_ENV, VoiceDelivery, type Delivery, type LiveSpeaker, type VoiceDeliveryOptions, } from "./delivery.js";
+export { BUILT_IN_TOOLS, SHOW_PAGE_TOOL, CallTools, type CallToolsOptions, type ToolDialect, type ToolHandler, type ToolResult, type ToolSpec, toolSchemas, } from "./callTools.js";
+export { flag, jsonObject, optional, required, vendorHost } from "./config.js";
+export { BACKGROUND_TASK_TOOL, CONSULT_TOOL, DEFAULT_CONSULT_TIMEOUT_MS, DEFAULT_RESUME_LIMIT, DEFAULT_TASK_TIMEOUT_MS, DEFAULT_TASK_TTL_MS, BackgroundTasks, Consultant, type Asker, type AskerFactory, type BackgroundTask, type BackgroundTasksOptions, type Deliverer, } from "./consult.js";
+export { CHAT_FALLBACK_WINDOW_MS, PersonalChats, type PersonalChat, DEFAULT_CHAT_URL, OUTBOUND_IMAGE_CONTENT_TYPES, OUTBOUND_IMAGE_MAX_BYTES, SCHEMA_VERSION, ChatChannel, type ChatChannelOptions, type InboundMessage, type OutboundImage, buildReply, isPersonal, outboundImage, parseInbound, sanitizeImageName, sniffImageType, } from "./chat.js";
+export { ECHO_BARGE_IN_RMS, ECHO_SUPPRESSION_WINDOW_MS, pcm16Rms as echoPcm16Rms, shouldSuppressEcho, type EchoGuardOptions, } from "./echoGuard.js";
+export { StandInError } from "./errors.js";
+export { DEFAULT_FOLLOW_UP_WINDOW_MS, GroupGate, type GateDecision, type GroupGateOptions, isAddressed, isMeetingThread, isVerbalInterrupt, } from "./gate.js";
+export { describeInboundRejection, isAllowlistedCaller, isInboundCallAllowed, normalizePhoneNumber, } from "./policy.js";
+export { type ForbiddenIpFn, type LookupFn, assertPublicHttpUrl, fetchPublicImage, isForbiddenIp, } from "./fetch.js";
+export type { CallHandler, CallSession, HandlerFactory } from "./handler.js";
+export { CHAT_REPLAY_WINDOW_MS, REPLAY_WINDOW_MS, SIGNATURE_HEADER, SIGNATURE_V2_HEADER, TIMESTAMP_HEADER, canonicalRequest, nowMs, signBody, signHandshake, signRequest, verifyBody, verifyHandshake, } from "./hmac.js";
+export { ATTACHMENT_NOTE_MAX_LINES, CARD_PAYLOAD_MAX_CHARS, CLIP_FETCH_ATTEMPTS, CLIP_FETCH_TIMEOUT_MS, IMAGE_FETCH_ATTEMPTS, IMAGE_FETCH_TIMEOUT_MS, MAX_CLIPS, MAX_CLIP_BYTES, MAX_IMAGES, type ChatAudio, type ChatImage, type ChatTurn, type ChatTurnOptions, type FetchOptions, type Transcriber, attachmentsNote, buildChatTurn, cardActionNote, chatAttachmentOrigin, chatImageData, chatImageDataUrl, fetchChatAudio, fetchChatImages, spoolClip, transcribeVoiceMessages, } from "./attachments.js";
+export { AMBIENT_BACKSTOP_MS, AMBIENT_SOURCE_ORDER, DEFAULT_AMBIENT_MAX_PER_MINUTE, MAX_QUEUED_AMBIENT_IMAGES, AmbientVision, type AmbientImage, type AmbientSession, type AmbientSink, type AmbientVisionOptions, ambientImageDataUrl, } from "./ambient.js";
+export { type Logger, setLogger } from "./log.js";
+export { MEDIA_ROOTS_ENV, type AgentMedia, type LoadMediaOptions, loadMedia, mediaRoots, parseMedia, } from "./media.js";
+export { DEFAULT_MAX_UTTERANCE_MS, DEFAULT_MIN_UTTERANCE_MS, DEFAULT_PREROLL_MS, DEFAULT_SILENCE_MS, DEFAULT_SPEECH_RMS, PacedPlayback, UtteranceSegmenter, type FrameSink, type Playback, type SegmenterOptions, decodeWav, encodeWav, } from "./voice.js";
+export { DOCUMENT_NOT_ATTACHED, MAX_TRANSCRIPT_CHARS, MAX_TRANSCRIPT_ENTRIES, MAX_TRANSCRIPT_ENTRY_CHARS, MAX_TRANSCRIPT_TURNS, MAX_TRANSCRIPT_VISUALS, MINUTES_TOOL, RECAP_MIN_TURNS, Transcript, type DeliveryTarget, type MinutesSection, type MinutesTargetOptions, type PostMinutesOptions, type PostOutcome, type Poster, type RecapResult, type Summariser, type TranscriptOptions, type Turn, type TurnRole, hasSpeakerPrefix, isSummaryRequest, minutesPrompt, parseMinutesSections, postMinutes, resolveMinutesTarget, writeMinutesDocx, } from "./minutes.js";
+export { CHAR_VISEMES, SILENCE_VISEME, TurnLipSync, estimateVisemes, visemeForChar, visemesFromAlignment, type TurnLipSyncOptions, } from "./lipsync.js";
+export { OutboundCaller, OutboundError, OutboundPolicy, PendingMessages, type OutboundCallerOptions, type OutboundPolicyOptions, type PendingMessage, type PlacedCall, stateDir, CALL_BACK_TOOL, CHAT_CALLBACK_TOOL, CHAT_CALLBACK_WINDOW_MS, DEFAULT_ANSWER_TIMEOUT_MS, MAX_PENDING_TEXT_CHARS, NO_ANSWER_PREFIX, OUTCOME_WORDING, UNANSWERED_OUTCOMES, OutboundLane, OutboundLeg, type ChatCallbackTarget, type ChatSender, type OutboundLaneOptions, type OutboundSession, type Speak, callThreadIsPostable, } from "./outbound.js";
+export { NUM_CHANNELS, SAMPLE_RATE_HZ, type Caller, type SessionStart, assistantCancel, audioFrame, contextSentences, decodePcm, parseMessage, parseSessionStart, pong, sessionEnd, } from "./protocol.js";
+export { MAX_TILE_FPS, TILE_HEIGHT, TILE_WIDTH, TileStream, type Encoder, type TileStreamOptions, jpegEncoder, } from "./tile.js";
+export { DISPLAY_MODES, KeyframeStore, PAGE_DISPLAY_MS, PAGE_RENDER_TIMEOUT_MS, MAX_SLIDESHOW_IMAGES, SLIDESHOW_HOLD_MS, SLIDESHOW_OVERLAP_MS, ShownImage, VisionBudget, VisionTools, displayImageName, normalizeDisplayMode, type PageRenderer, type ShowItem, type Speaker, type VisionToolsOptions, type WalkthroughStep, } from "./visionTools.js";
+export { MAX_PENDING_AUDIO, MAX_PENDING_CONTEXT, StartupBuffer, } from "./startup.js";
+export { VERSION } from "./version.js";
+export { DISPLAY_IMAGE_MIME_TYPES, MAX_IMAGE_BYTES, VIDEO_SOURCES, FrameDescriber, type FrameDescriberOptions, type DisplayFrameOptions, type DisplayImageMime, type DisplayImageMode, type DisplayImageOptions, type VideoFrame, type VideoSource, displayFrame, displayImage, parseVideoFrame, fallbackOwner, frameCaption, frameDigest, frameOwner, } from "./vision.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * StandIn SDK - put your AI agent into a Microsoft Teams call.
+ *
+ * StandIn (https://standin.komaa.com) is the hosted bridge that joins the Microsoft Teams
+ * call: it owns the Microsoft side entirely - the bot registration, Graph, media
+ * negotiation, the avatar tile - and speaks to your worker over one
+ * authenticated socket per call. This package is that socket's other end.
+ *
+ * The Python SDK (`standin-sdk` on PyPI) is the same API, same seam, same wire
+ * protocol. Which one you use is decided by the framework you are integrating,
+ * not by preference.
+ *
+ * This module is the CORE, and it is the whole reason one package works: it
+ * imports nothing from `plugins/`, so `import { CallServer } from
+ * "@komaa/standin-sdk"` succeeds on a machine with no framework installed at
+ * all. A plugin is reached by its own subpath - `@komaa/standin-sdk/echo`,
+ * `@komaa/standin-sdk/openclaw` - and only a caller that already has that
+ * framework ever loads it. Keep it that way: one framework import at the top of
+ * a file reachable from here would break every install that does not use it.
+ *
+ * You do not normally use this directly. Reach for the plugin for your
+ * framework; the root-level examples show a complete deployment of each.
+ *
+ * Writing a plugin is the other direction, and it is deliberately small -
+ * see {@link CallHandler}, or copy `plugins/echo`, which answers a real
+ * call in under 100 lines.
+ */
+export { BYTES_PER_SAMPLE, FRAME_BYTES, FRAME_MS, REALTIME_SAMPLE_RATE_HZ, FrameAligner, frameDurationMs, pcm16Rms, resamplePcm16, } from "./audio.js";
+export { EMOTIONS, ExpressionCue, MAX_EMOTION_CHARS, MAX_VISEME_ID, expression, inferEmotion, speechMarks, } from "./avatar.js";
+export { MAX_AUDIO_BUFFER_BYTES, CallServer, } from "./callServer.js";
+export { TROUBLE_ANSWERING, TROUBLE_HEARING, TROUBLE_SPEAKING, VoiceLane, } from "./lane.js";
+export { SyntheticCall, runSmoke, report as smokeReport, } from "./smoke.js";
+export { LiveCalls, TENANT_ENV, VoiceDelivery, } from "./delivery.js";
+export { BUILT_IN_TOOLS, SHOW_PAGE_TOOL, CallTools, toolSchemas, } from "./callTools.js";
+export { flag, jsonObject, optional, required, vendorHost } from "./config.js";
+export { BACKGROUND_TASK_TOOL, CONSULT_TOOL, DEFAULT_CONSULT_TIMEOUT_MS, DEFAULT_RESUME_LIMIT, DEFAULT_TASK_TIMEOUT_MS, DEFAULT_TASK_TTL_MS, BackgroundTasks, Consultant, } from "./consult.js";
+export { CHAT_FALLBACK_WINDOW_MS, PersonalChats, DEFAULT_CHAT_URL, OUTBOUND_IMAGE_CONTENT_TYPES, OUTBOUND_IMAGE_MAX_BYTES, SCHEMA_VERSION, ChatChannel, buildReply, isPersonal, outboundImage, parseInbound, sanitizeImageName, sniffImageType, } from "./chat.js";
+export { ECHO_BARGE_IN_RMS, ECHO_SUPPRESSION_WINDOW_MS, pcm16Rms as echoPcm16Rms, shouldSuppressEcho, } from "./echoGuard.js";
+export { StandInError } from "./errors.js";
+export { DEFAULT_FOLLOW_UP_WINDOW_MS, GroupGate, isAddressed, isMeetingThread, isVerbalInterrupt, } from "./gate.js";
+export { describeInboundRejection, isAllowlistedCaller, isInboundCallAllowed, normalizePhoneNumber, } from "./policy.js";
+export { assertPublicHttpUrl, fetchPublicImage, isForbiddenIp, } from "./fetch.js";
+export { CHAT_REPLAY_WINDOW_MS, REPLAY_WINDOW_MS, SIGNATURE_HEADER, SIGNATURE_V2_HEADER, TIMESTAMP_HEADER, canonicalRequest, nowMs, signBody, signHandshake, signRequest, verifyBody, verifyHandshake, } from "./hmac.js";
+export { ATTACHMENT_NOTE_MAX_LINES, CARD_PAYLOAD_MAX_CHARS, CLIP_FETCH_ATTEMPTS, CLIP_FETCH_TIMEOUT_MS, IMAGE_FETCH_ATTEMPTS, IMAGE_FETCH_TIMEOUT_MS, MAX_CLIPS, MAX_CLIP_BYTES, MAX_IMAGES, attachmentsNote, buildChatTurn, cardActionNote, chatAttachmentOrigin, chatImageData, chatImageDataUrl, fetchChatAudio, fetchChatImages, spoolClip, transcribeVoiceMessages, } from "./attachments.js";
+export { AMBIENT_BACKSTOP_MS, AMBIENT_SOURCE_ORDER, DEFAULT_AMBIENT_MAX_PER_MINUTE, MAX_QUEUED_AMBIENT_IMAGES, AmbientVision, ambientImageDataUrl, } from "./ambient.js";
+export { setLogger } from "./log.js";
+export { MEDIA_ROOTS_ENV, loadMedia, mediaRoots, parseMedia, } from "./media.js";
+export { DEFAULT_MAX_UTTERANCE_MS, DEFAULT_MIN_UTTERANCE_MS, DEFAULT_PREROLL_MS, DEFAULT_SILENCE_MS, DEFAULT_SPEECH_RMS, PacedPlayback, UtteranceSegmenter, decodeWav, encodeWav, } from "./voice.js";
+export { DOCUMENT_NOT_ATTACHED, MAX_TRANSCRIPT_CHARS, MAX_TRANSCRIPT_ENTRIES, MAX_TRANSCRIPT_ENTRY_CHARS, MAX_TRANSCRIPT_TURNS, MAX_TRANSCRIPT_VISUALS, MINUTES_TOOL, RECAP_MIN_TURNS, Transcript, hasSpeakerPrefix, isSummaryRequest, minutesPrompt, parseMinutesSections, postMinutes, resolveMinutesTarget, writeMinutesDocx, } from "./minutes.js";
+export { CHAR_VISEMES, SILENCE_VISEME, TurnLipSync, estimateVisemes, visemeForChar, visemesFromAlignment, } from "./lipsync.js";
+export { OutboundCaller, OutboundError, OutboundPolicy, PendingMessages, stateDir, CALL_BACK_TOOL, CHAT_CALLBACK_TOOL, CHAT_CALLBACK_WINDOW_MS, DEFAULT_ANSWER_TIMEOUT_MS, MAX_PENDING_TEXT_CHARS, NO_ANSWER_PREFIX, OUTCOME_WORDING, UNANSWERED_OUTCOMES, OutboundLane, OutboundLeg, callThreadIsPostable, } from "./outbound.js";
+export { NUM_CHANNELS, SAMPLE_RATE_HZ, assistantCancel, audioFrame, contextSentences, decodePcm, parseMessage, parseSessionStart, pong, sessionEnd, } from "./protocol.js";
+export { MAX_TILE_FPS, TILE_HEIGHT, TILE_WIDTH, TileStream, jpegEncoder, } from "./tile.js";
+export { DISPLAY_MODES, KeyframeStore, PAGE_DISPLAY_MS, PAGE_RENDER_TIMEOUT_MS, MAX_SLIDESHOW_IMAGES, SLIDESHOW_HOLD_MS, SLIDESHOW_OVERLAP_MS, ShownImage, VisionBudget, VisionTools, displayImageName, normalizeDisplayMode, } from "./visionTools.js";
+export { MAX_PENDING_AUDIO, MAX_PENDING_CONTEXT, StartupBuffer, } from "./startup.js";
+export { VERSION } from "./version.js";
+export { DISPLAY_IMAGE_MIME_TYPES, MAX_IMAGE_BYTES, VIDEO_SOURCES, FrameDescriber, displayFrame, displayImage, parseVideoFrame, fallbackOwner, frameCaption, frameDigest, frameOwner, } from "./vision.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}