@miragon/pulse-engine-client 0.0.0-bootstrap.0 → 0.25.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+import type { Client } from "./generated/client/types.gen.js";
+export type { Client };
+export type EngineAuthType = "basic" | "bearer" | "passthrough" | "none";
+/** Default per-request deadline for engine calls (`timeoutMs`). */
+export declare const DEFAULT_ENGINE_TIMEOUT_MS = 30000;
+export interface EngineClientOptions {
+    baseUrl: string;
+    /**
+     * Id of the configured engine this client talks to. Carried into every
+     * error message (`… (engine prod-a)`) so the model can tell WHICH engine
+     * failed in a multi-engine fleet; left out of the message when unset.
+     */
+    engineId?: string;
+    /**
+     * Per-request deadline in ms (default {@link DEFAULT_ENGINE_TIMEOUT_MS}),
+     * covering connect, headers and body. A hung engine then fails the call
+     * with a timeout error instead of holding it for undici's minutes-long
+     * defaults.
+     */
+    timeoutMs?: number;
+    authType?: EngineAuthType;
+    username?: string;
+    password?: string;
+    token?: string;
+    /**
+     * Token source for `authType: "passthrough"`, called on every request; the
+     * returned bearer token (without the `Bearer ` scheme prefix) is sent as
+     * the `Authorization` header. When it returns `undefined` (or no provider
+     * is given), the request is sent without auth, like `authType: "none"`;
+     * an engine with REST auth enabled then answers 401.
+     */
+    tokenProvider?: () => string | undefined;
+}
+/**
+ * Per-engine client factory. All defaults (JSON content negotiation headers,
+ * `throwOnError`, `responseStyle`) come from `createClientConfig` in
+ * src/hey-api.ts (the same function the generated default client uses), so
+ * runtime behavior and the generated SDK types stay in sync.
+ *
+ * Every client, whatever its auth type, carries a per-request deadline in its
+ * `fetch` (combined with a caller `signal`, see {@link withCallerSignal}) and
+ * an error interceptor that maps every failure to an `EngineRequestError`
+ * (status, exception type, engine message, engine id; credentials masked).
+ *
+ * The deadline binds the request as it LEAVES (after every request
+ * interceptor), so an interceptor that returns a new `Request` can neither
+ * detach it nor disguise it as a cancellation. A custom `fetch` (per call or
+ * via `setConfig`) replaces the deadline with it: wrap
+ * `client.getConfig().fetch` instead. Request interceptors should mutate the
+ * request (`request.headers.set(…)`); one that returns a new `Request` keeps
+ * the deadline, but the caller's signal reaches the new request only through
+ * the dropped one (undici follows signals via a `WeakRef`), so after a
+ * garbage collection a cancelled call runs on until the deadline.
+ */
+export declare function createEngineClient(options: EngineClientOptions): Client;
+/**
+ * A view of `client` whose READS honor the caller's `signal` (an MCP
+ * request's `ctx.signal`, aborted when the MCP client cancels or
+ * disconnects), on top of the client's own deadline. Writes never see it:
+ * aborting a started write cannot roll it back on the engine, it only turns
+ * a known outcome into an unknown one. An explicit per-call `signal` wins.
+ * Without a signal the client itself is returned.
+ */
+export declare function withCallerSignal(client: Client, signal: AbortSignal | undefined): Client;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAA;AAI7D,YAAY,EAAE,MAAM,EAAE,CAAA;AAEtB,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAA;AAExE,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAK/C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CACzC;AAsDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAsDvE;AAKD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CASxF"}

package/dist/client.js

