@sippulse/niva 0.1.0 → 0.1.1
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 +235 -56
- package/index.js +202 -51
- package/package.json +10 -6
package/README.md
CHANGED
|
@@ -1,92 +1,271 @@
|
|
|
1
1
|
# @sippulse/niva
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@sippulse/niva)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](./LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Command-line tool for managing and debugging [NIVA](https://niva.sippulse.com) — a low-code platform for building intelligent IVR systems with AI integration.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
## What do you want to do?
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
| Goal | Commands | Example |
|
|
12
|
+
|------|----------|---------|
|
|
13
|
+
| Debug a failed call | `calls trace`, `calls transcript`, `calls show` | `niva calls history --status failed` |
|
|
14
|
+
| Monitor system health | `fs status`, `fs capacity`, `fs sofia` | `niva fs status` |
|
|
15
|
+
| Design IVR plans | `plans create`, `plans validate`, `plans publish` | `niva plans list` |
|
|
16
|
+
| Analyze speech data | `dashboard sentiment`, `calls search-text` | `niva calls search-text "billing issue"` |
|
|
17
|
+
| Test a plan via chat | `chat test`, `ws chat` | `niva chat test <planId>` |
|
|
18
|
+
| Integrate with Claude Code | `install-skill` | `niva install-skill` |
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
10
21
|
|
|
11
22
|
```bash
|
|
12
|
-
# Global
|
|
13
23
|
npm i -g @sippulse/niva
|
|
14
24
|
|
|
15
|
-
|
|
16
|
-
|
|
25
|
+
niva config set url https://niva.yourcompany.com
|
|
26
|
+
niva config set api-key niva_xxx
|
|
17
27
|
|
|
18
|
-
|
|
19
|
-
npm i -D @sippulse/niva
|
|
28
|
+
niva fs status
|
|
20
29
|
```
|
|
21
30
|
|
|
22
|
-
|
|
31
|
+
**Requirements:** Node.js >= 22 (for native WebSocket support)
|
|
23
32
|
|
|
24
|
-
|
|
33
|
+
**Alternative install methods:**
|
|
25
34
|
|
|
26
35
|
```bash
|
|
27
|
-
niva
|
|
28
|
-
niva
|
|
36
|
+
npx @sippulse/niva calls list # one-shot (no install)
|
|
37
|
+
bunx @sippulse/niva dashboard metrics # bun alternative
|
|
38
|
+
npm i -D @sippulse/niva # project-local
|
|
29
39
|
```
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
## Command Reference
|
|
32
42
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
43
|
+
### Call Management
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
niva calls list List active calls
|
|
47
|
+
niva calls show <callRecordId> Show call detail (CDR)
|
|
48
|
+
niva calls history [options] Search call records with filters
|
|
49
|
+
niva calls hangup <uuid> Hang up an active call
|
|
50
|
+
niva calls trace <callRecordId> Node-by-node execution trace
|
|
51
|
+
niva calls transcript <callRecordId> Transcription + speech analytics
|
|
52
|
+
niva calls search-text <query> Semantic search across transcriptions
|
|
53
|
+
niva calls inspect <uuid> Inspect active call (node, vars, path)
|
|
54
|
+
niva calls follow <uuid> Stream live transcription (Ctrl+C to stop)
|
|
36
55
|
```
|
|
37
56
|
|
|
38
|
-
|
|
57
|
+
**`calls history` filters:**
|
|
39
58
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
|
49
|
-
|
|
50
|
-
|
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
59
|
+
| Flag | Description |
|
|
60
|
+
|------|-------------|
|
|
61
|
+
| `--from <date>` | Start date (YYYY-MM-DD) |
|
|
62
|
+
| `--to <date>` | End date |
|
|
63
|
+
| `--status <s>` | answered, missed, failed, busy |
|
|
64
|
+
| `--plan <id>` | Filter by visual plan ID |
|
|
65
|
+
| `--caller <search>` | Search caller ID |
|
|
66
|
+
| `--has-recording` | Only calls with recording |
|
|
67
|
+
| `--has-transcription` | Only calls with transcription |
|
|
68
|
+
| `--min-duration <s>` | Minimum duration (seconds) |
|
|
69
|
+
| `--max-duration <s>` | Maximum duration (seconds) |
|
|
70
|
+
| `--page <n>` | Page number (default: 1) |
|
|
71
|
+
| `--limit <n>` | Items per page (default: 20) |
|
|
72
|
+
|
|
73
|
+
### IVR Plan Design
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
niva plans list [--search <term>] List visual plans
|
|
77
|
+
niva plans show <planId> Show plan details and settings
|
|
78
|
+
niva plans create <name> [options] Create a new plan
|
|
79
|
+
niva plans edit <planId> [options] Update plan draft (execution plan)
|
|
80
|
+
niva plans configure <planId> [options] Configure settings, metadata, DIDs
|
|
81
|
+
niva plans validate [planId] Validate a plan (--file for local)
|
|
82
|
+
niva plans test <planId> --extension <e> Start a test call
|
|
83
|
+
niva plans publish <planId> [--notes] Publish the current draft
|
|
84
|
+
niva plans versions <planId> List version history
|
|
85
|
+
niva plans export <planId> Export plan as JSON to stdout
|
|
86
|
+
niva plans delete <planId> Delete a plan
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**`plans configure` options:**
|
|
90
|
+
|
|
91
|
+
| Flag | Description |
|
|
92
|
+
|------|-------------|
|
|
93
|
+
| `--name <name>` | Plan name |
|
|
94
|
+
| `--description <text>` | Plan description |
|
|
95
|
+
| `--recording` / `--no-recording` | Toggle call recording |
|
|
96
|
+
| `--transcription` / `--no-transcription` | Toggle transcription |
|
|
97
|
+
| `--transcription-language <code>` | Transcription language (e.g. pt-BR) |
|
|
98
|
+
| `--anonymize` / `--no-anonymize` | Toggle PII anonymization |
|
|
99
|
+
| `--speech-analytics` / `--no-speech-analytics` | Toggle speech analytics |
|
|
100
|
+
| `--topics <list>` | Topic detection topics (comma-separated) |
|
|
101
|
+
| `--assign-did <id>` | Assign phone number to plan |
|
|
102
|
+
| `--unassign-did <id>` | Unassign phone number |
|
|
103
|
+
| `--list-dids` | Show assigned and available numbers |
|
|
104
|
+
|
|
105
|
+
### System Monitoring
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
niva fs status Health check (DB, Redis, FreeSWITCH)
|
|
109
|
+
niva fs capacity Channel usage, license, AI usage
|
|
110
|
+
niva fs sofia SIP profile status
|
|
111
|
+
niva fs registrations Connected SIP endpoints
|
|
112
|
+
niva fs channels Active FreeSWITCH channels
|
|
113
|
+
niva fs dump <uuid> Dump channel variables for a call
|
|
114
|
+
niva fs show <entity> FreeSWITCH show command
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`fs show` entities: `channels`, `calls`, `registrations`, `codecs`, `modules`, `aliases`
|
|
118
|
+
|
|
119
|
+
### Speech Analytics & Dashboard
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
niva dashboard metrics [--from] [--to] Call metrics (total, answered, missed)
|
|
123
|
+
niva dashboard sentiment [options] Sentiment distribution
|
|
124
|
+
niva dashboard topics [--limit <n>] Top discussed topics
|
|
125
|
+
niva dashboard intents [--limit <n>] Detected intents
|
|
126
|
+
niva dashboard trend [--granularity] Sentiment trend over time
|
|
127
|
+
niva dashboard hourly Call volume by hour of day
|
|
128
|
+
niva dashboard top-plans [--limit <n>] Top IVR plans by volume
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Chat Testing
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
niva chat test <planId> Interactive test chat (isolated)
|
|
135
|
+
niva chat stop <sessionId> Stop a test chat session
|
|
136
|
+
niva ws chat <planId> Chat with published plan (production)
|
|
137
|
+
niva ws session <planId> Create session (returns wsUrl)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`chat test` runs the plan in isolation (no production traffic). `ws chat` hits the live endpoint.
|
|
141
|
+
|
|
142
|
+
### Outbound Calls
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
niva originate start --plan <id> --destination <target> [options]
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| Flag | Description |
|
|
149
|
+
|------|-------------|
|
|
150
|
+
| `--plan <id>` | Visual plan ID (required) |
|
|
151
|
+
| `--destination <target>` | Phone number or SIP URI (required) |
|
|
152
|
+
| `--caller-id <number>` | Caller ID to display |
|
|
153
|
+
| `--caller-id-name <name>` | Caller ID name |
|
|
154
|
+
| `--timeout <seconds>` | Ring timeout |
|
|
155
|
+
| `--var <key=value>` | Set call variable (repeatable) |
|
|
156
|
+
|
|
157
|
+
### TTS Resources
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
niva tts voices [--language <code>] [--model <m>] List voices
|
|
161
|
+
niva tts models List TTS models
|
|
162
|
+
niva tts languages List languages
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Other
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
niva ai agents List AI agents
|
|
169
|
+
niva audio-files list List audio files
|
|
170
|
+
niva schedules list List routing schedules
|
|
171
|
+
niva channels list [--type <type>] List channels (SIP, Telegram, etc.)
|
|
172
|
+
niva storage usage Storage usage breakdown
|
|
173
|
+
niva nodes list List IVR node types
|
|
174
|
+
niva nodes show <type> Node type details
|
|
175
|
+
niva nodes schema <type> JSON Schema for node config
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Configuration
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
niva config set <key> <value> Set config (url, api-key)
|
|
182
|
+
niva config get [key] Get config value
|
|
183
|
+
niva config show Show full config
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Config stored at `~/.niva/config.json` (mode 0600 on POSIX).
|
|
187
|
+
|
|
188
|
+
## Global Options
|
|
189
|
+
|
|
190
|
+
| Option | Description |
|
|
191
|
+
|--------|-------------|
|
|
192
|
+
| `--url <url>` | Server URL (overrides config/env) |
|
|
193
|
+
| `--api-key <key>` | API key (overrides config/env) |
|
|
194
|
+
| `--json` | JSON output |
|
|
195
|
+
| `--output <format>` | `json`, `table`, or `plain` |
|
|
196
|
+
| `--fields <list>` | Comma-separated fields (JSON mode) |
|
|
197
|
+
| `--yes` | Skip confirmation prompts |
|
|
198
|
+
| `--no-color` | Disable colors |
|
|
71
199
|
|
|
72
200
|
## Output Formats
|
|
73
201
|
|
|
74
202
|
```bash
|
|
75
|
-
niva calls
|
|
76
|
-
niva calls
|
|
77
|
-
niva calls
|
|
203
|
+
niva calls history --json # JSON output
|
|
204
|
+
niva calls history --output table # Table output (default in TTY)
|
|
205
|
+
niva calls history --json --fields id,status # Select specific fields
|
|
206
|
+
niva calls history --json | jq '.items[].status' # Pipe-friendly
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Auto-detection: table when connected to a terminal, JSON when piped.
|
|
210
|
+
|
|
211
|
+
## Environment Variables
|
|
212
|
+
|
|
213
|
+
| Variable | Description | Default |
|
|
214
|
+
|----------|-------------|---------|
|
|
215
|
+
| `NIVA_URL` | Server URL | `http://localhost:3000` |
|
|
216
|
+
| `NIVA_API_KEY` | API key for authentication | — |
|
|
217
|
+
| `NIVA_INSECURE` | Skip TLS verification (`true`) | — |
|
|
218
|
+
|
|
219
|
+
**Priority:** CLI flags > environment variables > config file > defaults
|
|
220
|
+
|
|
221
|
+
## CI/CD Usage
|
|
222
|
+
|
|
223
|
+
```yaml
|
|
224
|
+
# GitHub Actions
|
|
225
|
+
- name: Deploy IVR plan
|
|
226
|
+
env:
|
|
227
|
+
NIVA_URL: ${{ secrets.NIVA_URL }}
|
|
228
|
+
NIVA_API_KEY: ${{ secrets.NIVA_API_KEY }}
|
|
229
|
+
run: |
|
|
230
|
+
npx @sippulse/niva plans validate my-plan-id
|
|
231
|
+
npx @sippulse/niva plans publish my-plan-id --notes "deploy ${{ github.sha }}"
|
|
78
232
|
```
|
|
79
233
|
|
|
80
|
-
|
|
234
|
+
```yaml
|
|
235
|
+
# Bitbucket Pipelines
|
|
236
|
+
- step:
|
|
237
|
+
script:
|
|
238
|
+
- npx @sippulse/niva fs status
|
|
239
|
+
- npx @sippulse/niva plans publish $PLAN_ID --notes "build $BITBUCKET_BUILD_NUMBER"
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## Claude Code Integration
|
|
243
|
+
|
|
244
|
+
Install the NIVA CLI skill for [Claude Code](https://claude.ai/code) to enable AI-assisted IVR management:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
niva install-skill # Install to current project (.claude/skills/)
|
|
248
|
+
niva install-skill --global # Install globally (~/.claude/skills/)
|
|
249
|
+
```
|
|
81
250
|
|
|
82
|
-
|
|
251
|
+
Once installed, Claude Code can use the NIVA CLI to debug calls, create plans, monitor health, and more.
|
|
83
252
|
|
|
84
253
|
## Compatibility
|
|
85
254
|
|
|
86
|
-
| CLI version |
|
|
87
|
-
|
|
255
|
+
| CLI version | Server version |
|
|
256
|
+
|-------------|---------------|
|
|
88
257
|
| 0.1.x | 2.0.x+ |
|
|
89
258
|
|
|
259
|
+
## Exit Codes
|
|
260
|
+
|
|
261
|
+
| Code | Meaning |
|
|
262
|
+
|------|---------|
|
|
263
|
+
| `0` | Success |
|
|
264
|
+
| `1` | General error |
|
|
265
|
+
| `2` | Usage error (bad arguments) |
|
|
266
|
+
| `3` | Not found |
|
|
267
|
+
| `4` | Permission denied |
|
|
268
|
+
|
|
90
269
|
## License
|
|
91
270
|
|
|
92
271
|
Apache-2.0
|