@qlever-llc/trellis 0.5.1

package/script/trellis/kv.js

@@ -0,0 +1,354 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedKVEntry = exports.TypedKV = void 0;
+// @ts-nocheck -- svelte-check hits pathological generic instantiation in this file
+const kv_1 = require("@nats-io/kv");
+const trellis_result_1 = require("@qlever-llc/trellis-result");
+const ts_deepmerge_1 = require("ts-deepmerge");
+const value_1 = __importStar(require("typebox/value"));
+const index_js_1 = require("./errors/index.js");
+const helpers_js_1 = require("./helpers.js");
+function externalizeValue(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(externalizeValue);
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry !== undefined) {
+                out[key] = externalizeValue(entry);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+function parseExternalValue(schema, value) {
+    if (value_1.default.HasCodec(schema)) {
+        return value_1.default.Decode(schema, value);
+    }
+    return value_1.default.Parse(schema, value);
+}
+function serializeValue(schema, value) {
+    return JSON.stringify(value_1.default.Parse(schema, externalizeValue(value)));
+}
+function serializeExternalValue(schema, value) {
+    return serializeValue(schema, value);
+}
+class TypedKV {
+    constructor(schema, kv) {
+        Object.defineProperty(this, "schema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: schema
+        });
+        Object.defineProperty(this, "kv", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: kv
+        });
+    }
+    static async open(nats, name, schema, options) {
+        try {
+            const kvm = new kv_1.Kvm(nats);
+            const kv = options.bindOnly
+                ? await kvm.open(name)
+                : await kvm.create(name, {
+                    history: options.history ?? 1,
+                    ttl: options.ttl ?? 0,
+                    ...(options.maxValueBytes ? { maxValueSize: options.maxValueBytes } : {}),
+                });
+            const typedKv = new TypedKV(schema, kv);
+            return trellis_result_1.Result.ok(typedKv);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "open", cause }));
+        }
+    }
+    async get(key) {
+        let s;
+        try {
+            s = await this.kv.get((0, helpers_js_1.escapeKvKey)(key));
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "get", cause, context: { key } }));
+        }
+        if (!s) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({
+                operation: "get",
+                context: { key, reason: "not found" },
+            }));
+        }
+        return await createTypedKvEntry(this.schema, this.kv, s);
+    }
+    async create(key, value) {
+        const schema = this.schema;
+        const rawValue = value;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const serialized = serializeExternalValue(schema, rawValue);
+        try {
+            await this.kv.create((0, helpers_js_1.escapeKvKey)(key), serialized);
+            return trellis_result_1.Result.ok(undefined);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "create", cause, context: { key } }));
+        }
+    }
+    async put(key, value) {
+        const schema = this.schema;
+        const rawValue = value;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const serialized = serializeExternalValue(schema, rawValue);
+        try {
+            await this.kv.put((0, helpers_js_1.escapeKvKey)(key), serialized);
+            return trellis_result_1.Result.ok(undefined);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "put", cause, context: { key } }));
+        }
+    }
+    async delete(key) {
+        try {
+            await this.kv.delete((0, helpers_js_1.escapeKvKey)(key));
+            return trellis_result_1.Result.ok(undefined);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "delete", cause, context: { key } }));
+        }
+    }
+    async keys(filter = ">") {
+        try {
+            return trellis_result_1.Result.ok(await this.kv.keys(filter));
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "keys", cause, context: { filter } }));
+        }
+    }
+    async status() {
+        try {
+            const status = await this.kv.status();
+            return trellis_result_1.Result.ok({ values: status.values });
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "status", cause }));
+        }
+    }
+}
+exports.TypedKV = TypedKV;
+class TypedKVEntry {
+    constructor(schema, kv, entry, value) {
+        Object.defineProperty(this, "schema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: schema
+        });
+        Object.defineProperty(this, "kv", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: kv
+        });
+        Object.defineProperty(this, "entry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: entry
+        });
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // @ts-expect-error svelte-check hits excessive type instantiation on assignment
+        this.value = value;
+    }
+    static async create(schema, kv, entry) {
+        return await createTypedKvEntry(schema, kv, entry);
+    }
+    get key() {
+        return (0, helpers_js_1.decodeSubject)(this.entry.key);
+    }
+    /**
+     * Watch this KV entry for changes.
+     *
+     * @param callback - Function called when the entry changes
+     * @param opts - Watch options (e.g., includeDeletes)
+     * @returns A function to stop watching
+     */
+    async watch(callback, opts) {
+        const watcher = await this.kv.watch({
+            key: this.entry.key,
+            include: opts?.includeDeletes ? "history" : "updates",
+        });
+        const abortController = new AbortController();
+        // Start the async iteration in the background
+        (async () => {
+            for await (const entry of watcher) {
+                if (abortController.signal.aborted)
+                    break;
+                if (entry.operation === "DEL" || entry.operation === "PURGE") {
+                    if (opts?.includeDeletes) {
+                        callback({
+                            type: "delete",
+                            key: (0, helpers_js_1.decodeSubject)(entry.key),
+                            revision: entry.revision,
+                            timestamp: entry.created,
+                        });
+                    }
+                }
+                else {
+                    let validated;
+                    try {
+                        const json = entry.json();
+                        validated = parseExternalValue(this.schema, json);
+                    }
+                    catch {
+                        try {
+                            await this.kv.delete(entry.key, {
+                                previousSeq: entry.revision,
+                            });
+                        }
+                        catch {
+                            // Best-effort cleanup of invalid entries.
+                        }
+                        continue;
+                    }
+                    callback({
+                        type: "update",
+                        key: (0, helpers_js_1.decodeSubject)(entry.key),
+                        value: validated,
+                        revision: entry.revision,
+                        timestamp: entry.created,
+                    });
+                }
+            }
+        })();
+        return () => {
+            abortController.abort();
+            watcher.stop();
+        };
+    }
+    async merge(value, vcc) {
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const mergedData = (0, ts_deepmerge_1.merge)(this.value, value);
+        const schema = this.schema;
+        const mergedRawValue = mergedData;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const mergeResult = trellis_result_1.Result.try(() => serializeExternalValue(schema, mergedRawValue));
+        if (mergeResult.isErr()) {
+            const cause = mergeResult.error.cause;
+            if (cause instanceof value_1.ParseError) {
+                const errors = value_1.default.Errors(schema, externalizeValue(mergedData));
+                return trellis_result_1.Result.err(new index_js_1.ValidationError({ errors, cause }));
+            }
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "merge", cause: mergeResult.error, context: { key: this.key } }));
+        }
+        return this.put(mergedData, vcc);
+    }
+    async put(value, vcc) {
+        const schema = this.schema;
+        const serialized = serializeValue(schema, value);
+        try {
+            await this.kv.put(this.entry.key, serialized, {
+                previousSeq: vcc ? this.entry.revision : undefined,
+            });
+            return trellis_result_1.Result.ok(undefined);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "put", cause, context: { key: this.key } }));
+        }
+    }
+    async delete(vcc) {
+        try {
+            await this.kv.delete(this.entry.key, {
+                previousSeq: vcc ? this.entry.revision : undefined,
+            });
+            return trellis_result_1.Result.ok(undefined);
+        }
+        catch (cause) {
+            return trellis_result_1.Result.err(new index_js_1.KVError({ operation: "delete", cause, context: { key: this.key } }));
+        }
+    }
+}
+exports.TypedKVEntry = TypedKVEntry;
+async function createTypedKvEntry(schema, kv, entry) {
+    async function deleteInvalidEntry(reason) {
+        try {
+            await kv.delete(entry.key, {
+                previousSeq: entry.revision,
+            });
+            return {
+                key: (0, helpers_js_1.decodeSubject)(entry.key),
+                revision: entry.revision,
+                invalidEntryDeleted: true,
+                invalidEntryReason: reason,
+            };
+        }
+        catch (cause) {
+            return {
+                key: (0, helpers_js_1.decodeSubject)(entry.key),
+                revision: entry.revision,
+                invalidEntryDeleted: false,
+                invalidEntryDeleteError: cause instanceof Error ? cause.message : String(cause),
+                invalidEntryReason: reason,
+            };
+        }
+    }
+    const jsonResult = trellis_result_1.Result.try(() => entry.json());
+    if (jsonResult.isErr()) {
+        const context = await deleteInvalidEntry(`decode failed: ${jsonResult.error.message}`);
+        return trellis_result_1.Result.err(new index_js_1.ValidationError({
+            errors: [{ path: "", message: `Failed to decode KV value: ${jsonResult.error.message}` }],
+            cause: jsonResult.error,
+            context,
+        }));
+    }
+    const json = jsonResult.take();
+    const parseResult = trellis_result_1.Result.try(() => parseExternalValue(schema, json));
+    if (parseResult.isErr()) {
+        const cause = parseResult.error.cause;
+        if (cause instanceof value_1.ParseError) {
+            const errors = value_1.default.Errors(schema, json);
+            const context = await deleteInvalidEntry("schema parse failed");
+            return trellis_result_1.Result.err(new index_js_1.ValidationError({ errors, cause, context }));
+        }
+        const context = await deleteInvalidEntry(parseResult.error.message);
+        return trellis_result_1.Result.err(new index_js_1.ValidationError({
+            errors: [{ path: "", message: parseResult.error.message }],
+            cause: parseResult.error,
+            context,
+        }));
+    }
+    const typedEntry = new TypedKVEntry(schema, kv, entry, parseResult.take());
+    return trellis_result_1.Result.ok(typedEntry);
+}

