@sippulse/niva-sdk 0.1.0-rc.0 → 0.1.0-rc.5
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 +34 -2
- package/dts/src/client.d.ts +3 -2
- package/dts/src/generated/client.d.ts +214 -151
- package/dts/src/generated/meta.d.ts +1 -1
- package/dts/src/generated/operations.d.ts +1733 -98
- package/dts/src/generated/webhooks.d.ts +76 -1
- package/dts/src/index.d.ts +2 -2
- package/dts/src/safe.d.ts +56 -0
- package/dts/src/transport.d.ts +3 -1
- package/index.bun.js +840 -336
- package/index.default.js +840 -336
- package/index.deno.js +840 -336
- package/index.node.js +840 -336
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -57,12 +57,44 @@ All SDK failures extend `NivaError` and set a stable `name`:
|
|
|
57
57
|
|-------|---------|
|
|
58
58
|
| `NivaApiError` | The server answered a non-2xx status. `status`, `code`, `data`, `operation`, `requestId`. |
|
|
59
59
|
| `NivaConnectionError` | Transport failure. `reason` is `network`, `timeout` or `aborted`. |
|
|
60
|
-
| `NivaConfigurationError` | Invalid client options
|
|
60
|
+
| `NivaConfigurationError` | Invalid client options, an empty resolved API key, a throwing api-key/headers provider, or an input that could not be encoded. |
|
|
61
61
|
| `NivaIncompatibleServerError` | The server product version is outside the supported range. |
|
|
62
62
|
| `NivaUnavailableError` | The operation is not served, or its module is disabled. |
|
|
63
63
|
| `NivaWebhookError` | Webhook verification or payload failure (see below). |
|
|
64
64
|
|
|
65
|
-
`
|
|
65
|
+
### `safe`: typed result, no try/catch
|
|
66
|
+
|
|
67
|
+
Every operation method returns a `NivaCall`, a promise carrying that operation's error codes. `safe` turns it into a typed result and **never throws**:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { safe } from "@sippulse/niva-sdk";
|
|
71
|
+
|
|
72
|
+
const [error, data, isDefined, isSuccess] = await safe(
|
|
73
|
+
client.calls.originate({ plan_id, destination }),
|
|
74
|
+
);
|
|
75
|
+
|
|
76
|
+
if (error) {
|
|
77
|
+
if (isDefined) {
|
|
78
|
+
error.code; // NivaApiError<CallsOriginateErrorCode>: only this operation's codes
|
|
79
|
+
} else {
|
|
80
|
+
// NivaApiError (any code, the real one) | NivaConnectionError
|
|
81
|
+
// | NivaUnavailableError | NivaIncompatibleServerError | NivaConfigurationError
|
|
82
|
+
}
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
data.call_id; // CallsOriginateOutput
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The object form exposes the same four names:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
const { error, data, isDefined, isSuccess } = await safe(client.calls.originate(input));
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`isDefined` is true for a `NivaApiError` whose code is declared by that operation, no matter which request produced it (a handshake 401 `UNAUTHORIZED` during `calls.originate` is defined); a code the operation does not declare keeps its real code and is not defined. The decision never guesses from the status. SSE methods return a `NivaStream` and are not wrapped by `safe`.
|
|
96
|
+
|
|
97
|
+
`isNivaApiError(error)` narrows `unknown` to `NivaApiError`; with a code it narrows `error.code` to that literal, and its autocomplete lists all generated codes, not just the operation's.
|
|
66
98
|
|
|
67
99
|
## Streaming (SSE)
|
|
68
100
|
|
package/dts/src/client.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { NivaClient } from "./generated/client.js";
|
|
2
|
+
import { type NivaCall } from "./safe.js";
|
|
2
3
|
import type { NivaClientOptions, NivaRequestOptions } from "./types.js";
|
|
3
|
-
export type OperationCall = <
|
|
4
|
+
export type OperationCall = <Output, Code extends string>(opId: string, input: unknown, options?: NivaRequestOptions & {
|
|
4
5
|
range?: string;
|
|
5
|
-
}) =>
|
|
6
|
+
}) => NivaCall<Output, Code>;
|
|
6
7
|
export declare function createNivaClient(options: NivaClientOptions): NivaClient;
|