@qlever-llc/trellis 0.5.1

package/README.md

@@ -0,0 +1,9 @@
+# @qlever-llc/trellis
+
+JavaScript Trellis client runtime. Provides contract-driven client helpers and runtime error types.
+
+```typescript
+const client = contract.createClient(nc, auth, opts);
+```
+
+Server connection helpers live in `@qlever-llc/trellis-server` to keep this package browser-safe.

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,7 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -0,0 +1 @@
+export {};

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/trellis/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser-safe exports for @qlever-llc/trellis
+ */
+import "../_dnt.polyfills.js";
+export { Trellis } from "./trellis.js";
+export type { TrellisAuth } from "./trellis.js";
+export { TypedKV, TypedKVEntry } from "./kv.js";
+export type { WatchEvent, WatchOptions } from "./kv.js";
+export { AuthError, KVError, RemoteError, UnexpectedError, ValidationError, } from "./errors/index.js";
+export type { TrellisErrorInstance } from "./errors/index.js";
+//# sourceMappingURL=browser.d.ts.map

package/esm/trellis/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/trellis/browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGxD,OAAO,EACL,SAAS,EACT,OAAO,EACP,WAAW,EACX,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/esm/trellis/browser.js

@@ -0,0 +1,10 @@
+/**
+ * Browser-safe exports for @qlever-llc/trellis
+ */
+// Core Trellis client class (browser-safe)
+import "../_dnt.polyfills.js";
+export { Trellis } from "./trellis.js";
+// KV utilities (browser-safe)
+export { TypedKV, TypedKVEntry } from "./kv.js";
+// Error types (browser-safe)
+export { AuthError, KVError, RemoteError, UnexpectedError, ValidationError, } from "./errors/index.js";

package/esm/trellis/client.d.ts

@@ -0,0 +1,31 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import type { TrellisAPI } from "@qlever-llc/trellis-contracts";
+import type { Logger } from "pino";
+import type { TrellisAuth } from "./trellis.js";
+import { Trellis } from "./trellis.js";
+type NoResponderRetryOpts = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+};
+export type ClientOpts = {
+    /**
+     * Logical name for this client instance (used for logs and consumer names).
+     * Defaults to "client".
+     */
+    name?: string;
+    log?: Logger;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: NoResponderRetryOpts;
+};
+type ClientContract<TApi> = {
+    API: {
+        trellis: TApi;
+    };
+};
+/**
+ * Create a Trellis client typed from a contract module's derived outbound surface.
+ */
+export declare function createClient<TApi extends TrellisAPI>(contract: ClientContract<TApi>, nats: NatsConnection, auth: TrellisAuth, opts?: ClientOpts): Trellis<TApi>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/esm/trellis/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/trellis/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,KAAK,oBAAoB,GAAG;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;CACzC,CAAC;AAEF,KAAK,cAAc,CAAC,IAAI,IAAI;IAC1B,GAAG,EAAE;QACH,OAAO,EAAE,IAAI,CAAC;KACf,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,UAAU,EAClD,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAC9B,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,WAAW,EACjB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/esm/trellis/client.js

@@ -0,0 +1,13 @@
+import { Trellis } from "./trellis.js";
+/**
+ * Create a Trellis client typed from a contract module's derived outbound surface.
+ */
+export function createClient(contract, nats, auth, opts) {
+    return new Trellis(opts?.name ?? "client", nats, auth, {
+        log: opts?.log,
+        timeout: opts?.timeout,
+        stream: opts?.stream,
+        noResponderRetry: opts?.noResponderRetry,
+        api: contract.API.trellis,
+    });
+}

package/esm/trellis/codec.d.ts

