@jarenjs/contract 0.43.1

package/dist/types/port/frame.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @file The frame grammar of the port binding (docs/CONTRACT-FORMAT.md
+ * §16), shared by `servePort` and `openPortClient`: JSON-safe plain
+ * objects marked `jaren: "contract/0.1"`, so contract traffic is
+ * distinguishable BY SHAPE from anything else on a shared channel — a
+ * frame without the marker is never touched, and never answered.
+ *
+ * Request ids are `"<clientId>:<seq>"` — the client id a UUID per
+ * client instance, the sequence a per-client counter — so two clients
+ * on one broadcast channel can never collide, and a client recognizes
+ * its own responses with one cheap prefix test before any map lookup.
+ * The request members `attempt` and `key` are reserved by the grammar
+ * (`schemas/jaren-contract-port.schema.json`) and ignored by this
+ * order's server: the attempt id stays caller-side in `meta` (D6 — the
+ * identities live in state, never in the transport) and idempotency is
+ * not carried on this binding (`capabilities` says so).
+ */
+/** The frame marker: the protocol and its version. */
+export declare const FRAME_MARKER = "contract/0.1";
+export type RequestFrame = {
+    jaren: string;
+    id: string;
+    op: string;
+    input: unknown;
+};
+export type ResponseFrame = {
+    jaren: string;
+    id: string;
+    ok: true;
+    value: unknown;
+    trace: string;
+} | {
+    jaren: string;
+    id: string;
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+        retryable?: boolean;
+    };
+    trace: string;
+};
+export type CancelFrame = {
+    jaren: string;
+    cancel: string;
+};
+export type SubscribeFrame = {
+    jaren: string;
+    subscribe: string;
+    op: string;
+    input: unknown;
+    lastSeq?: number;
+};
+export type UnsubscribeFrame = {
+    jaren: string;
+    unsubscribe: string;
+};
+export type PushFrame = {
+    jaren: string;
+    id: string;
+    event: string;
+    seq: number;
+    data: unknown;
+};
+export type ChannelLike = {
+    postMessage: (message: any) => void;
+    addEventListener?: (type: string, listener: (event: any) => void) => void;
+    removeEventListener?: (type: string, listener: (event: any) => void) => void;
+    onmessage?: ((event: any) => void) | null;
+    start?: () => void;
+};
+/**
+ * A request frame. `input` is the whole (validated) input object, or
+ * `null` for an input-less operation.
+ * @typedef {{ jaren: string, id: string, op: string, input: unknown }} RequestFrame
+ */
+/**
+ * A response frame: success with the value, or an error envelope —
+ * `code` a declared error code or a `JC2xxx` taxonomy/binding code,
+ * `details` present only when the failure carries some. Every response
+ * carries the server's `trace`.
+ * @typedef {{ jaren: string, id: string, ok: true, value: unknown, trace: string }
+ *   | { jaren: string, id: string, ok: false, error: { code: string, message: string, details?: unknown, retryable?: boolean }, trace: string }} ResponseFrame
+ */
+/**
+ * A cancel frame: aborts the server-side signal of the named request —
+ * an optimization; the client's id scoping is the guarantee. Never
+ * answered.
+ * @typedef {{ jaren: string, cancel: string }} CancelFrame
+ */
+/**
+ * A subscribe frame: opens one stream (docs/CONTRACT-FORMAT.md §18.2).
+ * `input` is the whole (validated) input object or `null`; `lastSeq`,
+ * when present, asks to resume after that seq.
+ * @typedef {{ jaren: string, subscribe: string, op: string, input: unknown, lastSeq?: number }} SubscribeFrame
+ */
+/**
+ * An unsubscribe frame: closes the named stream. Never answered.
+ * @typedef {{ jaren: string, unsubscribe: string }} UnsubscribeFrame
+ */
+/**
+ * A push frame: one stream event, server → client. `event` is
+ * `snapshot | patch | error | end` with the §18 data shapes; `seq` is
+ * the event's seq (`error`/`end` carry the last delivered one).
+ * @typedef {{ jaren: string, id: string, event: string, seq: number, data: unknown }} PushFrame
+ */
+/**
+ * The channel shape both halves accept: a `MessagePort`, a `Worker`, a
+ * `BroadcastChannel`, a worker's own `self`, or any object with
+ * `postMessage` and a message-listener surface. `start` is called when
+ * present (a `MessagePort` queues until it is).
+ * @typedef {{ postMessage: (message: any) => void,
+ *   addEventListener?: (type: string, listener: (event: any) => void) => void,
+ *   removeEventListener?: (type: string, listener: (event: any) => void) => void,
+ *   onmessage?: ((event: any) => void) | null,
+ *   start?: () => void }} ChannelLike
+ */
+/**
+ * Whether a value is a contract frame at all — the marker test every
+ * listener applies first, so foreign traffic on a shared channel is
+ * ignored by shape. Reads one member of a plain object; total.
+ * @param {unknown} value
+ * @returns {value is { jaren: string }}
+ */
+export declare function isContractFrame(value: unknown): value is {
+    jaren: string;
+};
+/**
+ * @param {string} id
+ * @param {string} op
+ * @param {unknown} input
+ * @returns {RequestFrame}
+ */
+export declare function requestFrame(id: string, op: string, input: unknown): RequestFrame;
+/**
+ * @param {string} id
+ * @param {unknown} value - `undefined` is carried as `null` (frames are JSON)
+ * @param {string} trace
+ * @returns {ResponseFrame}
+ */
+export declare function valueFrame(id: string, value: unknown, trace: string): ResponseFrame;
+/**
+ * @param {string} id
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} details - omitted from the frame when `undefined`
+ * @param {boolean} retryable
+ * @param {string} trace
+ * @returns {ResponseFrame}
+ */
+export declare function errorFrame(id: string, code: string, message: string, details: unknown, retryable: boolean, trace: string): ResponseFrame;
+/**
+ * @param {string} id
+ * @returns {CancelFrame}
+ */
+export declare function cancelFrame(id: string): CancelFrame;
+/**
+ * @param {string} id
+ * @param {string} op
+ * @param {unknown} input
+ * @param {number | null} lastSeq - omitted from the frame when `null`
+ * @returns {SubscribeFrame}
+ */
+export declare function subscribeFrame(id: string, op: string, input: unknown, lastSeq: number | null): SubscribeFrame;
+/**
+ * @param {string} id
+ * @returns {UnsubscribeFrame}
+ */
+export declare function unsubscribeFrame(id: string): UnsubscribeFrame;
+/**
+ * @param {string} id
+ * @param {string} event - `snapshot | patch | error | end`
+ * @param {number} seq
+ * @param {unknown} data
+ * @returns {PushFrame}
+ */
+export declare function pushFrame(id: string, event: string, seq: number, data: unknown): PushFrame;
+/**
+ * Attach a message listener to a channel: `addEventListener` where the
+ * channel has one (plus `start()`, which a `MessagePort` needs to begin
+ * delivery), the `onmessage` slot otherwise. Returns the detacher.
+ * @param {ChannelLike} channel
+ * @param {(event: any) => void} listener
+ * @returns {() => void}
+ */
+export declare function attach(channel: ChannelLike, listener: (event: any) => void): () => void;
+/**
+ * Whether a value is a usable channel. The listener surface is either
+ * `addEventListener` or an assignable `onmessage` slot — `in` sees the
+ * slot on platform channels and plain fakes alike.
+ * @param {unknown} value
+ * @returns {value is ChannelLike}
+ */
+export declare function isChannel(value: unknown): value is ChannelLike;

