@nats-kit/rpc 0.3.0

package/dist/esm/eslint/index.js

@@ -0,0 +1,30 @@
+/**
+ * ESLint flat-config snippet (design §2.8): a lint-level nudge, not a
+ * guarantee — `no-restricted-properties` is purely syntactic. Spread into a
+ * consumer's flat config:
+ *
+ * ```js
+ * import { rpcBoundaryRules } from "@nats-kit/rpc/eslint";
+ * export default [{ files: ["src/**\/*.ts"], rules: { ...rpcBoundaryRules } }];
+ * ```
+ */
+export const rpcBoundaryRules = {
+    "no-restricted-properties": [
+        "error",
+        {
+            property: "respondError",
+            message: "Return fail(...) or throw RpcError from an RPC handler; the rpc layer owns ADR-32 error headers.",
+        },
+        {
+            object: "nc",
+            property: "request",
+            message: "Use a typed createRpcClient() method instead of raw nc.request().",
+        },
+        {
+            object: "msg",
+            property: "respond",
+            message: "Raw msg.respond() bypasses the RPC envelope. Use an RPC handler.",
+        },
+    ],
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/eslint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/eslint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,0BAA0B,EAAE;QAC1B,OAAO;QACP;YACE,QAAQ,EAAE,cAAc;YACxB,OAAO,EACL,kGAAkG;SACrG;QACD;YACE,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,mEAAmE;SAC7E;QACD;YACE,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,kEAAkE;SAC5E;KACF;CACF,CAAC"}

package/dist/esm/events.d.ts

@@ -0,0 +1,55 @@
+import { type MsgHdrs, type NatsConnectionLike, type NatsConnectionRunner, type PubAck } from "@nats-kit/core";
+import { z } from "zod";
+/** A CloudEvents-shaped event definition (§2.5, §4.8). */
+export interface EventContract<T extends z.ZodType> {
+    /** `<app>.<entity>.<event>` — also the CloudEvents `type` and the subject. */
+    type: string;
+    /** CloudEvents `source`, e.g. "urn:anki:sandbox". */
+    source: string;
+    data: T;
+}
+export declare function defineEvent<T extends z.ZodType>(def: EventContract<T>): EventContract<T>;
+/**
+ * `publishEvent` needs a JetStream client to get a `PubAck` (design §2.5);
+ * `NatsConnectionLike` alone is Core-NATS-only, so we widen it with just the
+ * one extra accessor both `NatsConnectionRunner` and the NestJS `NatsService`
+ * (which delegates to it) already expose.
+ */
+export interface PublishEventOptions {
+    nats: NatsConnectionLike & Pick<NatsConnectionRunner, "getJetStream">;
+    /** CloudEvents `id` and `Nats-Msg-Id`. Defaults to a nuid. */
+    id?: string;
+    /** RFC3339. Defaults to `new Date().toISOString()`. */
+    time?: string;
+    /** CloudEvents optional `subject` attribute (a resource id, NOT the NATS subject). */
+    subject?: string;
+    traceparent?: string;
+    /** Override the publish subject. Defaults to `event.type`. */
+    natsSubject?: string;
+}
+interface CloudEventEnvelope<T> {
+    specversion: "1.0";
+    id: string;
+    source: string;
+    type: string;
+    time: string;
+    subject?: string;
+    datacontenttype: "application/json";
+    data: T;
+}
+export type CloudEvent<T> = CloudEventEnvelope<T>;
+/**
+ * Publish a CloudEvents 1.0 structured-mode envelope (§4.8) via JetStream,
+ * with `Nats-Msg-Id` set to the CloudEvents `id` for stream-level dedup.
+ */
+export declare function publishEvent<T extends z.ZodType>(event: EventContract<T>, data: z.input<T>, options: PublishEventOptions): Promise<PubAck>;
+/**
+ * Parse a received JetStream/Core message as a CloudEvents envelope,
+ * validating the full envelope (not just `data`) per §4.8.
+ */
+export declare function parseEvent<T extends z.ZodType>(event: EventContract<T>, msg: {
+    data: Uint8Array;
+    headers?: MsgHdrs;
+}): CloudEvent<z.output<T>>;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/esm/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,0DAA0D;AAC1D,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO;IAChD,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;CACT;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAExF;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC,oBAAoB,EAAE,cAAc,CAAC,CAAC;IACtE,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,kBAAkB,CAAC,CAAC;IAC5B,WAAW,EAAE,KAAK,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,kBAAkB,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC;CACT;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAuClD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EACpD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC5C,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAKzB"}

package/dist/esm/events.js

@@ -0,0 +1,77 @@
+import { nuid } from "@nats-io/nuid";
+import { headers as buildMsgHdrs, } from "@nats-kit/core";
+import { z } from "zod";
+export function defineEvent(def) {
+    return def;
+}
+/** Validates the envelope shape (§4.8) around an arbitrary `data` payload. */
+const CloudEventEnvelopeSchema = z.object({
+    specversion: z.literal("1.0"),
+    id: z.string().min(1),
+    source: z.string().min(1),
+    type: z.string().min(1),
+    time: z.string().min(1),
+    subject: z.string().optional(),
+    datacontenttype: z.literal("application/json"),
+    data: z.unknown(),
+});
+/**
+ * JSON has no representation for `NaN`/`Infinity` — `JSON.stringify` silently
+ * turns them into `null`, which would silently corrupt an event's data on
+ * the wire. Walk the value and reject before that can happen.
+ */
+function assertJsonSafe(value, path = "$") {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`publishEvent: non-finite number (${String(value)}) at ${path} is not valid JSON`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => assertJsonSafe(v, `${path}[${i}]`));
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            assertJsonSafe(v, `${path}.${k}`);
+        }
+    }
+}
+/**
+ * Publish a CloudEvents 1.0 structured-mode envelope (§4.8) via JetStream,
+ * with `Nats-Msg-Id` set to the CloudEvents `id` for stream-level dedup.
+ */
+export async function publishEvent(event, data, options) {
+    const parsed = event.data.parse(data);
+    assertJsonSafe(parsed);
+    const id = options.id ?? nuid.next();
+    const envelope = {
+        specversion: "1.0",
+        id,
+        source: event.source,
+        type: event.type,
+        time: options.time ?? new Date().toISOString(),
+        subject: options.subject,
+        datacontenttype: "application/json",
+        data: parsed,
+    };
+    const h = buildMsgHdrs();
+    if (options.traceparent !== undefined) {
+        h.set("traceparent", options.traceparent);
+    }
+    const body = new TextEncoder().encode(JSON.stringify(envelope));
+    await options.nats.waitForReady();
+    const js = options.nats.getJetStream();
+    return js.publish(options.natsSubject ?? event.type, body, { msgID: id, headers: h });
+}
+/**
+ * Parse a received JetStream/Core message as a CloudEvents envelope,
+ * validating the full envelope (not just `data`) per §4.8.
+ */
+export function parseEvent(event, msg) {
+    const raw = JSON.parse(new TextDecoder().decode(msg.data));
+    const envelope = CloudEventEnvelopeSchema.parse(raw);
+    const data = event.data.parse(envelope.data);
+    return { ...envelope, data };
+}
+//# sourceMappingURL=events.js.map