@@ -0,0 +1,12 @@
+import { type InferSchemaType, type SchemaLike } from "@qlever-llc/trellis-contracts";
+import { Result } from "@qlever-llc/trellis-result";
+import type { StaticDecode, TSchema } from "typebox";
+import { UnexpectedError, ValidationError } from "./errors/index.js";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function parse<T extends TSchema>(schema: T, data: JsonValue): Result<StaticDecode<T>, ValidationError | UnexpectedError>;
+export declare function parseSchema<S extends SchemaLike>(schema: S, data: JsonValue): Result<InferSchemaType<S>, ValidationError | UnexpectedError>;
+export declare function encode<T extends TSchema>(schema: T, data: unknown): Result<string, ValidationError | UnexpectedError>;
+export declare function encodeSchema<S extends SchemaLike>(schema: S, data: unknown): Result<string, ValidationError | UnexpectedError>;
+//# sourceMappingURL=codec.d.ts.map

package/esm/trellis/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/trellis/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,UAAU,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAErE,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,CAAC;AAUJ,wBAAgB,KAAK,CAAC,CAAC,SAAS,OAAO,EACrC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC,CAU5D;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAC9C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,GACd,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC,CAW/D;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EACtC,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC,CAUnD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAC/C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC,CAWnD"}

package/esm/trellis/codec.js

