@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/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
|