@komaa/standin-sdk 0.1.0

package/dist/callServer.d.ts

@@ -0,0 +1,151 @@
+import type { CallHandler, HandlerFactory } from "./handler.js";
+/**
+ * Outbound bytes past which agent audio is dropped rather than queued.
+ *
+ * A slow or wedged peer turns "send everything" into an unbounded queue, and
+ * that queue is what stalls the provider receive loop feeding it. Shedding keeps
+ * the loop moving: the caller hears a gap rather than the call wedging.
+ *
+ * Audio only. Control frames are what END a call, and a call that cannot be
+ * ended is the failure this exists to prevent.
+ */
+export declare const MAX_AUDIO_BUFFER_BYTES: number;
+/**
+ * How long a call may go without an agent ever answering it.
+ *
+ * The one gap none of the other watchdogs cover. `preStartTimeoutMs` watches for
+ * session.start, which arrived. `onStartTimeoutMs` bounds onStart, which
+ * succeeded. `audioIdleTimeoutMs` is satisfied because the CALLER is still
+ * talking. So StandIn is on the call, the caller hears nothing, and nothing ends
+ * it.
+ */
+export declare const STALE_CALL_REAPER_MS = 120000;
+/**
+ * How often to look. Coarse on purpose: this is a grace period, not something
+ * anybody measures to the second.
+ */
+export declare const REAPER_CHECK_INTERVAL_MS = 15000;
+export declare const REAPER_MIN_INTERVAL_MS = 50;
+/**
+ * Whether this call has run past its grace with nothing answering it.
+ *
+ * Pure, with the clock passed in, so the boundary is testable without waiting.
+ * Strictly greater, so a tick landing exactly on the grace does not reap a call
+ * one instant early.
+ */
+export declare function isUnanswered(call: {
+    startedAtMs: number;
+    answeredAtMs?: number;
+}, staleMs: number, now: number): boolean;
+/** Options for {@link CallServer}. */
+export interface CallServerOptions {
+    /** Builds one {@link CallHandler} per call. This is the plugin. */
+    handlerFactory: HandlerFactory;
+    /**
+     * Called with (callId, outcome) when StandIn reports how an outbound call
+     * ended without anyone answering.
+     *
+     * Set it and the route exists; leave it and a POST there is a 404, so a
+     * worker that never places a call opens no extra surface.
+     */
+    onCallOutcome?: (callId: string, outcome: string) => void | Promise<void>;
+    /**
+     * The connection secret from the StandIn portal. Must byte-match, or the
+     * handshake is rejected with 401. Defaults to `STANDIN_SECRET`.
+     */
+    secret?: string;
+    /** Bind address. Defaults to `STANDIN_HOST` then `0.0.0.0`. */
+    host?: string;
+    /** Port. Defaults to `STANDIN_PORT` then 9442. */
+    port?: number;
+    /** Path StandIn dials. Defaults to `STANDIN_WS_PATH` then `/msteams/calling`. */
+    wsPath?: string;
+    /** Concurrent live calls, checked before any crypto runs. */
+    maxConnections?: number;
+    /** Ms a socket may stay silent after authenticating before it is dropped. */
+    preStartTimeoutMs?: number;
+    /** Ms without caller audio before a live call is declared dead (0 disables). */
+    audioIdleTimeoutMs?: number;
+    /**
+     * Ms a handler's onStart may take before the call is given up (0 disables).
+     * It does real network work - joining a room, opening a provider socket - and
+     * the frame loop is queued behind it, so an unbounded one holds a slot for the
+     * life of the worker.
+     */
+    onStartTimeoutMs?: number;
+    /**
+     * A hard ceiling on ONE call, from `session.start` (0 disables).
+     *
+     * Different from `audioIdleTimeoutMs`, which ends a call that went quiet: this
+     * one ends a call that is still going. A caller who will not hang up, a model
+     * looping at itself, an automated system that dialled and never stopped
+     * talking, all bill a provider by the minute for as long as the socket lives.
+     */
+    maxCallMs?: number;
+    /**
+     * What to say before hanging up on the limit. Delivered through the handler's
+     * `onGoodbye`, the same callback StandIn's own closing line uses, so a plugin
+     * needs no new code to honour it.
+     */
+    goodbyeText?: string;
+    /** Ms to let that line finish before the call ends. */
+    goodbyeGraceMs?: number;
+    /**
+     * Ms a call may run with nothing having answered it (0 disables).
+     *
+     * The gap none of the other watchdogs cover: an agent dispatch that never
+     * lands leaves StandIn on the call, the caller hearing nothing, and no timer
+     * that fires.
+     */
+    staleCallReaperMs?: number;
+}
+/**
+ * Answers the socket StandIn dials, and hands each call to a plugin.
+ *
+ * Defaults match the StandIn plugin layout: port 9442, path `/msteams/calling`.
+ * `0.0.0.0` because the worker usually runs in a container behind an ingress;
+ * bind `127.0.0.1` when only a local tunnel should reach the listener (the
+ * upgrade is HMAC-authenticated either way).
+ */
+export declare class CallServer {
+    #private;
+    readonly preStartTimeoutMs: number;
+    readonly audioIdleTimeoutMs: number;
+    readonly onStartTimeoutMs: number;
+    readonly maxCallMs: number;
+    readonly goodbyeText: string;
+    readonly goodbyeGraceMs: number;
+    readonly staleCallReaperMs: number;
+    /** Stop accepting new calls; live ones continue. */
+    draining: boolean;
+    constructor(options: CallServerOptions);
+    get wsPath(): string;
+    /** The interface the listener is bound to, or will be. */
+    get host(): string;
+    get port(): number;
+    get activeCalls(): number;
+    /**
+     * Whether the listener is actually bound.
+     *
+     * A host that calls connect twice today binds a second listener and leaks the
+     * first, and has no way to ask whether the bind succeeded, so it reports a
+     * dead platform as connected.
+     */
+    get running(): boolean;
+    /** @internal */
+    buildHandler(): CallHandler;
+    /** @internal */
+    release(callId: string): void;
+    /**
+     * Bind the listener. Transactional: either it is listening when this resolves,
+     * or nothing of it survives.
+     */
+    start(): Promise<void>;
+    /**
+     * Drain live calls, then stop listening. Awaits the calls' REAL teardown - a
+     * close that early-returns on an in-flight closer would let the process exit
+     * with teardown still pending, leaking sessions.
+     */
+    aclose(): Promise<void>;
+}
+//# sourceMappingURL=callServer.d.ts.map

package/dist/callServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callServer.d.ts","sourceRoot":"","sources":["../src/callServer.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,WAAW,EAAe,cAAc,EAAE,MAAM,cAAc,CAAC;AAuF7E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAOzC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAMT;AA6pBD,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,cAAc,EAAE,cAAc,CAAC;IAE/B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;;IASrB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAcnC,oDAAoD;IACpD,QAAQ,UAAS;gBAEL,OAAO,EAAE,iBAAiB;IAuCtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,0DAA0D;IAC1D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;;OAMG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gBAAgB;IAChB,YAAY,IAAI,WAAW;IAI3B,gBAAgB;IAChB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IA0F7B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4F5B;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAsH9B"}