@cleocode/lafs 2026.4.0 → 2026.4.3

package/dist/src/discovery.js

@@ -22,7 +22,16 @@ catch {
 // Utility Functions
 // ============================================================================
 /**
- * Build absolute URL from base and path
+ * Build an absolute URL from a base and path.
+ *
+ * @param base - Base URL prefix (may be `undefined` to infer from request)
+ * @param path - Relative or absolute path
+ * @param req - Optional Express request for protocol/host inference
+ * @returns Absolute URL string
+ *
+ * @remarks
+ * Resolution order: if `path` is already absolute, return as-is; otherwise
+ * combine with `base`, or fall back to request headers.
  */
 function buildUrl(base, path, req) {
     if (path.startsWith('http://') || path.startsWith('https://')) {
@@ -41,13 +50,29 @@ function buildUrl(base, path, req) {
     return path.startsWith('/') ? path : `/${path}`;
 }
 /**
- * Generate ETag from content
+ * Generate an ETag from content.
+ *
+ * @param content - Serialized content string
+ * @returns Quoted SHA-256 ETag (first 32 hex chars)
+ *
+ * @remarks
+ * Uses SHA-256 truncated to 32 hex characters for a compact but
+ * collision-resistant ETag value.
  */
 function generateETag(content) {
     return `"${createHash('sha256').update(content).digest('hex').slice(0, 32)}"`;
 }
 /**
- * Build A2A Agent Card from configuration
+ * Build an A2A Agent Card from configuration.
+ *
+ * @param config - Discovery configuration
+ * @param req - Optional Express request for URL construction
+ * @returns Fully-populated {@link AgentCard}
+ *
+ * @remarks
+ * Handles automatic migration from legacy `service` config to the A2A v1.0 format
+ * with a console deprecation warning. When `autoIncludeLafsExtension` is set, the
+ * LAFS extension is appended to the card's capabilities.
  */
 function buildAgentCard(config, req) {
     const schemaUrl = config.schemaUrl || 'https://lafs.dev/schemas/v1/agent-card.schema.json';
@@ -105,8 +130,17 @@ function buildAgentCard(config, req) {
     return card;
 }
 /**
- * Build legacy discovery document for backward compatibility
- * @deprecated Will be removed in v2.0.0
+ * Build a legacy discovery document for backward compatibility.
+ *
+ * @param config - Discovery configuration
+ * @param req - Optional Express request for URL construction
+ * @returns Legacy {@link DiscoveryDocument}
+ *
+ * @remarks
+ * Generates the pre-A2A discovery document format from either the legacy
+ * `service` config or the modern `agent` config.
+ *
+ * @deprecated Will be removed in v2.0.0.
  */
 function buildLegacyDiscoveryDocument(config, req) {
     const schemaUrl = config.schemaUrl || 'https://lafs.dev/schemas/v1/discovery.schema.json';
@@ -140,14 +174,17 @@ function buildLegacyDiscoveryDocument(config, req) {
 // Middleware
 // ============================================================================
 /**
- * Create Express middleware for serving A2A Agent Card
- *
- * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
- * Maintains backward compatibility with legacy /.well-known/lafs.json
+ * Create Express middleware for serving A2A Agent Card.
  *
  * @param config - Discovery configuration (A2A v1.0 format)
- * @param options - Middleware options
- * @returns Express RequestHandler
+ * @param options - Middleware options for path routing and caching
+ * @returns Express RequestHandler that serves the Agent Card
+ *
+ * @remarks
+ * Serves an A2A-compliant Agent Card at `/.well-known/agent-card.json`.
+ * Maintains backward compatibility with the legacy `/.well-known/lafs.json`
+ * path (with deprecation warnings). Supports ETag-based conditional requests,
+ * HEAD requests, and configurable cache headers.
  *
  * @example
  * ```typescript
@@ -301,10 +338,27 @@ export function discoveryMiddleware(config, options = {}) {
     };
 }
 /**
- * Fastify plugin for A2A Agent Card discovery
+ * Fastify plugin for A2A Agent Card discovery.
  *
  * @param fastify - Fastify instance
- * @param options - Plugin options
+ * @param options - Plugin options containing `config` and optional `path`
+ * @returns Promise that resolves when the plugin is registered
+ *
+ * @remarks
+ * Registers a route on the Fastify instance to serve the A2A Agent Card
+ * with proper caching headers. The actual route registration depends on
+ * the Fastify API; this provides a type-safe plugin signature.
+ *
+ * @example
+ * ```typescript
+ * import Fastify from "fastify";
+ * import { discoveryFastifyPlugin } from "@cleocode/lafs/discovery";
+ *
+ * const app = Fastify();
+ * app.register(discoveryFastifyPlugin, {
+ *   config: { agent: { name: "my-agent", ... } },
+ * });
+ * ```
  */
 export async function discoveryFastifyPlugin(fastify, options) {
     const _path = options.path || '/.well-known/agent-card.json';

package/dist/src/discovery.js.map

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

package/dist/src/envelope.d.ts

@@ -1,28 +1,131 @@
 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;
+    /**
+     * 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;
+    /** 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;
+    /**
+     * 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;
+    /** 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.
@@ -32,30 +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
+     */
     _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

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,QAAQ,EACT,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,eAAe,EAAG,kDAA2D,CAAC;AAE3F,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,EAAE,uBAAuB,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,EAAE,uBAAuB,CAAC;CAC/B;AAED,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,wBAAwB,CAAC;AAyBxF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,iBAAiB,EAAE,eAAe,CAW1E,CAAC;AAuCF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CA0BvE;AAED,qBAAa,SAAU,SAAQ,KAAM,YAAW,SAAS;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEJ,KAAK,EAAE,SAAS;CAc7B;AAED,MAAM,WAAW,wBAAwB;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAC3C,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAgBH"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"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"}