package/script/trellis/models/trellis/TrellisError.d.ts

@@ -0,0 +1,43 @@
+import Type, { type StaticDecode } from "typebox";
+/**
+ * Discriminated union schema for all possible Trellis error types.
+ * These errors can be serialized and sent over RPC.
+ * Note: RemoteError is not included here as it's a local wrapper, not a serializable error type.
+ */
+export declare const TrellisErrorDataSchema: Type.TUnion<[Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"UnexpectedError">;
+    message: Type.TString;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"ValidationError">;
+    message: Type.TString;
+    issues: Type.TArray<Type.TObject<{
+        path: Type.TString;
+        message: Type.TString;
+    }>>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"AuthError">;
+    message: Type.TString;
+    reason: Type.TUnion<[Type.TLiteral<"invalid_request">, Type.TLiteral<"missing_session_key">, Type.TLiteral<"missing_proof">, Type.TLiteral<"session_not_found">, Type.TLiteral<"session_expired">, Type.TLiteral<"invalid_signature">, Type.TLiteral<"user_not_found">, Type.TLiteral<"user_inactive">, Type.TLiteral<"unknown_service">, Type.TLiteral<"service_disabled">, Type.TLiteral<"iat_out_of_range">, Type.TLiteral<"invalid_binding_token">, Type.TLiteral<"session_corrupted">, Type.TLiteral<"session_already_bound">, Type.TLiteral<"authtoken_already_used">, Type.TLiteral<"oauth_session_key_mismatch">, Type.TLiteral<"service_role_on_user">, Type.TLiteral<"reply_subject_mismatch">, Type.TLiteral<"insufficient_permissions">, Type.TLiteral<"forbidden">]>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"KVError">;
+    message: Type.TString;
+    operation: Type.TOptional<Type.TString>;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>]>;
+/**
+ * Type for validated Trellis error data.
+ * This is a discriminated union that enables type narrowing based on the `type` field.
+ */
+export type TrellisErrorData = StaticDecode<typeof TrellisErrorDataSchema>;
+//# sourceMappingURL=TrellisError.d.ts.map