@@ -0,0 +1,60 @@
+import { unwrapSchema, } from "@qlever-llc/trellis-contracts";
+import { Result } from "@qlever-llc/trellis-result";
+import { EncodeError, ParseError, Value } from "typebox/value";
+import { UnexpectedError, ValidationError } from "./errors/index.js";
+function parseWithSchema(schema, data) {
+    return Value.Parse(schema, data);
+}
+function encodeWithSchema(schema, data) {
+    return JSON.stringify(Value.Encode(schema, data));
+}
+export function parse(schema, data) {
+    try {
+        return Result.ok(parseWithSchema(schema, data));
+    }
+    catch (cause) {
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(schema, data);
+            return Result.err(new ValidationError({ errors, cause }));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function parseSchema(schema, data) {
+    const raw = unwrapSchema(schema);
+    try {
+        return Result.ok(parseWithSchema(raw, data));
+    }
+    catch (cause) {
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(raw, data);
+            return Result.err(new ValidationError({ errors, cause }));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function encode(schema, data) {
+    try {
+        return Result.ok(encodeWithSchema(schema, data));
+    }
+    catch (cause) {
+        if (cause instanceof EncodeError) {
+            const errors = Value.Errors(schema, data);
+            return Result.err(new ValidationError({ errors, cause }));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}
+export function encodeSchema(schema, data) {
+    const raw = unwrapSchema(schema);
+    try {
+        return Result.ok(encodeWithSchema(raw, data));
+    }
+    catch (cause) {
+        if (cause instanceof EncodeError) {
+            const errors = Value.Errors(raw, data);
+            return Result.err(new ValidationError({ errors, cause }));
+        }
+        return Result.err(new UnexpectedError({ cause }));
+    }
+}

package/esm/trellis/env.d.ts

@@ -0,0 +1,2 @@
+export { getEnv } from "@qlever-llc/trellis-telemetry";
+//# sourceMappingURL=env.d.ts.map

package/esm/trellis/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/trellis/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC"}

package/esm/trellis/env.js

@@ -0,0 +1 @@
+export { getEnv } from "@qlever-llc/trellis-telemetry";

package/esm/trellis/errors/AuthError.d.ts

@@ -0,0 +1,30 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export declare const AuthErrorDataSchema: 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>;
+}>;
+export type AuthErrorData = Static<typeof AuthErrorDataSchema>;
+/**
+ * Error for authentication and authorization failures.
+ */
+export declare class AuthError extends TrellisError<AuthErrorData> {
+    readonly name: "AuthError";
+    readonly reason: AuthErrorData["reason"];
+    constructor(options: ErrorOptions & {
+        reason: AuthErrorData["reason"];
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): AuthErrorData;
+}
+//# sourceMappingURL=AuthError.d.ts.map

package/esm/trellis/errors/AuthError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthError.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/AuthError.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,mBAAmB;;;;;;;EA4B9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY,CAAC,aAAa,CAAC;IACxD,SAAkB,IAAI,cAAwB;IAC9C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;gBAGvC,OAAO,EAAE,YAAY,GAAG;QACtB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb;IAOH;;;;OAIG;IACM,cAAc,IAAI,aAAa;CAOzC"}

package/esm/trellis/errors/AuthError.js

@@ -0,0 +1,65 @@
+import Type from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export const AuthErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("AuthError"),
+    message: Type.String(),
+    reason: Type.Union([
+        Type.Literal("invalid_request"),
+        Type.Literal("missing_session_key"),
+        Type.Literal("missing_proof"),
+        Type.Literal("session_not_found"),
+        Type.Literal("session_expired"),
+        Type.Literal("invalid_signature"),
+        Type.Literal("user_not_found"),
+        Type.Literal("user_inactive"),
+        Type.Literal("unknown_service"),
+        Type.Literal("service_disabled"),
+        Type.Literal("iat_out_of_range"),
+        Type.Literal("invalid_binding_token"),
+        Type.Literal("session_corrupted"),
+        Type.Literal("session_already_bound"),
+        Type.Literal("authtoken_already_used"),
+        Type.Literal("oauth_session_key_mismatch"),
+        Type.Literal("service_role_on_user"),
+        Type.Literal("reply_subject_mismatch"),
+        Type.Literal("insufficient_permissions"),
+        Type.Literal("forbidden"),
+    ]),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for authentication and authorization failures.
+ */
+export class AuthError extends TrellisError {
+    constructor(options) {
+        const { reason, ...baseOptions } = options;
+        super(`Auth failed: ${reason}`, baseOptions);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "AuthError"
+        });
+        Object.defineProperty(this, "reason", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.reason = reason;
+    }
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            reason: this.reason,
+        };
+    }
+}

package/esm/trellis/errors/KVError.d.ts

@@ -0,0 +1,31 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export declare const KVErrorDataSchema: 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>;
+}>;
+export type KVErrorData = Static<typeof KVErrorDataSchema>;
+/**
+ * Error for KV storage operations.
+ * Used when key-value store operations fail.
+ */
+export declare class KVError extends TrellisError<KVErrorData> {
+    readonly name: "KVError";
+    readonly operation?: string;
+    constructor(options: ErrorOptions & {
+        operation?: string;
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): KVErrorData;
+}
+//# sourceMappingURL=KVError.d.ts.map

package/esm/trellis/errors/KVError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KVError.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/KVError.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,iBAAiB;;;;;;;EAO5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE3D;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,YAAY,CAAC,WAAW,CAAC;IACpD,SAAkB,IAAI,YAAsB;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAG1B,OAAO,EAAE,YAAY,GAAG;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb;IAQH;;;;OAIG;IACM,cAAc,IAAI,WAAW;CAOvC"}

package/esm/trellis/errors/KVError.js

@@ -0,0 +1,46 @@
+import Type from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export const KVErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("KVError"),
+    message: Type.String(),
+    operation: Type.Optional(Type.String()),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for KV storage operations.
+ * Used when key-value store operations fail.
+ */
+export class KVError extends TrellisError {
+    constructor(options) {
+        const { operation, ...baseOptions } = options;
+        const msg = `KV ${operation || ""} failed`;
+        super(msg, baseOptions);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "KVError"
+        });
+        Object.defineProperty(this, "operation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.operation = operation;
+    }
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            operation: this.operation,
+        };
+    }
+}

package/esm/trellis/errors/RemoteError.d.ts

