@ayepi/node 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,611 +1,9 @@
 import http from "node:http";
 import { WebSocketServer } from "ws";
-import { z } from "zod";
+import { AnySpec, Server } from "@ayepi/core";
 
-//#region ../core/dist/types.d.ts
-
-//#region src/types.d.ts
-/**
- * # Type utilities
- *
- * Small, dependency-free type-level helpers used across the library. None of
- * these emit runtime code — they exist purely to make the public generic
- * surface infer precisely without leaking `any`/`unknown` to consumers.
- *
- * @module
- */
-/**
- * Flatten an intersection (`A & B & …`) into a single object literal so editor
- * tooltips and `Equal<>` comparisons see one clean shape instead of a chain of
- * intersections.
- *
- * @example
- * ```ts
- * type Messy = { a: 1 } & { b: 2 }
- * type Clean = Simplify<Messy> // { a: 1; b: 2 }
- * ```
- */
-type Simplify<T> = { [K in keyof T]: T[K] } & {};
-/** A value that may be returned either synchronously or as a `Promise`. */
-
-/**
- * The empty object type. Used as the identity element when merging contributed
- * shapes (middleware context, path params, etc.) so an absent contribution adds
- * nothing rather than widening the result.
- */
-type EmptyObject = {};
-/**
- * Convert a union `A | B | C` into the intersection `A & B & C`.
- *
- * Drives middleware-context merging: each middleware contributes a shape, and
- * the handler sees the intersection of every contribution in its chain.
- */
-
-/** Distribute `keyof` across a union, yielding the union of every member's keys. */
-
-/**
- * Safe indexed access: resolves to `T[K]` when `K` is a key of `T`, otherwise
- * `undefined`. Lets optional config properties be read without first proving
- * they exist.
- */
-type Get<T, K extends string> = K extends keyof T ? T[K] : undefined;
-/**
- * A JSON-shaped value — the closed set of things the OpenAPI/AsyncAPI doc
- * generators produce and accept in their patch callbacks.
- */
-type Json = string | number | boolean | null | Json[] | {
-  [k: string]: Json;
-};
-//#endregion
-//#endregion
-//#region ../core/dist/errors.d.ts
-//#region src/manifest.d.ts
-
-/**
- * # Manifest
- *
- * The **zod-free runtime configuration** the client needs. It carries exactly
- * enough structure (per-endpoint key tables, method, path, streaming flags) for
- * the client to split a single `data` payload back into path/query/body/files
- * and pick a transport — with no zod schemas, so the frontend bundle stays
- * schema-free. Obtain it from `app.manifest()` or {@link manifestFromSpec}.
- *
- * Every field here is part of the **frozen v0 wire contract**.
- *
- * @module
- */
-/** The HTTP methods ayepi endpoints may use. */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-/**
- * Runtime description of a single endpoint — everything the client must know to
- * build a request and interpret a response without access to the zod schemas.
- */
-interface ManifestEndpoint {
-  /** HTTP method (default `POST`). */
-  readonly method: HttpMethod;
-  /** Path pattern with `:key` segments, e.g. `/users/:id`. */
-  readonly path: string;
-  /** Explicit WebSocket id, or `null` to address the endpoint by `method + path`. */
-  readonly ws: string | null;
-  /** When `true`, the endpoint cannot be called over ws (raw streams / files). */
-  readonly httpOnly: boolean;
-  /** Content-type of the streamed request body (raw, or NDJSON for item streams); `null` if none. */
-  readonly streamIn: string | null;
-  /** `true` when `streamIn` is a typed NDJSON item stream (vs a raw byte stream). */
-  readonly itemsIn: boolean;
-  /** Content-type of the streamed response (raw, or NDJSON/SSE for item streams); `null` if none. */
-  readonly streamOut: string | null;
-  /** `true` when `streamOut` is a typed item stream (vs a raw byte stream). */
-  readonly items: boolean;
-  /** Path-param keys, in path order. */
-  readonly p: readonly string[];
-  /** Query-param keys. */
-  readonly q: readonly string[];
-  /** Body keys, `'raw'` when the body is the entire data payload, or `null` when there is no body. */
-  readonly b: readonly string[] | 'raw' | null;
-  /** Multipart file-field keys. */
-  readonly f: readonly string[];
-  /** Whether the endpoint declares a body at all. */
-  readonly hasBody: boolean;
-  /** Whether the endpoint declares typed request headers. */
-  readonly hasHeaders: boolean;
-  /** When `true`, `call()` resolves a `{ status, data }` discriminated union. */
-  readonly multi: boolean;
-  /** Body wire encoding, or `null` when there is no body. */
-  readonly bodyEnc: 'json' | 'urlencoded' | null;
-}
-/** Runtime description of a single server-pushed event channel. */
-interface ManifestEvent {
-  /** WebSocket channel id. */
-  readonly ws: string;
-  /** Whether the channel is parameterized (subscriptions are keyed by params). */
-  readonly hasParams: boolean;
-}
-/**
- * The complete zod-free runtime manifest consumed by {@link client} — obtained
- * from `app.manifest()` or {@link manifestFromSpec}. Hand a client this manifest
- * (instead of the spec) to talk to a server without shipping its schema code.
- */
-interface Manifest {
-  readonly endpoints: Readonly<Record<string, ManifestEndpoint>>;
-  readonly events: Readonly<Record<string, ManifestEvent>>;
-}
-//#endregion
-//#region src/path.d.ts
-/**
- * A single path segment: either a string literal or a named parameter.
- *
- * The whole path-matching machinery operates on arrays of these, which is why
- * no part of it needs regex or `String.replace` over user input.
- */
-type PathPart = {
-  readonly t: 'lit';
-  readonly v: string;
-} | {
-  readonly t: 'param';
-  readonly k: string;
-};
-/**
- * The erased (non-generic) shape of a {@link PathTemplate}. Used wherever a
- * template is accepted without caring about its specific param types.
- */
-interface AnyPathTemplate {
-  readonly kind: 'path';
-  /** Segment array — never matched or built via string replacement. */
-  readonly parts: readonly PathPart[];
-  /** Display/wire form, derived from {@link parts} (e.g. `/users/:id`). */
-  readonly pattern: string;
-  /** Declared param keys, in path order. */
-  readonly keys: readonly string[];
-  /** Per-key zod schemas; each must accept string input. */
-  readonly schemas: Readonly<Record<string, z.ZodType>>;
-}
-/**
- * A typed path template produced by the {@link path} tag. Carries its pattern
- * and per-segment schemas, and can build a URL path from typed params or parse
- * one back into typed params.
- *
- * @typeParam PS - a `{ key: ZodType }` record describing each param segment.
- */
-
-//#endregion
-//#region src/payload.d.ts
-/** Input vs output side of a schema (request parsing vs response/handler view). */
-type IOMode = 'in' | 'out';
-/** Pick `z.input` or `z.output` of a schema by {@link IOMode}. */
-type ZIO<Z extends z.ZodType, M extends IOMode> = M extends 'in' ? z.input<Z> : z.output<Z>;
-type CfgOf<E extends AnyEndpoint> = E['cfg'];
-type LPOf<E extends AnyEndpoint> = E['__lp'];
-type LPShape<E extends AnyEndpoint, M extends IOMode> = { [K in keyof LPOf<E>]: LPOf<E>[K] extends z.ZodType ? ZIO<LPOf<E>[K], M> : never };
-/** Params contributed by a `path` template on `cfg.path`. */
-type TplOf<E extends AnyEndpoint> = Get<CfgOf<E>, 'path'> extends {
-  readonly __ps: infer PS extends object;
-} ? PS : EmptyObject;
-/** Params contributed by stacked path prefixes. */
-type PfxOf<E extends AnyEndpoint> = E extends {
-  readonly __pfx: infer PFX extends object;
-} ? PFX : EmptyObject;
-type PfxShape<E extends AnyEndpoint, M extends IOMode> = { -readonly [K in keyof PfxOf<E>]: PfxOf<E>[K] extends z.ZodType ? ZIO<PfxOf<E>[K], M> : never };
-type TplShape<E extends AnyEndpoint, M extends IOMode> = { -readonly [K in keyof TplOf<E>]: TplOf<E>[K] extends z.ZodType ? ZIO<TplOf<E>[K], M> : never };
-type PShape<E extends AnyEndpoint, M extends IOMode> = Simplify<(Get<CfgOf<E>, 'params'> extends z.ZodType ? ZIO<Get<CfgOf<E>, 'params'> & z.ZodType, M> : EmptyObject) & LPShape<E, M> & TplShape<E, M> & PfxShape<E, M>>;
-type QShape<E extends AnyEndpoint, M extends IOMode> = Get<CfgOf<E>, 'query'> extends z.ZodType ? ZIO<Get<CfgOf<E>, 'query'> & z.ZodType, M> : EmptyObject;
-/** File fields map to data keys; a file schema whose input accepts `undefined` (e.g. `z.file().optional()`) becomes an optional key. */
-type FShape<E extends AnyEndpoint, M extends IOMode> = Get<CfgOf<E>, 'files'> extends infer F extends Readonly<Record<string, z.ZodType>> ? Simplify<{ -readonly [K in keyof F as undefined extends z.input<F[K]> ? never : K]: ZIO<F[K], M> } & { -readonly [K in keyof F as undefined extends z.input<F[K]> ? K : never]?: ZIO<F[K], M> }> : EmptyObject;
-type HasBody<E extends AnyEndpoint> = Get<CfgOf<E>, 'body'> extends z.ZodType ? true : false;
-type BRaw<E extends AnyEndpoint, M extends IOMode> = Get<CfgOf<E>, 'body'> extends z.ZodType ? ZIO<Get<CfgOf<E>, 'body'> & z.ZodType, M> : never;
-/** A body merges into the flat object only when it is a plain string-keyed record. */
-type BMergeable<E extends AnyEndpoint, M extends IOMode> = HasBody<E> extends true ? ([BRaw<E, M>] extends [Record<string, unknown>] ? true : false) : false;
-type BFlat<E extends AnyEndpoint, M extends IOMode> = BMergeable<E, M> extends true ? BRaw<E, M> : EmptyObject;
-type NonMergeableBody<E extends AnyEndpoint> = HasBody<E> extends true ? (BMergeable<E, 'in'> extends true ? false : true) : false;
-type ClientFlat<E extends AnyEndpoint> = Simplify<PShape<E, 'in'> & QShape<E, 'in'> & BFlat<E, 'in'> & FShape<E, 'in'>>;
-/**
- * The single `data` argument the client passes to `call()` — the merged
- * path/query/body/files object, or the raw value when the body is a non-object
- * (then it *is* the data).
- */
-type ClientData<E extends AnyEndpoint> = NonMergeableBody<E> extends true ? BRaw<E, 'in'> : ClientFlat<E>;
-/** Accepted shapes for a raw streaming request body. */
-
-/** The positional arguments to `emit(name, …)`: `(params, data)` for parameterized events, `(data)` otherwise. */
-type EmitArgs<Ev extends EventConfig> = Get<Ev, 'params'> extends z.ZodType ? [params: z.input<Get<Ev, 'params'> & z.ZodType>, data: z.input<Ev['data']>] : [data: z.input<Ev['data']>];
-/** The typed `emit` function for a spec's events, available on the server and in handlers. */
-type EmitFn<S extends AnySpec> = <K extends keyof EventsOf<S> & string>(name: K, ...args: EmitArgs<EventsOf<S>[K] & EventConfig>) => void;
-/**
- * The object a handler receives. The middleware context spreads at the root,
- * alongside a single merged `data`, the declared kinds (`stream`, `headers`,
- * `cookies`), and the framework toolkit (`req`, `signal`, `emit`, `status()`,
- * `header()`, `cookie()`, and — gated by config — `out`/`download()`/`length()`/`fail()`).
- *
- * @typeParam S - the owning spec (for the typed `emit`).
- * @typeParam E - the endpoint.
- */
-
-/** A live WebSocket connection, as seen by the server's ws handler. */
-interface WsConn {
-  readonly id: number;
-  readonly req: Request;
-  /** internal */
-  readonly send: (frame: string) => void;
-  /** internal */
-  readonly subs: Set<string>;
-  /** internal */
-  readonly streams: Map<string, {
-    push(v: unknown): void;
-    end(): void;
-    fail(err: unknown): void;
-  }>;
-  /** internal: per-call abort controllers, so an `{ id, abort: true }` frame can cancel a call */
-  readonly calls: Map<string, AbortController>;
-}
-/** Cross-origin resource sharing configuration. */
-
-/** The assembled server: a fetch handler, a ws handler, the manifest, `emit`, and doc generators. */
-interface Server<S extends AnySpec> {
-  readonly spec: S;
-  /** The entire HTTP surface — pass any `Request`, get a `Response`. */
-  fetch(req: Request): Promise<Response>;
-  /** The zod-free runtime manifest the client routes from (also derivable via {@link manifestFromSpec}). */
-  manifest(): Manifest;
-  /** Publish a typed event to all subscribers (across instances via the {@link Broker}). */
-  emit: EmitFn<S>;
-  /** Generate the OpenAPI 3.1 document. */
-  openapi(info?: {
-    title?: string;
-    version?: string;
-  }): Json;
-  /** Generate the AsyncAPI 3.0 document. */
-  asyncapi(info?: {
-    title?: string;
-    version?: string;
-  }): Json;
-  /**
-   * Call one of this server's endpoints **in-process** by name with just its data
-   * payload — runs the full middleware chain + validation, but skips HTTP
-   * serialization. The invocation's `io.transport` is `'local'`. Pass `headers` via
-   * `opts` to satisfy auth-style middleware. Streaming/file endpoints are best
-   * called over a {@link client} instead.
-   *
-   * The result is loosely typed here (a low-level escape hatch) — for the typed
-   * surface use {@link localClient}, which returns a {@link LocalClient}.
-   */
-  call<K extends keyof S['endpoints'] & string>(name: K, ...args: LocalCallArgs<S['endpoints'][K]>): Promise<unknown>;
-  /**
-   * Mount another spec + its builders into this **running** server — its endpoints,
-   * events, routes, and middleware go live immediately and the manifest/docs caches
-   * refresh. Typed like {@link server}: every endpoint needs a handler and every
-   * chain middleware a binding (a shared middleware def already bound by an earlier
-   * mount is reused, not re-bound). Collisions (endpoint name / route / ws / event)
-   * throw. Returns a {@link MountHandle} for {@link Server.uninstall}.
-   */
-  install<S2 extends AnySpec, const H2 extends readonly {
-    readonly __hk?: keyof S2['endpoints'] & string;
-  }[]>(spec: S2, builders: H2, ...rest: [MissingHandlers<S2, H2>] extends [never] ? [] : [error: {
-    readonly missingHandlers: MissingHandlers<S2, H2>;
-  }]): MountHandle;
-  /** Remove a previously {@link Server.install | installed} mount — deletes exactly its endpoints, events, routes, and bindings, and clears its subscriptions. */
-  uninstall(handle: MountHandle): void;
-  /** WebSocket lifecycle hooks for an adapter to drive. */
-  readonly ws: {
-    /** Register a new connection given its `send` and the upgrade `Request`. */
-    open(send: (frame: string) => void, req: Request): WsConn;
-    /** Handle one inbound text frame. */
-    message(conn: WsConn, raw: string): Promise<void>;
-    /** Tear down a connection (cleans up its subscriptions). */
-    close(conn: WsConn): void;
-  };
-}
-/** Per-call options for an in-process {@link Server.call} / {@link LocalClient}. */
-interface LocalCallOptions {
-  /** Request headers visible to the chain (e.g. an `authorization` token for auth middleware). */
-  readonly headers?: Readonly<Record<string, string>>;
-  /** Abort signal for the call. */
-  readonly signal?: AbortSignal;
-}
-/** The arguments an in-process call takes: `[opts?]` when the endpoint has no input, else `[data, opts?]`. */
-type LocalCallArgs<E extends AnyEndpoint> = [keyof ClientData<E>] extends [never] ? [opts?: LocalCallOptions] : [data: ClientData<E>, opts?: LocalCallOptions];
-/**
- * A typed in-process caller for a spec's endpoints — the no-serialization loopback
- * over {@link Server.call}, retyped against `S`. Use it to invoke another spec's
- * endpoints (e.g. a dependency's) from server-side code with just a data payload.
- */
-
-/** The endpoint-name union a builder has handled — read off its `__hk` phantom (never expands the methods). */
-type BuilderKeys<B> = B extends {
-  readonly __hk?: infer K;
-} ? K : never;
-/** Endpoint names with no handler across the supplied builders — surfaced as a compile error. */
-type MissingHandlers<S extends AnySpec, H extends readonly unknown[]> = Exclude<keyof S['endpoints'] & string, BuilderKeys<H[number]>>;
-/** Loosest internal function type — replaces the banned `Function` in plumbing signatures. */
-
-/** internal: a normalized event with its guard chain bound — held in the live `events` registry. */
-interface LiveEvent {
-  readonly name: string;
-  readonly cfg: EventConfig;
-  readonly ws: string;
-  readonly chain: AnyMiddleware[];
-}
-/**
- * An opaque handle to a mounted spec, returned by {@link Server.install} and passed
- * back to {@link Server.uninstall} to remove exactly what that install added.
- */
-interface MountHandle {
-  /** @internal the normalized endpoints this mount added. */
-  readonly eps: readonly NormalizedEp[];
-  /** @internal the live events this mount added. */
-  readonly events: readonly LiveEvent[];
-  /** @internal the middleware defs this mount bound (removed from the global impl map on uninstall). */
-  readonly impls: readonly AnyMiddleware[];
-  /** @internal this mount's spec-level doc patch, if any. */
-  readonly doc: SpecDoc | undefined;
-}
-/**
- * Assemble a {@link Server} from a spec and one or more {@link implement} builders.
- *
- * Every endpoint must have exactly one handler: a missing handler is a **compile
- * error** that names the offending endpoints (via the final `error` argument), and
- * a duplicate/unknown handler throws at startup. Every middleware in an endpoint or
- * event-guard chain must be bound via `.middleware(def, impl)` — an unbound def
- * throws at assembly.
- *
- * @param spec     - the validated spec from {@link spec}.
- * @param builders - one or more builders from {@link implement}.
- * @param rest     - `[options?]` when all handlers are present, else `[{ missingHandlers }]`.
- *
- * @example
- * ```ts
- * const app = server(api, [implement(api).middleware(auth, authImpl).handlers({ … })], { cors, broker })
- * const res = await app.fetch(new Request('http://x/getUser/u1', { method: 'POST' }))
- * ```
- */
-
-declare const MW_PROVIDES: unique symbol;
-/**
- * Opaque token returned by `next()`; carries (type-only) the context a
- * middleware provides so the next link and the handler can see it.
- *
- * @typeParam P - the context shape this step contributes.
- */
-interface MiddlewareResult<P extends object> {
-  readonly [MW_PROVIDES]?: P;
-}
-/**
- * The argument passed to a middleware function.
- *
- * @typeParam Req - the accumulated context from earlier middleware in the chain.
- */
-
-/**
- * Erased middleware shape used by the runtime and by variance-friendly
- * constraints. Carries phantom fields (`__p`/`__req`/`__lp`/`__opt`/`__isLoader`/
- * `__lz`) that are type-only.
- *
- * A middleware value is a **def** (contract only): its {@link AnyMiddleware.run}
- * is an unbound placeholder that throws if executed. The runtime fn is supplied
- * separately via `implement(api).middleware(def, impl)` and bound at `server()`.
- *
- * @internal
- */
-interface AnyMiddleware {
-  readonly kind: 'middleware';
-  readonly name: string;
-  readonly requires: readonly AnyMiddleware[];
-  readonly optional: readonly AnyMiddleware[];
-  readonly paramKey: string | undefined;
-  readonly paramSchema: z.ZodType | undefined;
-  readonly doc: MiddlewareDoc | undefined;
-  /** internal: loosest possible run signature; on a def it is an unbound placeholder that throws. */
-  readonly run: (io: {
-    req: Request;
-    ctx: never;
-    next: (add?: object) => Promise<MiddlewareResult<object>>;
-    value?: never;
-  }) => Promise<MiddlewareResult<object> | Response>;
-  readonly __p: object;
-  readonly __req: readonly AnyMiddleware[];
-  readonly __lp: object;
-  /** internal phantom: the `optional` list, so an impl's `io.ctx` can include `Partial<provides-of-optional>`. */
-  readonly __opt: readonly AnyMiddleware[];
-  /** internal phantom: `true` only for `middleware.loader` defs — selects the loader-shaped impl. */
-  readonly __isLoader: boolean;
-  /** internal phantom: a loader def's own param schema (the `value` an impl receives); `ZodNever` for non-loaders. */
-  readonly __lz: z.ZodType;
-}
-/** Everything a middleware provides, including (recursively) what its `requires` provide. */
-
-/**
- * Middleware-level OpenAPI contributions, applied to every operation whose chain
- * includes the middleware.
- */
-interface MiddlewareDoc {
-  /** Named security schemes — merged into `components.securitySchemes` and required on each op. */
-  readonly security?: Readonly<Record<string, Json>>;
-  /** Patch applied to every operation whose chain includes this middleware. */
-  readonly openapi?: (op: Record<string, Json>) => Record<string, Json>;
-}
-/**
- * Expand `requires` (auto-include) and topologically order a middleware list.
- *
- * `requires` edges pull dependencies in and force them earlier; `optional` edges
- * only reorder middleware that are *already present*. Throws on a dependency
- * cycle.
- *
- * @internal
- */
-//#endregion
-//#region src/endpoint.d.ts
-/** Endpoint-level OpenAPI metadata, plus an escape hatch over the generated operation. */
-interface EndpointDoc {
-  readonly summary?: string;
-  readonly description?: string;
-  readonly tags?: readonly string[];
-  readonly deprecated?: boolean;
-  readonly operationId?: string;
-  /** Final say over this endpoint's generated operation object. */
-  readonly openapi?: (op: Record<string, Json>) => Record<string, Json>;
-}
-/** Event-level AsyncAPI metadata, plus an escape hatch over the generated channel. */
-interface EventDoc {
-  readonly summary?: string;
-  readonly description?: string;
-  /** Final say over this event's generated channel object. */
-  readonly asyncapi?: (channel: Record<string, Json>) => Record<string, Json>;
-}
-/** Spec-level final patches over the whole generated documents. */
-interface SpecDoc {
-  readonly openapi?: (doc: Record<string, Json>) => Record<string, Json>;
-  readonly asyncapi?: (doc: Record<string, Json>) => Record<string, Json>;
-}
-/** Options for a `Set-Cookie` written via the handler's `cookie()`. */
-
-/**
- * The declarative configuration for one endpoint.
- *
- * Schemas are the single source of truth: each kind below contributes typed keys
- * to the endpoint's single `data` payload (path params, query, body, files), and
- * the kinds must be disjoint. Streaming, multi-status, typed errors, custom
- * method/path, and documentation are all declared here.
- */
-interface EndpointConfig {
-  /** Path params as a `z.object`; keys must be positioned in the path. */
-  readonly params?: z.ZodType;
-  /** Query params as a `z.object`. */
-  readonly query?: z.ZodType;
-  /** Request body — a `z.object` (merges into `data`) or any other schema (then it *is* `data`). */
-  readonly body?: z.ZodType;
-  /** Multipart file fields, keyed by form-field name. Declaring files forces `httpOnly`. */
-  readonly files?: Readonly<Record<string, z.ZodType>>;
-  /** Typed request headers (`z.object`, lowercase keys) — handler gets `headers`; never merged into `data`. */
-  readonly headers?: z.ZodType;
-  /** Typed request cookies (`z.object`) — handler gets `cookies`; server-side input only. */
-  readonly cookies?: z.ZodType;
-  /** Single success response schema. */
-  readonly response?: z.ZodType;
-  /** Multi-status success responses by code — handler returns `{ status, data }`, client gets a `{ status, data }` union. */
-  readonly responses?: Readonly<Record<number, z.ZodType>>;
-  /** Declared error responses by status — documents them and types the handler's `fail()`. */
-  readonly errors?: Readonly<Record<number, z.ZodType>>;
-  /** Body wire encoding (default `'json'`); `'urlencoded'` for `application/x-www-form-urlencoded` HTML forms. */
-  readonly bodyEncoding?: 'json' | 'urlencoded';
-  /** Typed item-stream output encoding (default `'ndjson'`); `'sse'` for `text/event-stream`. */
-  readonly streamEncoding?: 'ndjson' | 'sse';
-  readonly doc?: EndpointDoc;
-  /** HTTP method (default `POST`). */
-  readonly method?: HttpMethod;
-  /** Custom path: a `:key` string, or a {@link path} template whose schemas join the params kind. */
-  readonly path?: string | AnyPathTemplate;
-  /** Explicit WebSocket id (default: the un-injected url pattern + method). */
-  readonly ws?: string;
-  /** Force the endpoint to be HTTP-only (no ws). */
-  readonly httpOnly?: boolean;
-  /**
-   * Streaming request body. `string` → raw byte stream with that content-type
-   * (`stream: ReadableStream<Uint8Array>`); zod schema → typed NDJSON item stream
-   * (client passes an async iterable as `stream`, handler for-awaits validated items).
-   */
-  readonly streamIn?: string | z.ZodType;
-  /**
-   * Streaming response. `string` → raw byte stream with that content-type
-   * (handler returns/pipes bytes); zod schema → typed item stream over
-   * NDJSON/SSE (handler is an async generator, client `for await`s typed items).
-   */
-  readonly streamOut?: string | z.ZodType;
-  /** Raw `streamOut` only: serve with `Content-Disposition: attachment; filename="…"`. */
-  readonly download?: string;
-}
-/** Erased (non-generic) endpoint shape used by the runtime. @internal */
-interface AnyEndpoint {
-  readonly kind: 'endpoint';
-  readonly cfg: EndpointConfig;
-  readonly mws: readonly AnyMiddleware[];
-  readonly prefixes: ReadonlyArray<string | AnyPathTemplate>;
-  readonly __ctx: object;
-  readonly __lp: object;
-}
-/**
- * A fully-typed endpoint declaration.
- *
- * @typeParam C   - the literal {@link EndpointConfig}.
- * @typeParam Ctx - middleware-provided context visible to the handler.
- * @typeParam LP  - loader-param schemas in scope.
- * @typeParam PFX - prefix-param schemas in scope.
- */
-
-/** Configuration for a server-pushed event channel. */
-interface EventConfig {
-  /** Channel params as a `z.object` — subscriptions are keyed by these. */
-  readonly params?: z.ZodType;
-  /** Event payload schema. */
-  readonly data: z.ZodType;
-  /** Middleware chain that must pass before a client may subscribe. */
-  readonly guard?: readonly AnyMiddleware[];
-  /** Explicit WebSocket channel id (default: the event name). */
-  readonly ws?: string;
-  readonly doc?: EventDoc;
-}
-/** The shape passed to {@link spec}. */
-interface SpecShape {
-  readonly endpoints: Readonly<Record<string, AnyEndpoint>>;
-  readonly events?: Readonly<Record<string, EventConfig>>;
-  readonly doc?: SpecDoc;
-}
-/** Any normalized spec. */
-type AnySpec = SpecShape;
-/** Extract the events record of a spec (or `{}` when it has none). */
-type EventsOf<S extends AnySpec> = S['events'] extends Readonly<Record<string, EventConfig>> ? S['events'] : EmptyObject;
-/**
- * Finalize a set of endpoints + events into a spec, validating every endpoint at
- * definition time.
- *
- * Beyond the compile-time {@link CheckCfg} guarantees, this performs runtime
- * sanity checks (flag exclusivity, kind shapes) and full
- * {@link normalizeEndpoint | path/coverage/disjointness} validation — throwing
- * immediately on any violation so misconfiguration fails at module init.
- *
- * @returns the same spec object, now type-branded and validated.
- */
-
-/** Read the keys of a `z.object` schema, or `null` for any other (or absent) schema. @internal */
-
-/** The fully-resolved runtime description of one endpoint. @internal */
-interface NormalizedEp {
-  readonly name: string;
-  readonly def: AnyEndpoint;
-  readonly method: HttpMethod;
-  readonly parts: readonly PathPart[];
-  readonly path: string;
-  /** Explicit ws id only — the default ws identity is method + path pattern. */
-  readonly ws: string | null;
-  readonly wsEligible: boolean;
-  readonly httpOnly: boolean;
-  readonly streamInCt: string | null;
-  readonly itemsIn: boolean;
-  readonly streamOutCt: string | null;
-  readonly items: boolean;
-  readonly sse: boolean;
-  readonly multi: boolean;
-  readonly bodyEnc: 'json' | 'urlencoded' | null;
-  readonly p: readonly string[];
-  readonly q: readonly string[];
-  readonly b: readonly string[] | null;
-  readonly bRaw: boolean;
-  readonly f: readonly string[];
-  readonly loaders: ReadonlyMap<string, z.ZodType>;
-  /** Per-key schemas from own + prefix templates. */
-  readonly tplSchemas: ReadonlyMap<string, z.ZodType>;
-  readonly chain: readonly AnyMiddleware[];
-}
-/**
- * Resolve an endpoint declaration into a {@link NormalizedEp}: assemble its path
- * parts (prefixes → own path → default), verify exact-once param declaration and
- * positioning, and enforce kind disjointness. Throws on any violation.
- *
- * @internal
- */
-//#endregion
-//#region src/caller.d.ts
-/** Deterministic JSON (sorted keys) — the default cache key for a call's `data`. */
-//#endregion
 //#region src/index.d.ts
+
 /** A minimal structural view of the ayepi server surface this adapter drives. */
 type AnyApp = Server<AnySpec>;
 /** Options for {@link serve}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Node.js (node:http + ws) adapter for @ayepi/core — bridges IncomingMessage ⇄ fetch Request/Response and serves WebSocket upgrades",
   "license": "MIT",
   "publishConfig": {
@@ -18,7 +18,8 @@
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "ayepi-*.md"
   ],
   "exports": {
     ".": {
@@ -37,7 +38,7 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@ayepi/core": "^0.1.0"
+    "@ayepi/core": "^0.2.0"
   },
   "dependencies": {
     "ws": "^8.18.0"
@@ -50,7 +51,7 @@
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
     "zod": "^4.4.3",
-    "@ayepi/core": "0.1.0"
+    "@ayepi/core": "0.2.0"
   },
   "keywords": [
     "ayepi",