package/script/trellis/models/trellis/TrellisError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrellisError.d.ts","sourceRoot":"","sources":["../../../../src/trellis/models/trellis/TrellisError.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAMlD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAKjC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/script/trellis/models/trellis/TrellisError.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrellisErrorDataSchema = void 0;
+const typebox_1 = __importDefault(require("typebox"));
+const mod_js_1 = require("@qlever-llc/trellis-result");
+const ValidationError_js_1 = require("../../errors/ValidationError.js");
+const AuthError_js_1 = require("../../errors/AuthError.js");
+const KVError_js_1 = require("../../errors/KVError.js");
+/**
+ * Discriminated union schema for all possible Trellis error types.
+ * These errors can be serialized and sent over RPC.
+ * Note: RemoteError is not included here as it's a local wrapper, not a serializable error type.
+ */
+exports.TrellisErrorDataSchema = typebox_1.default.Union([
+    mod_js_1.UnexpectedErrorDataSchema,
+    ValidationError_js_1.ValidationErrorDataSchema,
+    AuthError_js_1.AuthErrorDataSchema,
+    KVError_js_1.KVErrorDataSchema,
+]);

package/script/trellis/tasks.d.ts

@@ -0,0 +1,11 @@
+import { AsyncResult, type BaseError } from "@qlever-llc/trellis-result";
+import type { Logger } from "pino";
+export declare class TrellisTasks {
+    #private;
+    constructor(opts: {
+        log?: Logger;
+    });
+    add<E extends BaseError>(name: string, task: AsyncResult<void, E>): void;
+    wait(): AsyncResult<void, BaseError>;
+}
+//# sourceMappingURL=tasks.d.ts.map