@@ -0,0 +1,47 @@
+import { Result, UnexpectedError } from "@qlever-llc/trellis-result";
+import Type, { type Static } from "typebox";
+import { ValidationError } from "./ValidationError.js";
+import { TrellisError } from "./TrellisError.js";
+import type { TrellisErrorData } from "../models/trellis/TrellisError.js";
+export declare const RemoteErrorDataSchema: Type.TObject<{
+    id: Type.TString;
+    type: Type.TLiteral<"RemoteError">;
+    message: Type.TString;
+    remoteError: Type.TAny;
+    context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    traceId: Type.TOptional<Type.TString>;
+}>;
+export type RemoteErrorData = Static<typeof RemoteErrorDataSchema>;
+/**
+ * Error for wrapping errors received from remote Trellis services.
+ * This is the only error type with parseJSON/parseObject methods for deserializing remote errors.
+ */
+export declare class RemoteError extends TrellisError<RemoteErrorData> {
+    readonly name: "RemoteError";
+    readonly remoteError: TrellisErrorData;
+    constructor(options: ErrorOptions & {
+        error: TrellisErrorData;
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): RemoteErrorData;
+    /**
+     * Parses and validates a plain object as TrellisErrorData.
+     * Use this to deserialize errors received from remote services.
+     *
+     * @param obj - Plain object to validate
+     * @returns Result containing validated TrellisError or a ValidationError or UnexpectedError
+     */
+    static parse(data: unknown): Result<TrellisErrorData, ValidationError | UnexpectedError>;
+    /**
+     * Alias for parse() - parses JSON string or object as TrellisErrorData.
+     * @see parse
+     */
+    static parseJSON: typeof RemoteError.parse;
+}
+//# sourceMappingURL=RemoteError.d.ts.map

package/esm/trellis/errors/RemoteError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteError.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/RemoteError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,eAAO,MAAM,qBAAqB;;;;;;;EAOhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE;;;GAGG;AACH,qBAAa,WAAY,SAAQ,YAAY,CAAC,eAAe,CAAC;IAC5D,SAAkB,IAAI,gBAA0B;IAChD,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;gBAGrC,OAAO,EAAE,YAAY,GAAG;QACtB,KAAK,EAAE,gBAAgB,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb;IAOH;;;;OAIG;IACM,cAAc,IAAI,eAAe;IAQ1C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACV,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,gBAAgB,EAAE,eAAe,GAAG,eAAe,CAAC;IAqB9D;;;OAGG;IACH,MAAM,CAAC,SAAS,2BAAqB;CACtC"}

package/esm/trellis/errors/RemoteError.js

@@ -0,0 +1,80 @@
+import { Result } from "@qlever-llc/trellis-result";
+import Type from "typebox";
+import { ParseError, Value } from "typebox/value";
+import { ValidationError } from "./ValidationError.js";
+import { TrellisError } from "./TrellisError.js";
+import { TrellisErrorDataSchema } from "../models/trellis/TrellisError.js";
+export const RemoteErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("RemoteError"),
+    message: Type.String(),
+    remoteError: Type.Any(),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for wrapping errors received from remote Trellis services.
+ * This is the only error type with parseJSON/parseObject methods for deserializing remote errors.
+ */
+export class RemoteError extends TrellisError {
+    constructor(options) {
+        const { error, ...baseOptions } = options;
+        super(`Remote error: ${error.message}`, baseOptions);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "RemoteError"
+        });
+        Object.defineProperty(this, "remoteError", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.remoteError = error;
+    }
+    /**
+     * Serializes error to a plain object.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            remoteError: this.remoteError,
+        };
+    }
+    /**
+     * Parses and validates a plain object as TrellisErrorData.
+     * Use this to deserialize errors received from remote services.
+     *
+     * @param obj - Plain object to validate
+     * @returns Result containing validated TrellisError or a ValidationError or UnexpectedError
+     */
+    static parse(data) {
+        return Result.try(() => typeof data === "string" ? JSON.parse(data) : data).andThen((obj) => {
+            const parseResult = Result.try(() => Value.Parse(TrellisErrorDataSchema, obj));
+            if (parseResult.isErr()) {
+                const cause = parseResult.error.cause;
+                if (cause instanceof ParseError) {
+                    const errors = Value.Errors(TrellisErrorDataSchema, obj);
+                    return Result.err(new ValidationError({ errors, cause }));
+                }
+                return Result.err(parseResult.error);
+            }
+            return Result.ok(parseResult.take());
+        });
+    }
+}
+/**
+ * Alias for parse() - parses JSON string or object as TrellisErrorData.
+ * @see parse
+ */
+Object.defineProperty(RemoteError, "parseJSON", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: RemoteError.parse
+});