package/dist/esm/events.js.map

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

package/dist/esm/headers.d.ts

@@ -0,0 +1,53 @@
+import { type MsgHdrs } from "@nats-kit/core";
+import { type RpcCaller } from "./types.js";
+/** Header names (D5, §4.2). Never mint a bare `Nats-*` header — that prefix is server/ADR-32 territory. */
+export declare const HEADER_REQUEST_ID = "Nk-Request-Id";
+export declare const HEADER_CALLER_KIND = "Nk-Caller-Kind";
+export declare const HEADER_CALLER_ID = "Nk-Caller-Id";
+export declare const HEADER_CALLER_ROLE = "Nk-Caller-Role";
+export declare const HEADER_DEADLINE = "Nk-Deadline";
+export declare const HEADER_CONTENT_TYPE = "Content-Type";
+export declare const HEADER_TRACEPARENT = "traceparent";
+export declare const HEADER_TRACESTATE = "tracestate";
+export declare const CONTENT_TYPE_JSON = "application/json";
+export interface BuildRequestHeadersInit {
+    requestId: string;
+    caller: RpcCaller;
+    deadlineMs?: number;
+    traceparent?: string;
+    tracestate?: string;
+    /** Extra `Nk-*` headers. `Nats-*` and reserved names are rejected by the caller (client.ts). */
+    extra?: Record<string, string>;
+}
+/** Build the request `MsgHdrs` per §4.2. */
+export declare function buildRequestHeaders(init: BuildRequestHeadersInit): MsgHdrs;
+/**
+ * Parse `Nk-Caller-Role` per §4.2: comma-separated, no spaces, absent/empty
+ * means an empty set. Guards the classic `"".split(",")` trap, which yields
+ * `[""]` rather than `[]`.
+ */
+export declare function parseRoles(headerValue: string | undefined | null): readonly string[];
+export declare function isValidRole(role: string): boolean;
+export declare function isValidRequestId(id: string): boolean;
+export interface ParsedRequestHeaders {
+    requestId: string;
+    callerKind: "user" | "service";
+    callerId?: string;
+    roles: readonly string[];
+    deadlineMs?: number;
+    traceparent?: string;
+}
+export type ParseHeadersResult = {
+    ok: true;
+    value: ParsedRequestHeaders;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Parse and validate the required/conditional request headers per §4.2.
+ * Used by `createRpcServer` as dispatch step 1 (missing/malformed -> 400;
+ * `user` with no `Nk-Caller-Id` -> handled by the caller as 401).
+ */
+export declare function parseRequestHeaders(h: MsgHdrs | undefined): ParseHeadersResult;
+//# sourceMappingURL=headers.d.ts.map

package/dist/esm/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAC/C,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAKpD,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CA0B1E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,MAAM,EAAE,CAGpF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,kBAAkB,CAmD9E"}

package/dist/esm/headers.js

@@ -0,0 +1,108 @@
+import { headers as buildMsgHdrs } from "@nats-kit/core";
+import { Match } from "@nats-io/nats-core";
+/** Header names (D5, §4.2). Never mint a bare `Nats-*` header — that prefix is server/ADR-32 territory. */
+export const HEADER_REQUEST_ID = "Nk-Request-Id";
+export const HEADER_CALLER_KIND = "Nk-Caller-Kind";
+export const HEADER_CALLER_ID = "Nk-Caller-Id";
+export const HEADER_CALLER_ROLE = "Nk-Caller-Role";
+export const HEADER_DEADLINE = "Nk-Deadline";
+export const HEADER_CONTENT_TYPE = "Content-Type";
+export const HEADER_TRACEPARENT = "traceparent";
+export const HEADER_TRACESTATE = "tracestate";
+export const CONTENT_TYPE_JSON = "application/json";
+const ROLE_RE = /^[A-Za-z0-9_:-]{1,64}$/;
+const REQUEST_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** Build the request `MsgHdrs` per §4.2. */
+export function buildRequestHeaders(init) {
+    const h = buildMsgHdrs();
+    h.set(HEADER_CONTENT_TYPE, CONTENT_TYPE_JSON);
+    h.set(HEADER_REQUEST_ID, init.requestId);
+    h.set(HEADER_CALLER_KIND, init.caller.kind);
+    if (init.caller.id !== undefined) {
+        h.set(HEADER_CALLER_ID, init.caller.id);
+    }
+    if (init.caller.roles && init.caller.roles.length > 0) {
+        h.set(HEADER_CALLER_ROLE, init.caller.roles.join(","));
+    }
+    if (init.deadlineMs !== undefined) {
+        h.set(HEADER_DEADLINE, String(Math.trunc(init.deadlineMs)));
+    }
+    if (init.traceparent !== undefined) {
+        h.set(HEADER_TRACEPARENT, init.traceparent);
+    }
+    if (init.tracestate !== undefined) {
+        h.set(HEADER_TRACESTATE, init.tracestate);
+    }
+    if (init.extra) {
+        for (const [k, v] of Object.entries(init.extra)) {
+            h.set(k, v);
+        }
+    }
+    return h;
+}
+/**
+ * Parse `Nk-Caller-Role` per §4.2: comma-separated, no spaces, absent/empty
+ * means an empty set. Guards the classic `"".split(",")` trap, which yields
+ * `[""]` rather than `[]`.
+ */
+export function parseRoles(headerValue) {
+    if (!headerValue)
+        return [];
+    return headerValue.split(",").filter((r) => r.length > 0);
+}
+export function isValidRole(role) {
+    return ROLE_RE.test(role);
+}
+export function isValidRequestId(id) {
+    return REQUEST_ID_RE.test(id);
+}
+/**
+ * Parse and validate the required/conditional request headers per §4.2.
+ * Used by `createRpcServer` as dispatch step 1 (missing/malformed -> 400;
+ * `user` with no `Nk-Caller-Id` -> handled by the caller as 401).
+ */
+export function parseRequestHeaders(h) {
+    if (!h) {
+        return { ok: false, message: "missing required headers" };
+    }
+    const contentType = h.get(HEADER_CONTENT_TYPE, Match.IgnoreCase);
+    if (contentType && contentType !== CONTENT_TYPE_JSON) {
+        return { ok: false, message: `unsupported ${HEADER_CONTENT_TYPE}: "${contentType}"` };
+    }
+    const requestId = h.get(HEADER_REQUEST_ID, Match.IgnoreCase);
+    if (!requestId || !isValidRequestId(requestId)) {
+        return { ok: false, message: `missing or malformed ${HEADER_REQUEST_ID}` };
+    }
+    const callerKind = h.get(HEADER_CALLER_KIND, Match.IgnoreCase);
+    if (callerKind !== "user" && callerKind !== "service") {
+        return { ok: false, message: `missing or invalid ${HEADER_CALLER_KIND}` };
+    }
+    const rawCallerId = h.get(HEADER_CALLER_ID, Match.IgnoreCase) || undefined;
+    if (rawCallerId !== undefined && (rawCallerId.length < 1 || rawCallerId.length > 256)) {
+        return { ok: false, message: `${HEADER_CALLER_ID} must be 1-256 chars` };
+    }
+    const callerId = rawCallerId;
+    const rawRoles = h.get(HEADER_CALLER_ROLE, Match.IgnoreCase);
+    const roles = parseRoles(rawRoles);
+    if (rawRoles) {
+        for (const role of roles) {
+            if (!isValidRole(role)) {
+                return { ok: false, message: `malformed role in ${HEADER_CALLER_ROLE}: "${role}"` };
+            }
+        }
+    }
+    const rawDeadline = h.get(HEADER_DEADLINE, Match.IgnoreCase);
+    let deadlineMs;
+    if (rawDeadline) {
+        if (!/^\d+$/.test(rawDeadline)) {
+            return { ok: false, message: `malformed ${HEADER_DEADLINE}` };
+        }
+        deadlineMs = Number(rawDeadline);
+    }
+    const traceparent = h.get(HEADER_TRACEPARENT, Match.IgnoreCase) || undefined;
+    return {
+        ok: true,
+        value: { requestId, callerKind, callerId, roles, deadlineMs, traceparent },
+    };
+}
+//# sourceMappingURL=headers.js.map

package/dist/esm/headers.js.map

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

package/dist/esm/index.d.ts

@@ -0,0 +1,15 @@
+export { defineService, method, methodSubject, serviceName, groupSubject, SUBJECT_SEGMENT_RE, } from "./contract.js";
+export type { RpcMethodDef, ServiceContract } from "./contract.js";
+export { createRpcClient } from "./client.js";
+export type { RpcCaller, RpcCallOptions, RpcClient, RpcClientOptions, } from "./types.js";
+export { createRpcServer, ok, fail, newRequestId } from "./server.js";
+export type { RpcContext, RpcResult, RpcHandlers, RpcAuthorize, RpcServerOptions, RpcServerHandle, } from "./types.js";
+export { RpcError, isRpcError, isDomainError, isTransportError, TRANSPORT_ERROR_CODES, SERVICE_ERROR_CODES, } from "./errors.js";
+export type { RpcErrorKind, RpcErrorInit } from "./errors.js";
+export { HEADER_REQUEST_ID, HEADER_CALLER_KIND, HEADER_CALLER_ID, HEADER_CALLER_ROLE, HEADER_DEADLINE, HEADER_CONTENT_TYPE, HEADER_TRACEPARENT, HEADER_TRACESTATE, CONTENT_TYPE_JSON, parseRoles, parseRequestHeaders, } from "./headers.js";
+export { defineEvent, publishEvent, parseEvent } from "./events.js";
+export type { EventContract, PublishEventOptions, CloudEvent } from "./events.js";
+export { defineKvValue } from "./kv.js";
+export type { KvValueContract } from "./kv.js";
+export { ServiceError } from "@nats-io/services";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,aAAa,EACb,MAAM,EACN,aAAa,EACb,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EACV,SAAS,EACT,cAAc,EACd,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI9D,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,25 @@
+// Public surface of @nats-kit/rpc — typed request/reply RPC over NATS,
+// built on @nats-io/services (ADR-32) with a reconnect supervisor.
+//
+// See docs/spec/nats-kit-wire-spec.md for the language-neutral wire spec this
+// package implements (mirrors design doc §4).
+// Contract
+export { defineService, method, methodSubject, serviceName, groupSubject, SUBJECT_SEGMENT_RE, } from "./contract.js";
+// Client
+export { createRpcClient } from "./client.js";
+// Server
+export { createRpcServer, ok, fail, newRequestId } from "./server.js";
+// Errors
+export { RpcError, isRpcError, isDomainError, isTransportError, TRANSPORT_ERROR_CODES, SERVICE_ERROR_CODES, } from "./errors.js";
+// Headers (exposed for consumers building their own low-level tooling, e.g.
+// the interop test harness or a Go-side test client written in TS).
+export { HEADER_REQUEST_ID, HEADER_CALLER_KIND, HEADER_CALLER_ID, HEADER_CALLER_ROLE, HEADER_DEADLINE, HEADER_CONTENT_TYPE, HEADER_TRACEPARENT, HEADER_TRACESTATE, CONTENT_TYPE_JSON, parseRoles, parseRequestHeaders, } from "./headers.js";
+// Events
+export { defineEvent, publishEvent, parseEvent } from "./events.js";
+// KV
+export { defineKvValue } from "./kv.js";
+// Re-export the ADR-32 error class from `@nats-io/services` so consumers can
+// `instanceof`-check it without a direct dependency (mirrors the core
+// barrel's `@nats-io/*` re-export rule).
+export { ServiceError } from "@nats-io/services";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,8CAA8C;AAE9C,WAAW;AACX,OAAO,EACL,aAAa,EACb,MAAM,EACN,aAAa,EACb,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQ9C,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAUtE,SAAS;AACT,OAAO,EACL,QAAQ,EACR,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,4EAA4E;AAC5E,oEAAoE;AACpE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,SAAS;AACT,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGpE,KAAK;AACL,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,6EAA6E;AAC7E,sEAAsE;AACtE,yCAAyC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/kv.d.ts

@@ -0,0 +1,13 @@
+import { type z } from "zod";
+/** A typed KV value contract (§2.5, §4.9). No envelope; a breaking shape change means a new bucket. */
+export interface KvValueContract<T extends z.ZodType> {
+    bucket: string;
+    value: T;
+    /** Builds a validated, dot-joined key from parts; each part must be `[a-zA-Z0-9_-]+`. */
+    key(...parts: string[]): string;
+}
+export declare function defineKvValue<T extends z.ZodType>(def: {
+    bucket: string;
+    value: T;
+}): KvValueContract<T>;
+//# sourceMappingURL=kv.d.ts.map

package/dist/esm/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,uGAAuG;AACvG,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;IACT,yFAAyF;IACzF,GAAG,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;CACV,GAAG,eAAe,CAAC,CAAC,CAAC,CAiBrB"}

package/dist/esm/kv.js

@@ -0,0 +1,20 @@
+const KV_KEY_PART_RE = /^[a-zA-Z0-9_-]+$/;
+export function defineKvValue(def) {
+    return {
+        bucket: def.bucket,
+        value: def.value,
+        key(...parts) {
+            for (const part of parts) {
+                if (!KV_KEY_PART_RE.test(part)) {
+                    throw new Error(`defineKvValue(${def.bucket}): invalid key part "${part}"`);
+                }
+            }
+            const key = parts.join(".");
+            if (key.length === 0 || key.length > 255) {
+                throw new Error(`defineKvValue(${def.bucket}): key length out of bounds`);
+            }
+            return key;
+        },
+    };
+}
+//# sourceMappingURL=kv.js.map

package/dist/esm/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/kv.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAU1C,MAAM,UAAU,aAAa,CAAsB,GAGlD;IACC,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,KAAe;YACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC/B,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,wBAAwB,IAAI,GAAG,CAAC,CAAC;gBAC9E,CAAC;YACH,CAAC;YACD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACzC,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,6BAA6B,CAAC,CAAC;YAC5E,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/dist/esm/server.d.ts

@@ -0,0 +1,45 @@
+import { type ServiceHandler } from "@nats-io/services";
+import { type ServiceContract } from "./contract.js";
+import { type RpcAuthorize, type RpcContext, type RpcHandlers, type RpcResult, type RpcServerHandle, type RpcServerOptions } from "./types.js";
+/** Build a successful `RpcResult`. */
+export declare function ok<T>(result: T): {
+    ok: true;
+    result: T;
+};
+/** Build a domain-error `RpcResult`. */
+export declare function fail<E extends string>(code: E, message: string, details?: unknown): {
+    ok: false;
+    error: {
+        code: E;
+        message: string;
+        details?: unknown;
+    };
+};
+/**
+ * Build the `ServiceHandler` for one contract method — dispatch order fixed
+ * by design §2.4 / wire spec §4.5.
+ *
+ * The library's own synchronous try/catch around `handler(err, msg)` (see
+ * `ServiceImpl.setupHandler`) cannot observe an `async` handler's rejection,
+ * so it never counts our service errors toward `num_errors` — we build every
+ * response (success, domain error, service error) explicitly instead of
+ * throwing, which is what lets a 400/403 carry a JSON `details` body. This is
+ * a documented deviation from `nats micro stats` incrementing on our service
+ * errors; see the package README.
+ *
+ * Exported for unit tests (mock `ServiceMsg` + assert the dispatch order) and
+ * for advanced embedding over a transport other than `@nats-io/services`'
+ * `ServiceHandler`. Not part of the documented public API surface.
+ */
+export declare function buildEndpointHandler<C extends ServiceContract>(contract: C, methodName: string, options: RpcServerOptions<C>, drainSignal: AbortSignal): ServiceHandler;
+/**
+ * Start the reconnect supervisor loop for one contract (design §3).
+ *
+ * `Svcm`-backed `Service` instances permanently stop on connection loss with
+ * no restart path, so this loop rebuilds the service every time it stops
+ * (healthy stop or connection loss) until `signal` aborts.
+ */
+export declare function createRpcServer<C extends ServiceContract>(contract: C, options: RpcServerOptions<C>): RpcServerHandle;
+export declare function newRequestId(): string;
+export type { RpcHandlers, RpcAuthorize, RpcContext, RpcResult, RpcServerHandle, RpcServerOptions };
+//# sourceMappingURL=server.d.ts.map

package/dist/esm/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AAQ7F,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAIpB,sCAAsC;AACtC,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAExD;AAED,wCAAwC;AACxC,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EACnC,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,GAChB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAEvE;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAC5D,QAAQ,EAAE,CAAC,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,WAAW,EAAE,WAAW,GACvB,cAAc,CA0NhB;AAyED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,eAAe,CAsHjB;AAID,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC"}