@@ -0,0 +1,144 @@
+import { createClient } from "./generated/client/client.gen.js";
+import { createClientConfig } from "./hey-api.js";
+import { toEngineRequestError } from "./engine-error.js";
+/** Default per-request deadline for engine calls (`timeoutMs`). */
+export const DEFAULT_ENGINE_TIMEOUT_MS = 30_000;
+/** The largest delay a Node timer holds; a longer one would fire immediately. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+function buildAuthHeader(options) {
+    const { authType = "none", username, password, token } = options;
+    if (authType === "basic" && username && password) {
+        const encoded = typeof btoa === "function"
+            ? btoa(`${username}:${password}`)
+            : Buffer.from(`${username}:${password}`).toString("base64");
+        return { Authorization: `Basic ${encoded}` };
+    }
+    if (authType === "bearer" && token) {
+        return { Authorization: `Bearer ${token}` };
+    }
+    // "passthrough" deliberately sets no static header: the per-request
+    // interceptor below owns the Authorization header instead.
+    return {};
+}
+/** The remedy a 401 message names: it depends on where the credential came from. */
+function unauthorizedHint(options) {
+    switch (options.authType ?? "none") {
+        case "passthrough":
+            return options.tokenProvider?.()
+                ? "The engine rejected the forwarded bearer token."
+                : "The MCP request carried no bearer token to pass through.";
+        case "none":
+            return "The engine requires authentication, but none is configured.";
+        default:
+            return "The engine rejected the configured credentials.";
+    }
+}
+function resolveTimeout(timeoutMs) {
+    if (timeoutMs === undefined)
+        return DEFAULT_ENGINE_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new RangeError(`Engine request timeout must be a positive integer of at most ${MAX_TIMEOUT_MS} ms, got ${timeoutMs}`);
+    }
+    return timeoutMs;
+}
+/**
+ * The credentials a request carried, for masking in error text (an engine or
+ * proxy may quote them back): the configured password/token and whatever the
+ * request's own `Authorization` header holds (the Basic value, a static or a
+ * passed-through bearer token).
+ */
+function credentialsOf(options, request) {
+    const authorization = request?.headers.get("Authorization") ?? undefined;
+    return [options.password, options.token, authorization?.replace(/^\S+\s+/, "")];
+}
+/**
+ * Per-engine client factory. All defaults (JSON content negotiation headers,
+ * `throwOnError`, `responseStyle`) come from `createClientConfig` in
+ * src/hey-api.ts (the same function the generated default client uses), so
+ * runtime behavior and the generated SDK types stay in sync.
+ *
+ * Every client, whatever its auth type, carries a per-request deadline in its
+ * `fetch` (combined with a caller `signal`, see {@link withCallerSignal}) and
+ * an error interceptor that maps every failure to an `EngineRequestError`
+ * (status, exception type, engine message, engine id; credentials masked).
+ *
+ * The deadline binds the request as it LEAVES (after every request
+ * interceptor), so an interceptor that returns a new `Request` can neither
+ * detach it nor disguise it as a cancellation. A custom `fetch` (per call or
+ * via `setConfig`) replaces the deadline with it: wrap
+ * `client.getConfig().fetch` instead. Request interceptors should mutate the
+ * request (`request.headers.set(…)`); one that returns a new `Request` keeps
+ * the deadline, but the caller's signal reaches the new request only through
+ * the dropped one (undici follows signals via a `WeakRef`), so after a
+ * garbage collection a cancelled call runs on until the deadline.
+ */
+export function createEngineClient(options) {
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+    // Keyed by the request hey-api sends, i.e. the one its error interceptors
+    // receive: tells OUR deadline from a caller's cancellation, and keeps the
+    // timer alive exactly as long as hey-api holds that request (body read
+    // included).
+    const deadlines = new WeakMap();
+    const fetchWithDeadline = (request) => {
+        const deadline = AbortSignal.timeout(timeoutMs);
+        deadlines.set(request, deadline);
+        return fetch(request, { signal: AbortSignal.any([request.signal, deadline]) });
+    };
+    const client = createClient(createClientConfig({
+        baseUrl: options.baseUrl,
+        headers: buildAuthHeader(options),
+        // hey-api calls its `fetch` with the finished Request only.
+        fetch: fetchWithDeadline,
+        // Redirects are FOLLOWED, hey-api's own default, stated so the difference shows: the CLI
+        // and the VS Code extension send `redirect: "manual"` (a followed 302/303 turns a write
+        // into a GET). One policy for all three is a behaviour change of its own.
+        redirect: "follow",
+    }));
+    if (options.authType === "passthrough" && options.tokenProvider) {
+        const { tokenProvider } = options;
+        // Not the hey-api `auth` option: the generated operations all declare the
+        // `basic` security scheme, so `auth` would base64-mangle a bearer token.
+        // The interceptor must only ever touch Authorization: the multipart
+        // operations rely on an absent Content-Type for the boundary parameter.
+        client.interceptors.request.use((request) => {
+            const token = tokenProvider();
+            if (token) {
+                request.headers.set("Authorization", `Bearer ${token}`);
+            }
+            return request;
+        });
+    }
+    // Always on: hey-api throws the parsed error BODY (an ExceptionDto object,
+    // the text, or `{}`), which the model would read as "[object Object]".
+    client.interceptors.error.use((error, response, request) => toEngineRequestError(error, {
+        response,
+        request,
+        engineId: options.engineId,
+        timeoutMs,
+        timedOut: request ? deadlines.get(request)?.aborted === true : false,
+        unauthorizedHint: response?.status === 401 ? unauthorizedHint(options) : undefined,
+        secrets: credentialsOf(options, request),
+    }));
+    return client;
+}
+/** The methods a caller's cancellation may abort: reads, never writes. */
+const CANCELLABLE_METHODS = ["get", "head", "options"];
+/**
+ * A view of `client` whose READS honor the caller's `signal` (an MCP
+ * request's `ctx.signal`, aborted when the MCP client cancels or
+ * disconnects), on top of the client's own deadline. Writes never see it:
+ * aborting a started write cannot roll it back on the engine, it only turns
+ * a known outcome into an unknown one. An explicit per-call `signal` wins.
+ * Without a signal the client itself is returned.
+ */
+export function withCallerSignal(client, signal) {
+    if (!signal)
+        return client;
+    const bound = { ...client };
+    for (const method of CANCELLABLE_METHODS) {
+        const call = client[method];
+        bound[method] = ((callOptions) => call({ ...callOptions, signal: callOptions.signal ?? signal }));
+    }
+    return bound;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/engine-contract/batches.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Batches. A batch write (`POST /job/retries`, `POST /migration/executeAsync`)
+ * returns as soon as the engine has QUEUED the batch: the work and its
+ * failures happen later, in batch jobs. A tool must therefore never report
+ * the queued batch as done: it hands back the batch id with status `queued`,
+ * and `engine_get_batch` reports what became of it.
+ */
+import type { BatchDto, BatchStatisticsDto, HistoricBatchDto } from "../generated/types.gen.js";
+/** What a batch write returns: the id to follow up on, never a success flag. */
+export interface QueuedBatch {
+    batchId: string;
+    status: "queued";
+    /** Engine batch type, e.g. `set-job-retries`, `instance-migration`. */
+    type: string | null;
+    totalJobs: number | null;
+}
+export declare function queuedBatch(batch: BatchDto): QueuedBatch;
+/**
+ * - `running`: batch jobs are still being created or executed;
+ * - `failing`: some batch jobs ran out of retries, so the batch cannot finish
+ *   until they are retried or the batch is deleted;
+ * - `suspended`: suspended, nothing executes;
+ * - `completed`: the batch ended (all jobs done, or it was deleted).
+ */
+export type BatchStatus = "running" | "failing" | "suspended" | "completed";
+export interface BatchReport {
+    batchId: string;
+    type: string | null;
+    status: BatchStatus;
+    totalJobs: number | null;
+    /** Runtime counts, null once the batch has ended. */
+    remainingJobs: number | null;
+    completedJobs: number | null;
+    failedJobs: number | null;
+    startTime: string | null;
+    endTime: string | null;
+}
+export declare function runningBatchReport(stats: BatchStatisticsDto): BatchReport;
+/** A batch the runtime no longer holds, from its history record. */
+export declare function endedBatchReport(batch: HistoricBatchDto): BatchReport;
+//# sourceMappingURL=batches.d.ts.map

package/dist/engine-contract/batches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.d.ts","sourceRoot":"","sources":["../../src/engine-contract/batches.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAE/F,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,QAAQ,CAAA;IAChB,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAOxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAA;AAE3E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,WAAW,CAAA;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,qDAAqD;IACrD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,WAAW,CAczE;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAarE"}

package/dist/engine-contract/batches.js

@@ -0,0 +1,39 @@
+export function queuedBatch(batch) {
+    return {
+        batchId: batch.id ?? "",
+        status: "queued",
+        type: batch.type ?? null,
+        totalJobs: batch.totalJobs ?? null,
+    };
+}
+export function runningBatchReport(stats) {
+    const failedJobs = stats.failedJobs ?? 0;
+    const status = stats.suspended ? "suspended" : failedJobs > 0 ? "failing" : "running";
+    return {
+        batchId: stats.id ?? "",
+        type: stats.type ?? null,
+        status,
+        totalJobs: stats.totalJobs ?? null,
+        remainingJobs: stats.remainingJobs ?? null,
+        completedJobs: stats.completedJobs ?? null,
+        failedJobs,
+        startTime: stats.startTime ?? null,
+        endTime: null,
+    };
+}
+/** A batch the runtime no longer holds, from its history record. */
+export function endedBatchReport(batch) {
+    return {
+        batchId: batch.id ?? "",
+        type: batch.type ?? null,
+        // A historic batch without endTime is one the runtime query just missed.
+        status: batch.endTime ? "completed" : "running",
+        totalJobs: batch.totalJobs ?? null,
+        remainingJobs: null,
+        completedJobs: null,
+        failedJobs: null,
+        startTime: batch.startTime ?? null,
+        endTime: batch.endTime ?? null,
+    };
+}
+//# sourceMappingURL=batches.js.map

package/dist/engine-contract/batches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.js","sourceRoot":"","sources":["../../src/engine-contract/batches.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;QACvB,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;KACnC,CAAA;AACH,CAAC;AAwBD,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAA;IACxC,MAAM,MAAM,GAAgB,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;IAClG,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;QACvB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;QACxB,MAAM;QACN,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;QAC1C,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;QAC1C,UAAU;QACV,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,OAAO,EAAE,IAAI;KACd,CAAA;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,KAAuB;IACtD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;QACvB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;QACxB,yEAAyE;QACzE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;QAC/C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,aAAa,EAAE,IAAI;QACnB,aAAa,EAAE,IAAI;QACnB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;KAC/B,CAAA;AACH,CAAC"}

package/dist/engine-contract/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The engine contract's SDK-bound half: the reads whose REST contract differs from the client
+ * defaults (text-only endpoints, raw variable reads, the batch fallback) and the batch status.
+ * The pure rules (dates, filters, sorting, variable writes, incident recovery) live in
+ * `@miragon/pulse-engine-core`; this package stays a leaf and does not import it. The engine
+ * module's tools (`tools/`) and widget feeds (`data/`) take both from there (CLAUDE.md
+ * invariant 7).
+ */
+export { endedBatchReport, queuedBatch, runningBatchReport, type BatchReport, type BatchStatus, type QueuedBatch, } from "./batches.js";
+export { fetchExternalTaskErrorDetails, fetchJobStacktrace, readBatch, readProcessInstanceVariables, readTaskVariables, type VariableMap, } from "./reads.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/engine-contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine-contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,SAAS,EACT,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAA"}

