@sippulse/niva 0.1.3 → 0.3.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/README.md +73 -12
- package/index.js +235 -86
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -13,9 +13,10 @@ Command-line tool for managing and debugging [NIVA](https://niva.sippulse.com)
|
|
|
13
13
|
| Debug a failed call | `calls trace`, `calls transcript`, `calls show` | `niva calls history --status failed` |
|
|
14
14
|
| Monitor system health | `fs status`, `fs capacity`, `fs sofia` | `niva fs status` |
|
|
15
15
|
| Design IVR plans | `plans create`, `plans validate`, `plans publish` | `niva plans list` |
|
|
16
|
+
| Run outbound dialer campaigns | `campaigns create`, `mailing import`, `campaigns start` | `niva campaigns watch <id>` |
|
|
16
17
|
| Analyze speech data | `dashboard sentiment`, `calls search-text` | `niva calls search-text "billing issue"` |
|
|
17
18
|
| Test a plan via chat | `chat test`, `ws chat` | `niva chat test <planId>` |
|
|
18
|
-
| Integrate with
|
|
19
|
+
| Integrate with coding agents | `install-skill` | `niva install-skill` |
|
|
19
20
|
|
|
20
21
|
## Quick Start
|
|
21
22
|
|
|
@@ -23,13 +24,25 @@ Command-line tool for managing and debugging [NIVA](https://niva.sippulse.com)
|
|
|
23
24
|
npm i -g @sippulse/niva
|
|
24
25
|
|
|
25
26
|
niva config set url https://niva.yourcompany.com
|
|
26
|
-
niva
|
|
27
|
+
niva login
|
|
27
28
|
|
|
28
29
|
niva fs status
|
|
29
30
|
```
|
|
30
31
|
|
|
31
32
|
**Requirements:** Node.js >= 22 (for native WebSocket support)
|
|
32
33
|
|
|
34
|
+
For a headless server, use `niva login --device`. For CI and automation, keep using
|
|
35
|
+
`NIVA_URL` and `NIVA_API_KEY` instead of an interactive session.
|
|
36
|
+
|
|
37
|
+
Useful authentication commands:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
niva login # Sign in through the browser
|
|
41
|
+
niva login --device # Sign in from SSH, a VM, or a container
|
|
42
|
+
niva whoami # Show the active identity and credential source
|
|
43
|
+
niva logout # Revoke the saved OAuth session
|
|
44
|
+
```
|
|
45
|
+
|
|
33
46
|
**Alternative install methods:**
|
|
34
47
|
|
|
35
48
|
```bash
|
|
@@ -79,6 +92,7 @@ niva plans create <name> [options] Create a new plan
|
|
|
79
92
|
niva plans edit <planId> [options] Update plan draft (execution plan)
|
|
80
93
|
niva plans configure <planId> [options] Configure settings, metadata, DIDs
|
|
81
94
|
niva plans validate [planId] Validate a plan (--file for local)
|
|
95
|
+
niva plans import <planId> <file> Import JSON as the draft of an existing plan
|
|
82
96
|
niva plans test <planId> --extension <e> Start a test call
|
|
83
97
|
niva plans publish <planId> [--notes] Publish the current draft
|
|
84
98
|
niva plans versions <planId> List version history
|
|
@@ -151,9 +165,49 @@ niva originate start --plan <id> --destination <target> [options]
|
|
|
151
165
|
| `--destination <target>` | Phone number or SIP URI (required) |
|
|
152
166
|
| `--caller-id <number>` | Caller ID to display |
|
|
153
167
|
| `--caller-id-name <name>` | Caller ID name |
|
|
168
|
+
| `--amd` | Beta: classify the answer as machine, human, or unknown; requires `ENABLE_ORIGINATE_ANSWER_RECOGNITION=true` and emits `call.amd_completed` |
|
|
169
|
+
| `--machine-type` | Beta: enable AMD and, after a machine result, persist its type and include `machine_type` in the same `call.amd_completed`; requires licensed AI and a resolvable SipPulse AI key |
|
|
154
170
|
| `--timeout <seconds>` | Ring timeout |
|
|
155
171
|
| `--var <key=value>` | Set call variable (repeatable) |
|
|
156
172
|
|
|
173
|
+
### Outbound Dialer
|
|
174
|
+
|
|
175
|
+
Requires the `dialer` module license. A campaign dials a **published** plan against an imported mailing list.
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
niva campaigns list List dialer campaigns
|
|
179
|
+
niva campaigns create <name> --plan <id> Create a campaign (dials a published plan)
|
|
180
|
+
niva campaigns start <campaignId> Start dialing (also: pause, resume, stop)
|
|
181
|
+
niva campaigns watch <campaignId> Live campaign stats (SSE; --json = NDJSON)
|
|
182
|
+
niva campaigns stats <campaignId> Counters snapshot + capacity context
|
|
183
|
+
niva mailing import <campaignId> <file> Import a CSV mailing (auto-guesses columns)
|
|
184
|
+
niva mailing export <campaignId> Export the mailing to CSV (-o file)
|
|
185
|
+
niva dnc add <phone> Add a number to the do-not-call list
|
|
186
|
+
niva dnc check <phone> Check DNC (exit 0 = listed, 3 = not listed)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`mailing import` prints the guessed column mapping and asks to confirm; pass `--yes` (or `--map`, `--separator`, `--watch`) for non-interactive use. `campaigns start` dials real numbers.
|
|
190
|
+
|
|
191
|
+
### Audio Library
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
niva audio-files list List audio files
|
|
195
|
+
niva audio-files upload <file...> Upload one or more audio files
|
|
196
|
+
niva audio-files show <id> Audio file metadata
|
|
197
|
+
niva audio-files download <id> [-o <path>] Download the audio content ('-' = stdout)
|
|
198
|
+
niva audio-files download <id> --force Overwrite an existing local file
|
|
199
|
+
niva audio-files update <id> [--name] [--description] Rename or re-describe
|
|
200
|
+
niva audio-files delete <id> Delete (asks to confirm)
|
|
201
|
+
niva audio-files generate-tts --name <n> --text <t> Synthesize a new audio file
|
|
202
|
+
niva audio-files regenerate-tts <id> --text <t> Re-synthesize an existing TTS file
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Accepted formats: wav, mp3, ogg, flac, m4a, up to 10 MB each. Uploads run one file at a time and above 10 files ask to confirm; pass `--yes` for non-interactive use. A bad file does not stop the batch: every file gets a row in the summary and the exit code is the worst one.
|
|
206
|
+
|
|
207
|
+
Duration is read from the file header (wav, mp3), else from `ffprobe` when it is installed, else left empty — `--duration-ms <n>` sets it explicitly, `--no-probe` skips the ffprobe step, and `NIVA_FFPROBE` points at an ffprobe outside `PATH`.
|
|
208
|
+
|
|
209
|
+
Without `--out`, `download` writes to the current directory under the library filename and refuses to overwrite an existing file (exit 5) unless you pass `--force`. `--text-file <path>` (`-` = stdin) replaces `--text` for long scripts.
|
|
210
|
+
|
|
157
211
|
### TTS Resources
|
|
158
212
|
|
|
159
213
|
```
|
|
@@ -166,7 +220,7 @@ niva tts languages List languages
|
|
|
166
220
|
|
|
167
221
|
```
|
|
168
222
|
niva ai agents List AI agents
|
|
169
|
-
niva
|
|
223
|
+
niva webhooks events List webhook schemas and examples
|
|
170
224
|
niva schedules list List routing schedules
|
|
171
225
|
niva channels list [--type <type>] List channels (SIP, Telegram, etc.)
|
|
172
226
|
niva storage usage Storage usage breakdown
|
|
@@ -239,22 +293,28 @@ Auto-detection: table when connected to a terminal, JSON when piped.
|
|
|
239
293
|
- npx @sippulse/niva plans publish $PLAN_ID --notes "build $BITBUCKET_BUILD_NUMBER"
|
|
240
294
|
```
|
|
241
295
|
|
|
242
|
-
##
|
|
296
|
+
## Coding Agent Integration
|
|
243
297
|
|
|
244
|
-
Install the
|
|
298
|
+
Install the bundled Agent Skill to enable AI-assisted IVR management in Claude Code,
|
|
299
|
+
OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, opencode, and other compatible agents:
|
|
245
300
|
|
|
246
301
|
```bash
|
|
247
|
-
niva install-skill #
|
|
248
|
-
niva install-skill --global #
|
|
302
|
+
niva install-skill # Choose agent targets for the current project
|
|
303
|
+
niva install-skill --global # Choose targets under your home directory
|
|
304
|
+
niva install-skill --yes # Install to .agents/ and .claude/ without prompting
|
|
249
305
|
```
|
|
250
306
|
|
|
251
|
-
Once installed,
|
|
307
|
+
Once installed, the coding agent can use the NIVA CLI to debug calls, create plans,
|
|
308
|
+
monitor health, and more.
|
|
252
309
|
|
|
253
310
|
## Compatibility
|
|
254
311
|
|
|
255
|
-
| CLI version |
|
|
256
|
-
|
|
257
|
-
| 0.
|
|
312
|
+
| CLI version | NIVA version | npm dist-tag |
|
|
313
|
+
|-------------|--------------|--------------|
|
|
314
|
+
| 0.3.x | 2.0.x | `niva-2.0` |
|
|
315
|
+
|
|
316
|
+
`latest` points to the newest CLI. To select the CLI maintained for the NIVA 2.0
|
|
317
|
+
line explicitly, run `npx @sippulse/niva@niva-2.0 <command>`.
|
|
258
318
|
|
|
259
319
|
## Exit Codes
|
|
260
320
|
|
|
@@ -264,7 +324,8 @@ Once installed, Claude Code can use the NIVA CLI to debug calls, create plans, m
|
|
|
264
324
|
| `1` | General error |
|
|
265
325
|
| `2` | Usage error (bad arguments) |
|
|
266
326
|
| `3` | Not found |
|
|
267
|
-
| `4` | Permission denied |
|
|
327
|
+
| `4` | Permission denied or module unavailable |
|
|
328
|
+
| `5` | Conflict with existing state (duplicate, or a resource still in use) |
|
|
268
329
|
|
|
269
330
|
## License
|
|
270
331
|
|