package/dist/types/port/serve.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file `servePort(contract, handlers, options)`: the server half of the
+ * port binding (docs/CONTRACT-FORMAT.md §16) — request/response over a
+ * `MessagePort`, a `Worker`, a `BroadcastChannel` or a worker's own
+ * `self`. Requests run through the same neutral pipeline as every other
+ * server binding, under one `AbortController` per request id; a cancel
+ * frame aborts it (an optimization — the client's id scoping is the
+ * guarantee), and the response is posted back on the same channel.
+ *
+ * The listener touches nothing without the frame marker — other traffic
+ * may share the channel and is never answered — and never answers a
+ * RESPONSE frame either, so two ends on one broadcast channel cannot
+ * echo at each other. A request naming an operation this channel does
+ * not serve (unknown, or opaque — a port carries JSON only) is answered
+ * `JC2071` without echoing what it asked for; an invalid input is
+ * `JC2006` with details by the operation's policy; a handler fault of
+ * any class is `JC2070` with the cause reported to `onError`, never
+ * onto the wire. Exactly ONE server should serve a shared channel — two
+ * would both answer every request.
+ */
+import { PORT_LOCAL_ERRORS } from '../pipeline.js';
+export { openPortClient } from './client.js';
+export { FRAME_MARKER, isContractFrame } from './frame.js';
+export { PORT_LOCAL_ERRORS };
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type Catalog = import('../http/wire.js').Catalog;
+export type Handler = import('../http/dispatch.js').Handler;
+export type PipelineRoute = import('../pipeline.js').PipelineRoute;
+export type ChannelLike = import('./frame.js').ChannelLike;
+export type ServePortOptions = {
+    /**
+     * - the channel to serve (required)
+     */
+    channel: ChannelLike;
+    /**
+     * - the server trace generator; default `crypto.randomUUID`
+     */
+    trace?: () => string;
+    /**
+     * - `'never'` is a declared
+     * downgrade, reported in `capabilities.validatedOutput`
+     */
+    validateOutput?: 'always' | 'never';
+    /**
+     * - a message catalog consulted before the English one
+     */
+    catalog?: Record<string, string | ((params: object) => string)>;
+    /**
+     * - observes the cause behind every `JC2070` frame, validator throws
+     * and a channel whose `postMessage` throws
+     */
+    onError?: (error: unknown, ctx: {
+        op: string;
+        trace: string;
+    } | null) => void;
+};
+export type PortServerCapabilities = {
+    name: 'port';
+    status: false;
+    headers: false;
+    media: false;
+    etag: false;
+    idempotency: false;
+    validatedOutput: boolean;
+    /**
+     * - subscribe operations stream as push frames (docs/CONTRACT-FORMAT.md §18.2)
+     */
+    stream: true;
+    cancel: 'message';
+};
+export type PortServer = {
+    capabilities: PortServerCapabilities;
+    contract: Contract;
+    describe: () => any;
+    /**
+     * - ends every live stream with `end`
+     * (`server-shutdown`), detaches the listener and aborts every in-flight request
+     */
+    close: () => void;
+};
+export type PortRoute = PipelineRoute & {
+    stream: boolean;
+};
+/**
+ * Serve a compiled contract over a message channel. Construction refuses
+ * host mistakes (`JC1001` handler table, channel or option, `JC1002`
+ * missing handler — an opaque operation is exempt, it is answered
+ * `JC2071` instead of served).
+ *
+ * @param {Contract} contract
+ * @param {Record<string, Handler>} handlers - operation id → handler
+ * @param {ServePortOptions} options
+ * @returns {PortServer}
+ * @throws {ContractHostError}
+ * @example
+ * // inside a worker: serve the worker's own channel
+ * servePort(contract, handlers, { channel: self });
+ * // and the same handlers to every tab on a BroadcastChannel
+ * servePort(contract, handlers, { channel: new BroadcastChannel('app') });
+ */
+export declare function servePort(contract: Contract, handlers: Record<string, Handler>, options: ServePortOptions): PortServer;