package/script/trellis/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/trellis/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAU,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,qBAAa,YAAY;;gBAKX,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAOlC,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IAejE,IAAI,IAAI,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC;CAGrC"}

package/script/trellis/tasks.js

@@ -0,0 +1,45 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _TrellisTasks_tasks, _TrellisTasks_log;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrellisTasks = void 0;
+const trellis_result_1 = require("@qlever-llc/trellis-result");
+const globals_js_1 = require("./globals.js");
+class TrellisTasks {
+    constructor(opts) {
+        _TrellisTasks_tasks.set(this, {});
+        _TrellisTasks_log.set(this, void 0);
+        __classPrivateFieldSet(this, _TrellisTasks_log, opts.log ?? globals_js_1.logger, "f");
+    }
+    /*
+     * Add a task to the task queue
+     */
+    add(name, task) {
+        if (name in __classPrivateFieldGet(this, _TrellisTasks_tasks, "f")) {
+            __classPrivateFieldGet(this, _TrellisTasks_log, "f").error({ name }, "Task already running?");
+            throw new Error(`Task ${name} already running`);
+        }
+        __classPrivateFieldGet(this, _TrellisTasks_log, "f").debug({ name }, "Added task");
+        __classPrivateFieldGet(this, _TrellisTasks_tasks, "f")[name] = task.then((r) => {
+            if (trellis_result_1.Result.isErr(r)) {
+                __classPrivateFieldGet(this, _TrellisTasks_log, "f").error(r, "Task encountered a runtime error");
+            }
+            return r;
+        });
+    }
+    wait() {
+        return trellis_result_1.AsyncResult.any(Object.values(__classPrivateFieldGet(this, _TrellisTasks_tasks, "f")));
+    }
+}
+exports.TrellisTasks = TrellisTasks;
+_TrellisTasks_tasks = new WeakMap(), _TrellisTasks_log = new WeakMap();

package/script/trellis/tracing.d.ts

@@ -0,0 +1,5 @@
+import "../_dnt.polyfills.js";
+export type { HeaderCarrier, NatsHeadersLike } from "@qlever-llc/trellis-telemetry";
+export { configureErrorTraceId, context, createMapCarrier, createNatsHeaderCarrier, extractTraceContext, getActiveSpan, getTrellisTracer as getTracer, injectTraceContext, SpanKind, SpanStatusCode, startClientSpan, startServerSpan, trace, withSpan, withSpanAsync } from "@qlever-llc/trellis-telemetry";
+export declare function initTracing(serviceName: string): void;
+//# sourceMappingURL=tracing.d.ts.map

package/script/trellis/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/trellis/tracing.ts"],"names":[],"mappings":"AAEA,OAAO,sBAAsB,CAAC;AAE9B,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAC,qBAAqB,EAC3B,OAAO,EACP,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,EAAC,gBAAgB,IAAI,SAAS,EAC3C,kBAAkB,EAClB,QAAQ,EACR,cAAc,EAAC,eAAe,EAAE,eAAe,EAC/C,KAAK,EACL,QAAQ,EACR,aAAa,EACd,MAAM,+BAA+B,CAAC;AACvC,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAErD"}

