@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/envelope.d.ts

@@ -1,29 +1,132 @@
-import type { LAFSEnvelope, LAFSError, LAFSErrorCategory, LAFSAgentAction, LAFSMeta, LAFSTransport, MVILevel } from "./types.js";
+import type { LAFSAgentAction, LAFSEnvelope, LAFSError, LAFSErrorCategory, LAFSMeta, LAFSTransport, MVILevel } from './types.js';
+/**
+ * Canonical JSON Schema URL for the LAFS v1 envelope.
+ *
+ * @remarks
+ * Every LAFS envelope includes this URL in its `$schema` field so that
+ * validators and tooling can locate the authoritative schema definition.
+ *
+ * @example
+ * ```ts
+ * import { LAFS_SCHEMA_URL } from '@cleocode/lafs';
+ * console.log(LAFS_SCHEMA_URL);
+ * // => 'https://lafs.dev/schemas/v1/envelope.schema.json'
+ * ```
+ */
 export declare const LAFS_SCHEMA_URL: "https://lafs.dev/schemas/v1/envelope.schema.json";
+/**
+ * Input for constructing the `_meta` block of a LAFS envelope.
+ *
+ * @remarks
+ * Only `operation` and `requestId` are required; all other fields have
+ * sensible defaults (see {@link createEnvelope} for the resolution logic).
+ */
 export interface CreateEnvelopeMetaInput {
+    /** Dot-delimited operation identifier (e.g. `"tasks.list"`). */
     operation: string;
+    /** Unique identifier for correlating this request/response pair. */
     requestId: string;
+    /**
+     * Transport protocol for this envelope.
+     *
+     * @defaultValue 'sdk'
+     */
     transport?: LAFSTransport;
+    /**
+     * LAFS spec version to stamp on the envelope.
+     *
+     * @defaultValue '1.0.0'
+     */
     specVersion?: string;
+    /**
+     * JSON Schema version to stamp on the envelope.
+     *
+     * @defaultValue '1.0.0'
+     */
     schemaVersion?: string;
+    /**
+     * ISO 8601 timestamp; auto-generated when omitted.
+     *
+     * @defaultValue undefined
+     */
     timestamp?: string;
+    /**
+     * Whether strict schema validation should be applied.
+     *
+     * @defaultValue true
+     */
     strict?: boolean;
+    /**
+     * MVI level as a string, or `true` for `'minimal'` / `false` for `'standard'`.
+     *
+     * @defaultValue 'standard'
+     */
     mvi?: MVILevel | boolean;
+    /**
+     * Context ledger version the caller is operating against.
+     *
+     * @defaultValue 0
+     */
     contextVersion?: number;
+    /**
+     * Session identifier for multi-step workflow correlation.
+     *
+     * @defaultValue undefined
+     */
     sessionId?: string;
-    warnings?: LAFSMeta["warnings"];
+    /**
+     * Non-fatal warnings to attach to the envelope metadata.
+     *
+     * @defaultValue undefined
+     */
+    warnings?: LAFSMeta['warnings'];
 }
+/**
+ * Input for creating a successful LAFS envelope.
+ *
+ * @remarks
+ * When `success` is `true`, the `result` field carries the operation payload
+ * and `error` is forced to `null` in the output envelope.
+ */
 export interface CreateEnvelopeSuccessInput {
+    /** Discriminant marking this as a success input. */
     success: true;
-    result: LAFSEnvelope["result"];
-    page?: LAFSEnvelope["page"];
+    /** Operation result payload (object, array, or `null`). */
+    result: LAFSEnvelope['result'];
+    /**
+     * Pagination metadata for collection results.
+     *
+     * @defaultValue undefined
+     */
+    page?: LAFSEnvelope['page'];
+    /**
+     * Must be `null` for success inputs; exists for type uniformity with error inputs.
+     *
+     * @defaultValue undefined
+     */
     error?: null;
-    _extensions?: LAFSEnvelope["_extensions"];
+    /**
+     * Vendor or protocol extension data.
+     *
+     * @defaultValue undefined
+     */
+    _extensions?: LAFSEnvelope['_extensions'];
+    /** Metadata input for constructing the envelope's `_meta` block. */
     meta: CreateEnvelopeMetaInput;
 }
