@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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 SIPhon Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,155 @@
1
+ # @siphon-project/control (TypeScript)
2
+
3
+ TypeScript / Node client for the [SIPhon](https://github.com/siphon-project/siphon-sip)
4
+ external control plane (`siphon-control.v1`) — an ARI/ESL-class rail for driving
5
+ handed-over calls out of process. The third client language alongside the Rust
6
+ (`siphon-control-client`) and Python (`siphon-control`) SDKs, over the
7
+ byte-identical wire.
8
+
9
+ The wire is hidden: no manual JSON, no request-id bookkeeping, no hand-rolled
10
+ `rpc()`. You get a `Call` handle whose verbs mirror the in-process siphon
11
+ scripting API (`call.answer()`, `call.terminate()`, `call.transfer()`, …), so an
12
+ out-of-process controller reads like an in-process script.
13
+
14
+ > **Package name.** Published as `@siphon-project/control` (scoped to the
15
+ > `siphon-project` npm org).
16
+
17
+ ## Install
18
+
19
+ ```sh
20
+ npm install @siphon-project/control ws
21
+ ```
22
+
23
+ `ws` is a peer runtime dependency (the Node WebSocket implementation).
24
+
25
+ ## Quick start
26
+
27
+ ```ts
28
+ import { SipClient, ControlError } from "@siphon-project/control";
29
+
30
+ const client = await SipClient.connect({
31
+ url: "ws://siphon:9090/control/ws",
32
+ app: "ivr-app",
33
+ token: "s3cr3t",
34
+ });
35
+
36
+ await client.onCall(async (call) => {
37
+ await call.answer();
38
+ try {
39
+ await call.transfer("sip:agent@pbx"); // REFER; awaits the correlated reply
40
+ } catch (error) {
41
+ if (error instanceof ControlError) {
42
+ console.log("transfer rejected:", error.code);
43
+ }
44
+ }
45
+ });
46
+ ```
47
+
48
+ ## Two connection modes
49
+
50
+ Same wire protocol (subprotocol `siphon-control.v1`), two ways to connect:
51
+
52
+ - **Inbound-persistent** (`SipClient`): the app is a WebSocket *client* that
53
+ dials into siphon's `control.listen`, sends a `hello`, and owns the calls
54
+ assigned to it. It can `resync` to re-attach its calls after a reconnect.
55
+ - **Per-call-connect** (`SipServer`, the documented multi-pod default): siphon
56
+ *dials the app* once per handed-over call, so the app is a WebSocket *server*.
57
+ No `hello` — the first frame is `StasisStart`, and the accepting socket owns
58
+ exactly that one call, so "the audio lands on the wrong pod" is structurally
59
+ impossible.
60
+
61
+ ```ts
62
+ import { SipServer } from "@siphon-project/control";
63
+
64
+ const server = await SipServer.bind({
65
+ host: "0.0.0.0",
66
+ port: 8443,
67
+ app: "ivr-app",
68
+ token: "changeme-dev-token",
69
+ });
70
+ await server.onCall(async (call) => {
71
+ await call.answer();
72
+ });
73
+ ```
74
+
75
+ ## Layering: protocol-agnostic core + typed facade
76
+
77
+ - `ControlClient` / `ControlServer` are the **generic core**: transport, `hello`,
78
+ request-id correlation, reconnect + `resync`, and a generic event stream.
79
+ Their headline primitive is `command(module, verb, target, args)`, which works
80
+ for any adapter (`sip` today; `smpp`/`ss7` later) with zero changes.
81
+ - `SipClient` / `SipServer` are the **typed SIP facade** on top: a `Call`'s
82
+ verbs are thin wrappers over `command("sip", …)`, and `StasisStart`→`Call`
83
+ dispatch lives there. A future `smpp` / `ss7` facade is an additive sibling
84
+ over the same core.
85
+
86
+ ```ts
87
+ // The generic escape hatch (any module / verb):
88
+ const schema = await client.controlClient.describe();
89
+ await client.command("sip", "answer", { channel: "ch1" }, { code: 200 });
90
+ ```
91
+
92
+ ## `Call` verbs (mirror the in-process scripting API)
93
+
94
+ | Method | Wire verb (`module`) | Notes |
95
+ | --- | --- | --- |
96
+ | `answer(options?)` | `answer` (`sip`) | UAS 2xx (default `200 OK`) |
97
+ | `progress(options?)` | `progress` (`sip`) | UAS 1xx / early media (default `183`) |
98
+ | `reject(code, reason?)` | `reject` (`sip`) | final non-2xx + teardown |
99
+ | `terminate(reason?)` | `hangup` (`sip`) | primary teardown name |
100
+ | `hangup(reason?)` | `hangup` (`sip`) | alias for `terminate` |
101
+ | `refer(to)` | `refer` (`sip`) | in-dialog REFER (blind transfer) |
102
+ | `transfer(to)` | `refer` (`sip`) | alias for `refer` |
103
+ | `referReplaces(to, replaces)` | `refer` (`sip`) | attended transfer (RFC 3891) |
104
+ | `setHeader(name, value)` | `set_header` (`sip`) | on the stored A-leg INVITE |
105
+ | `getHeader(name)` | `get_header` (`sip`) | returns `string \| null` |
106
+ | `setVar(key, value)` | `set_var` (substrate) | per-call variable |
107
+ | `getVar(key)` | `get_var` (substrate) | returns `string \| null` |
108
+ | `removeHeader(name)` | `remove_header` (`sip`) | ‡ |
109
+ | `acceptRefer(options?)` | `accept_refer` (`sip`) | ‡ |
110
+ | `rejectRefer(code, reason?)` | `reject_refer` (`sip`) | ‡ |
111
+ | `playFile(file)` | `play` (`sip`) | ‡ media |
112
+ | `dtmf(digits)` | `dtmf` (`sip`) | ‡ media |
113
+ | `command(verb, args?)` | (`sip`) | arbitrary SIP-adapter verb |
114
+ | `nextEvent()` / `events()` | — | per-call event stream |
115
+
116
+ Identity/context getters: `channelId`, `callId`, `sipCallId`, `app`, `payload`,
117
+ `reattached`.
118
+
119
+ ‡ Accepted verb names the Phase-1 server answers with a `ControlError` whose
120
+ `.code === "unsupported_verb"` (`error.isUnsupportedVerb()`) until it implements
121
+ them. They send a real command — nothing is stubbed client-side.
122
+
123
+ ## Errors
124
+
125
+ A `status:"error"` reply throws a `ControlError` carrying the stable wire code in
126
+ `.code` (`not_found`, `forbidden`, `unsupported_verb`, `unauthorized`, …).
127
+ Transport / handshake / timeout failures throw a `ControlError` with a `.kind`
128
+ (`unauthorized`, `handshake`, `closed`, `timeout`, `websocket`, `config`) and no
129
+ `.code`.
130
+
131
+ ```ts
132
+ try {
133
+ await call.playFile("/prompts/welcome.wav");
134
+ } catch (error) {
135
+ if (error instanceof ControlError && error.isUnsupportedVerb()) {
136
+ // media isn't wired server-side yet — fall back gracefully
137
+ }
138
+ }
139
+ ```
140
+
141
+ ## Build & test
142
+
143
+ ```sh
144
+ npm install
145
+ npm run build # dual ESM + CJS + .d.ts (tsup)
146
+ npm run typecheck # tsc --noEmit
147
+ npm test # vitest
148
+ ```
149
+
150
+ The package ships ESM and CommonJS with type declarations for both. The
151
+ `wire.test.ts` suite pins the exact command bytes against the server contract.
152
+
153
+ ## License
154
+
155
+ MIT