package/dist/types/project/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file The projections of a compiled contract (`@jarenjs/contract/project`):
+ * `publicProjection` (the browser-safe subset — itself a `$contract`
+ * document, and what the revision hashes), `toOpenApi` (OpenAPI 3.1
+ * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
+ * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
+ * definitions, no import edge) and the same-document bundler they share.
+ * This is the one subpath that imports `@jarenjs/emit`; a consumer that
+ * never imports it never loads it.
+ */
+export { publicProjection } from '../public.js';
+export { toOpenApi } from './openapi.js';
+export { toTypeScript } from './typescript.js';
+export { toMarkdown } from './markdown.js';
+export { contractTools } from './tools.js';
+export { reachableDefs, bundleSameDocument } from '../bundle.js';
+export type PublicProjectionOptions = import('../public.js').PublicProjectionOptions;
+export type OpenApiOptions = import('./openapi.js').OpenApiOptions;
+export type OpenApiResult = import('./openapi.js').OpenApiResult;
+export type DroppedKeyword = import('./openapi.js').DroppedKeyword;
+export type TypeScriptOptions = import('./typescript.js').TypeScriptOptions;
+export type MarkdownOptions = import('./markdown.js').MarkdownOptions;
+export type ToolDefinition = import('./tools.js').ToolDefinition;
+export type ContractToolsOptions = import('./tools.js').ContractToolsOptions;
+/**
+ * @typedef {import('../public.js').PublicProjectionOptions} PublicProjectionOptions
+ * @typedef {import('./openapi.js').OpenApiOptions} OpenApiOptions
+ * @typedef {import('./openapi.js').OpenApiResult} OpenApiResult
+ * @typedef {import('./openapi.js').DroppedKeyword} DroppedKeyword
+ * @typedef {import('./typescript.js').TypeScriptOptions} TypeScriptOptions
+ * @typedef {import('./markdown.js').MarkdownOptions} MarkdownOptions
+ * @typedef {import('./tools.js').ToolDefinition} ToolDefinition
+ * @typedef {import('./tools.js').ContractToolsOptions} ContractToolsOptions
+ */