package/dist/engine-contract/index.js

@@ -0,0 +1,11 @@
+/**
+ * The engine contract's SDK-bound half: the reads whose REST contract differs from the client
+ * defaults (text-only endpoints, raw variable reads, the batch fallback) and the batch status.
+ * The pure rules (dates, filters, sorting, variable writes, incident recovery) live in
+ * `@miragon/pulse-engine-core`; this package stays a leaf and does not import it. The engine
+ * module's tools (`tools/`) and widget feeds (`data/`) take both from there (CLAUDE.md
+ * invariant 7).
+ */
+export { endedBatchReport, queuedBatch, runningBatchReport, } from "./batches.js";
+export { fetchExternalTaskErrorDetails, fetchJobStacktrace, readBatch, readProcessInstanceVariables, readTaskVariables, } from "./reads.js";
+//# sourceMappingURL=index.js.map

package/dist/engine-contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine-contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GAInB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,SAAS,EACT,4BAA4B,EAC5B,iBAAiB,GAElB,MAAM,YAAY,CAAA"}

package/dist/engine-contract/reads.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Engine reads whose REST contract differs from the client defaults, the
+ * ONE place `tools/` and `data/` take them from, so no call site can forget
+ * the override:
+ *
+ * - Text endpoints (`/job/{id}/stacktrace`, `/external-task/{id}/errorDetails`)
+ *   produce ONLY `text/plain` and answer the client's default
+ *   `Accept: application/json` with a 406 before the resource runs.
+ * - Runtime variable reads default to `deserializeValues=true`: the engine
+ *   then deserializes every Object variable eagerly (one class missing on its
+ *   classpath fails the WHOLE read with a 500) and renders Json variables as
+ *   Jackson's view of the Spin node instead of their JSON. With `false`,
+ *   Object/Json/Xml values come back as their serialized string + `valueInfo`,
+ *   exactly the shape a variable write takes back.
+ */
+import type { Client } from "../generated/client/types.gen.js";
+import type { VariableValueDto } from "../generated/types.gen.js";
+import { type BatchReport } from "./batches.js";
+export type VariableMap = Record<string, VariableValueDto>;
+/**
+ * The exception stacktrace of a job; `null` when the job has none or no
+ * longer exists (404). Every other failure throws: the caller decides
+ * whether a missing stacktrace may degrade.
+ */
+export declare function fetchJobStacktrace(client: Client, jobId: string): Promise<string | null>;
+/**
+ * The error details a worker reported for an external task (its
+ * `failedExternalTask` stacktrace); `null` when there are none or the task no
+ * longer exists (404). Every other failure throws.
+ */
+export declare function fetchExternalTaskErrorDetails(client: Client, externalTaskId: string): Promise<string | null>;
+/** All variables of a process instance, serialized (see the module doc). */
+export declare function readProcessInstanceVariables(client: Client, processInstanceId: string): Promise<VariableMap>;
+/** All variables visible from a task, serialized (see the module doc). */
+export declare function readTaskVariables(client: Client, taskId: string): Promise<VariableMap>;
+/**
+ * Where a batch stands: the runtime statistics while it exists (counts incl.
+ * failed batch jobs), its history record once it ended. A batch neither
+ * holds is reported as an error: it never existed, or ended on an engine
+ * without batch history.
+ */
+export declare function readBatch(client: Client, batchId: string): Promise<BatchReport>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/engine-contract/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/engine-contract/reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAA;AAS9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAEjE,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAYrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAiB1D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO9F;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC,CAMtB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAYrF"}

