@cleocode/lafs 2026.4.0 → 2026.4.4

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 (131) hide show
  1. package/README.md +97 -68
  2. package/dist/src/a2a/bindings/grpc.d.ts +117 -11
  3. package/dist/src/a2a/bindings/grpc.d.ts.map +1 -1
  4. package/dist/src/a2a/bindings/grpc.js +79 -8
  5. package/dist/src/a2a/bindings/grpc.js.map +1 -1
  6. package/dist/src/a2a/bindings/http.d.ts +129 -14
  7. package/dist/src/a2a/bindings/http.d.ts.map +1 -1
  8. package/dist/src/a2a/bindings/http.js +93 -12
  9. package/dist/src/a2a/bindings/http.js.map +1 -1
  10. package/dist/src/a2a/bindings/index.d.ts +80 -7
  11. package/dist/src/a2a/bindings/index.d.ts.map +1 -1
  12. package/dist/src/a2a/bindings/index.js +69 -2
  13. package/dist/src/a2a/bindings/index.js.map +1 -1
  14. package/dist/src/a2a/bindings/jsonrpc.d.ts +193 -9
  15. package/dist/src/a2a/bindings/jsonrpc.d.ts.map +1 -1
  16. package/dist/src/a2a/bindings/jsonrpc.js +152 -9
  17. package/dist/src/a2a/bindings/jsonrpc.js.map +1 -1
  18. package/dist/src/a2a/bridge.d.ts +232 -37
  19. package/dist/src/a2a/bridge.d.ts.map +1 -1
  20. package/dist/src/a2a/bridge.js +172 -24
  21. package/dist/src/a2a/bridge.js.map +1 -1
  22. package/dist/src/a2a/extensions.d.ts +221 -12
  23. package/dist/src/a2a/extensions.d.ts.map +1 -1
  24. package/dist/src/a2a/extensions.js +175 -11
  25. package/dist/src/a2a/extensions.js.map +1 -1
  26. package/dist/src/a2a/index.d.ts +2 -0
  27. package/dist/src/a2a/index.d.ts.map +1 -1
  28. package/dist/src/a2a/index.js +2 -0
  29. package/dist/src/a2a/index.js.map +1 -1
  30. package/dist/src/a2a/streaming.d.ts +274 -2
  31. package/dist/src/a2a/streaming.d.ts.map +1 -1
  32. package/dist/src/a2a/streaming.js +245 -2
  33. package/dist/src/a2a/streaming.js.map +1 -1
  34. package/dist/src/a2a/task-lifecycle.d.ts +339 -19
  35. package/dist/src/a2a/task-lifecycle.d.ts.map +1 -1
  36. package/dist/src/a2a/task-lifecycle.js +302 -19
  37. package/dist/src/a2a/task-lifecycle.js.map +1 -1
  38. package/dist/src/budgetEnforcement.d.ts +88 -14
  39. package/dist/src/budgetEnforcement.d.ts.map +1 -1
  40. package/dist/src/budgetEnforcement.js +132 -19
  41. package/dist/src/budgetEnforcement.js.map +1 -1
  42. package/dist/src/circuit-breaker/index.d.ts +254 -9
  43. package/dist/src/circuit-breaker/index.d.ts.map +1 -1
  44. package/dist/src/circuit-breaker/index.js +218 -9
  45. package/dist/src/circuit-breaker/index.js.map +1 -1
  46. package/dist/src/compliance.d.ts +176 -0
  47. package/dist/src/compliance.d.ts.map +1 -1
  48. package/dist/src/compliance.js +100 -0
  49. package/dist/src/compliance.js.map +1 -1
  50. package/dist/src/conformance.d.ts +52 -0
  51. package/dist/src/conformance.d.ts.map +1 -1
  52. package/dist/src/conformance.js +41 -0
  53. package/dist/src/conformance.js.map +1 -1
  54. package/dist/src/conformanceProfiles.d.ts +66 -0
  55. package/dist/src/conformanceProfiles.d.ts.map +1 -1
  56. package/dist/src/conformanceProfiles.js +51 -0
  57. package/dist/src/conformanceProfiles.js.map +1 -1
  58. package/dist/src/deprecationRegistry.d.ts +80 -0
  59. package/dist/src/deprecationRegistry.d.ts.map +1 -1
  60. package/dist/src/deprecationRegistry.js +50 -0
  61. package/dist/src/deprecationRegistry.js.map +1 -1
  62. package/dist/src/discovery.d.ts +344 -63
  63. package/dist/src/discovery.d.ts.map +1 -1
  64. package/dist/src/discovery.js +67 -13
  65. package/dist/src/discovery.js.map +1 -1
  66. package/dist/src/envelope.d.ts +252 -0
  67. package/dist/src/envelope.d.ts.map +1 -1
  68. package/dist/src/envelope.js +165 -0
  69. package/dist/src/envelope.js.map +1 -1
  70. package/dist/src/errorRegistry.d.ts +159 -0
  71. package/dist/src/errorRegistry.d.ts.map +1 -1
  72. package/dist/src/errorRegistry.js +115 -0
  73. package/dist/src/errorRegistry.js.map +1 -1
  74. package/dist/src/fieldExtraction.d.ts +125 -25
  75. package/dist/src/fieldExtraction.d.ts.map +1 -1
  76. package/dist/src/fieldExtraction.js +85 -16
  77. package/dist/src/fieldExtraction.js.map +1 -1
  78. package/dist/src/flagResolver.d.ts +75 -9
  79. package/dist/src/flagResolver.d.ts.map +1 -1
  80. package/dist/src/flagResolver.js +20 -4
  81. package/dist/src/flagResolver.js.map +1 -1
  82. package/dist/src/flagSemantics.d.ts +76 -1
  83. package/dist/src/flagSemantics.d.ts.map +1 -1
  84. package/dist/src/flagSemantics.js +66 -0
  85. package/dist/src/flagSemantics.js.map +1 -1
  86. package/dist/src/health/index.d.ts +87 -6
  87. package/dist/src/health/index.d.ts.map +1 -1
  88. package/dist/src/health/index.js +54 -6
  89. package/dist/src/health/index.js.map +1 -1
  90. package/dist/src/index.d.ts +12 -1
  91. package/dist/src/index.d.ts.map +1 -1
  92. package/dist/src/index.js +12 -1
  93. package/dist/src/index.js.map +1 -1
  94. package/dist/src/mviProjection.d.ts +42 -6
  95. package/dist/src/mviProjection.d.ts.map +1 -1
  96. package/dist/src/mviProjection.js +31 -5
  97. package/dist/src/mviProjection.js.map +1 -1
  98. package/dist/src/native-loader.d.ts +49 -0
  99. package/dist/src/native-loader.d.ts.map +1 -0
  100. package/dist/src/native-loader.js +56 -0
  101. package/dist/src/native-loader.js.map +1 -0
  102. package/dist/src/problemDetails.d.ts +70 -4
  103. package/dist/src/problemDetails.d.ts.map +1 -1
  104. package/dist/src/problemDetails.js +21 -3
  105. package/dist/src/problemDetails.js.map +1 -1
  106. package/dist/src/shutdown/index.d.ts +96 -7
  107. package/dist/src/shutdown/index.d.ts.map +1 -1
  108. package/dist/src/shutdown/index.js +72 -7
  109. package/dist/src/shutdown/index.js.map +1 -1
  110. package/dist/src/tokenEstimator.d.ts +97 -11
  111. package/dist/src/tokenEstimator.d.ts.map +1 -1
  112. package/dist/src/tokenEstimator.js +90 -11
  113. package/dist/src/tokenEstimator.js.map +1 -1
  114. package/dist/src/types.d.ts +467 -2
  115. package/dist/src/types.d.ts.map +1 -1
  116. package/dist/src/types.js +64 -0
  117. package/dist/src/types.js.map +1 -1
  118. package/dist/src/validateEnvelope.d.ts +59 -1
  119. package/dist/src/validateEnvelope.d.ts.map +1 -1
  120. package/dist/src/validateEnvelope.js +75 -9
  121. package/dist/src/validateEnvelope.js.map +1 -1
  122. package/dist/tsconfig.build.tsbuildinfo +1 -1
  123. package/lafs.md +3 -4
  124. package/package.json +6 -3
  125. package/dist/src/mcpAdapter.d.ts +0 -29
  126. package/dist/src/mcpAdapter.d.ts.map +0 -1
  127. package/dist/src/mcpAdapter.js +0 -286
  128. package/dist/src/mcpAdapter.js.map +0 -1
  129. package/schemas/v1/conformance-profiles.d.ts +0 -15
  130. package/schemas/v1/envelope.schema.d.ts +0 -14
  131. package/schemas/v1/error-registry.d.ts +0 -24