package/dist/types/project/markdown.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file `toMarkdown`: a compiled contract as one reference document —
+ * the title and version, an operations table, one section per public
+ * operation (its doc, parameters, body, responses, errors) and the types
+ * rendered through `@jarenjs/emit`'s Markdown target over the SAME type
+ * model the TypeScript projection uses (`contractTypeModel`), so the
+ * names a reader meets in the operation sections are the names the
+ * `.d.ts` declares. The document shape is a JTLT stylesheet (compiled
+ * once at module scope); the JavaScript half derives the rows.
+ */
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type MarkdownOptions = {
+    /**
+     * - the document title (default: the contract id, or `jaren-contract`)
+     */
+    title?: string;
+};
+/**
+ * Project a compiled contract to Markdown reference documentation.
+ * @param {Contract} contract
+ * @param {MarkdownOptions} [options]
+ * @returns {string} Markdown
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or a malformed option
+ * @example
+ * writeFileSync('shop.md', toMarkdown(contract, { title: 'Shop API' }));
+ */
+export declare function toMarkdown(contract: Contract, options?: MarkdownOptions): string;

package/dist/types/project/openapi.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file `toOpenApi`: the public projection of a compiled contract as a
+ * valid, deterministic OpenAPI 3.1 document (docs/CONTRACT-FORMAT.md
+ * §12.2), in two stages that each own one concern:
+ *
+ *  1. **The keyword policy** (this file, JavaScript) walks every schema
+ *     the projection carries and maps it into the OpenAPI 3.1 dialect —
+ *     `#/$defs/X` → `#/components/schemas/X`, `nullable: true` → `null`
+ *     in `type` — or refuses what it cannot map honestly (`JC0060`: a
+ *     boolean `required`, a `components` member inside a schema, a
+ *     same-document `$ref` that lands outside `$defs`) or drops and
+ *     REPORTS what is Jaren-side (`$query`, `$data`, `errorMessage`,
+ *     `x-form` and other `x-*`) in the `dropped` list with the `docPath`
+ *     of the keyword in the contract document. Nothing unsupported passes
+ *     through silently. It also derives, per operation, the facts a
+ *     document cannot carry for a `$ref` input — the member table with
+ *     each member's location, requiredness and effective schema — from
+ *     the compiled operation.
+ *  2. **The stylesheet** (`openapi.jslt.json`, a JSLT document compiled
+ *     once at module scope) shapes the document: `paths` grouped by
+ *     canonical path and sorted by path then method, the operation
+ *     object in a fixed member order, parameters, the request body, the
+ *     success response, the declared errors grouped by status into
+ *     wire-error schemas (`code` enum-pinned, `details` the declared
+ *     schema), the binding's own statuses as shared
+ *     `components.responses`, `components.schemas` from `$defs`, and the
+ *     `x-jaren-policy` extension.
+ *
+ * Rendered twice, the document is byte-identical; a test validates it
+ * against the vendored OpenAPI 3.1 meta-schema with `JarenValidator`.
+ */
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type DroppedKeyword = {
+    /**
+     * - JSON Pointer of the keyword in the contract document
+     */
+    docPath: string;
+    keyword: string;
+    reason: string;
+};
+export type OpenApiOptions = {
+    /**
+     * -
+     * the `info` object; `title` defaults to the contract id, `version` to
+     * the contract version
+     */
+    info?: {
+        title?: string;
+        version?: string;
+        [k: string]: unknown;
+    };
+    /**
+     * - the `servers` array, verbatim
+     */
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    /**
+     * - drop and report a boolean `required`
+     * and an unmappable same-document `$ref` instead of refusing (`JC0060`)
+     */
+    lenient?: boolean;
+};
+export type OpenApiResult = {
+    /**
+     * - the OpenAPI 3.1 document
+     */
+    document: Record<string, unknown>;
+    /**
+     * - every keyword the keyword policy removed
+     */
+    dropped: DroppedKeyword[];
+};
+export type MapContext = {
+    lenient: boolean;
+    dropped: DroppedKeyword[];
+    /**
+     * - the `$defs` names the projection carries
+     */
+    defs: Set<string>;
+    /**
+     * - source schema node → its mapped
+     * copy; every node is mapped once (the projection's roots cover every
+     * member), so a member's mapped schema is a lookup, and a keyword is
+     * reported once
+     */
+    mapped: Map<object, any>;
+};
+/**
+ * Project a compiled contract to an OpenAPI 3.1 document.
+ * @param {Contract} contract
+ * @param {OpenApiOptions} [options]
+ * @returns {OpenApiResult}
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or a malformed option
+ * @throws {ContractCompileError} `JC0060` — a schema keyword the projection refuses (see `lenient`)
+ * @example
+ * const { document, dropped } = toOpenApi(contract, { info: { title: 'Shop', version: '5' } });
+ * document.paths['/api/catalog'].get.operationId; // 'catalog.load'
+ */
+export declare function toOpenApi(contract: Contract, options?: OpenApiOptions): OpenApiResult;