+/**
+ * Input for creating a failing LAFS envelope.
+ *
+ * @remarks
+ * When `success` is `false`, the `error` field is required and will be
+ * normalized (category, agent action, doc URL) via the error registry.
+ * An optional `result` can carry actionable data alongside the error.
+ */
 export interface CreateEnvelopeErrorInput {
+    /** Discriminant marking this as an error input. */
     success: false;
-    error: Partial<LAFSError> & Pick<LAFSError, "code" | "message">;
+    /** Partial error object; at minimum `code` and `message` are required. */
+    error: Partial<LAFSError> & Pick<LAFSError, 'code' | 'message'>;
     /**
      * Optional result payload to include alongside the error.
      * For validation tools (linters, type checkers), the actionable data
@@ -32,29 +135,179 @@ export interface CreateEnvelopeErrorInput {
      * and the detailed result in a single response.
      *
      * When omitted or null, the envelope emits `result: null` (default behavior).
+     *
+     * @defaultValue undefined
+     */
+    result?: LAFSEnvelope['result'] | null;
+    /**
+     * Pagination metadata, if applicable even in error scenarios.
+     *
+     * @defaultValue undefined
+     */
+    page?: LAFSEnvelope['page'];
+    /**
+     * Vendor or protocol extension data.
+     *
+     * @defaultValue undefined
      */
-    result?: LAFSEnvelope["result"] | null;
-    page?: LAFSEnvelope["page"];
-    _extensions?: LAFSEnvelope["_extensions"];
+    _extensions?: LAFSEnvelope['_extensions'];
+    /** Metadata input for constructing the envelope's `_meta` block. */
     meta: CreateEnvelopeMetaInput;
 }
+/**
+ * Discriminated union of success and error inputs for {@link createEnvelope}.
+ *
+ * @remarks
+ * The `success` boolean discriminant determines which branch is active and
+ * which fields are required.
+ */
 export type CreateEnvelopeInput = CreateEnvelopeSuccessInput | CreateEnvelopeErrorInput;
+/**
+ * Default agent action for each error category.
+ *
+ * @remarks
+ * When a {@link LAFSError} does not specify an explicit `agentAction` and the
+ * error registry has no override, this map provides the fallback recommendation
+ * based on the error's category.
+ *
+ * @example
+ * ```ts
+ * import { CATEGORY_ACTION_MAP } from '@cleocode/lafs';
+ * const action = CATEGORY_ACTION_MAP['RATE_LIMIT']; // => 'wait'
+ * ```
+ */
 export declare const CATEGORY_ACTION_MAP: Record<LAFSErrorCategory, LAFSAgentAction>;
+/**
+ * Create a fully validated LAFS envelope from a success or error input.
+ *
+ * @param input - Discriminated union of success or error input data.
+ * @returns A complete {@link LAFSEnvelope} ready for serialization.
+ *
+ * @remarks
+ * This is the primary factory for LAFS envelopes. It delegates to
+ * internal `createMeta` for metadata construction and `normalizeError`
+ * for error normalization. Optional fields (`page`, `_extensions`) are only
+ * included when explicitly provided, keeping the envelope minimal.
+ *
+ * @example
+ * ```ts
+ * import { createEnvelope } from '@cleocode/lafs';
+ *
+ * const envelope = createEnvelope({
+ *   success: true,
+ *   result: { items: [] },
+ *   meta: { operation: 'tasks.list', requestId: 'req-1' },
+ * });
+ * ```
+ */
 export declare function createEnvelope(input: CreateEnvelopeInput): LAFSEnvelope;
+/**
+ * Error subclass that carries the full {@link LAFSError} payload.
+ *
+ * @remarks
+ * Thrown by {@link parseLafsResponse} when the envelope indicates failure.
+ * Implements {@link LAFSError} so consumers can access structured error
+ * metadata directly on the caught error instance. The `registered` flag
+ * indicates whether the error code exists in the canonical error registry.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   parseLafsResponse(envelope);
+ * } catch (err) {
+ *   if (err instanceof LafsError) {
+ *     console.log(err.code, err.agentAction);
+ *   }
+ * }
+ * ```
+ */
 export declare class LafsError extends Error implements LAFSError {
+    /** Stable, machine-readable error code. */
     code: string;
+    /** High-level classification of the error. */
     category: LAFSErrorCategory;
+    /** Whether the operation can be retried without modification. */
     retryable: boolean;
+    /** Suggested delay in milliseconds before retrying, or `null` if not applicable. */
     retryAfterMs: number | null;
+    /** Arbitrary key-value pairs with additional context about the error. */
     details: Record<string, unknown>;
+    /** Whether this error code exists in the canonical error registry. */
     registered: boolean;
+    /**
+     * Recommended action for the consuming agent.
+     *
+     * @defaultValue undefined
+     */
     agentAction?: LAFSAgentAction;
+    /**
+     * Whether the error requires human or higher-privilege intervention.
+     *
+     * @defaultValue undefined
+     */
     escalationRequired?: boolean;
+    /**
+     * Free-text description of a suggested recovery action.
+     *
+     * @defaultValue undefined
+     */
     suggestedAction?: string;
+    /**
+     * URL pointing to documentation about this error code.
+     *
+     * @defaultValue undefined
+     */
     docUrl?: string;
+    /**
+     * Create a new `LafsError` from a structured {@link LAFSError} payload.
+     *
+     * @param error - The structured error data to wrap.
+     *
+     * @remarks
+     * Copies all fields from the input and sets `registered` by checking the
+     * error code against the canonical registry via {@link isRegisteredErrorCode}.
+     */
     constructor(error: LAFSError);
 }