package/dist/engine-contract/reads.js

@@ -0,0 +1,86 @@
+import { getBatchStatistics, getExternalTaskErrorDetails, getHistoricBatch, getProcessInstanceVariables, getStacktrace, getTaskVariables, } from "../generated/sdk.gen.js";
+import { EngineRequestError } from "../engine-error.js";
+import { endedBatchReport, runningBatchReport } from "./batches.js";
+/** Request options for a `text/plain`-only endpoint. */
+const TEXT_PLAIN = { parseAs: "text", headers: { Accept: "text/plain" } };
+/**
+ * The query the variable reads send. The rule's home is engine-core's `RAW_VARIABLES`; this leaf
+ * does not import engine-core, so its SDK reads restate the flag (the engine connector's wire
+ * tests hold every variable read to `deserializeValues=false`).
+ */
+const RAW_VARIABLES = { deserializeValues: false };
+/**
+ * The client's "missing" rule: EVERY 404. Broader than engine-core's `isMissing`, which leaves
+ * out a 404 of the JAX-RS `NotFoundException` (no such endpoint: a wrong REST root) and of
+ * `QueryParamException`; so here a wrong REST root reads as "none". Kept as it is in a refactor:
+ * one rule for both is a behaviour change of its own.
+ */
+function isAnyNotFound(error) {
+    return error instanceof EngineRequestError && error.httpStatus === 404;
+}
+/** Engine text, `null` for an empty body (204, or a resource without one). */
+function textOrNull(text) {
+    return typeof text === "string" && text.length > 0 ? text : null;
+}
+/**
+ * The exception stacktrace of a job; `null` when the job has none or no
+ * longer exists (404). Every other failure throws: the caller decides
+ * whether a missing stacktrace may degrade.
+ */
+export async function fetchJobStacktrace(client, jobId) {
+    try {
+        return textOrNull(await getStacktrace({ client, path: { id: jobId }, ...TEXT_PLAIN }));
+    }
+    catch (error) {
+        if (isAnyNotFound(error))
+            return null;
+        throw error;
+    }
+}
+/**
+ * The error details a worker reported for an external task (its
+ * `failedExternalTask` stacktrace); `null` when there are none or the task no
+ * longer exists (404). Every other failure throws.
+ */
+export async function fetchExternalTaskErrorDetails(client, externalTaskId) {
+    try {
+        return textOrNull(await getExternalTaskErrorDetails({ client, path: { id: externalTaskId }, ...TEXT_PLAIN }));
+    }
+    catch (error) {
+        if (isAnyNotFound(error))
+            return null;
+        throw error;
+    }
+}
+/** All variables of a process instance, serialized (see the module doc). */
+export function readProcessInstanceVariables(client, processInstanceId) {
+    return getProcessInstanceVariables({
+        client,
+        path: { id: processInstanceId },
+        query: RAW_VARIABLES,
+    });
+}
+/** All variables visible from a task, serialized (see the module doc). */
+export function readTaskVariables(client, taskId) {
+    return getTaskVariables({ client, path: { id: taskId }, query: RAW_VARIABLES });
+}
+/**
+ * Where a batch stands: the runtime statistics while it exists (counts incl.
+ * failed batch jobs), its history record once it ended. A batch neither
+ * holds is reported as an error: it never existed, or ended on an engine
+ * without batch history.
+ */
+export async function readBatch(client, batchId) {
+    const running = await getBatchStatistics({ client, query: { batchId } });
+    if (Array.isArray(running) && running[0])
+        return runningBatchReport(running[0]);
+    try {
+        return endedBatchReport(await getHistoricBatch({ client, path: { id: batchId } }));
+    }
+    catch (error) {
+        if (!isAnyNotFound(error))
+            throw error;
+        throw new Error(`Batch ${batchId} not found: no running batch has this id and the engine history holds no record of it`, { cause: error });
+    }
+}
+//# sourceMappingURL=reads.js.map

