@dotcms/ai 26.10.20-1 → 26.10.21-1

package/errors.esm.js

@@ -0,0 +1,180 @@
+/**
+ * The single typed error hierarchy for `@dotcms/ai`.
+ *
+ * Both verbs of the runtime — `request()` (direct) and `run()` (sandboxed) — surface
+ * the *same* error types, because both route through one shared request core. The
+ * model-facing string an MCP tool builds is *formatting on top of* these errors, not a
+ * separate error model.
+ *
+ * Every error carries a stable, machine-readable `code` and a `toJSON()` so it survives
+ * the worker→host serialization boundary (a thrown error becomes `{ name, message, stack }`
+ * by default; these types preserve `code` and the structured detail too).
+ */
+class DotCMSError extends Error {
+    constructor(message, options) {
+        super(message);
+        // A fallback only: every subclass declares its own `name`. The class name cannot be
+        // trusted — a bundler minifies it, and the built MCP server showed the model
+        // "b: …" for a PolicyError. A new subclass must declare `override readonly name`.
+        this.name = new.target.name;
+        if (options?.cause !== undefined) {
+            // Standard ES2022 `cause`, but assigned defensively for older lib targets.
+            this.cause = options.cause;
+        }
+        // Restore the prototype chain so `instanceof` works after transpilation to ES5/ES2017.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** Type-specific structured detail; overridden by subclasses that carry data. */
+    detail() {
+        return undefined;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            stack: this.stack,
+            detail: this.detail()
+        };
+    }
+}
+/** Adapter input failed validation, or request options were malformed. */
+class ValidationError extends DotCMSError {
+    constructor(message, issues) {
+        super(message);
+        this.name = 'ValidationError';
+        this.code = 'VALIDATION';
+        this.issues = issues;
+    }
+    detail() {
+        return this.issues ? { issues: this.issues } : undefined;
+    }
+}
+/** The allow-list / policy rejected the call before it reached the network. */
+class PolicyError extends DotCMSError {
+    constructor(message, method, path) {
+        super(message);
+        this.name = 'PolicyError';
+        this.code = 'POLICY';
+        this.method = method;
+        this.path = path;
+    }
+    detail() {
+        return { method: this.method, path: this.path };
+    }
+}
+/** dotCMS responded with a non-2xx status. Carries the status and the (text) body. */
+class HttpError extends DotCMSError {
+    constructor(status, statusText, body) {
+        super(`HTTP ${status} ${statusText}: ${body}`);
+        this.name = 'HttpError';
+        this.code = 'HTTP';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+    detail() {
+        return { status: this.status, statusText: this.statusText, body: this.body };
+    }
+}
+/**
+ * The request never got a response — the connection was refused or reset, the host did not
+ * resolve, the socket timed out. Distinct from `HttpError` (the instance answered, with an
+ * error) because the two call for opposite reactions: this one is usually worth retrying.
+ */
+class NetworkError extends DotCMSError {
+    constructor(method, path, cause) {
+        const reason = networkReason(cause);
+        super(`Request ${method} ${path} could not reach the dotCMS instance` +
+            (reason ? ` (${reason})` : '') +
+            '. The instance may be down, unreachable or restarting; this is worth retrying.', { cause });
+        this.name = 'NetworkError';
+        this.code = 'NETWORK';
+        this.method = method;
+        this.path = path;
+        this.reason = reason;
+    }
+    detail() {
+        return { method: this.method, path: this.path, reason: this.reason };
+    }
+}
+/** The most specific reason a failed `fetch` carries — undici nests it under `cause`. */
+function networkReason(error) {
+    const nested = error?.cause;
+    const code = nested?.code ?? error?.code;
+    if (typeof code === 'string' && code) {
+        return code;
+    }
+    const message = nested?.message ?? error?.message;
+    return typeof message === 'string' && message ? message : undefined;
+}
+/** A timeout elapsed (sandbox wall-clock, per-adapter-call, or context load). */
+class TimeoutError extends DotCMSError {
+    constructor(message, timeoutMs) {
+        super(message);
+        this.name = 'TimeoutError';
+        this.code = 'TIMEOUT';
+        this.timeoutMs = timeoutMs;
+    }
+    detail() {
+        return this.timeoutMs === undefined ? undefined : { timeoutMs: this.timeoutMs };
+    }
+}
+/** The call was aborted in-flight (typically because the sandbox timed out). */
+class AbortError extends DotCMSError {
+    constructor() {
+        super(...arguments);
+        this.name = 'AbortError';
+        this.code = 'ABORT';
+    }
+}
+/** Model-authored code threw while executing inside the sandbox. */
+class SandboxError extends DotCMSError {
+    constructor(message, originalName, stack) {
+        super(message);
+        this.name = 'SandboxError';
+        this.code = 'SANDBOX';
+        this.originalName = originalName;
+        if (stack)
+            this.stack = stack;
+    }
+    detail() {
+        return this.originalName ? { originalName: this.originalName } : undefined;
+    }
+}
+/** Catch-all for runtime-internal failures that don't fit a more specific type. */
+class RuntimeError extends DotCMSError {
+    constructor() {
+        super(...arguments);
+        this.name = 'RuntimeError';
+        this.code = 'RUNTIME';
+    }
+}
+/** Type guard for any error in the hierarchy. */
+function isDotCMSError(value) {
+    return value instanceof DotCMSError;
+}
+/**
+ * Normalize any thrown value into a serializable error shape. Used at the worker→host
+ * boundary and when formatting a result, so callers always get a consistent structure
+ * regardless of what was thrown.
+ */
+function serializeError(value) {
+    if (isDotCMSError(value)) {
+        return value.toJSON();
+    }
+    if (value instanceof Error) {
+        // Preserve a code already set on a plain Error (e.g. Node system errors, or an
+        // adapter that tags its own); fall back to RUNTIME.
+        const existingCode = value.code;
+        return {
+            name: value.name,
+            code: (typeof existingCode === 'string' ? existingCode : 'RUNTIME'),
+            message: value.message,
+            stack: value.stack
+        };
+    }
+    return { name: 'Error', code: 'RUNTIME', message: String(value) };
+}
+
+export { AbortError as A, DotCMSError as D, HttpError as H, NetworkError as N, PolicyError as P, RuntimeError as R, SandboxError as S, TimeoutError as T, ValidationError as V, isDotCMSError as i, serializeError as s };