@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.
Files changed (3) hide show
  1. package/README.md +73 -12
  2. package/index.js +235 -86
  3. 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 Claude Code | `install-skill` | `niva install-skill` |
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 config set api-key niva_xxx
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 audio-files list List audio files
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
- ## Claude Code Integration
296
+ ## Coding Agent Integration
243
297
 
244
- Install the NIVA CLI skill for [Claude Code](https://claude.ai/code) to enable AI-assisted IVR management:
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 # Install to current project (.claude/skills/)
248
- niva install-skill --global # Install globally (~/.claude/skills/)
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, Claude Code can use the NIVA CLI to debug calls, create plans, monitor health, and more.
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 | Server version |
256
- |-------------|---------------|
257
- | 0.1.x | 2.0.x+ |
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