+/**
+ * Options for {@link parseLafsResponse}.
+ *
+ * @remarks
+ * Controls how strictly the parser validates the error code against the
+ * canonical error registry.
+ */
 export interface ParseLafsResponseOptions {
+    /**
+     * When `true`, unregistered error codes cause an additional `Error` to be
+     * thrown instead of the normal {@link LafsError}.
+     *
+     * @defaultValue undefined
+     */
     requireRegisteredErrorCode?: boolean;
 }
+/**
+ * Parse and unwrap a raw LAFS envelope, returning the result or throwing on error.
+ *
+ * @typeParam T - Expected type of the result payload.
+ * @param input - Raw value expected to be a valid {@link LAFSEnvelope}.
+ * @param options - Parsing options controlling error-code validation.
+ * @returns The `result` field of the envelope cast to `T`.
+ * @throws {LafsError} When the envelope indicates failure (`success=false`).
+ * @throws {Error} When the envelope is structurally invalid or
+ *   `requireRegisteredErrorCode` is `true` and the code is unregistered.
+ *
+ * @remarks
+ * Delegates to {@link assertEnvelope} for schema validation before inspecting
+ * the `success` flag. On success, the `result` is returned directly. On
+ * failure, the `error` payload is wrapped in a {@link LafsError} and thrown.
+ *
+ * @example
+ * ```ts
+ * import { parseLafsResponse } from '@cleocode/lafs';
+ *
+ * interface TaskList { items: Task[] }
+ * const tasks = parseLafsResponse<TaskList>(rawEnvelope);
+ * ```
+ */
 export declare function parseLafsResponse<T = unknown>(input: unknown, options?: ParseLafsResponseOptions): T;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"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"}

package/dist/src/envelope.js

