@siphon-project/control 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +155 -0
- package/dist/index.cjs +970 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +588 -0
- package/dist/index.d.ts +588 -0
- package/dist/index.js +943 -0
- package/dist/index.js.map +1 -0
- package/package.json +67 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,588 @@
|
|
|
1
|
+
import * as node_net from 'node:net';
|
|
2
|
+
import { AddressInfo } from 'node:net';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The client error type for the SIPhon control plane.
|
|
6
|
+
*
|
|
7
|
+
* The load-bearing case is a server `status:"error"` reply, which becomes a
|
|
8
|
+
* {@link ControlError} carrying the stable {@link ControlErrorCode} in `.code`
|
|
9
|
+
* so callers can branch on the cause (e.g. treat `unsupported_verb` as "the
|
|
10
|
+
* server doesn't do media yet" rather than a hard failure). Mirrors the Rust
|
|
11
|
+
* `ControlError` enum and the Python `ControlError` exception.
|
|
12
|
+
*/
|
|
13
|
+
/** Stable machine-readable error codes returned in a reply's `error.code`. */
|
|
14
|
+
type ControlErrorCode = "unauthorized" | "forbidden" | "not_found" | "bad_request" | "rate_limited" | "originate_denied" | "unsupported_verb" | "unsupported_version" | "protocol_error" | "unavailable";
|
|
15
|
+
/**
|
|
16
|
+
* How a {@link ControlError} arose. `command` is the wire-level rejection (it
|
|
17
|
+
* carries a {@link ControlErrorCode}); the rest are transport / local failures
|
|
18
|
+
* that never had a wire code.
|
|
19
|
+
*/
|
|
20
|
+
type ControlErrorKind = "command" | "unauthorized" | "handshake" | "closed" | "timeout" | "websocket" | "config";
|
|
21
|
+
/** Everything that can go wrong driving the control plane. */
|
|
22
|
+
declare class ControlError extends Error {
|
|
23
|
+
/** The classification of this error. */
|
|
24
|
+
readonly kind: ControlErrorKind;
|
|
25
|
+
/** The stable wire code, present only for a `command` rejection. */
|
|
26
|
+
readonly code?: ControlErrorCode;
|
|
27
|
+
/** The HTTP status of a rejected upgrade, present only for `unauthorized`. */
|
|
28
|
+
readonly status?: number;
|
|
29
|
+
constructor(kind: ControlErrorKind, message: string, options?: {
|
|
30
|
+
code?: ControlErrorCode;
|
|
31
|
+
status?: number;
|
|
32
|
+
});
|
|
33
|
+
/**
|
|
34
|
+
* True when this is a server-side `unsupported_verb` rejection — the state a
|
|
35
|
+
* media verb (`playFile`/`dtmf`/…) lands in until the server implements it.
|
|
36
|
+
*/
|
|
37
|
+
isUnsupportedVerb(): boolean;
|
|
38
|
+
/** A server `status:"error"` reply. */
|
|
39
|
+
static command(code: ControlErrorCode, message: string): ControlError;
|
|
40
|
+
/** The WebSocket upgrade was rejected before it opened (bad/missing token). */
|
|
41
|
+
static unauthorized(status: number): ControlError;
|
|
42
|
+
/** The `hello` handshake (or subprotocol negotiation) failed. */
|
|
43
|
+
static handshake(detail: string): ControlError;
|
|
44
|
+
/** The connection is closed (or was never established). */
|
|
45
|
+
static closed(): ControlError;
|
|
46
|
+
/** A command was sent but no reply arrived within the configured window. */
|
|
47
|
+
static timeout(timeoutMs: number): ControlError;
|
|
48
|
+
/** A transport-level WebSocket error. */
|
|
49
|
+
static websocket(detail: string): ControlError;
|
|
50
|
+
/** A configuration value was invalid (bad URL, bad listen address, …). */
|
|
51
|
+
static config(detail: string): ControlError;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Wire protocol for the SIPhon external control plane (`siphon-control.v1`).
|
|
56
|
+
*
|
|
57
|
+
* This module is the TypeScript mirror of the Rust `siphon-control-proto` crate
|
|
58
|
+
* and the server's inline `src/control/protocol.rs`. The frame shapes here are
|
|
59
|
+
* **byte-identical** to what the server emits and parses:
|
|
60
|
+
*
|
|
61
|
+
* - **command** (client → siphon): `{id, type:"command", module?, verb, target, args}`
|
|
62
|
+
* - **reply** (siphon → client, `id` echoed): `{id, type:"reply", status, result|error}`
|
|
63
|
+
* - **event** (siphon → client, un-id'd, pushed): `{type:"event", event, channel?, app?, call_id?, sip_call_id?, payload?}`
|
|
64
|
+
*
|
|
65
|
+
* `module` routes a command to the registered adapter (`sip`|`smpp`|`ss7`);
|
|
66
|
+
* substrate verbs (`hello`, `resync`, `describe`, `set_var`, `get_var`) omit it.
|
|
67
|
+
*/
|
|
68
|
+
/** The WebSocket subprotocol token this rail speaks. */
|
|
69
|
+
declare const SUBPROTOCOL = "siphon-control.v1";
|
|
70
|
+
/** The protocol version this build implements. */
|
|
71
|
+
declare const PROTOCOL_VERSION = 1;
|
|
72
|
+
/** Adapter routing key for the built-in SIP adapter. */
|
|
73
|
+
declare const MODULE_SIP = "sip";
|
|
74
|
+
/** Adapter routing key for an SMPP adapter (registered by a host binary). */
|
|
75
|
+
declare const MODULE_SMPP = "smpp";
|
|
76
|
+
/** Adapter routing key for an SS7 adapter (registered by a host binary). */
|
|
77
|
+
declare const MODULE_SS7 = "ss7";
|
|
78
|
+
/** The mandatory first-frame handshake verb. */
|
|
79
|
+
declare const HELLO = "hello";
|
|
80
|
+
/** Substrate verb: re-enumerate the channels this connection owns. */
|
|
81
|
+
declare const RESYNC = "resync";
|
|
82
|
+
/** Substrate verb: fetch the registered adapters' schema. */
|
|
83
|
+
declare const DESCRIBE = "describe";
|
|
84
|
+
/** Substrate verb: set a per-channel variable. */
|
|
85
|
+
declare const SET_VAR = "set_var";
|
|
86
|
+
/** Substrate verb: read a per-channel variable. */
|
|
87
|
+
declare const GET_VAR = "get_var";
|
|
88
|
+
/** The `type` discriminator on every frame. */
|
|
89
|
+
type FrameType = "command" | "reply" | "event";
|
|
90
|
+
/** The status of a reply. */
|
|
91
|
+
type ReplyStatus = "ok" | "error";
|
|
92
|
+
|
|
93
|
+
/** The error body of a failed reply. */
|
|
94
|
+
interface ReplyError {
|
|
95
|
+
code: ControlErrorCode;
|
|
96
|
+
message: string;
|
|
97
|
+
}
|
|
98
|
+
/** A reply frame (siphon → client, `id` echoed). */
|
|
99
|
+
interface ReplyFrame {
|
|
100
|
+
id: string;
|
|
101
|
+
type: "reply";
|
|
102
|
+
status: ReplyStatus;
|
|
103
|
+
/** Present on success. */
|
|
104
|
+
result?: unknown;
|
|
105
|
+
/** Present on failure. */
|
|
106
|
+
error?: ReplyError;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* A pushed event frame (siphon → client, un-id'd).
|
|
110
|
+
*
|
|
111
|
+
* Carries the stable id triple `{channel, call_id, sip_call_id}` so a controller
|
|
112
|
+
* joins CDR + HEP with no mapping table: `sip_call_id` is byte-identical to the
|
|
113
|
+
* CDR `call_id` and the HEP correlation chunk.
|
|
114
|
+
*/
|
|
115
|
+
interface EventFrame {
|
|
116
|
+
type: "event";
|
|
117
|
+
/** Event name (e.g. `"StasisStart"`, `"StasisEnd"`). */
|
|
118
|
+
event: string;
|
|
119
|
+
/** The channel this event concerns (leg-scoped id), when applicable. */
|
|
120
|
+
channel?: string;
|
|
121
|
+
/** The application the channel was handed to. */
|
|
122
|
+
app?: string;
|
|
123
|
+
/** The internal call UUID (`CallActor.id`) — the grouping key across legs. */
|
|
124
|
+
call_id?: string;
|
|
125
|
+
/** The per-leg SIP Call-ID — the CDR / HEP join key. */
|
|
126
|
+
sip_call_id?: string;
|
|
127
|
+
/** Event-specific payload. */
|
|
128
|
+
payload?: unknown;
|
|
129
|
+
}
|
|
130
|
+
/** Arguments of the `hello` handshake command. */
|
|
131
|
+
interface HelloArgs {
|
|
132
|
+
app: string;
|
|
133
|
+
protocol?: number;
|
|
134
|
+
}
|
|
135
|
+
/** The `result` of a successful `hello` reply. */
|
|
136
|
+
interface HelloResult {
|
|
137
|
+
app: string;
|
|
138
|
+
protocol: number;
|
|
139
|
+
subprotocol: string;
|
|
140
|
+
}
|
|
141
|
+
/** One channel in a `resync` reply — the id triple plus its state + vars. */
|
|
142
|
+
interface ChannelSnapshot {
|
|
143
|
+
channel: string;
|
|
144
|
+
call_id: string;
|
|
145
|
+
sip_call_id: string;
|
|
146
|
+
state: string;
|
|
147
|
+
vars: Record<string, string>;
|
|
148
|
+
}
|
|
149
|
+
/** The `result` of a successful `resync` reply. */
|
|
150
|
+
interface ResyncResult {
|
|
151
|
+
channels: ChannelSnapshot[];
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Serialize a command frame to the exact JSON bytes the server parses.
|
|
155
|
+
*
|
|
156
|
+
* Field order follows the server's struct declaration order — `id`, `type`,
|
|
157
|
+
* `module` (omitted when absent), `verb`, `target`, `args` — so the bytes are
|
|
158
|
+
* identical to the Rust `CommandFrame` serialization. `target`/`args` are always
|
|
159
|
+
* emitted (defaulting to JSON `null`); `module` is dropped when null/undefined.
|
|
160
|
+
*/
|
|
161
|
+
declare function encodeCommand(id: string, module: string | null | undefined, verb: string, target: unknown, args: unknown): string;
|
|
162
|
+
/** Parse an inbound text frame into a {@link ReplyFrame} or {@link EventFrame}. */
|
|
163
|
+
declare function parseInboundFrame(text: string): ReplyFrame | EventFrame | null;
|
|
164
|
+
/**
|
|
165
|
+
* The verbs the built-in SIP adapter accepts (`module = "sip"`).
|
|
166
|
+
*
|
|
167
|
+
* These are the exact wire tokens. The Phase-1 server implements
|
|
168
|
+
* `answer`/`progress`/`reject`/`hangup`/`refer`/`set_header`/`get_header`;
|
|
169
|
+
* the rest (`remove_header`, `accept_refer`, `reject_refer`, `play`, `dtmf`)
|
|
170
|
+
* are accepted names the server answers `unsupported_verb` until it implements
|
|
171
|
+
* them.
|
|
172
|
+
*/
|
|
173
|
+
declare const SipVerb: {
|
|
174
|
+
readonly Answer: "answer";
|
|
175
|
+
readonly Progress: "progress";
|
|
176
|
+
readonly Reject: "reject";
|
|
177
|
+
readonly Hangup: "hangup";
|
|
178
|
+
readonly Refer: "refer";
|
|
179
|
+
readonly SetHeader: "set_header";
|
|
180
|
+
readonly GetHeader: "get_header";
|
|
181
|
+
readonly RemoveHeader: "remove_header";
|
|
182
|
+
readonly AcceptRefer: "accept_refer";
|
|
183
|
+
readonly RejectRefer: "reject_refer";
|
|
184
|
+
readonly Play: "play";
|
|
185
|
+
readonly Dtmf: "dtmf";
|
|
186
|
+
};
|
|
187
|
+
/** A value of {@link SipVerb}. */
|
|
188
|
+
type SipVerbToken = (typeof SipVerb)[keyof typeof SipVerb];
|
|
189
|
+
/** The well-known SIP-adapter event names (the ARI *Stasis* model). */
|
|
190
|
+
type SipEventKind = "StasisStart" | "StasisEnd" | "ChannelStateChange" | "ChannelHangupRequest" | (string & {});
|
|
191
|
+
/** Parse a wire event name; unknown names pass through verbatim (forward-compatible). */
|
|
192
|
+
declare function sipEventKind(name: string): SipEventKind;
|
|
193
|
+
|
|
194
|
+
/** Small internal utilities shared by the client, server, and SIP facade. */
|
|
195
|
+
/**
|
|
196
|
+
* An unbounded, single-consumer async queue (the TypeScript analogue of Rust's
|
|
197
|
+
* `tokio::sync::mpsc::unbounded_channel`). `push` never blocks; `next` resolves
|
|
198
|
+
* with the next item, or `null` once the queue is closed and drained.
|
|
199
|
+
*/
|
|
200
|
+
declare class AsyncQueue<T> {
|
|
201
|
+
private readonly items;
|
|
202
|
+
private readonly waiters;
|
|
203
|
+
private closed;
|
|
204
|
+
/** Enqueue an item (or hand it directly to a waiting consumer). */
|
|
205
|
+
push(item: T): void;
|
|
206
|
+
/** Await the next item, or `null` once the queue is closed and drained. */
|
|
207
|
+
next(): Promise<T | null>;
|
|
208
|
+
/** Close the queue: pending and future `next()` calls resolve with `null`. */
|
|
209
|
+
close(): void;
|
|
210
|
+
/** Async-iterate the queue until it closes. */
|
|
211
|
+
[Symbol.asyncIterator](): AsyncIterableIterator<T>;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* One live WebSocket connection: request-id correlation, the read path, and
|
|
216
|
+
* generic event fan-out. Knows nothing about SIP — it moves opaque `{module,
|
|
217
|
+
* verb, target, args}` frames and hands every event to a sink.
|
|
218
|
+
*
|
|
219
|
+
* Shared verbatim by the inbound client and the per-call-connect server; only
|
|
220
|
+
* how the socket is *acquired* differs. Mirrors the Rust `SessionCore`.
|
|
221
|
+
*/
|
|
222
|
+
|
|
223
|
+
/** A sink the read path calls for every inbound event frame (any module). */
|
|
224
|
+
type EventSink = (frame: EventFrame) => void;
|
|
225
|
+
/**
|
|
226
|
+
* Anything that can send a control command and await its correlated reply.
|
|
227
|
+
*
|
|
228
|
+
* Implemented by {@link Session} (bound to one connection — the per-call-connect
|
|
229
|
+
* server) and by the client's commander (routes to the current session,
|
|
230
|
+
* surviving reconnects — the inbound client). Lets a facade's handle command its
|
|
231
|
+
* call without caring which mode it runs in.
|
|
232
|
+
*/
|
|
233
|
+
interface CommandTransport {
|
|
234
|
+
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/**
|
|
238
|
+
* The protocol-agnostic inbound-persistent control client.
|
|
239
|
+
*
|
|
240
|
+
* Knows nothing about SIP: it owns the transport, the `hello` handshake,
|
|
241
|
+
* request-id correlation, reconnect + `resync`, and a generic event stream. Its
|
|
242
|
+
* headline primitive is {@link ControlClient.command} over `{module, verb,
|
|
243
|
+
* target, args}`, which works for any adapter with zero changes. Typed
|
|
244
|
+
* per-protocol facades (see {@link SipClient}) are built on top. Mirrors the
|
|
245
|
+
* Rust `ControlClient`.
|
|
246
|
+
*/
|
|
247
|
+
|
|
248
|
+
/** How a {@link ControlClient} connects and behaves. */
|
|
249
|
+
interface ClientConfig {
|
|
250
|
+
/** The control-plane URL, e.g. `ws://siphon:9090/control/ws` (or `wss://…`). */
|
|
251
|
+
url: string;
|
|
252
|
+
/** The application name — must equal the token's configured app. */
|
|
253
|
+
app: string;
|
|
254
|
+
/** The bearer token presented on the upgrade. */
|
|
255
|
+
token: string;
|
|
256
|
+
/** Protocol version to advertise in `hello` (defaults to {@link PROTOCOL_VERSION}). */
|
|
257
|
+
protocol?: number;
|
|
258
|
+
/** How long a command waits for its reply before a timeout (default 10 000 ms). */
|
|
259
|
+
replyTimeoutMs?: number;
|
|
260
|
+
/** Backoff between reconnect attempts in {@link ControlClient.run} (default 1 000 ms). */
|
|
261
|
+
reconnectBackoffMs?: number;
|
|
262
|
+
}
|
|
263
|
+
/** An item on the client's generic event stream. */
|
|
264
|
+
type ClientEvent = {
|
|
265
|
+
type: "event";
|
|
266
|
+
frame: EventFrame;
|
|
267
|
+
} | {
|
|
268
|
+
type: "reattach";
|
|
269
|
+
snapshot: ChannelSnapshot;
|
|
270
|
+
};
|
|
271
|
+
type EventCallback = (event: ClientEvent) => void;
|
|
272
|
+
/** A generic subscription to the client's event stream (see {@link ControlClient.events}). */
|
|
273
|
+
declare class EventStream {
|
|
274
|
+
private readonly queue;
|
|
275
|
+
constructor(queue: AsyncQueue<ClientEvent>);
|
|
276
|
+
/** Await the next event. `null` once the client shuts down. */
|
|
277
|
+
next(): Promise<ClientEvent | null>;
|
|
278
|
+
[Symbol.asyncIterator](): AsyncIterableIterator<ClientEvent>;
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* The protocol-agnostic inbound-persistent control client.
|
|
282
|
+
*
|
|
283
|
+
* Use {@link ControlClient.command} directly for any module, or wrap it in a
|
|
284
|
+
* typed facade such as {@link SipClient}.
|
|
285
|
+
*/
|
|
286
|
+
declare class ControlClient {
|
|
287
|
+
private readonly config;
|
|
288
|
+
private readonly nextId;
|
|
289
|
+
private current;
|
|
290
|
+
private eventCallback;
|
|
291
|
+
private shutdownRequested;
|
|
292
|
+
private readonly shutdownWaiters;
|
|
293
|
+
private constructor();
|
|
294
|
+
/**
|
|
295
|
+
* Connect + `hello`. A bad token surfaces as a {@link ControlError} of kind
|
|
296
|
+
* `unauthorized` (the upgrade is rejected 401 before the socket opens).
|
|
297
|
+
*/
|
|
298
|
+
static connect(config: ClientConfig): Promise<ControlClient>;
|
|
299
|
+
/**
|
|
300
|
+
* Register a callback for every event (pushed events + reconnect reattach).
|
|
301
|
+
* Overwrites any previous callback / stream. Facades set this internally.
|
|
302
|
+
*/
|
|
303
|
+
onEvent(callback: EventCallback): void;
|
|
304
|
+
/** A pull-style stream of every event. Overwrites any previous callback. */
|
|
305
|
+
events(): EventStream;
|
|
306
|
+
/**
|
|
307
|
+
* Send a raw command on the current session and return the reply's `result`.
|
|
308
|
+
* The generic primitive every facade is built on.
|
|
309
|
+
*/
|
|
310
|
+
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
311
|
+
/** Fetch the registered adapters' verb/event schema (`describe`). */
|
|
312
|
+
describe(): Promise<unknown>;
|
|
313
|
+
/** Re-enumerate the channels this connection owns (`resync`). */
|
|
314
|
+
resync(): Promise<ChannelSnapshot[]>;
|
|
315
|
+
/**
|
|
316
|
+
* A {@link CommandTransport} that routes to the client's *current* session (so
|
|
317
|
+
* a facade handle keeps working across reconnects). Used by {@link SipClient}.
|
|
318
|
+
*/
|
|
319
|
+
commander(): CommandTransport;
|
|
320
|
+
/**
|
|
321
|
+
* Drive the client: keep the connection alive, reconnecting with backoff and
|
|
322
|
+
* re-attaching owned channels (`resync`, delivered as `reattach` events) after
|
|
323
|
+
* each reconnect. Resolves on {@link ControlClient.shutdown}, or rejects on a
|
|
324
|
+
* fatal error (token revoked → `unauthorized`).
|
|
325
|
+
*/
|
|
326
|
+
run(): Promise<void>;
|
|
327
|
+
/** Stop the client: close the current session and unblock {@link ControlClient.run}. */
|
|
328
|
+
shutdown(): void;
|
|
329
|
+
private shutdownSignal;
|
|
330
|
+
private emit;
|
|
331
|
+
private connectAndHandshake;
|
|
332
|
+
private openSocket;
|
|
333
|
+
private resyncAndReattach;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* Outbound per-call-connect mode: siphon *dials the application* at handover,
|
|
338
|
+
* so the app is a WebSocket **server**. This is the documented default for
|
|
339
|
+
* multi-pod controllers — the accepting socket owns exactly that one call, so
|
|
340
|
+
* "the audio lands on the wrong pod" is structurally impossible.
|
|
341
|
+
*
|
|
342
|
+
* No `hello` is exchanged: siphon presents the token in the dial headers, and
|
|
343
|
+
* the first frame the app receives is a pushed event (`StasisStart` for SIP).
|
|
344
|
+
* Mirrors the Rust `ControlServer`.
|
|
345
|
+
*/
|
|
346
|
+
|
|
347
|
+
/** How a {@link ControlServer} listens for siphon's per-call dials. */
|
|
348
|
+
interface ServerConfig {
|
|
349
|
+
/** The host to bind (e.g. `0.0.0.0`). */
|
|
350
|
+
host: string;
|
|
351
|
+
/** The port to bind (`0` picks a free port — read it back via `localAddr`). */
|
|
352
|
+
port: number;
|
|
353
|
+
/** The application name (context / logging). */
|
|
354
|
+
app: string;
|
|
355
|
+
/** The bearer token siphon must present on the dial. */
|
|
356
|
+
token: string;
|
|
357
|
+
/** How long a command waits for its reply before a timeout (default 10 000 ms). */
|
|
358
|
+
replyTimeoutMs?: number;
|
|
359
|
+
}
|
|
360
|
+
/** A sink the server calls for each event, carrying the {@link CommandTransport}
|
|
361
|
+
* of the connection that produced it (so a facade commands back on the right one). */
|
|
362
|
+
type ConnectionEventSink = (frame: EventFrame, transport: CommandTransport) => void;
|
|
363
|
+
/** The protocol-agnostic per-call-connect control server. */
|
|
364
|
+
declare class ControlServer {
|
|
365
|
+
private readonly config;
|
|
366
|
+
private readonly wss;
|
|
367
|
+
private readonly nextId;
|
|
368
|
+
private eventSink;
|
|
369
|
+
private readonly closeWaiters;
|
|
370
|
+
private readonly sockets;
|
|
371
|
+
private closed;
|
|
372
|
+
private constructor();
|
|
373
|
+
/** Bind the listener (so the assigned port is known before accepting). */
|
|
374
|
+
static bind(config: ServerConfig): Promise<ControlServer>;
|
|
375
|
+
/** The actual bound address (useful when binding to port 0 in tests). */
|
|
376
|
+
localAddr(): AddressInfo;
|
|
377
|
+
/** Register the sink for `(event, connection-commander)` pairs. Facades set this internally. */
|
|
378
|
+
onConnectionEvent(sink: ConnectionEventSink): void;
|
|
379
|
+
/** Resolve once the server has been closed (`run` resolves at the same time). */
|
|
380
|
+
run(): Promise<void>;
|
|
381
|
+
/** Stop accepting dials, drop live connections, and close the listener. */
|
|
382
|
+
close(): Promise<void>;
|
|
383
|
+
private markClosed;
|
|
384
|
+
private onConnection;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/** One event delivered to a call's stream (`ChannelStateChange`,
|
|
388
|
+
* `ChannelHangupRequest`, `StasisEnd`, …). */
|
|
389
|
+
interface CallEvent {
|
|
390
|
+
/** The parsed event kind. */
|
|
391
|
+
kind: SipEventKind;
|
|
392
|
+
/** The event-specific payload. */
|
|
393
|
+
payload: unknown;
|
|
394
|
+
/** The raw frame (for fields not surfaced above). */
|
|
395
|
+
frame: EventFrame;
|
|
396
|
+
}
|
|
397
|
+
/** Options for a UAS provisional / final response (`answer` / `progress`). */
|
|
398
|
+
interface ResponseOptions {
|
|
399
|
+
code?: number;
|
|
400
|
+
reason?: string;
|
|
401
|
+
body?: string;
|
|
402
|
+
contentType?: string;
|
|
403
|
+
}
|
|
404
|
+
/** The RFC 3891 `Replaces` triple for an attended transfer. */
|
|
405
|
+
interface ReferReplaces {
|
|
406
|
+
callId: string;
|
|
407
|
+
fromTag: string;
|
|
408
|
+
toTag: string;
|
|
409
|
+
earlyOnly?: boolean;
|
|
410
|
+
}
|
|
411
|
+
/** Options for {@link Call.acceptRefer}. */
|
|
412
|
+
interface AcceptReferOptions {
|
|
413
|
+
target?: string;
|
|
414
|
+
nextHop?: string;
|
|
415
|
+
mode?: "terminate" | "transparent";
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* A handed-over SIP call. Cheap to hold (shares one connection + event stream).
|
|
419
|
+
* Verb names mirror the in-process `call.*` scripting API.
|
|
420
|
+
*/
|
|
421
|
+
declare class Call {
|
|
422
|
+
private readonly transport;
|
|
423
|
+
/** The leg-scoped channel id — the address for every verb on this call. */
|
|
424
|
+
readonly channelId: string;
|
|
425
|
+
/** The internal `CallActor` id (the grouping key across legs), if known. */
|
|
426
|
+
readonly callId: string | null;
|
|
427
|
+
/** The per-leg SIP `Call-ID` — byte-identical to the CDR / HEP join key. */
|
|
428
|
+
readonly sipCallId: string | null;
|
|
429
|
+
/** The application this call was handed to. */
|
|
430
|
+
readonly app: string | null;
|
|
431
|
+
/** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
|
|
432
|
+
readonly payload: unknown;
|
|
433
|
+
/** True when this call came from a `resync` re-attach after a reconnect. */
|
|
434
|
+
readonly reattached: boolean;
|
|
435
|
+
private readonly eventQueue;
|
|
436
|
+
constructor(transport: CommandTransport,
|
|
437
|
+
/** The leg-scoped channel id — the address for every verb on this call. */
|
|
438
|
+
channelId: string,
|
|
439
|
+
/** The internal `CallActor` id (the grouping key across legs), if known. */
|
|
440
|
+
callId: string | null,
|
|
441
|
+
/** The per-leg SIP `Call-ID` — byte-identical to the CDR / HEP join key. */
|
|
442
|
+
sipCallId: string | null,
|
|
443
|
+
/** The application this call was handed to. */
|
|
444
|
+
app: string | null,
|
|
445
|
+
/** The `StasisStart` payload (full SIP context), or the `resync` snapshot. */
|
|
446
|
+
payload: unknown,
|
|
447
|
+
/** True when this call came from a `resync` re-attach after a reconnect. */
|
|
448
|
+
reattached: boolean, eventQueue: AsyncQueue<CallEvent>);
|
|
449
|
+
private target;
|
|
450
|
+
private sip;
|
|
451
|
+
private substrate;
|
|
452
|
+
/** Send a UAS 2xx to the parked A-leg (default `200 OK`). */
|
|
453
|
+
answer(options?: ResponseOptions): Promise<void>;
|
|
454
|
+
/** Send a UAS 1xx / early media (default `183 Session Progress`). */
|
|
455
|
+
progress(options?: ResponseOptions): Promise<void>;
|
|
456
|
+
/** Send a final non-2xx and tear the call down. */
|
|
457
|
+
reject(code: number, reason?: string): Promise<void>;
|
|
458
|
+
/**
|
|
459
|
+
* Tear the call down: BYE an answered call (full teardown funnel), or reject
|
|
460
|
+
* an unanswered one. Mirrors the in-process `call.terminate()`.
|
|
461
|
+
*/
|
|
462
|
+
terminate(reason?: string): Promise<void>;
|
|
463
|
+
/** Alias for {@link Call.terminate}. */
|
|
464
|
+
hangup(reason?: string): Promise<void>;
|
|
465
|
+
/** Send an in-dialog REFER on the A-leg (blind transfer). */
|
|
466
|
+
refer(to: string): Promise<void>;
|
|
467
|
+
/** Blind-transfer alias for {@link Call.refer}. */
|
|
468
|
+
transfer(to: string): Promise<void>;
|
|
469
|
+
/** Attended transfer — REFER with a `Replaces` triple (RFC 3891). */
|
|
470
|
+
referReplaces(to: string, replaces: ReferReplaces): Promise<void>;
|
|
471
|
+
/**
|
|
472
|
+
* Accept an inbound REFER on this tracked call. **Not implemented server-side
|
|
473
|
+
* in Phase 1** — resolves to a {@link ControlError} with `code ===
|
|
474
|
+
* "unsupported_verb"` until the server adds it.
|
|
475
|
+
*/
|
|
476
|
+
acceptRefer(options?: AcceptReferOptions): Promise<void>;
|
|
477
|
+
/**
|
|
478
|
+
* Reject an inbound REFER on this tracked call. **Not implemented server-side
|
|
479
|
+
* in Phase 1** — see {@link Call.acceptRefer}.
|
|
480
|
+
*/
|
|
481
|
+
rejectRefer(code: number, reason?: string): Promise<void>;
|
|
482
|
+
/** Set a header on the stored A-leg INVITE. */
|
|
483
|
+
setHeader(name: string, value: string): Promise<void>;
|
|
484
|
+
/** Read a header from the stored A-leg INVITE (`null` when absent). */
|
|
485
|
+
getHeader(name: string): Promise<string | null>;
|
|
486
|
+
/**
|
|
487
|
+
* Remove a header from the stored A-leg INVITE. **Not implemented server-side
|
|
488
|
+
* in Phase 1** — resolves to a {@link ControlError} with `code ===
|
|
489
|
+
* "unsupported_verb"` until the server adds it.
|
|
490
|
+
*/
|
|
491
|
+
removeHeader(name: string): Promise<void>;
|
|
492
|
+
/** Set a per-call variable (survives a reconnect via `resync`). */
|
|
493
|
+
setVar(key: string, value: string): Promise<void>;
|
|
494
|
+
/** Read a per-call variable (`null` when unset). */
|
|
495
|
+
getVar(key: string): Promise<string | null>;
|
|
496
|
+
/**
|
|
497
|
+
* Play an announcement. **Not yet implemented server-side** — resolves to a
|
|
498
|
+
* {@link ControlError} with `code === "unsupported_verb"` until the media
|
|
499
|
+
* backend lands.
|
|
500
|
+
*/
|
|
501
|
+
playFile(file: string): Promise<void>;
|
|
502
|
+
/** Send DTMF. **Not yet implemented server-side** — see {@link Call.playFile}. */
|
|
503
|
+
dtmf(digits: string): Promise<void>;
|
|
504
|
+
/** Send an arbitrary SIP-adapter verb + args and return the raw result. */
|
|
505
|
+
command(verb: string, args?: unknown): Promise<unknown>;
|
|
506
|
+
/**
|
|
507
|
+
* Await the next event for this call (`ChannelStateChange`,
|
|
508
|
+
* `ChannelHangupRequest`, `StasisEnd`). `null` once the stream closes.
|
|
509
|
+
*/
|
|
510
|
+
nextEvent(): Promise<CallEvent | null>;
|
|
511
|
+
/** Async-iterate this call's events until the stream closes. */
|
|
512
|
+
events(): AsyncIterableIterator<CallEvent>;
|
|
513
|
+
}
|
|
514
|
+
/** A per-call handler. Both sync (`void`) and async (`Promise<void>`) supported. */
|
|
515
|
+
type CallHandler = (call: Call) => void | Promise<void>;
|
|
516
|
+
/** A pull-style stream of handed-over calls (alternative to a handler). */
|
|
517
|
+
declare class CallStream {
|
|
518
|
+
private readonly queue;
|
|
519
|
+
constructor(queue: AsyncQueue<Call>);
|
|
520
|
+
/** Await the next handed-over call. `null` once the client/server shuts down. */
|
|
521
|
+
next(): Promise<Call | null>;
|
|
522
|
+
[Symbol.asyncIterator](): AsyncIterableIterator<Call>;
|
|
523
|
+
}
|
|
524
|
+
/**
|
|
525
|
+
* The SIP facade over an inbound-persistent {@link ControlClient}.
|
|
526
|
+
*
|
|
527
|
+
* ```ts
|
|
528
|
+
* const client = await SipClient.connect({
|
|
529
|
+
* url: "ws://siphon:9090/control/ws",
|
|
530
|
+
* app: "ivr-app",
|
|
531
|
+
* token: "s3cr3t",
|
|
532
|
+
* });
|
|
533
|
+
* await client.onCall(async (call) => {
|
|
534
|
+
* await call.answer();
|
|
535
|
+
* await call.transfer("sip:agent@pbx");
|
|
536
|
+
* });
|
|
537
|
+
* ```
|
|
538
|
+
*/
|
|
539
|
+
declare class SipClient {
|
|
540
|
+
private readonly client;
|
|
541
|
+
private readonly facade;
|
|
542
|
+
private constructor();
|
|
543
|
+
/** Connect + `hello`, then install the SIP event router. */
|
|
544
|
+
static connect(config: ClientConfig): Promise<SipClient>;
|
|
545
|
+
/** Wrap an already-connected generic client with the SIP facade. */
|
|
546
|
+
static wrap(client: ControlClient): SipClient;
|
|
547
|
+
/** The underlying generic client (for raw `command` on any module). */
|
|
548
|
+
get controlClient(): ControlClient;
|
|
549
|
+
/** Register a call handler (does not block). */
|
|
550
|
+
setCallHandler(handler: CallHandler): void;
|
|
551
|
+
/**
|
|
552
|
+
* Register a call handler **and drive the client to completion** (the
|
|
553
|
+
* supervised reconnect + resync loop).
|
|
554
|
+
*/
|
|
555
|
+
onCall(handler: CallHandler): Promise<void>;
|
|
556
|
+
/** A pull-style stream of handed-over calls (alternative to a handler). */
|
|
557
|
+
calls(): CallStream;
|
|
558
|
+
/** Drive the supervised connection loop (reconnect + resync). */
|
|
559
|
+
run(): Promise<void>;
|
|
560
|
+
/** Fetch the registered adapters' schema (`describe`). */
|
|
561
|
+
describe(): Promise<unknown>;
|
|
562
|
+
/** Send a raw command on any module (the generic escape hatch). */
|
|
563
|
+
command(module: string | null, verb: string, target: unknown, args: unknown): Promise<unknown>;
|
|
564
|
+
/** Stop the client. */
|
|
565
|
+
shutdown(): void;
|
|
566
|
+
}
|
|
567
|
+
/** The SIP facade over a per-call-connect {@link ControlServer}. */
|
|
568
|
+
declare class SipServer {
|
|
569
|
+
private readonly server;
|
|
570
|
+
private readonly facade;
|
|
571
|
+
private constructor();
|
|
572
|
+
/** Bind the listener and install the SIP event router. */
|
|
573
|
+
static bind(config: ServerConfig): Promise<SipServer>;
|
|
574
|
+
/** The actual bound address (useful when binding to port 0 in tests). */
|
|
575
|
+
localAddr(): node_net.AddressInfo;
|
|
576
|
+
/** Register a call handler (does not block). */
|
|
577
|
+
setCallHandler(handler: CallHandler): void;
|
|
578
|
+
/** A pull-style stream of dialed-in calls (alternative to a handler). */
|
|
579
|
+
calls(): CallStream;
|
|
580
|
+
/** Register a call handler **and run the accept loop** to completion. */
|
|
581
|
+
onCall(handler: CallHandler): Promise<void>;
|
|
582
|
+
/** Accept siphon's per-call dials until the server is closed. */
|
|
583
|
+
run(): Promise<void>;
|
|
584
|
+
/** Stop accepting dials and close the listener. */
|
|
585
|
+
close(): Promise<void>;
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
export { type AcceptReferOptions, Call, type CallEvent, type CallHandler, CallStream, type ChannelSnapshot, type ClientConfig, type ClientEvent, type CommandTransport, type ConnectionEventSink, ControlClient, ControlError, type ControlErrorCode, type ControlErrorKind, ControlServer, DESCRIBE, type EventFrame, type EventSink, EventStream, type FrameType, GET_VAR, HELLO, type HelloArgs, type HelloResult, MODULE_SIP, MODULE_SMPP, MODULE_SS7, PROTOCOL_VERSION, RESYNC, type ReferReplaces, type ReplyError, type ReplyFrame, type ReplyStatus, type ResponseOptions, type ResyncResult, SET_VAR, SUBPROTOCOL, type ServerConfig, SipClient, type SipEventKind, SipServer, SipVerb, type SipVerbToken, encodeCommand, parseInboundFrame, sipEventKind };
|