package/esm/trellis/errors/TrellisError.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Base class for all Trellis-specific errors.
+ * Extends BaseError and relies on the traceId getter being configured via initTracing.
+ */
+import { BaseError, type BaseErrorSchema } from "@qlever-llc/trellis-result";
+/**
+ * Abstract base class for Trellis errors.
+ * Trellis errors automatically include traceId when initTracing() has been called
+ * and a span is active in the current context.
+ *
+ * The traceId integration is configured by the tracing module's initTracing() function,
+ * which sets up BaseError.traceIdGetter to retrieve the traceId from the active span.
+ */
+export declare abstract class TrellisError<TData extends BaseErrorSchema = BaseErrorSchema> extends BaseError<TData> {
+}
+//# sourceMappingURL=TrellisError.d.ts.map

package/esm/trellis/errors/TrellisError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrellisError.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/TrellisError.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;;;GAOG;AACH,8BAAsB,YAAY,CAChC,KAAK,SAAS,eAAe,GAAG,eAAe,CAC/C,SAAQ,SAAS,CAAC,KAAK,CAAC;CAGzB"}

package/esm/trellis/errors/TrellisError.js

@@ -0,0 +1,15 @@
+/**
+ * Base class for all Trellis-specific errors.
+ * Extends BaseError and relies on the traceId getter being configured via initTracing.
+ */
+import { BaseError } from "@qlever-llc/trellis-result";
+/**
+ * Abstract base class for Trellis errors.
+ * Trellis errors automatically include traceId when initTracing() has been called
+ * and a span is active in the current context.
+ *
+ * The traceId integration is configured by the tracing module's initTracing() function,
+ * which sets up BaseError.traceIdGetter to retrieve the traceId from the active span.
+ */
+export class TrellisError extends BaseError {
+}

package/esm/trellis/errors/ValidationError.d.ts

@@ -0,0 +1,51 @@
+import type { TLocalizedValidationError } from "typebox/error";
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+export type ValidationErrorInput = TLocalizedValidationError | {
+    path: string;
+    message: string;
+};
+/**
+ * Schema for validation issue in ValidationError.
+ */
+export declare const ValidationIssueSchema: Type.TObject<{
+    path: Type.TString;
+    message: Type.TString;
+}>;
+export type ValidationIssue = Static<typeof ValidationIssueSchema>;
+/**
+ * Schema for ValidationError serialization.
+ */
+export declare const ValidationErrorDataSchema: 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>;
+}>;
+export type ValidationErrorData = Static<typeof ValidationErrorDataSchema>;
+/**
+ * Error for data validation failures.
+ * Includes schema validation and missing required data.
+ */
+export declare class ValidationError extends TrellisError<ValidationErrorData> {
+    #private;
+    readonly name: "ValidationError";
+    constructor(options: ErrorOptions & {
+        errors: Iterable<ValidationErrorInput>;
+        context?: Record<string, unknown>;
+        id?: string;
+    });
+    /**
+     * Serializes error to a plain object.
+     * Transforms internal errors array to issues array for serialization.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable(): ValidationErrorData;
+}
+//# sourceMappingURL=ValidationError.d.ts.map

package/esm/trellis/errors/ValidationError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationError.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/ValidationError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,MAAM,oBAAoB,GAC5B,yBAAyB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAWtC;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;EAGhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;EAOpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE3E;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY,CAAC,mBAAmB,CAAC;;IACpE,SAAkB,IAAI,oBAA8B;gBAIlD,OAAO,EAAE,YAAY,GAAG;QACtB,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAC;QACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb;IAWH;;;;;OAKG;IACM,cAAc,IAAI,mBAAmB;CAU/C"}