@pellux/goodvibes-errors 0.35.0 → 0.36.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 +64 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,24 +4,40 @@ Public GoodVibes error package for structured SDK, transport, and daemon failure
|
|
|
4
4
|
|
|
5
5
|
Most applications should install `@pellux/goodvibes-sdk` and import `@pellux/goodvibes-sdk/errors`. Install this package directly when you only need the shared error model.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Install
|
|
8
8
|
|
|
9
|
-
```
|
|
10
|
-
|
|
9
|
+
```sh
|
|
10
|
+
npm install @pellux/goodvibes-errors
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- HTTP status
|
|
15
|
-
- error category
|
|
16
|
-
- error source
|
|
17
|
-
- recovery hints
|
|
18
|
-
- request ids
|
|
19
|
-
- retry timing
|
|
13
|
+
## The error model
|
|
20
14
|
|
|
21
|
-
|
|
15
|
+
Every error thrown from the SDK's public surface is a `GoodVibesSdkError`. The `kind` field is the primary discriminant — switch on it instead of `instanceof` chains or message parsing:
|
|
22
16
|
|
|
23
17
|
```ts
|
|
24
|
-
import {
|
|
18
|
+
import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
|
|
19
|
+
|
|
20
|
+
try {
|
|
21
|
+
await callIntegration();
|
|
22
|
+
} catch (err) {
|
|
23
|
+
if (err instanceof GoodVibesSdkError) {
|
|
24
|
+
switch (err.kind) {
|
|
25
|
+
case 'auth': /* re-authenticate */ break;
|
|
26
|
+
case 'rate-limit': await delay(err.retryAfterMs ?? 1000); break;
|
|
27
|
+
case 'network':
|
|
28
|
+
case 'service': if (err.recoverable) { /* retry with backoff */ } break;
|
|
29
|
+
default: /* log and surface */ break;
|
|
30
|
+
}
|
|
31
|
+
} else {
|
|
32
|
+
throw err;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Concrete subclasses (`ConfigurationError`, `ContractError`, `HttpStatusError`) remain available for class-specific handling:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { HttpStatusError } from '@pellux/goodvibes-errors';
|
|
25
41
|
|
|
26
42
|
try {
|
|
27
43
|
// integration code
|
|
@@ -32,4 +48,40 @@ try {
|
|
|
32
48
|
}
|
|
33
49
|
```
|
|
34
50
|
|
|
51
|
+
The same symbols are re-exported from the SDK facade, so SDK consumers can import them from `@pellux/goodvibes-sdk/errors` instead:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { HttpStatusError } from '@pellux/goodvibes-sdk/errors';
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Branch on structured fields
|
|
58
|
+
|
|
59
|
+
Use the structured fields instead of fragile message parsing:
|
|
60
|
+
|
|
61
|
+
- HTTP status (`status`)
|
|
62
|
+
- error category (`category`) and source (`source`)
|
|
63
|
+
- recovery hints (`recoverable`, `hint`, `retryAfterMs`)
|
|
64
|
+
- request correlation (`requestId`)
|
|
65
|
+
- typed code (`code`) — match it with `isErrorCode(err, SDKErrorCodes.RATE_LIMITED)`
|
|
66
|
+
|
|
67
|
+
## Daemon wire contract
|
|
68
|
+
|
|
69
|
+
The `./daemon-error-contract` subpath exports the daemon-side wire types, independent of the runtime error classes:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import {
|
|
73
|
+
DaemonErrorCategory,
|
|
74
|
+
type DaemonErrorSource,
|
|
75
|
+
type StructuredDaemonErrorBody,
|
|
76
|
+
} from '@pellux/goodvibes-errors/daemon-error-contract';
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`DaemonErrorCategory` is both a string-literal union and a runtime const; `StructuredDaemonErrorBody` is the JSON shape the daemon returns in HTTP error responses.
|
|
80
|
+
|
|
35
81
|
The exported fields are intended to replace fragile message parsing in client and daemon integrations.
|
|
82
|
+
|
|
83
|
+
## Documentation
|
|
84
|
+
|
|
85
|
+
- [SDK Error Kinds](../../docs/error-kinds.md) — per-kind consumer reference
|
|
86
|
+
- [Error Handling](../../docs/error-handling.md) — handling patterns
|
|
87
|
+
- [Error Architecture](../../docs/errors.md) — internal source map
|