@@ -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) {
@@ -1 +1 @@
1
- {"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"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"}
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;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kDAA2D,CAAC;AA0J3F;;;;;;;;;;GAUG;AACH,SAAS,eAAe,CAAC,KAAqC;IAC5D,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,IAAI,UAAU,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,UAAU,CAAC,KAA8B;IAChD,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,OAAO;QACzC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,OAAO;QAC7C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;QACnC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC;QAC/B,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,CAAC;QACzC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA+C;IAC7E,UAAU,EAAE,gBAAgB;IAC5B,IAAI,EAAE,cAAc;IACpB,UAAU,EAAE,UAAU;IACtB,SAAS,EAAE,MAAM;IACjB,QAAQ,EAAE,gBAAgB;IAC1B,UAAU,EAAE,MAAM;IAClB,SAAS,EAAE,OAAO;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,gBAAgB;IAC1B,SAAS,EAAE,MAAM;CAClB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAS,cAAc,CAAC,KAAwC;IAC9D,MAAM,aAAa,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,aAAa,EAAE,QAAQ,IAAI,UAAU,CAAsB,CAAC;IAChG,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,aAAa,EAAE,SAAS,IAAI,KAAK,CAAC;IAEvE,8DAA8D;IAC9D,MAAM,WAAW,GACf,KAAK,CAAC,WAAW,IAAI,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAEnF,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAErD,MAAM,MAAM,GAAc;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ;QACR,SAAS;QACT,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;KAC7B,CAAC;IAEF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;IACnC,CAAC;IACD,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,CAAC;IACvD,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;IACjD,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEpC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO;YACL,OAAO,EAAE,eAAe;YACxB,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,KAAK;QACd,0EAA0E;QAC1E,6EAA6E;QAC7E,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;QAClC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,2CAA2C;IAC3C,IAAI,CAAS;IACb,8CAA8C;IAC9C,QAAQ,CAAoB;IAC5B,iEAAiE;IACjE,SAAS,CAAU;IACnB,oFAAoF;IACpF,YAAY,CAAgB;IAC5B,yEAAyE;IACzE,OAAO,CAA0B;IACjC,sEAAsE;IACtE,UAAU,CAAU;IACpB;;;;OAIG;IACH,WAAW,CAAmB;IAC9B;;;;OAIG;IACH,kBAAkB,CAAW;IAC7B;;;;OAIG;IACH,eAAe,CAAU;IACzB;;;;OAIG;IACH,MAAM,CAAU;IAEhB;;;;;;;;OAQG;IACH,YAAY,KAAgB;QAC1B,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QAC1E,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS;YAAE,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,CAAC;QAC/F,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS;YAAE,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;QACtF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7D,CAAC;CACF;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,UAAoC,EAAE;IAEtC,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC,MAAW,CAAC;IAC9B,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,OAAO,CAAC,0BAA0B,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC"}
@@ -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;AA0BpF,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAA8B,CAAC;AACxC,CAAC;AAED,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,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,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,WAA0C,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,OAAO,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,MAAM,CAAC;AACvB,CAAC;AAED,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"}
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"}