package/script/trellis/tracing.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSpanAsync = exports.withSpan = exports.trace = exports.startServerSpan = exports.startClientSpan = exports.SpanStatusCode = exports.SpanKind = exports.injectTraceContext = exports.getTracer = exports.getActiveSpan = exports.extractTraceContext = exports.createNatsHeaderCarrier = exports.createMapCarrier = exports.context = exports.configureErrorTraceId = void 0;
+exports.initTracing = initTracing;
+// Keep this subpath for Trellis-specific tracing convenience without exposing
+// telemetry from the root `@qlever-llc/trellis` package surface.
+require("../_dnt.polyfills.js");
+var trellis_telemetry_1 = require("@qlever-llc/trellis-telemetry");
+Object.defineProperty(exports, "configureErrorTraceId", { enumerable: true, get: function () { return trellis_telemetry_1.configureErrorTraceId; } });
+Object.defineProperty(exports, "context", { enumerable: true, get: function () { return trellis_telemetry_1.context; } });
+Object.defineProperty(exports, "createMapCarrier", { enumerable: true, get: function () { return trellis_telemetry_1.createMapCarrier; } });
+Object.defineProperty(exports, "createNatsHeaderCarrier", { enumerable: true, get: function () { return trellis_telemetry_1.createNatsHeaderCarrier; } });
+Object.defineProperty(exports, "extractTraceContext", { enumerable: true, get: function () { return trellis_telemetry_1.extractTraceContext; } });
+Object.defineProperty(exports, "getActiveSpan", { enumerable: true, get: function () { return trellis_telemetry_1.getActiveSpan; } });
+Object.defineProperty(exports, "getTracer", { enumerable: true, get: function () { return trellis_telemetry_1.getTrellisTracer; } });
+Object.defineProperty(exports, "injectTraceContext", { enumerable: true, get: function () { return trellis_telemetry_1.injectTraceContext; } });
+Object.defineProperty(exports, "SpanKind", { enumerable: true, get: function () { return trellis_telemetry_1.SpanKind; } });
+Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return trellis_telemetry_1.SpanStatusCode; } });
+Object.defineProperty(exports, "startClientSpan", { enumerable: true, get: function () { return trellis_telemetry_1.startClientSpan; } });
+Object.defineProperty(exports, "startServerSpan", { enumerable: true, get: function () { return trellis_telemetry_1.startServerSpan; } });
+Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return trellis_telemetry_1.trace; } });
+Object.defineProperty(exports, "withSpan", { enumerable: true, get: function () { return trellis_telemetry_1.withSpan; } });
+Object.defineProperty(exports, "withSpanAsync", { enumerable: true, get: function () { return trellis_telemetry_1.withSpanAsync; } });
+function initTracing(serviceName) {
+    void Promise.resolve().then(() => __importStar(require("@qlever-llc/trellis-telemetry"))).then((mod) => mod.initTracing(serviceName));
+}

package/script/trellis/trellis.d.ts