package/dist/types/project/tools.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file `contractTools`: the public, invokable operations of a contract as
+ * tool definitions for `@jarenjs/ai`'s toolbox — `{ name, description,
+ * inputSchema, execute }`, a plain object the toolbox and a WebMCP host
+ * read, so this package never imports the ai package (the generated-
+ * document rule). `execute` calls the client's `invoke` and answers the
+ * outcome JSON, so a model sees the same `{ ok, value | error, meta }`
+ * an app does; the toolbox validates the arguments against `inputSchema`
+ * before `execute` runs, and `invoke` validates them again against the
+ * same schema (the contract's own validator) before anything is sent.
+ */
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    /**
+     * - the operation's input schema, self-contained
+     */
+    inputSchema: any;
+    /**
+     * - `client.invoke(op, args)`, resolving the outcome
+     */
+    execute: (args: any) => any;
+};
+export type ToolClient = {
+    invoke: (op: string, input: any, ctx?: any) => any;
+};
+export type ContractToolsOptions = {
+    /**
+     * - the operations to expose (default:
+     * every public, non-opaque, non-subscribe operation); an opaque,
+     * subscribe or unknown id is refused
+     */
+    ops?: readonly string[];
+    /**
+     * - the tool name of an
+     * operation (default: the id with `.` → `_`); must satisfy OpenAI's
+     * `^[a-zA-Z0-9_-]{1,64}$` and be distinct per operation
+     */
+    name?: (id: string) => string;
+};
+/**
+ * Tool definitions for the public, invokable operations of a contract.
+ * @param {Contract} contract
+ * @param {ToolClient} client - a client opened on the same contract (`openHttpClient`, or any binding's)
+ * @param {ContractToolsOptions} [options]
+ * @returns {ToolDefinition[]} in document order
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, a client
+ *   without `invoke`, `ops` naming an unknown or opaque operation, a tool
+ *   name outside `^[a-zA-Z0-9_-]{1,64}$`, or two operations mapping to one name
+ * @example
+ * const toolbox = createToolbox();                    // @jarenjs/ai
+ * for (const tool of contractTools(contract, client)) toolbox.add(tool);
+ * await toolbox.execute('product_save', { id: 1, revision: 2, product: { … } }); // → an outcome
+ */
+export declare function contractTools(contract: Contract, client: ToolClient, options?: ContractToolsOptions): ToolDefinition[];

package/dist/types/project/typescript.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file `toTypeScript`: a compiled contract as one `.d.ts` — every public
+ * operation's input, output and error-details types through
+ * `@jarenjs/emit`'s type model (`compileEmitModel` + `renderTypeScript`,
+ * the suite's one declaration renderer), then a typed operation map and
+ * the client/handler declarations through a JTLT stylesheet
+ * (`typescript.jtlt.json`, compiled once at module scope).
+ *
+ * One emit model covers the whole contract: a synthetic root whose
+ * `$defs` holds the operation types first (`<PascalOp>Input`,
+ * `<PascalOp>Output`, `<PascalOp><PascalCode>Details`) and the reachable
+ * contract `$defs` after them. Emit declares `$defs` first and in
+ * document order and names each after its key, so the operation types
+ * keep the names this module gives them (a contract `$defs` entry that
+ * spells the same name is the one emit suffixes); their `#/$defs/X`
+ * references resolve against the same root, so a `Product` referenced
+ * from three operations is declared once. The root's own declaration
+ * (`unknown`) is not rendered.
+ *
+ * `Meta`, `WireError`, `Outcome<T>`, `InvokeContext`, `Client`,
+ * `Failure`, `HandlerContext` and `Handlers` are fixed text in the
+ * stylesheet — the D6 shapes as every binding carries them
+ * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
+ * are the runtime twins; a test holds the text to them).
+ */
+export type Contract = import('../compile.js').Contract;
+export type CompiledOperation = import('../compile.js').CompiledOperation;
+export type TypeScriptOptions = {
+    /**
+     * - emit the do-not-edit header
+     */
+    banner?: boolean;
+};
+/**
+ * The type model of a contract: the synthetic `$defs` root, the row per
+ * operation the stylesheet renders, and the rendered declarations.
+ * @param {Contract} contract
+ * @param {CompiledOperation[]} ops
+ * @param {string} source - what the model records as its source
+ * @returns {{ types: string, rows: Record<string, unknown>[], model: import('@jarenjs/emit/model').EmitModel }}
+ */
+export declare function contractTypeModel(contract: Contract, ops: CompiledOperation[], source: string): {
+    types: string;
+    rows: Record<string, unknown>[];
+    model: import('@jarenjs/emit/model').EmitModel;
+};
+/**
+ * Project a compiled contract to TypeScript declarations: the operation
+ * types, `Operations`, `UrlOperations`, `Meta`, `WireError`, `Outcome<T>`,
+ * `InvokeContext`, `Client`, `Failure`, `HandlerContext`, `Handlers`.
+ * @param {Contract} contract
+ * @param {TypeScriptOptions} [options]
+ * @returns {string} TypeScript source (`.d.ts`)
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or a malformed option
+ * @example
+ * writeFileSync('shop.d.ts', toTypeScript(contract));
+ * // import type { Client, Operations } from './shop.js';
+ */
+export declare function toTypeScript(contract: Contract, options?: TypeScriptOptions): string;

