@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.
Files changed (3) hide show
  1. package/README.md +235 -56
  2. package/index.js +202 -51
  3. package/package.json +10 -6
package/README.md CHANGED
@@ -1,92 +1,271 @@
1
1
  # @sippulse/niva
2
2
 
3
- CLI tool for managing your [NIVA](https://niva.sippulse.com) IVR platform.
3
+ [![npm version](https://img.shields.io/npm/v/@sippulse/niva.svg)](https://www.npmjs.com/package/@sippulse/niva)
4
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
5
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
4
6
 
5
- ## Requirements
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
- - **Node.js >= 22** (for native WebSocket support)
9
+ ## What do you want to do?
8
10
 
9
- ## Install
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
- # One-shot
16
- npx @sippulse/niva calls list
25
+ niva config set url https://niva.yourcompany.com
26
+ niva config set api-key niva_xxx
17
27
 
18
- # Project-local
19
- npm i -D @sippulse/niva
28
+ niva fs status
20
29
  ```
21
30
 
22
- ## Setup
31
+ **Requirements:** Node.js >= 22 (for native WebSocket support)
23
32
 
24
- Configure your NIVA server URL and API key:
33
+ **Alternative install methods:**
25
34
 
26
35
  ```bash
27
- niva config set url https://niva.yourcompany.com
28
- niva config set api-key niva_xxx
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
- Or via environment variables (useful for CI):
41
+ ## Command Reference
32
42
 
33
- ```bash
34
- export NIVA_URL=https://niva.yourcompany.com
35
- export NIVA_API_KEY=niva_xxx
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
- Or via flags:
57
+ **`calls history` filters:**
39
58
 
40
- ```bash
41
- niva --url https://... --api-key niva_... calls list
42
- ```
43
-
44
- Precedence: flags > env vars > config file.
45
-
46
- ## Commands
47
-
48
- | Command | Description |
49
- |---------|-------------|
50
- | `niva calls list` | List call records with filters |
51
- | `niva calls show <id>` | Show call details |
52
- | `niva calls follow <uuid>` | Follow an active call in real-time |
53
- | `niva plans list` | List visual plans |
54
- | `niva plans show <id>` | Show plan details |
55
- | `niva plans create <name>` | Create a new plan |
56
- | `niva plans publish <id>` | Publish plan draft |
57
- | `niva plans export <id>` | Export plan as JSON |
58
- | `niva plans validate [id]` | Validate a plan |
59
- | `niva chat test <planId>` | Start interactive test chat session |
60
- | `niva originate <planId>` | Originate an outbound call |
61
- | `niva dashboard` | Show system dashboard |
62
- | `niva tts voices` | List available TTS voices |
63
- | `niva audio-files list` | List audio files |
64
- | `niva ai transcription <id>` | Get call transcription |
65
- | `niva ai search <query>` | Search call transcriptions |
66
- | `niva fs show <entity>` | FreeSWITCH show commands |
67
- | `niva config set <key> <value>` | Set config value |
68
- | `niva config get [key]` | Show config |
69
-
70
- Use `niva --help` or `niva <command> --help` for details.
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 list --json # JSON output
76
- niva calls list --output table # Table output (default in TTY)
77
- niva calls list --fields id,status,duration # Select fields (JSON mode)
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
- ## Configuration
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
- Config is stored in `~/.niva/config.json` (mode 0600 on POSIX).
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 | Compatible server versions |
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