@@ -0,0 +1,117 @@
+import { type NatsConnection } from "@nats-io/nats-core";
+import type { InferSchemaType, TrellisAPI } from "@qlever-llc/trellis-contracts";
+import { AsyncResult, type BaseError, type MaybeAsync, Result } from "@qlever-llc/trellis-result";
+import { API as trellisCoreApi } from "@qlever-llc/trellis-sdk-core";
+import type { Logger } from "pino";
+import { type TrellisErrorInstance, UnexpectedError, ValidationError } from "./errors/index.js";
+import { RemoteError } from "./errors/RemoteError.js";
+type SessionUser = {
+    id: string;
+    origin: string;
+    active: boolean;
+    name: string;
+    email: string;
+    image?: string;
+    capabilities: string[];
+    lastLogin?: string;
+};
+export type TrellisSigner = (data: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+export type TrellisAuth = {
+    sessionKey: string;
+    sign: TrellisSigner;
+};
+type AnyTrellisAPI = TrellisAPI;
+type MethodsOf<TA extends AnyTrellisAPI> = keyof TA["rpc"] & string;
+type EventsOf<TA extends AnyTrellisAPI> = keyof TA["events"] & string;
+type MethodInputOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = InferSchemaType<TA["rpc"][M]["input"]>;
+type MethodOutputOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = InferSchemaType<TA["rpc"][M]["output"]>;
+type EventOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = InferSchemaType<TA["events"][E]["event"]>;
+type EventPayloadOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = Omit<EventOf<TA, E>, "header">;
+type NoResponderRetryOpts = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+};
+type TrellisOpts<TA extends AnyTrellisAPI> = {
+    log?: Logger;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: NoResponderRetryOpts;
+    api?: TA;
+    authBypassMethods?: string[];
+};
+type RequestOpts = {
+    timeout?: number;
+};
+type HandlerFn<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = (m: MethodInputOf<TA, M>, context: {
+    user: SessionUser;
+    sessionKey: string;
+}) => Promise<Result<MethodOutputOf<TA, M>, TrellisErrorInstance>>;
+type DeepRecord<T> = {
+    [k: string]: T | DeepRecord<T>;
+};
+export declare class Trellis<TA extends AnyTrellisAPI = typeof trellisCoreApi> {
+    #private;
+    readonly name: string;
+    readonly timeout: number;
+    readonly stream: string;
+    private nats;
+    private js;
+    protected auth: TrellisAuth;
+    readonly api: TA;
+    constructor(name: string, // Must be unique for a service
+    nats: NatsConnection, auth: TrellisAuth, opts?: TrellisOpts<TA>);
+    /**
+     * Returns the underlying NATS connection.
+     */
+    get natsConnection(): NatsConnection;
+    /**
+     * Makes an authenticated request to a Trellis RPC method.
+     *
+     * @template M The specific RPC method being called.
+     * @param method The name of the RPC method to call.
+     * @param input The input data for the method, conforming to its schema.
+     * @param opts Optional request-specific options.
+     * @returns A promise that resolves with a `Result` containing either the method's
+     * output or an error.
+     * @returns A `Result` object:
+     *              ok: A validated reponse of method M
+     *              err: RemoteError | ValidationError | UnexpectedError
+     */
+    request<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<Result<MethodOutputOf<TA, M>, RemoteError | ValidationError | UnexpectedError>>;
+    mount<M extends MethodsOf<TA>>(method: M, fn: HandlerFn<TA, M>): Promise<void>;
+    publish<E extends EventsOf<TA>>(event: E, data: EventPayloadOf<TA, E>): Promise<Result<void, ValidationError | UnexpectedError>>;
+    event<E extends EventsOf<TA>>(event: E, subjectData: DeepRecord<string | number | boolean>, fn: (m: EventOf<TA, E>) => MaybeAsync<void, BaseError>): Promise<Result<void, ValidationError | UnexpectedError>>;
+    wait(): AsyncResult<void, BaseError>;
+    template(subject: string, data: unknown, allowWildcards?: boolean): Result<string, ValidationError>;
+}
+type TrellisServerOpts<TA extends AnyTrellisAPI> = Omit<TrellisOpts<TA>, "api"> & {
+    api: TA;
+    version?: string;
+};
+export declare class TrellisServer<TA extends AnyTrellisAPI = AnyTrellisAPI> extends Trellis<TA> {
+    #private;
+    private constructor();
+    /**
+     * Creates an authenticated TrellisServer instance.
+     *
+     * Services connect to NATS using the session-key auth flow (see ADR):
+     * - NATS `auth_token` (aka `token`) is a JSON string `{ v: 1, sessionKey, iat, sig }`
+     * - `sig` signs SHA-256(`nats-connect:${iat}`) with the session key
+     * - `inboxPrefix` MUST be `_INBOX.${sessionKey.slice(0, 16)}`
+     *
+     * @param name Unique name for this service
+     * @param nats Existing NATS connection (already authenticated)
+     * @param auth Service session-key credentials
+     * @param opts Optional server options
+     * @returns An authenticated TrellisServer instance
+     */
+    static create<TA extends AnyTrellisAPI = AnyTrellisAPI>(name: string, nats: NatsConnection, auth: TrellisAuth, opts: TrellisServerOpts<TA>): TrellisServer<TA>;
+    /**
+     * Stops the server by clearing refresh timers and draining the NATS connection.
+     * Draining allows in-flight messages to complete before closing the connection.
+     * This method is idempotent and can be called multiple times safely.
+     */
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=trellis.d.ts.map