package/dist/engine-contract/reads.js.map

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

package/dist/engine-error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Typed engine-call failures. hey-api throws whatever the engine sent (the
+ * parsed `ExceptionDto` object for a JSON error body, the raw text otherwise,
+ * `{}` for an empty body) and a bare `TypeError("fetch failed")` for network
+ * failures. None of that is an `Error` carrying a readable message, so every
+ * engine 4xx/5xx used to reach the model as "[object Object]". The client's
+ * always-on error interceptor ([[createEngineClient]]) funnels every failure
+ * through {@link toEngineRequestError} instead.
+ */
+/**
+ * What went wrong: an engine error response, no connection to the engine, a
+ * connection that failed mid-request, the deadline, or the caller.
+ */
+export type EngineFailureKind = "http" | "unreachable" | "connection" | "timeout" | "cancelled";
+/**
+ * An engine call that failed, with a model-actionable `message`:
+ *
+ * - `[404 InvalidRequestException] Process instance with id x does not exist (engine prod-a)`
+ * - `[500] Internal Server Error — empty response body (engine prod-a)`
+ * - `engine prod-a unreachable (ECONNREFUSED)`
+ * - `connection to engine prod-a failed (UND_ERR_SOCKET) — the POST may still have been applied; …`
+ * - `engine prod-a did not respond within 30000 ms (timeout)`
+ *
+ * The HTTP status is `httpStatus`, deliberately NOT `status` (and the
+ * engine's numeric error code is `engineCode`, not `code`): widget-shell's
+ * `withToolErrors` prefixes any `status`/`code` property as `[…] `, which
+ * would print the status twice. The message is complete on its own.
+ */
+export declare class EngineRequestError extends Error {
+    readonly kind: EngineFailureKind;
+    /** HTTP status of the engine's error response; `undefined` when none arrived. */
+    readonly httpStatus?: number;
+    /** The engine's exception class (`ExceptionDto.type`), e.g. `InvalidRequestException`. */
+    readonly type?: string;
+    /** The engine's own message (or the truncated body / failure detail), undecorated. */
+    readonly engineMessage: string;
+    /** The engine's numeric error code (`ExceptionDto.code`), when it sent one. */
+    readonly engineCode?: number;
+    /** Id of the configured engine the request went to, when the client knows it. */
+    readonly engineId?: string;
+    constructor(message: string, details: {
+        kind: EngineFailureKind;
+        engineMessage: string;
+        httpStatus?: number;
+        type?: string;
+        engineCode?: number;
+        engineId?: string;
+        cause?: unknown;
+    });
+}
+export interface EngineErrorContext {
+    /** The engine's error response; `undefined` when none arrived. */
+    response?: Response;
+    /** The request as sent (after the client's own interceptors). */
+    request?: Request;
+    /** Engine id for the message suffix; omitted when unknown. */
+    engineId?: string;
+    /** The per-request deadline, for the timeout message. */
+    timeoutMs: number;
+    /** Whether THIS client's deadline (not a caller signal) aborted the request. */
+    timedOut: boolean;
+    /** Appended as a sentence to 401 messages (auth-type-specific remedy). */
+    unauthorizedHint?: string;
+    /** Credentials the request carried, masked wherever engine text is echoed. */
+    secrets?: ReadonlyArray<string | undefined>;
+}
+/**
+ * Maps whatever a failed engine call threw to an {@link EngineRequestError}.
+ * Errors that are none of these kinds (e.g. a request that could not even be
+ * built) pass through unchanged: they already carry their own message.
+ */
+export declare function toEngineRequestError(error: unknown, ctx: EngineErrorContext): unknown;
+//# sourceMappingURL=engine-error.d.ts.map

package/dist/engine-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-error.d.ts","sourceRoot":"","sources":["../src/engine-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAA;AAQ/F;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,sFAAsF;IACtF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;gBAGxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,IAAI,EAAE,iBAAiB,CAAA;QACvB,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAWJ;AAiFD,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAC5C;AAoGD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAgBrF"}