package/dist/types/public.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file `publicProjection`: the browser-safe subset of a compiled contract
+ * as a JSON document that is ITSELF a valid `$contract` 0.1 — what a
+ * client needs and no more, what the revision hashes, and what every other
+ * projection (OpenAPI, TypeScript, Markdown, tools) is built on.
+ *
+ * Retained: the operations whose `policy.audience` is not `server` (and,
+ * when the caller narrows with `ops`, only those), each with its resolved
+ * binding and policy minus the server-side knobs (`limits`,
+ * `errors.details`), plus the `$defs` the retained schemas reach. Member
+ * order is FIXED (docs/CONTRACT-FORMAT.md §12.1 — normative, because the
+ * revision is the SHA-256 of the canonical bytes of this document): root
+ * `$contract, id, version, compat, $defs, operations`; operation `kind,
+ * input, output, errors, policy, http, doc`; policy `task, idempotency,
+ * revision, cache, retry, stream, audience`; http `method, path, in, body, status,
+ * media`; error `status, schema`; operations in document order; `$defs` in
+ * first-reference order. Defaults are materialized (the projection says
+ * what the binding DOES, not what the author typed), so two documents
+ * that behave alike project alike, and the projection of a projection is
+ * the projection.
+ */
+export type Contract = import('./compile.js').Contract;
+export type CompiledOperation = import('./compile.js').CompiledOperation;
+export type PublicProjectionOptions = {
+    /**
+     * - the operations to keep, a subset
+     * of the contract's ids (default: all); `server` operations are never
+     * kept, listed or not
+     */
+    ops?: readonly string[];
+};
+/**
+ * @typedef {import('./compile.js').Contract} Contract
+ * @typedef {import('./compile.js').CompiledOperation} CompiledOperation
+ */
+/**
+ * @typedef {Object} PublicProjectionOptions
+ * @property {readonly string[]} [ops] - the operations to keep, a subset
+ *   of the contract's ids (default: all); `server` operations are never
+ *   kept, listed or not
+ */
+/**
+ * Whether `value` is a compiled contract — reads the members every
+ * projection needs.
+ * @param {unknown} value
+ * @returns {value is Contract}
+ */
+export declare function isCompiledContract(value: unknown): value is Contract;
+/**
+ * The operations a projection retains, in document order: the public
+ * ones, narrowed by `ops` when given. Throws `JC1008` for a malformed
+ * `contract` or an `ops` entry that names no operation.
+ * @param {Contract} contract
+ * @param {readonly string[] | undefined} ops
+ * @param {string} who - the projection's name, for the message
+ * @returns {CompiledOperation[]}
+ */
+export declare function retainedOperations(contract: Contract, ops: readonly string[] | undefined, who: string): CompiledOperation[];
+/**
+ * The public projection of a compiled contract: a `$contract` 0.1
+ * document (it compiles) holding the public operations with their
+ * resolved bindings and policies and the `$defs` they reach, in the fixed
+ * member order the revision hashes. Schema subtrees are the contract's own
+ * (frozen); the composition is fresh.
+ * @param {Contract} contract
+ * @param {PublicProjectionOptions} [options]
+ * @returns {Record<string, unknown>}
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or `ops` names no operation
+ * @example
+ * const pub = publicProjection(contract);
+ * compileContract(pub).ids; // the public operations, in document order
+ */
+export declare function publicProjection(contract: Contract, options?: PublicProjectionOptions): Record<string, unknown>;