@cleocode/lafs 2026.4.0 → 2026.4.3
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 +97 -68
- package/dist/src/a2a/bindings/grpc.d.ts +117 -11
- package/dist/src/a2a/bindings/grpc.d.ts.map +1 -1
- package/dist/src/a2a/bindings/grpc.js +79 -8
- package/dist/src/a2a/bindings/grpc.js.map +1 -1
- package/dist/src/a2a/bindings/http.d.ts +129 -14
- package/dist/src/a2a/bindings/http.d.ts.map +1 -1
- package/dist/src/a2a/bindings/http.js +93 -12
- package/dist/src/a2a/bindings/http.js.map +1 -1
- package/dist/src/a2a/bindings/index.d.ts +80 -7
- package/dist/src/a2a/bindings/index.d.ts.map +1 -1
- package/dist/src/a2a/bindings/index.js +69 -2
- package/dist/src/a2a/bindings/index.js.map +1 -1
- package/dist/src/a2a/bindings/jsonrpc.d.ts +193 -9
- package/dist/src/a2a/bindings/jsonrpc.d.ts.map +1 -1
- package/dist/src/a2a/bindings/jsonrpc.js +152 -9
- package/dist/src/a2a/bindings/jsonrpc.js.map +1 -1
- package/dist/src/a2a/bridge.d.ts +232 -37
- package/dist/src/a2a/bridge.d.ts.map +1 -1
- package/dist/src/a2a/bridge.js +172 -24
- package/dist/src/a2a/bridge.js.map +1 -1
- package/dist/src/a2a/extensions.d.ts +221 -12
- package/dist/src/a2a/extensions.d.ts.map +1 -1
- package/dist/src/a2a/extensions.js +175 -11
- package/dist/src/a2a/extensions.js.map +1 -1
- package/dist/src/a2a/index.d.ts +2 -0
- package/dist/src/a2a/index.d.ts.map +1 -1
- package/dist/src/a2a/index.js +2 -0
- package/dist/src/a2a/index.js.map +1 -1
- package/dist/src/a2a/streaming.d.ts +274 -2
- package/dist/src/a2a/streaming.d.ts.map +1 -1
- package/dist/src/a2a/streaming.js +245 -2
- package/dist/src/a2a/streaming.js.map +1 -1
- package/dist/src/a2a/task-lifecycle.d.ts +339 -19
- package/dist/src/a2a/task-lifecycle.d.ts.map +1 -1
- package/dist/src/a2a/task-lifecycle.js +302 -19
- package/dist/src/a2a/task-lifecycle.js.map +1 -1
- package/dist/src/budgetEnforcement.d.ts +88 -14
- package/dist/src/budgetEnforcement.d.ts.map +1 -1
- package/dist/src/budgetEnforcement.js +132 -19
- package/dist/src/budgetEnforcement.js.map +1 -1
- package/dist/src/circuit-breaker/index.d.ts +254 -9
- package/dist/src/circuit-breaker/index.d.ts.map +1 -1
- package/dist/src/circuit-breaker/index.js +218 -9
- package/dist/src/circuit-breaker/index.js.map +1 -1
- package/dist/src/compliance.d.ts +176 -0
- package/dist/src/compliance.d.ts.map +1 -1
- package/dist/src/compliance.js +100 -0
- package/dist/src/compliance.js.map +1 -1
- package/dist/src/conformance.d.ts +52 -0
- package/dist/src/conformance.d.ts.map +1 -1
- package/dist/src/conformance.js +41 -0
- package/dist/src/conformance.js.map +1 -1
- package/dist/src/conformanceProfiles.d.ts +66 -0
- package/dist/src/conformanceProfiles.d.ts.map +1 -1
- package/dist/src/conformanceProfiles.js +51 -0
- package/dist/src/conformanceProfiles.js.map +1 -1
- package/dist/src/deprecationRegistry.d.ts +80 -0
- package/dist/src/deprecationRegistry.d.ts.map +1 -1
- package/dist/src/deprecationRegistry.js +50 -0
- package/dist/src/deprecationRegistry.js.map +1 -1
- package/dist/src/discovery.d.ts +344 -63
- package/dist/src/discovery.d.ts.map +1 -1
- package/dist/src/discovery.js +67 -13
- package/dist/src/discovery.js.map +1 -1
- package/dist/src/envelope.d.ts +252 -0
- package/dist/src/envelope.d.ts.map +1 -1
- package/dist/src/envelope.js +165 -0
- package/dist/src/envelope.js.map +1 -1
- package/dist/src/errorRegistry.d.ts +159 -0
- package/dist/src/errorRegistry.d.ts.map +1 -1
- package/dist/src/errorRegistry.js +115 -0
- package/dist/src/errorRegistry.js.map +1 -1
- package/dist/src/fieldExtraction.d.ts +125 -25
- package/dist/src/fieldExtraction.d.ts.map +1 -1
- package/dist/src/fieldExtraction.js +85 -16
- package/dist/src/fieldExtraction.js.map +1 -1
- package/dist/src/flagResolver.d.ts +75 -9
- package/dist/src/flagResolver.d.ts.map +1 -1
- package/dist/src/flagResolver.js +20 -4
- package/dist/src/flagResolver.js.map +1 -1
- package/dist/src/flagSemantics.d.ts +76 -1
- package/dist/src/flagSemantics.d.ts.map +1 -1
- package/dist/src/flagSemantics.js +66 -0
- package/dist/src/flagSemantics.js.map +1 -1
- package/dist/src/health/index.d.ts +87 -6
- package/dist/src/health/index.d.ts.map +1 -1
- package/dist/src/health/index.js +54 -6
- package/dist/src/health/index.js.map +1 -1
- package/dist/src/index.d.ts +12 -1
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +12 -1
- package/dist/src/index.js.map +1 -1
- package/dist/src/mviProjection.d.ts +42 -6
- package/dist/src/mviProjection.d.ts.map +1 -1
- package/dist/src/mviProjection.js +31 -5
- package/dist/src/mviProjection.js.map +1 -1
- package/dist/src/native-loader.d.ts +49 -0
- package/dist/src/native-loader.d.ts.map +1 -0
- package/dist/src/native-loader.js +56 -0
- package/dist/src/native-loader.js.map +1 -0
- package/dist/src/problemDetails.d.ts +70 -4
- package/dist/src/problemDetails.d.ts.map +1 -1
- package/dist/src/problemDetails.js +21 -3
- package/dist/src/problemDetails.js.map +1 -1
- package/dist/src/shutdown/index.d.ts +96 -7
- package/dist/src/shutdown/index.d.ts.map +1 -1
- package/dist/src/shutdown/index.js +72 -7
- package/dist/src/shutdown/index.js.map +1 -1
- package/dist/src/tokenEstimator.d.ts +97 -11
- package/dist/src/tokenEstimator.d.ts.map +1 -1
- package/dist/src/tokenEstimator.js +90 -11
- package/dist/src/tokenEstimator.js.map +1 -1
- package/dist/src/types.d.ts +467 -2
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js +64 -0
- package/dist/src/types.js.map +1 -1
- package/dist/src/validateEnvelope.d.ts +59 -1
- package/dist/src/validateEnvelope.d.ts.map +1 -1
- package/dist/src/validateEnvelope.js +75 -9
- package/dist/src/validateEnvelope.js.map +1 -1
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/lafs.md +3 -4
- package/package.json +6 -3
- package/dist/src/mcpAdapter.d.ts +0 -29
- package/dist/src/mcpAdapter.d.ts.map +0 -1
- package/dist/src/mcpAdapter.js +0 -286
- package/dist/src/mcpAdapter.js.map +0 -1
- package/schemas/v1/conformance-profiles.d.ts +0 -15
- package/schemas/v1/envelope.schema.d.ts +0 -14
- package/schemas/v1/error-registry.d.ts +0 -24
package/dist/src/envelope.js
CHANGED
|
@@ -1,12 +1,48 @@
|
|
|
1
1
|
import { getAgentAction, getDocUrl, getRegistryCode, isRegisteredErrorCode, } from './errorRegistry.js';
|
|
2
2
|
import { assertEnvelope } from './validateEnvelope.js';
|
|
3
|
+
/**
|
|
4
|
+
* Canonical JSON Schema URL for the LAFS v1 envelope.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Every LAFS envelope includes this URL in its `$schema` field so that
|
|
8
|
+
* validators and tooling can locate the authoritative schema definition.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* import { LAFS_SCHEMA_URL } from '@cleocode/lafs';
|
|
13
|
+
* console.log(LAFS_SCHEMA_URL);
|
|
14
|
+
* // => 'https://lafs.dev/schemas/v1/envelope.schema.json'
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
3
17
|
export const LAFS_SCHEMA_URL = 'https://lafs.dev/schemas/v1/envelope.schema.json';
|
|
18
|
+
/**
|
|
19
|
+
* Resolve an MVI input (string, boolean, or undefined) to a canonical {@link MVILevel}.
|
|
20
|
+
*
|
|
21
|
+
* @param input - MVI value from the caller: a level string, `true` for minimal,
|
|
22
|
+
* `false` for standard, or `undefined` for the default.
|
|
23
|
+
* @returns The resolved {@link MVILevel} string.
|
|
24
|
+
*
|
|
25
|
+
* @remarks
|
|
26
|
+
* Boolean shorthand exists for CLI convenience: `--mvi` (no value) maps to
|
|
27
|
+
* `true` which resolves to `'minimal'`.
|
|
28
|
+
*/
|
|
4
29
|
function resolveMviLevel(input) {
|
|
5
30
|
if (typeof input === 'boolean') {
|
|
6
31
|
return input ? 'minimal' : 'standard';
|
|
7
32
|
}
|
|
8
33
|
return input ?? 'standard';
|
|
9
34
|
}
|
|
35
|
+
/**
|
|
36
|
+
* Build a fully populated {@link LAFSMeta} object from partial input.
|
|
37
|
+
*
|
|
38
|
+
* @param input - Caller-supplied metadata fields; missing values receive defaults.
|
|
39
|
+
* @returns A complete {@link LAFSMeta} ready for embedding in an envelope.
|
|
40
|
+
*
|
|
41
|
+
* @remarks
|
|
42
|
+
* Defaults: `specVersion` and `schemaVersion` to `'1.0.0'`, `transport` to
|
|
43
|
+
* `'sdk'`, `strict` to `true`, `mvi` to `'standard'`, `contextVersion` to `0`,
|
|
44
|
+
* and `timestamp` to the current time.
|
|
45
|
+
*/
|
|
10
46
|
function createMeta(input) {
|
|
11
47
|
return {
|
|
12
48
|
specVersion: input.specVersion ?? '1.0.0',
|
|
@@ -22,6 +58,20 @@ function createMeta(input) {
|
|
|
22
58
|
...(input.warnings ? { warnings: input.warnings } : {}),
|
|
23
59
|
};
|
|
24
60
|
}
|
|
61
|
+
/**
|
|
62
|
+
* Default agent action for each error category.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* When a {@link LAFSError} does not specify an explicit `agentAction` and the
|
|
66
|
+
* error registry has no override, this map provides the fallback recommendation
|
|
67
|
+
* based on the error's category.
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```ts
|
|
71
|
+
* import { CATEGORY_ACTION_MAP } from '@cleocode/lafs';
|
|
72
|
+
* const action = CATEGORY_ACTION_MAP['RATE_LIMIT']; // => 'wait'
|
|
73
|
+
* ```
|
|
74
|
+
*/
|
|
25
75
|
export const CATEGORY_ACTION_MAP = {
|
|
26
76
|
VALIDATION: 'retry_modified',
|
|
27
77
|
AUTH: 'authenticate',
|
|
@@ -34,6 +84,19 @@ export const CATEGORY_ACTION_MAP = {
|
|
|
34
84
|
CONTRACT: 'retry_modified',
|
|
35
85
|
MIGRATION: 'stop',
|
|
36
86
|
};
|
|
87
|
+
/**
|
|
88
|
+
* Normalize a partial error input into a fully populated {@link LAFSError}.
|
|
89
|
+
*
|
|
90
|
+
* @param error - Partial error with at least `code` and `message`.
|
|
91
|
+
* @returns A complete {@link LAFSError} with category, retryable flag, agent
|
|
92
|
+
* action, and optional doc URL resolved from the error registry and
|
|
93
|
+
* category-action map.
|
|
94
|
+
*
|
|
95
|
+
* @remarks
|
|
96
|
+
* Resolution precedence for `agentAction`: explicit caller value > error
|
|
97
|
+
* registry entry > {@link CATEGORY_ACTION_MAP} fallback. The same pattern
|
|
98
|
+
* applies to `category`, `retryable`, and `docUrl`.
|
|
99
|
+
*/
|
|
37
100
|
function normalizeError(error) {
|
|
38
101
|
const registryEntry = getRegistryCode(error.code);
|
|
39
102
|
const category = (error.category ?? registryEntry?.category ?? 'INTERNAL');
|
|
@@ -63,6 +126,29 @@ function normalizeError(error) {
|
|
|
63
126
|
}
|
|
64
127
|
return result;
|
|
65
128
|
}
|
|
129
|
+
/**
|
|
130
|
+
* Create a fully validated LAFS envelope from a success or error input.
|
|
131
|
+
*
|
|
132
|
+
* @param input - Discriminated union of success or error input data.
|
|
133
|
+
* @returns A complete {@link LAFSEnvelope} ready for serialization.
|
|
134
|
+
*
|
|
135
|
+
* @remarks
|
|
136
|
+
* This is the primary factory for LAFS envelopes. It delegates to
|
|
137
|
+
* internal `createMeta` for metadata construction and `normalizeError`
|
|
138
|
+
* for error normalization. Optional fields (`page`, `_extensions`) are only
|
|
139
|
+
* included when explicitly provided, keeping the envelope minimal.
|
|
140
|
+
*
|
|
141
|
+
* @example
|
|
142
|
+
* ```ts
|
|
143
|
+
* import { createEnvelope } from '@cleocode/lafs';
|
|
144
|
+
*
|
|
145
|
+
* const envelope = createEnvelope({
|
|
146
|
+
* success: true,
|
|
147
|
+
* result: { items: [] },
|
|
148
|
+
* meta: { operation: 'tasks.list', requestId: 'req-1' },
|
|
149
|
+
* });
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
66
152
|
export function createEnvelope(input) {
|
|
67
153
|
const meta = createMeta(input.meta);
|
|
68
154
|
if (input.success) {
|
|
@@ -88,17 +174,72 @@ export function createEnvelope(input) {
|
|
|
88
174
|
...(input._extensions !== undefined ? { _extensions: input._extensions } : {}),
|
|
89
175
|
};
|
|
90
176
|
}
|
|
177
|
+
/**
|
|
178
|
+
* Error subclass that carries the full {@link LAFSError} payload.
|
|
179
|
+
*
|
|
180
|
+
* @remarks
|
|
181
|
+
* Thrown by {@link parseLafsResponse} when the envelope indicates failure.
|
|
182
|
+
* Implements {@link LAFSError} so consumers can access structured error
|
|
183
|
+
* metadata directly on the caught error instance. The `registered` flag
|
|
184
|
+
* indicates whether the error code exists in the canonical error registry.
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* ```ts
|
|
188
|
+
* try {
|
|
189
|
+
* parseLafsResponse(envelope);
|
|
190
|
+
* } catch (err) {
|
|
191
|
+
* if (err instanceof LafsError) {
|
|
192
|
+
* console.log(err.code, err.agentAction);
|
|
193
|
+
* }
|
|
194
|
+
* }
|
|
195
|
+
* ```
|
|
196
|
+
*/
|
|
91
197
|
export class LafsError extends Error {
|
|
198
|
+
/** Stable, machine-readable error code. */
|
|
92
199
|
code;
|
|
200
|
+
/** High-level classification of the error. */
|
|
93
201
|
category;
|
|
202
|
+
/** Whether the operation can be retried without modification. */
|
|
94
203
|
retryable;
|
|
204
|
+
/** Suggested delay in milliseconds before retrying, or `null` if not applicable. */
|
|
95
205
|
retryAfterMs;
|
|
206
|
+
/** Arbitrary key-value pairs with additional context about the error. */
|
|
96
207
|
details;
|
|
208
|
+
/** Whether this error code exists in the canonical error registry. */
|
|
97
209
|
registered;
|
|
210
|
+
/**
|
|
211
|
+
* Recommended action for the consuming agent.
|
|
212
|
+
*
|
|
213
|
+
* @defaultValue undefined
|
|
214
|
+
*/
|
|
98
215
|
agentAction;
|
|
216
|
+
/**
|
|
217
|
+
* Whether the error requires human or higher-privilege intervention.
|
|
218
|
+
*
|
|
219
|
+
* @defaultValue undefined
|
|
220
|
+
*/
|
|
99
221
|
escalationRequired;
|
|
222
|
+
/**
|
|
223
|
+
* Free-text description of a suggested recovery action.
|
|
224
|
+
*
|
|
225
|
+
* @defaultValue undefined
|
|
226
|
+
*/
|
|
100
227
|
suggestedAction;
|
|
228
|
+
/**
|
|
229
|
+
* URL pointing to documentation about this error code.
|
|
230
|
+
*
|
|
231
|
+
* @defaultValue undefined
|
|
232
|
+
*/
|
|
101
233
|
docUrl;
|
|
234
|
+
/**
|
|
235
|
+
* Create a new `LafsError` from a structured {@link LAFSError} payload.
|
|
236
|
+
*
|
|
237
|
+
* @param error - The structured error data to wrap.
|
|
238
|
+
*
|
|
239
|
+
* @remarks
|
|
240
|
+
* Copies all fields from the input and sets `registered` by checking the
|
|
241
|
+
* error code against the canonical registry via {@link isRegisteredErrorCode}.
|
|
242
|
+
*/
|
|
102
243
|
constructor(error) {
|
|
103
244
|
super(error.message);
|
|
104
245
|
this.name = 'LafsError';
|
|
@@ -118,6 +259,30 @@ export class LafsError extends Error {
|
|
|
118
259
|
this.docUrl = error.docUrl;
|
|
119
260
|
}
|
|
120
261
|
}
|
|
262
|
+
/**
|
|
263
|
+
* Parse and unwrap a raw LAFS envelope, returning the result or throwing on error.
|
|
264
|
+
*
|
|
265
|
+
* @typeParam T - Expected type of the result payload.
|
|
266
|
+
* @param input - Raw value expected to be a valid {@link LAFSEnvelope}.
|
|
267
|
+
* @param options - Parsing options controlling error-code validation.
|
|
268
|
+
* @returns The `result` field of the envelope cast to `T`.
|
|
269
|
+
* @throws {LafsError} When the envelope indicates failure (`success=false`).
|
|
270
|
+
* @throws {Error} When the envelope is structurally invalid or
|
|
271
|
+
* `requireRegisteredErrorCode` is `true` and the code is unregistered.
|
|
272
|
+
*
|
|
273
|
+
* @remarks
|
|
274
|
+
* Delegates to {@link assertEnvelope} for schema validation before inspecting
|
|
275
|
+
* the `success` flag. On success, the `result` is returned directly. On
|
|
276
|
+
* failure, the `error` payload is wrapped in a {@link LafsError} and thrown.
|
|
277
|
+
*
|
|
278
|
+
* @example
|
|
279
|
+
* ```ts
|
|
280
|
+
* import { parseLafsResponse } from '@cleocode/lafs';
|
|
281
|
+
*
|
|
282
|
+
* interface TaskList { items: Task[] }
|
|
283
|
+
* const tasks = parseLafsResponse<TaskList>(rawEnvelope);
|
|
284
|
+
* ```
|
|
285
|
+
*/
|
|
121
286
|
export function parseLafsResponse(input, options = {}) {
|
|
122
287
|
const envelope = assertEnvelope(input);
|
|
123
288
|
if (envelope.success) {
|
package/dist/src/envelope.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,SAAS,EACT,eAAe,EACf,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,CAAC,MAAM,eAAe,GAAG,kDAA2D,CAAC;
|
|
1
|
+
{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,29 +1,188 @@
|
|
|
1
1
|
import type { LAFSAgentAction } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* A single entry in the LAFS error-code registry.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Each entry defines the canonical error code, its category, human-readable
|
|
7
|
+
* description, retry semantics, and transport-specific status mappings.
|
|
8
|
+
*/
|
|
2
9
|
export interface RegistryCode {
|
|
10
|
+
/** The canonical LAFS error code (e.g., `"E_FORMAT_CONFLICT"`). */
|
|
3
11
|
code: string;
|
|
12
|
+
/** Broad error category (e.g., `"client"`, `"server"`, `"auth"`). */
|
|
4
13
|
category: string;
|
|
14
|
+
/** Human-readable description of when this error occurs. */
|
|
5
15
|
description: string;
|
|
16
|
+
/** Whether the operation that produced this error is safe to retry. */
|
|
6
17
|
retryable: boolean;
|
|
18
|
+
/** HTTP status code mapped to this error. */
|
|
7
19
|
httpStatus: number;
|
|
20
|
+
/** gRPC status string mapped to this error. */
|
|
8
21
|
grpcStatus: string;
|
|
22
|
+
/** CLI exit code mapped to this error. */
|
|
9
23
|
cliExit: number;
|
|
24
|
+
/**
|
|
25
|
+
* Suggested agent action from the registry (e.g., `"retry"`, `"abort"`).
|
|
26
|
+
* @defaultValue undefined
|
|
27
|
+
*/
|
|
10
28
|
agentAction?: string;
|
|
29
|
+
/**
|
|
30
|
+
* RFC 9457 type URI for this error, used in Problem Details responses.
|
|
31
|
+
* @defaultValue undefined
|
|
32
|
+
*/
|
|
11
33
|
typeUri?: string;
|
|
34
|
+
/**
|
|
35
|
+
* URL pointing to human-readable documentation for this error.
|
|
36
|
+
* @defaultValue undefined
|
|
37
|
+
*/
|
|
12
38
|
docUrl?: string;
|
|
13
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* Top-level shape of the LAFS error-registry JSON file.
|
|
42
|
+
*
|
|
43
|
+
* @remarks
|
|
44
|
+
* Contains a version string for schema evolution and the complete list
|
|
45
|
+
* of registered error codes.
|
|
46
|
+
*/
|
|
14
47
|
export interface ErrorRegistry {
|
|
48
|
+
/** Semantic version of the error-registry schema. */
|
|
15
49
|
version: string;
|
|
50
|
+
/** All registered LAFS error codes. */
|
|
16
51
|
codes: RegistryCode[];
|
|
17
52
|
}
|
|
53
|
+
/**
|
|
54
|
+
* A transport-specific status value resolved from the error registry.
|
|
55
|
+
*
|
|
56
|
+
* @remarks
|
|
57
|
+
* For HTTP and CLI, `value` is a number (status code / exit code).
|
|
58
|
+
* For gRPC, `value` is a string (status name).
|
|
59
|
+
*/
|
|
18
60
|
export type TransportMapping = {
|
|
61
|
+
/** The transport protocol this mapping applies to. */
|
|
19
62
|
transport: 'http' | 'grpc' | 'cli';
|
|
63
|
+
/** The transport-specific status value (numeric for HTTP/CLI, string for gRPC). */
|
|
20
64
|
value: number | string;
|
|
21
65
|
};
|
|
66
|
+
/**
|
|
67
|
+
* Loads the full LAFS error registry from the bundled JSON.
|
|
68
|
+
*
|
|
69
|
+
* @remarks
|
|
70
|
+
* Returns the parsed `error-registry.json` as a typed {@link ErrorRegistry}.
|
|
71
|
+
*
|
|
72
|
+
* @returns The complete error registry with version and all registered codes.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* const registry = getErrorRegistry();
|
|
77
|
+
* console.log(registry.version, registry.codes.length);
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
22
80
|
export declare function getErrorRegistry(): ErrorRegistry;
|
|
81
|
+
/**
|
|
82
|
+
* Checks whether a given error code exists in the LAFS error registry.
|
|
83
|
+
*
|
|
84
|
+
* @remarks
|
|
85
|
+
* Performs a linear scan of the registry codes array. Suitable for
|
|
86
|
+
* validation-time lookups; not optimized for hot-path usage.
|
|
87
|
+
*
|
|
88
|
+
* @param code - The error code string to look up (e.g., `"E_FORMAT_CONFLICT"`).
|
|
89
|
+
* @returns `true` if the code is registered, `false` otherwise.
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ```ts
|
|
93
|
+
* isRegisteredErrorCode('E_FORMAT_CONFLICT'); // true
|
|
94
|
+
* isRegisteredErrorCode('E_UNKNOWN'); // false
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
23
97
|
export declare function isRegisteredErrorCode(code: string): boolean;
|
|
98
|
+
/**
|
|
99
|
+
* Retrieves the full registry entry for a given error code.
|
|
100
|
+
*
|
|
101
|
+
* @remarks
|
|
102
|
+
* Returns `undefined` when the code is not found, allowing callers to
|
|
103
|
+
* distinguish between "code exists" and "code absent" without exceptions.
|
|
104
|
+
*
|
|
105
|
+
* @param code - The error code string to look up.
|
|
106
|
+
* @returns The matching {@link RegistryCode} or `undefined` if not found.
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```ts
|
|
110
|
+
* const entry = getRegistryCode('E_FORMAT_CONFLICT');
|
|
111
|
+
* if (entry) {
|
|
112
|
+
* console.log(entry.httpStatus); // 409
|
|
113
|
+
* }
|
|
114
|
+
* ```
|
|
115
|
+
*/
|
|
24
116
|
export declare function getRegistryCode(code: string): RegistryCode | undefined;
|
|
117
|
+
/**
|
|
118
|
+
* Returns the default agent action for a given error code.
|
|
119
|
+
*
|
|
120
|
+
* @remarks
|
|
121
|
+
* Delegates to {@link getRegistryCode} and extracts the `agentAction`
|
|
122
|
+
* field. Returns `undefined` when the code is unregistered or has no
|
|
123
|
+
* default action.
|
|
124
|
+
*
|
|
125
|
+
* @param code - The error code string to look up.
|
|
126
|
+
* @returns The {@link LAFSAgentAction} or `undefined` if unavailable.
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```ts
|
|
130
|
+
* const action = getAgentAction('E_RATE_LIMIT');
|
|
131
|
+
* console.log(action); // "retry"
|
|
132
|
+
* ```
|
|
133
|
+
*/
|
|
25
134
|
export declare function getAgentAction(code: string): LAFSAgentAction | undefined;
|
|
135
|
+
/**
|
|
136
|
+
* Returns the RFC 9457 type URI for a given error code.
|
|
137
|
+
*
|
|
138
|
+
* @remarks
|
|
139
|
+
* Useful for constructing Problem Details responses. Returns `undefined`
|
|
140
|
+
* when the code is unregistered or has no type URI.
|
|
141
|
+
*
|
|
142
|
+
* @param code - The error code string to look up.
|
|
143
|
+
* @returns The type URI string or `undefined` if unavailable.
|
|
144
|
+
*
|
|
145
|
+
* @example
|
|
146
|
+
* ```ts
|
|
147
|
+
* const uri = getTypeUri('E_VALIDATION');
|
|
148
|
+
* // "https://lafs.dev/errors/E_VALIDATION"
|
|
149
|
+
* ```
|
|
150
|
+
*/
|
|
26
151
|
export declare function getTypeUri(code: string): string | undefined;
|
|
152
|
+
/**
|
|
153
|
+
* Returns the documentation URL for a given error code.
|
|
154
|
+
*
|
|
155
|
+
* @remarks
|
|
156
|
+
* Provides a link to human-readable docs for the error. Returns
|
|
157
|
+
* `undefined` when the code is unregistered or has no doc URL.
|
|
158
|
+
*
|
|
159
|
+
* @param code - The error code string to look up.
|
|
160
|
+
* @returns The documentation URL string or `undefined` if unavailable.
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* ```ts
|
|
164
|
+
* const url = getDocUrl('E_VALIDATION');
|
|
165
|
+
* // "https://lafs.dev/docs/errors/E_VALIDATION"
|
|
166
|
+
* ```
|
|
167
|
+
*/
|
|
27
168
|
export declare function getDocUrl(code: string): string | undefined;
|
|
169
|
+
/**
|
|
170
|
+
* Resolves the transport-specific status value for a given error code and transport.
|
|
171
|
+
*
|
|
172
|
+
* @remarks
|
|
173
|
+
* Looks up the registry entry and extracts `httpStatus`, `grpcStatus`, or
|
|
174
|
+
* `cliExit` depending on the requested transport. Returns `null` when the
|
|
175
|
+
* error code is not registered.
|
|
176
|
+
*
|
|
177
|
+
* @param code - The error code string to look up.
|
|
178
|
+
* @param transport - The transport protocol to resolve a mapping for.
|
|
179
|
+
* @returns A {@link TransportMapping} or `null` if the code is unregistered.
|
|
180
|
+
*
|
|
181
|
+
* @example
|
|
182
|
+
* ```ts
|
|
183
|
+
* const mapping = getTransportMapping('E_NOT_FOUND', 'http');
|
|
184
|
+
* console.log(mapping); // { transport: 'http', value: 404 }
|
|
185
|
+
* ```
|
|
186
|
+
*/
|
|
28
187
|
export declare function getTransportMapping(code: string, transport: 'http' | 'grpc' | 'cli'): TransportMapping | null;
|
|
29
188
|
//# sourceMappingURL=errorRegistry.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errorRegistry.d.ts","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGxE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GACjC,gBAAgB,GAAG,IAAI,CAazB"}
|
|
1
|
+
{"version":3,"file":"errorRegistry.d.ts","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sDAAsD;IACtD,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,mFAAmF;IACnF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GACjC,gBAAgB,GAAG,IAAI,CAazB"}
|
|
@@ -1,26 +1,141 @@
|
|
|
1
1
|
import errorRegistry from '../schemas/v1/error-registry.json' with { type: 'json' };
|
|
2
|
+
/**
|
|
3
|
+
* Loads the full LAFS error registry from the bundled JSON.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Returns the parsed `error-registry.json` as a typed {@link ErrorRegistry}.
|
|
7
|
+
*
|
|
8
|
+
* @returns The complete error registry with version and all registered codes.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* const registry = getErrorRegistry();
|
|
13
|
+
* console.log(registry.version, registry.codes.length);
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
2
16
|
export function getErrorRegistry() {
|
|
3
17
|
return errorRegistry;
|
|
4
18
|
}
|
|
19
|
+
/**
|
|
20
|
+
* Checks whether a given error code exists in the LAFS error registry.
|
|
21
|
+
*
|
|
22
|
+
* @remarks
|
|
23
|
+
* Performs a linear scan of the registry codes array. Suitable for
|
|
24
|
+
* validation-time lookups; not optimized for hot-path usage.
|
|
25
|
+
*
|
|
26
|
+
* @param code - The error code string to look up (e.g., `"E_FORMAT_CONFLICT"`).
|
|
27
|
+
* @returns `true` if the code is registered, `false` otherwise.
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```ts
|
|
31
|
+
* isRegisteredErrorCode('E_FORMAT_CONFLICT'); // true
|
|
32
|
+
* isRegisteredErrorCode('E_UNKNOWN'); // false
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
5
35
|
export function isRegisteredErrorCode(code) {
|
|
6
36
|
const registry = getErrorRegistry();
|
|
7
37
|
return registry.codes.some((item) => item.code === code);
|
|
8
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* Retrieves the full registry entry for a given error code.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* Returns `undefined` when the code is not found, allowing callers to
|
|
44
|
+
* distinguish between "code exists" and "code absent" without exceptions.
|
|
45
|
+
*
|
|
46
|
+
* @param code - The error code string to look up.
|
|
47
|
+
* @returns The matching {@link RegistryCode} or `undefined` if not found.
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* ```ts
|
|
51
|
+
* const entry = getRegistryCode('E_FORMAT_CONFLICT');
|
|
52
|
+
* if (entry) {
|
|
53
|
+
* console.log(entry.httpStatus); // 409
|
|
54
|
+
* }
|
|
55
|
+
* ```
|
|
56
|
+
*/
|
|
9
57
|
export function getRegistryCode(code) {
|
|
10
58
|
return getErrorRegistry().codes.find((item) => item.code === code);
|
|
11
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* Returns the default agent action for a given error code.
|
|
62
|
+
*
|
|
63
|
+
* @remarks
|
|
64
|
+
* Delegates to {@link getRegistryCode} and extracts the `agentAction`
|
|
65
|
+
* field. Returns `undefined` when the code is unregistered or has no
|
|
66
|
+
* default action.
|
|
67
|
+
*
|
|
68
|
+
* @param code - The error code string to look up.
|
|
69
|
+
* @returns The {@link LAFSAgentAction} or `undefined` if unavailable.
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```ts
|
|
73
|
+
* const action = getAgentAction('E_RATE_LIMIT');
|
|
74
|
+
* console.log(action); // "retry"
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
12
77
|
export function getAgentAction(code) {
|
|
13
78
|
const entry = getRegistryCode(code);
|
|
14
79
|
return entry?.agentAction;
|
|
15
80
|
}
|
|
81
|
+
/**
|
|
82
|
+
* Returns the RFC 9457 type URI for a given error code.
|
|
83
|
+
*
|
|
84
|
+
* @remarks
|
|
85
|
+
* Useful for constructing Problem Details responses. Returns `undefined`
|
|
86
|
+
* when the code is unregistered or has no type URI.
|
|
87
|
+
*
|
|
88
|
+
* @param code - The error code string to look up.
|
|
89
|
+
* @returns The type URI string or `undefined` if unavailable.
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ```ts
|
|
93
|
+
* const uri = getTypeUri('E_VALIDATION');
|
|
94
|
+
* // "https://lafs.dev/errors/E_VALIDATION"
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
16
97
|
export function getTypeUri(code) {
|
|
17
98
|
const entry = getRegistryCode(code);
|
|
18
99
|
return entry?.typeUri;
|
|
19
100
|
}
|
|
101
|
+
/**
|
|
102
|
+
* Returns the documentation URL for a given error code.
|
|
103
|
+
*
|
|
104
|
+
* @remarks
|
|
105
|
+
* Provides a link to human-readable docs for the error. Returns
|
|
106
|
+
* `undefined` when the code is unregistered or has no doc URL.
|
|
107
|
+
*
|
|
108
|
+
* @param code - The error code string to look up.
|
|
109
|
+
* @returns The documentation URL string or `undefined` if unavailable.
|
|
110
|
+
*
|
|
111
|
+
* @example
|
|
112
|
+
* ```ts
|
|
113
|
+
* const url = getDocUrl('E_VALIDATION');
|
|
114
|
+
* // "https://lafs.dev/docs/errors/E_VALIDATION"
|
|
115
|
+
* ```
|
|
116
|
+
*/
|
|
20
117
|
export function getDocUrl(code) {
|
|
21
118
|
const entry = getRegistryCode(code);
|
|
22
119
|
return entry?.docUrl;
|
|
23
120
|
}
|
|
121
|
+
/**
|
|
122
|
+
* Resolves the transport-specific status value for a given error code and transport.
|
|
123
|
+
*
|
|
124
|
+
* @remarks
|
|
125
|
+
* Looks up the registry entry and extracts `httpStatus`, `grpcStatus`, or
|
|
126
|
+
* `cliExit` depending on the requested transport. Returns `null` when the
|
|
127
|
+
* error code is not registered.
|
|
128
|
+
*
|
|
129
|
+
* @param code - The error code string to look up.
|
|
130
|
+
* @param transport - The transport protocol to resolve a mapping for.
|
|
131
|
+
* @returns A {@link TransportMapping} or `null` if the code is unregistered.
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```ts
|
|
135
|
+
* const mapping = getTransportMapping('E_NOT_FOUND', 'http');
|
|
136
|
+
* console.log(mapping); // { transport: 'http', value: 404 }
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
24
139
|
export function getTransportMapping(code, transport) {
|
|
25
140
|
const registryCode = getRegistryCode(code);
|
|
26
141
|
if (!registryCode) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errorRegistry.js","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;
|
|
1
|
+
{"version":3,"file":"errorRegistry.js","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAsEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAA8B,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,gBAAgB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,WAA0C,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,MAAM,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAkC;IAElC,MAAM,YAAY,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC;IACvD,CAAC;IACD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;AACpD,CAAC"}
|