@@ -1,20 +1,56 @@
-import { isRegisteredErrorCode, getRegistryCode, getAgentAction, getDocUrl } from "./errorRegistry.js";
-import { assertEnvelope } from "./validateEnvelope.js";
-export const LAFS_SCHEMA_URL = "https://lafs.dev/schemas/v1/envelope.schema.json";
+import { getAgentAction, getDocUrl, getRegistryCode, isRegisteredErrorCode, } from './errorRegistry.js';
+import { assertEnvelope } from './validateEnvelope.js';
+/**
+ * Canonical JSON Schema URL for the LAFS v1 envelope.
+ *
+ * @remarks
+ * Every LAFS envelope includes this URL in its `$schema` field so that
+ * validators and tooling can locate the authoritative schema definition.
+ *
+ * @example
+ * ```ts
+ * import { LAFS_SCHEMA_URL } from '@cleocode/lafs';
+ * console.log(LAFS_SCHEMA_URL);
+ * // => 'https://lafs.dev/schemas/v1/envelope.schema.json'
+ * ```
+ */
+export const LAFS_SCHEMA_URL = 'https://lafs.dev/schemas/v1/envelope.schema.json';
+/**
+ * Resolve an MVI input (string, boolean, or undefined) to a canonical {@link MVILevel}.
+ *
+ * @param input - MVI value from the caller: a level string, `true` for minimal,
+ *   `false` for standard, or `undefined` for the default.
+ * @returns The resolved {@link MVILevel} string.
+ *
+ * @remarks
+ * Boolean shorthand exists for CLI convenience: `--mvi` (no value) maps to
+ * `true` which resolves to `'minimal'`.
+ */
 function resolveMviLevel(input) {
-    if (typeof input === "boolean") {
-        return input ? "minimal" : "standard";
+    if (typeof input === 'boolean') {
+        return input ? 'minimal' : 'standard';
     }
-    return input ?? "standard";
+    return input ?? 'standard';
 }
+/**
+ * Build a fully populated {@link LAFSMeta} object from partial input.
+ *
+ * @param input - Caller-supplied metadata fields; missing values receive defaults.
+ * @returns A complete {@link LAFSMeta} ready for embedding in an envelope.
+ *
+ * @remarks
+ * Defaults: `specVersion` and `schemaVersion` to `'1.0.0'`, `transport` to
+ * `'sdk'`, `strict` to `true`, `mvi` to `'standard'`, `contextVersion` to `0`,
+ * and `timestamp` to the current time.
+ */
 function createMeta(input) {
     return {
-        specVersion: input.specVersion ?? "1.0.0",
-        schemaVersion: input.schemaVersion ?? "1.0.0",
+        specVersion: input.specVersion ?? '1.0.0',
+        schemaVersion: input.schemaVersion ?? '1.0.0',
         timestamp: input.timestamp ?? new Date().toISOString(),
         operation: input.operation,
         requestId: input.requestId,
-        transport: input.transport ?? "sdk",
+        transport: input.transport ?? 'sdk',
         strict: input.strict ?? true,
         mvi: resolveMviLevel(input.mvi),
         contextVersion: input.contextVersion ?? 0,
@@ -22,6 +58,20 @@ function createMeta(input) {
         ...(input.warnings ? { warnings: input.warnings } : {}),
     };
 }
+/**
+ * Default agent action for each error category.
+ *
+ * @remarks
+ * When a {@link LAFSError} does not specify an explicit `agentAction` and the
+ * error registry has no override, this map provides the fallback recommendation
+ * based on the error's category.
+ *
+ * @example
+ * ```ts
+ * import { CATEGORY_ACTION_MAP } from '@cleocode/lafs';
+ * const action = CATEGORY_ACTION_MAP['RATE_LIMIT']; // => 'wait'
+ * ```
+ */
 export const CATEGORY_ACTION_MAP = {
     VALIDATION: 'retry_modified',
     AUTH: 'authenticate',
@@ -34,14 +84,25 @@ export const CATEGORY_ACTION_MAP = {
     CONTRACT: 'retry_modified',
     MIGRATION: 'stop',
 };
+/**
+ * Normalize a partial error input into a fully populated {@link LAFSError}.
+ *
+ * @param error - Partial error with at least `code` and `message`.
+ * @returns A complete {@link LAFSError} with category, retryable flag, agent
+ *   action, and optional doc URL resolved from the error registry and
+ *   category-action map.
+ *
+ * @remarks
+ * Resolution precedence for `agentAction`: explicit caller value > error
+ * registry entry > {@link CATEGORY_ACTION_MAP} fallback. The same pattern
+ * applies to `category`, `retryable`, and `docUrl`.
+ */
 function normalizeError(error) {
     const registryEntry = getRegistryCode(error.code);
-    const category = (error.category ?? registryEntry?.category ?? "INTERNAL");
+    const category = (error.category ?? registryEntry?.category ?? 'INTERNAL');
     const retryable = error.retryable ?? registryEntry?.retryable ?? false;
     // Derive agentAction: explicit > registry > category fallback
-    const agentAction = error.agentAction ??
-        getAgentAction(error.code) ??
-        CATEGORY_ACTION_MAP[category];
+    const agentAction = error.agentAction ?? getAgentAction(error.code) ?? CATEGORY_ACTION_MAP[category];
     const docUrl = error.docUrl ?? getDocUrl(error.code);
     const result = {
         code: error.code,
@@ -65,6 +126,29 @@ function normalizeError(error) {
     }
     return result;
 }
+/**
+ * Create a fully validated LAFS envelope from a success or error input.
+ *
+ * @param input - Discriminated union of success or error input data.
+ * @returns A complete {@link LAFSEnvelope} ready for serialization.
+ *
+ * @remarks
+ * This is the primary factory for LAFS envelopes. It delegates to
+ * internal `createMeta` for metadata construction and `normalizeError`
+ * for error normalization. Optional fields (`page`, `_extensions`) are only
+ * included when explicitly provided, keeping the envelope minimal.
+ *
+ * @example
+ * ```ts
+ * import { createEnvelope } from '@cleocode/lafs';
+ *
+ * const envelope = createEnvelope({
+ *   success: true,
+ *   result: { items: [] },
+ *   meta: { operation: 'tasks.list', requestId: 'req-1' },
+ * });
+ * ```
+ */
 export function createEnvelope(input) {
     const meta = createMeta(input.meta);
     if (input.success) {
@@ -90,20 +174,75 @@ export function createEnvelope(input) {
         ...(input._extensions !== undefined ? { _extensions: input._extensions } : {}),
     };
 }
+/**
+ * Error subclass that carries the full {@link LAFSError} payload.
+ *
+ * @remarks
+ * Thrown by {@link parseLafsResponse} when the envelope indicates failure.
+ * Implements {@link LAFSError} so consumers can access structured error
+ * metadata directly on the caught error instance. The `registered` flag
+ * indicates whether the error code exists in the canonical error registry.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   parseLafsResponse(envelope);
+ * } catch (err) {
+ *   if (err instanceof LafsError) {
+ *     console.log(err.code, err.agentAction);
+ *   }
+ * }
+ * ```
+ */
 export class LafsError extends Error {
+    /** Stable, machine-readable error code. */
     code;
+    /** High-level classification of the error. */
     category;
+    /** Whether the operation can be retried without modification. */
     retryable;
+    /** Suggested delay in milliseconds before retrying, or `null` if not applicable. */
     retryAfterMs;
+    /** Arbitrary key-value pairs with additional context about the error. */
     details;
+    /** Whether this error code exists in the canonical error registry. */
     registered;
+    /**
+     * Recommended action for the consuming agent.
+     *
+     * @defaultValue undefined
+     */
     agentAction;
+    /**
+     * Whether the error requires human or higher-privilege intervention.
+     *
+     * @defaultValue undefined
+     */
     escalationRequired;
+    /**
+     * Free-text description of a suggested recovery action.
+     *
+     * @defaultValue undefined
+     */
     suggestedAction;
+    /**
+     * URL pointing to documentation about this error code.
+     *
+     * @defaultValue undefined
+     */
     docUrl;
+    /**
+     * Create a new `LafsError` from a structured {@link LAFSError} payload.
+     *
+     * @param error - The structured error data to wrap.
+     *
+     * @remarks
+     * Copies all fields from the input and sets `registered` by checking the
+     * error code against the canonical registry via {@link isRegisteredErrorCode}.
+     */
     constructor(error) {
         super(error.message);
-        this.name = "LafsError";
+        this.name = 'LafsError';
         this.code = error.code;
         this.category = error.category;
         this.retryable = error.retryable;
@@ -120,6 +259,30 @@ export class LafsError extends Error {
             this.docUrl = error.docUrl;
     }
 }
+/**
+ * Parse and unwrap a raw LAFS envelope, returning the result or throwing on error.
+ *
+ * @typeParam T - Expected type of the result payload.
+ * @param input - Raw value expected to be a valid {@link LAFSEnvelope}.
+ * @param options - Parsing options controlling error-code validation.
+ * @returns The `result` field of the envelope cast to `T`.
+ * @throws {LafsError} When the envelope indicates failure (`success=false`).
+ * @throws {Error} When the envelope is structurally invalid or
+ *   `requireRegisteredErrorCode` is `true` and the code is unregistered.
+ *
+ * @remarks
+ * Delegates to {@link assertEnvelope} for schema validation before inspecting
+ * the `success` flag. On success, the `result` is returned directly. On
+ * failure, the `error` payload is wrapped in a {@link LafsError} and thrown.
+ *
+ * @example
+ * ```ts
+ * import { parseLafsResponse } from '@cleocode/lafs';
+ *
+ * interface TaskList { items: Task[] }
+ * const tasks = parseLafsResponse<TaskList>(rawEnvelope);
+ * ```
+ */
 export function parseLafsResponse(input, options = {}) {
     const envelope = assertEnvelope(input);
     if (envelope.success) {
@@ -127,10 +290,11 @@ export function parseLafsResponse(input, options = {}) {
     }
     const error = envelope.error;
     if (!error) {
-        throw new Error("Invalid LAFS envelope: success=false requires error object");
+        throw new Error('Invalid LAFS envelope: success=false requires error object');
     }
     if (options.requireRegisteredErrorCode && !isRegisteredErrorCode(error.code)) {
         throw new Error(`Unregistered LAFS error code: ${error.code}`);
     }
     throw new LafsError(error);
 }
+//# sourceMappingURL=envelope.js.map

package/dist/src/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"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"}