@pipelex/sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,884 @@
+import { pollUntilResult, } from "./runs.js";
+import { ApiResponseError, ApiUnreachableError, PipelineExecuteTimeoutError, PipelineRequestError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
+/** Hosted default — the client composes every endpoint as `{base}/v1/{endpoint}`. */
+export const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
+// The client composes every endpoint from one origin (PIPELEX_API_URL): `{base}/v1/{endpoint}`.
+// The same paths are served by the Pipelex Hosted API (api.pipelex.com) and by a bare
+// OSS pipelex-api runner (localhost:8081) — the protocol surface is identical; only
+// the hosted extensions (e.g. run polling) differ, detectable via GET /v1/version.
+const API_PREFIX = "v1";
+const RUNS = "runs";
+const DEFAULT_REQUEST_TIMEOUT_MS = 1_200_000; // 20 min — matches the runner's blocking execute ceiling.
+const POLL_REQUEST_TIMEOUT_MS = 30_000; // single status/result GETs; the hosted gateway caps responses at ~30s.
+const DEFAULT_DEGRADED_RETRY_SECONDS = 5; // matches the platform's `_DEGRADE_RETRY_AFTER_SECONDS`.
+const VALIDATE_MARKDOWN_RENDER_FORMAT = "markdown";
+/**
+ * `VersionInfo.implementation` of the bare open-source runner (no run store).
+ * Anything else — the hosted `pipelex-hosted` first — is assumed to serve the
+ * durable run-lifecycle extension; a wrong guess still fails with the clear
+ * `RunLifecycleUnavailableError` on the first poll.
+ */
+const BARE_RUNNER_IMPLEMENTATION = "pipelex-api";
+/**
+ * Client for the Pipelex hosted API — and any MTHDS-compliant runner.
+ *
+ * One base URL (`PIPELEX_API_URL`); every endpoint is `<base>/v1/<endpoint>`:
+ * - **protocol** (`execute` / `start` / `validate` / `models` / `version`) — works
+ *   against any MTHDS-compliant runner, hosted or bare.
+ * - **build extensions** (`/v1/build/*`) — the Pipelex API's authoring helpers.
+ * - **run lifecycle** (`getRunStatus` / `getRunResult` / `waitForResult`) — the
+ *   durable polling extension that survives long runs and lets a caller resume by
+ *   id. Served only by a deployment that includes the platform block (the Pipelex
+ *   Hosted API); a bare `pipelex-api` runner 404s those routes, which the lifecycle
+ *   methods translate into a clear `RunLifecycleUnavailableError`.
+ *
+ * Implements `MTHDSProtocol<DictPipeOutput>` so the protocol-execution methods
+ * stay shaped like the standard's wire surface (`mthds/protocol`). The Pipelex
+ * extensions (build, run lifecycle) ride on top.
+ */
+export class PipelexApiClient {
+    apiToken;
+    baseUrl;
+    /** Origin root derived from the base URL — `/health` lives here, not under `/v1`. */
+    originUrl;
+    /** Cached `/v1/version` handshake outcome — whether the durable lifecycle is served. */
+    lifecycleAvailable;
+    constructor(options = {}) {
+        this.apiToken = options.apiToken ?? process.env.PIPELEX_API_KEY;
+        const normalizedBaseUrl = (options.baseUrl ??
+            process.env.PIPELEX_API_URL ??
+            DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+        // The base URL must be host-only: direct SDK usage and PIPELEX_API_URL reach
+        // this constructor and must be held to that rule, or a path-prefixed value
+        // (e.g. `.../v1`) composes as `/v1/v1/...` and fails with a misleading
+        // endpoint error instead of a clear base-URL one. Trailing slashes are
+        // stripped first; a remaining path/query/fragment/credentials is rejected.
+        if (!isValidBaseUrl(normalizedBaseUrl)) {
+            throw new PipelineRequestError(`Invalid API base URL "${normalizedBaseUrl}": must be host-only ` +
+                `(http/https, no path, query, fragment, or credentials). Endpoints ` +
+                `compose as {base}/v1/{endpoint}.`);
+        }
+        this.baseUrl = normalizedBaseUrl;
+        this.originUrl = new URL("/", this.baseUrl).origin;
+    }
+    // ── URL resolution ───────────────────────────────────────────────────
+    /** Build an API URL: `<base>/v1/<endpoint>`. */
+    url(endpoint) {
+        return `${this.baseUrl}/${API_PREFIX}/${endpoint.replace(/^\/+/, "")}`;
+    }
+    // ── Transport ──────────────────────────────────────────────────────
+    /**
+     * Issue one HTTP request and return the raw status/headers/body. Wraps
+     * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
+     * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
+     * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
+     * resolved absolute URL.
+     */
+    async requestRaw(method, url, options = {}) {
+        const headers = { Accept: "application/json" };
+        if (this.apiToken) {
+            headers["Authorization"] = `Bearer ${this.apiToken}`;
+        }
+        const hasBody = options.body !== undefined;
+        if (hasBody) {
+            headers["Content-Type"] = "application/json";
+        }
+        const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException("Request timed out.", "TimeoutError")), timeoutMs);
+        const userSignal = options.signal;
+        const onUserAbort = () => controller.abort(userSignal?.reason);
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort(userSignal.reason);
+            else
+                userSignal.addEventListener("abort", onUserAbort, { once: true });
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: hasBody ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // A caller-initiated abort (not our timeout) propagates untouched so
+            // `waitForResult` callers can distinguish "I stopped waiting" from a
+            // network failure.
+            if (userSignal?.aborted)
+                throw err;
+            // undici (Node fetch) wraps DNS/connect/TLS failures as
+            // `TypeError("fetch failed")` with the system error attached as `cause`.
+            // Our timeout aborts the controller with a "TimeoutError" DOMException.
+            const code = extractNetworkErrorCode(err);
+            throw new ApiUnreachableError(`Could not reach Pipelex API at ${this.baseUrl} (${code ?? "network error"})`, this.baseUrl, code, { cause: err });
+        }
+        finally {
+            clearTimeout(timer);
+            if (userSignal)
+                userSignal.removeEventListener("abort", onUserAbort);
+        }
+        const body = await response.text().catch(() => "");
+        return {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            body,
+        };
+    }
+    /**
+     * Issue a request and parse the JSON body, throwing a plain `Error` on a
+     * non-2xx response. Used by the build extensions and `health` — surfaces
+     * that don't need the protocol's structured error taxonomy.
+     */
+    async requestJson(method, url, body) {
+        const headers = { Accept: "application/json" };
+        if (this.apiToken) {
+            headers["Authorization"] = `Bearer ${this.apiToken}`;
+        }
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`API ${method} ${url} failed (${res.status}): ${text || res.statusText}`);
+        }
+        return res.json();
+    }
+    postApi(path, body) {
+        return this.requestJson("POST", this.url(path), body);
+    }
+    /**
+     * Issue a Pipelex-product request (`/v1/me`, `/v1/methods`, `/v1/billing/*`,
+     * …) and parse its JSON body, mapping a non-2xx response to the typed
+     * `ApiResponseError` so callers branch on the structured `code` discriminant,
+     * not the HTTP status. Empty-body tolerant — DELETE / onboarding / updateRun
+     * answer 2xx with no body, returned as `undefined`. Uses the management-call
+     * timeout, not the blocking-execute ceiling.
+     */
+    async requestProduct(method, endpoint, body, options = {}) {
+        const res = await this.requestRaw(method, this.url(endpoint), {
+            body,
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+            signal: options.signal,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError(method, endpoint, res);
+        }
+        return (res.body ? JSON.parse(res.body) : undefined);
+    }
+    throwApiResponseError(method, endpoint, res) {
+        const { errorType, serverMessage, validationErrors, code } = parseErrorBody(res.body);
+        throw new ApiResponseError(`API ${method} /${API_PREFIX}/${endpoint} failed (${res.status}): ${serverMessage ?? (res.body || res.statusText)}`, this.baseUrl, res.status, res.statusText, res.body, errorType, serverMessage, validationErrors, code);
+    }
+    /**
+     * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
+     * into a clear `RunLifecycleUnavailableError`. The platform's own 404s (run
+     * not found / cross-org) carry a structured error envelope (a `code` field)
+     * and are left for normal handling.
+     */
+    throwIfLifecycleUnavailable(res, url) {
+        if (res.status !== 404)
+            return;
+        if (!isMissingRoute404(res.body))
+            return;
+        throw new RunLifecycleUnavailableError(`The durable run lifecycle is not available: ${url} returned 404. Run polling is a ` +
+            `hosted-API extension (/${API_PREFIX}/${RUNS}/*), not part of the MTHDS Protocol; ` +
+            "PIPELEX_API_URL points at a bare runner that does not serve it.", this.baseUrl);
+    }
+    /**
+     * Map the protocol's optional 202 execute degrade to a typed
+     * error. Hosted does not emit 202 today, but the protocol permits it;
+     * raising a typed error (with the `pipeline_run_id` + `Location` + `Retry-After`
+     * hints) beats a generic parse failure on an unexpected body shape.
+     */
+    throwIfExecuteDegraded(res) {
+        if (res.status !== 202)
+            return;
+        let runId = "";
+        try {
+            const parsed = JSON.parse(res.body);
+            if (parsed && typeof parsed === "object") {
+                const candidate = parsed.pipeline_run_id;
+                if (typeof candidate === "string")
+                    runId = candidate;
+            }
+        }
+        catch {
+            // Non-JSON 202 body — keep runId empty; the error message covers it.
+        }
+        throw new RunStillRunningError(`execute() was accepted asynchronously (202): run ${runId || "<unknown>"} is still ` +
+            "running server-side. Poll its results (hosted) or use start().", runId, parseRetryAfter(res.headers), res.headers.get("location"));
+    }
+    // ── Health ────────────────────────────────────────────────────────
+    async health() {
+        // `/health` is origin-level, NOT under the `/v1` prefix.
+        return this.requestJson("GET", `${this.originUrl}/health`);
+    }
+    // ── Protocol surface ─────────────────────────────────────────────────
+    /**
+     * Execute a method synchronously and wait for its completion —
+     * `POST /v1/execute`.
+     *
+     * Behind the hosted gateway, synchronous requests terminate at ~30s; a run
+     * that exceeds that surfaces as `PipelineExecuteTimeoutError` pointing at the
+     * durable start+poll path. Throws `RunStillRunningError` on the protocol's
+     * optional 202 degrade.
+     */
+    async execute(options) {
+        const extensions = buildExtensions(options.extra);
+        if (!options.pipe_code &&
+            (!options.mthds_contents || options.mthds_contents.length === 0) &&
+            Object.keys(extensions).length === 0) {
+            throw new PipelineRequestError("Either pipe_code, mthds_contents or a server-specific extension arg (extra) must be provided to execute().");
+        }
+        const request = {
+            pipe_code: options.pipe_code,
+            mthds_contents: options.mthds_contents,
+            inputs: options.inputs,
+            output_name: options.output_name,
+            output_multiplicity: options.output_multiplicity,
+            dynamic_output_concept_ref: options.dynamic_output_concept_ref,
+            ...extensions,
+        };
+        const startedAt = Date.now();
+        try {
+            const res = await this.requestRaw("POST", this.url("execute"), {
+                body: request,
+            });
+            this.throwIfExecuteDegraded(res);
+            if (res.status < 200 || res.status >= 300) {
+                this.throwApiResponseError("POST", "execute", res);
+            }
+            return JSON.parse(res.body);
+        }
+        catch (err) {
+            if (err instanceof RunStillRunningError)
+                throw err;
+            // The hosted gateway terminates synchronous requests at ~30s. A run that
+            // exceeds that comes back as a gateway 503/504 (or a client abort) —
+            // translate it into a clear, actionable error pointing at start+poll.
+            const elapsedMs = Date.now() - startedAt;
+            if (isGatewayTimeout(err, elapsedMs)) {
+                throw new PipelineExecuteTimeoutError(elapsedMs, { cause: err });
+            }
+            throw err;
+        }
+    }
+    /**
+     * Start a method asynchronously — `POST /v1/start` (202, no output yet).
+     *
+     * Server-specific extension args ride `options.extra` and merge into the
+     * request body — the server you call defines and handles them (including a
+     * client-supplied run id where a server supports one). The returned
+     * `pipeline_run_id` is always authoritative; on a hosted deployment it is
+     * durable — poll `getRunStatus` / `getRunResult`.
+     */
+    async start(options) {
+        const extensions = buildExtensions(options.extra);
+        if (!options.pipe_code &&
+            (!options.mthds_contents || options.mthds_contents.length === 0) &&
+            Object.keys(extensions).length === 0) {
+            throw new PipelineRequestError("Either pipe_code, mthds_contents or a server-specific extension arg (extra) must be provided to start().");
+        }
+        // `?? undefined` so JSON.stringify drops absent fields from the wire body.
+        const request = {
+            pipe_code: options.pipe_code ?? undefined,
+            mthds_contents: options.mthds_contents ?? undefined,
+            inputs: options.inputs ?? undefined,
+            output_name: options.output_name ?? undefined,
+            output_multiplicity: options.output_multiplicity ?? undefined,
+            dynamic_output_concept_ref: options.dynamic_output_concept_ref ?? undefined,
+            ...extensions,
+        };
+        const url = this.url("start");
+        const res = await this.requestRaw("POST", url, {
+            body: request,
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+        });
+        // A bare runner with no run store 404s here just as it does on the result
+        // routes — surface the same clear `RunLifecycleUnavailableError` (and let
+        // `startAndWaitForResult` fall back to the blocking `execute`).
+        this.throwIfLifecycleUnavailable(res, url);
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("POST", "start", res);
+        }
+        return JSON.parse(res.body);
+    }
+    /**
+     * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
+     *
+     * `/validate` is a diagnostic endpoint: every produced verdict rides a **200**,
+     * discriminated on `is_valid`. This returns the `PipelexValidationResult` union
+     * verbatim — `is_valid: true` ⇒ the typed `PipelexValidationReport` (structural
+     * artifacts), `is_valid: false` ⇒ a `PipelexInvalidReport` (`validation_errors[]`).
+     * An invalid bundle is NOT thrown — the caller pattern-matches `is_valid`. Only a
+     * *no-verdict* condition (a malformed request, an `mthds_sources` length mismatch,
+     * auth, a server fault) is non-2xx and surfaces as `ApiResponseError`.
+     *
+     * `mthdsSources` (optional, parallel to `mthdsContents`) names each submitted
+     * content — a Pipelex-API extension threaded onto `blueprint.source`, so
+     * cross-file diagnostics name the owning file (an unnamed content yields
+     * `source: null`). The server 422s a length mismatch; this client sends the
+     * arrays verbatim and surfaces that as an `ApiResponseError`.
+     *
+     * `render` is the Pipelex-API presentation hint — a list of view-format tokens.
+     * This client always asks for Markdown so both valid results and produced
+     * validation-error verdicts carry `rendered_markdown`; callers may add more
+     * tokens. Unknown tokens are server-side lenient-ignored (never a 422).
+     */
+    async validate(mthdsContents, allowSignatures = false, mthdsSources, render) {
+        const body = {
+            mthds_contents: mthdsContents,
+            allow_signatures: allowSignatures,
+        };
+        if (mthdsSources !== undefined) {
+            body.mthds_sources = mthdsSources;
+        }
+        body.render = withValidateMarkdownRender(render);
+        const res = await this.requestRaw("POST", this.url("validate"), { body });
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("POST", "validate", res);
+        }
+        return JSON.parse(res.body);
+    }
+    /**
+     * Validate paired MTHDS files while preserving URI attribution for diagnostics.
+     *
+     * This adapter intentionally keeps the low-level `validate(...)` payload shape
+     * intact for existing consumers. When any file has a URI, every content gets a
+     * parallel source label; inline labels are deterministic so the server never
+     * sees a length-mismatched `mthds_sources` array.
+     */
+    async validateFiles(files, options = {}) {
+        if (files.length === 0) {
+            throw new PipelineRequestError("At least one MTHDS file must be provided to validateFiles().");
+        }
+        const mthdsContents = files.map((file) => file.content);
+        const hasAnyUri = files.some((file) => file.uri !== undefined);
+        const mthdsSources = hasAnyUri
+            ? files.map((file, index) => file.uri ?? `inline://file-${index + 1}.mthds`)
+            : undefined;
+        return this.validate(mthdsContents, options.allowSignatures ?? false, mthdsSources, options.render);
+    }
+    /** The model deck the runner can route to — `GET /v1/models[?type=]`. */
+    async models(category) {
+        const endpoint = category ? `models?type=${encodeURIComponent(category)}` : "models";
+        const res = await this.requestRaw("GET", this.url(endpoint), {
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("GET", endpoint, res);
+        }
+        return JSON.parse(res.body);
+    }
+    /**
+     * Protocol + implementation versions — `GET /v1/version` (always public).
+     * The handshake for feature detection (hosted extensions or not).
+     */
+    async version() {
+        const res = await this.requestRaw("GET", this.url("version"), {
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("GET", "version", res);
+        }
+        return JSON.parse(res.body);
+    }
+    // ── Build extensions (Pipelex API layer 2 — `/v1/build/*`) ────────
+    async buildInputs(request) {
+        return this.postApi("build/inputs", request);
+    }
+    async buildOutput(request) {
+        return this.postApi("build/output", request);
+    }
+    async buildRunner(request) {
+        return this.postApi("build/runner", request);
+    }
+    async concept(request) {
+        return this.postApi("build/concept", request);
+    }
+    async pipeSpec(request) {
+        return this.postApi("build/pipe-spec", request);
+    }
+    // ── Hosted extension: durable run lifecycle (NOT part of the protocol) ──
+    /**
+     * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
+     *
+     * Self-healing: a finished-but-unrecorded run resolves to its true terminal
+     * status on read. `degraded: true` means Temporal was unreachable and
+     * `status` is the last-known value; `retry_after_seconds` carries the
+     * server's backoff hint when present. Throws `RunLifecycleUnavailableError`
+     * when the lifecycle routes are absent (a bare runner).
+     */
+    async getRunStatus(runId, options = {}) {
+        const endpoint = `${RUNS}/${encodeURIComponent(runId)}/status`;
+        const url = this.url(endpoint);
+        const res = await this.requestRaw("GET", url, {
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+            signal: options.signal,
+        });
+        this.throwIfLifecycleUnavailable(res, url);
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("GET", endpoint, res);
+        }
+        const run = JSON.parse(res.body);
+        const retryAfter = parseRetryAfter(res.headers);
+        return retryAfter !== null ? { ...run, retry_after_seconds: retryAfter } : run;
+    }
+    /**
+     * Single-shot result lookup — `GET /v1/runs/{pipeline_run_id}/results`.
+     * Maps the server's poll semantics to a discriminated union:
+     * - HTTP 202 → `running` (with the `Retry-After` hint)
+     * - HTTP 200 → `completed` (with the result artifacts)
+     * - HTTP 409 → `failed` (terminal non-`COMPLETED`)
+     * - HTTP 503 → `running` (Temporal degraded — retry, never fail a poller)
+     *
+     * Throws `RunLifecycleUnavailableError` when the lifecycle routes are absent
+     * (a bare runner).
+     */
+    async getRunResult(runId, options = {}) {
+        const endpoint = `${RUNS}/${encodeURIComponent(runId)}/results`;
+        const url = this.url(endpoint);
+        const res = await this.requestRaw("GET", url, {
+            timeoutMs: POLL_REQUEST_TIMEOUT_MS,
+            signal: options.signal,
+        });
+        if (res.status === 202 || res.status === 503) {
+            return {
+                state: "running",
+                pipeline_run_id: runId,
+                retry_after_seconds: parseRetryAfter(res.headers) ?? DEFAULT_DEGRADED_RETRY_SECONDS,
+            };
+        }
+        if (res.status === 409) {
+            const { serverMessage } = parseErrorBody(res.body);
+            const message = serverMessage ?? "Run finished without a result.";
+            return {
+                state: "failed",
+                pipeline_run_id: runId,
+                status: extractRunStatusFromMessage(message),
+                message,
+            };
+        }
+        this.throwIfLifecycleUnavailable(res, url);
+        if (res.status < 200 || res.status >= 300) {
+            this.throwApiResponseError("GET", endpoint, res);
+        }
+        const result = JSON.parse(res.body);
+        return { state: "completed", pipeline_run_id: runId, result };
+    }
+    /** Poll an already-started run (by id) until it reaches a terminal state. */
+    async waitForResult(runId, options) {
+        return pollUntilResult((id, opts) => this.getRunResult(id, opts), runId, options);
+    }
+    /**
+     * Whether the configured server serves the durable run lifecycle, decided
+     * via the `GET /v1/version` handshake and cached for the client's lifetime. A
+     * bare `pipelex-api` runner has no run store; anything else is assumed hosted.
+     * When the handshake itself fails, assume hosted (the SDK default) and let the
+     * start call surface the real error.
+     */
+    async supportsRunLifecycle() {
+        if (this.lifecycleAvailable === undefined) {
+            try {
+                const info = await this.version();
+                const impl = info.implementation;
+                this.lifecycleAvailable = !(typeof impl === "string" && impl === BARE_RUNNER_IMPLEMENTATION);
+            }
+            catch {
+                this.lifecycleAvailable = true;
+            }
+        }
+        return this.lifecycleAvailable;
+    }
+    /**
+     * Start a run and wait for its result.
+     *
+     * - **Hosted** (per the `/v1/version` handshake): durable start + poll, the
+     *   path that survives the gateway's ~30s synchronous ceiling.
+     * - **Bare runner** (no run store): the blocking `POST /v1/execute`, which
+     *   has no gateway cap off-platform and returns the native `pipe_output`.
+     */
+    async startAndWaitForResult(options, pollOptions) {
+        if (await this.supportsRunLifecycle()) {
+            // A runner can look hosted yet lack the durable routes — `implementation`
+            // is an extension field, so a compliant bare runner that omits it is
+            // misdetected here. Such a runner raises `RunLifecycleUnavailableError`
+            // from `start()`, BEFORE any run is created, so falling back to the
+            // blocking path cannot double-run. Cache the negative so later calls skip
+            // the durable attempt.
+            let ack;
+            try {
+                ack = await this.start(options);
+            }
+            catch (err) {
+                if (!(err instanceof RunLifecycleUnavailableError))
+                    throw err;
+                this.lifecycleAvailable = false;
+                return this.executeBlocking(options);
+            }
+            return this.waitForResult(ack.pipeline_run_id, pollOptions);
+        }
+        return this.executeBlocking(options);
+    }
+    // ── Pipelex product surface (hosted management routes) ─────────────────
+    //
+    // The hosted catalog/account routes the webapp drives. Every one rides the
+    // same `{base}/v1/*` surface, `Authorization: Bearer`, org-from-JWT contract
+    // as the protocol routes, and maps a non-2xx `problem+json` to a typed
+    // `ApiResponseError` (branch on `.code`, not the status).
+    /** The authenticated user's profile — `GET /v1/me`. */
+    async getMe() {
+        return this.requestProduct("GET", "me");
+    }
+    /** List the caller's saved methods — `GET /v1/methods`. */
+    async listMethods() {
+        return this.requestProduct("GET", "methods");
+    }
+    /** Fetch one method by id — `GET /v1/methods/{id}`. */
+    async getMethod(methodId) {
+        return this.requestProduct("GET", `methods/${encodeURIComponent(methodId)}`);
+    }
+    /** Create a method — `POST /v1/methods`. */
+    async createMethod(input) {
+        return this.requestProduct("POST", "methods", input);
+    }
+    /** Replace a method (rename = changed `name`) — `PUT /v1/methods/{id}`. */
+    async updateMethod(methodId, input) {
+        return this.requestProduct("PUT", `methods/${encodeURIComponent(methodId)}`, input);
+    }
+    /** Delete a method — `DELETE /v1/methods/{id}`. */
+    async deleteMethod(methodId) {
+        await this.requestProduct("DELETE", `methods/${encodeURIComponent(methodId)}`);
+    }
+    /** The caller's org memberships + active-org feature flags — `GET /v1/organizations/memberships`. */
+    async listMemberships() {
+        return this.requestProduct("GET", "organizations/memberships");
+    }
+    /** Create an organization — `POST /v1/organizations`. */
+    async createOrganization(input) {
+        return this.requestProduct("POST", "organizations", input);
+    }
+    /** Rename an organization — `PATCH /v1/organizations/{org_id}`. */
+    async renameOrganization(orgId, input) {
+        return this.requestProduct("PATCH", `organizations/${encodeURIComponent(orgId)}`, input);
+    }
+    /** The active org's subscription state — `GET /v1/billing/subscription`. */
+    async getSubscription() {
+        return this.requestProduct("GET", "billing/subscription");
+    }
+    /** Available plans (with `is_current`) — `GET /v1/billing/plans`. */
+    async listPlans() {
+        return this.requestProduct("GET", "billing/plans");
+    }
+    /** Past invoices — `GET /v1/billing/invoices`. */
+    async listInvoices() {
+        return this.requestProduct("GET", "billing/invoices");
+    }
+    /** Open a Stripe checkout for a plan — `POST /v1/billing/checkout`. */
+    async createCheckout(input) {
+        return this.requestProduct("POST", "billing/checkout", input);
+    }
+    /**
+     * Switch the existing subscription's plan — `POST /v1/billing/change-plan`.
+     * A 409 `conflict` (`ApiResponseError.code`) means there is no subscription
+     * to change — start one via `createCheckout` first.
+     */
+    async changePlan(input) {
+        return this.requestProduct("POST", "billing/change-plan", input);
+    }
+    /**
+     * A Stripe billing-portal session URL — `GET /v1/billing/portal`. A 409
+     * `conflict` (`ApiResponseError.code`) means there is no subscription yet.
+     */
+    async getBillingPortal() {
+        return this.requestProduct("GET", "billing/portal");
+    }
+    /** List the caller's Pipelex API keys — `GET /v1/pipelex-api-keys`. */
+    async listPipelexApiKeys() {
+        return this.requestProduct("GET", "pipelex-api-keys");
+    }
+    /**
+     * Mint a Pipelex API key — `POST /v1/pipelex-api-keys`. The plaintext
+     * `api_key` is returned ONCE. A 409 `pipelex_api_key_limit_reached`
+     * (`ApiResponseError.code`) means the per-account key limit is hit.
+     */
+    async createPipelexApiKey(input) {
+        return this.requestProduct("POST", "pipelex-api-keys", input);
+    }
+    /** Revoke a Pipelex API key — `DELETE /v1/pipelex-api-keys/{id}`. */
+    async revokePipelexApiKey(id) {
+        await this.requestProduct("DELETE", `pipelex-api-keys/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Rotate a Pipelex API key — `POST /v1/pipelex-api-keys/{id}/rotate` (no
+     * body). Returns the new plaintext `api_key` once; the old key stops working.
+     */
+    async rotatePipelexApiKey(id) {
+        return this.requestProduct("POST", `pipelex-api-keys/${encodeURIComponent(id)}/rotate`);
+    }
+    /**
+     * Provision the gateway (LLM inference) API key — `POST /v1/gateway-api-key`.
+     * The JSON body is ALWAYS sent (even with `promo_code: null`) — the server
+     * 422s an empty body.
+     */
+    async createGatewayApiKey(input) {
+        return this.requestProduct("POST", "gateway-api-key", input);
+    }
+    /** The gateway key status (`null` until provisioned) — `GET /v1/gateway-api-key`. */
+    async getGatewayApiKey() {
+        return this.requestProduct("GET", "gateway-api-key");
+    }
+    /** Submit the onboarding questionnaire — `POST /v1/onboarding/submit`. */
+    async submitOnboarding(input) {
+        await this.requestProduct("POST", "onboarding/submit", input);
+    }
+    /** Resolve a storage URI to a presigned URL — `POST /v1/resolve-storage-url`. */
+    async resolveStorageUrl(input) {
+        return this.requestProduct("POST", "resolve-storage-url", input);
+    }
+    /** Upload a base64 file — `POST /v1/upload`. */
+    async upload(input) {
+        return this.requestProduct("POST", "upload", input);
+    }
+    /** List a method's runs — `GET /v1/runs?method_id={methodId}`. */
+    async listRuns(methodId) {
+        return this.requestProduct("GET", `runs?method_id=${encodeURIComponent(methodId)}`);
+    }
+    /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
+    async updateRun(runId, input) {
+        await this.requestProduct("PUT", `runs/${encodeURIComponent(runId)}`, input);
+    }
+    /**
+     * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
+     * path. Forwards every protocol field PLUS the `extra` extension passthrough:
+     * an extension-only call (`{ extra }` with no pipe_code/bundle) or a vendor
+     * selector riding `extra` must survive this path, not just the durable one.
+     */
+    async executeBlocking(options) {
+        const response = await this.execute({
+            pipe_code: options.pipe_code ?? undefined,
+            mthds_contents: options.mthds_contents ?? undefined,
+            inputs: options.inputs ?? undefined,
+            output_name: options.output_name ?? undefined,
+            output_multiplicity: options.output_multiplicity ?? undefined,
+            dynamic_output_concept_ref: options.dynamic_output_concept_ref ?? undefined,
+            extra: options.extra ?? undefined,
+        });
+        return mapRunResultToRunResults(response);
+    }
+}
+// ── Module helpers ────────────────────────────────────────────────────
+/**
+ * Whether a base URL is host-only — http/https, no path, query, fragment, or
+ * embedded credentials (auth travels in the Authorization header, never the URL).
+ * Endpoints compose as `{base}/v1/{endpoint}`, so a path-prefixed base would
+ * double the prefix.
+ */
+function isValidBaseUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return false;
+    if (parsed.pathname !== "/" && parsed.pathname !== "")
+        return false;
+    if (parsed.username || parsed.password)
+        return false;
+    return !parsed.search && !parsed.hash;
+}
+/**
+ * Map the protocol's blocking `POST /v1/execute` response onto the lifecycle's
+ * `RunResults`. The bare-runner path returns `pipe_output` (native runner
+ * shape); `main_stuff` is a hosted-durable artifact and stays null here.
+ * Consumers read `main_stuff ?? pipe_output` (the documented hosted/bare
+ * output-shape difference).
+ */
+function mapRunResultToRunResults(response) {
+    const pipeOutput = response.pipe_output;
+    return {
+        pipeline_run_id: response.pipeline_run_id,
+        main_stuff: null,
+        // The bare-runner blocking `pipe_output` carries no graph artifact; the
+        // hosted graph_spec rides the durable `/v1/runs/{id}/results` payload.
+        graph_spec: null,
+        pipe_output: pipeOutput ?? null,
+    };
+}
+// The protocol's own request fields — `extra` is for extension args only.
+const PROTOCOL_REQUEST_KEYS = new Set([
+    "pipe_code",
+    "mthds_contents",
+    "inputs",
+    "output_name",
+    "output_multiplicity",
+    "dynamic_output_concept_ref",
+]);
+/**
+ * Validate and copy the generic `extra` passthrough. Extension args ride the
+ * request body as top-level properties; protocol args must be passed as named
+ * options, never smuggled through `extra`.
+ */
+function buildExtensions(extra) {
+    if (!extra)
+        return {};
+    const overlap = Object.keys(extra).filter((key) => PROTOCOL_REQUEST_KEYS.has(key));
+    if (overlap.length > 0) {
+        throw new PipelineRequestError(`extra carries protocol args [${overlap.sort().join(", ")}] — pass them as named options instead.`);
+    }
+    return { ...extra };
+}
+function withValidateMarkdownRender(render) {
+    const formats = new Set(render ?? []);
+    formats.add(VALIDATE_MARKDOWN_RENDER_FORMAT);
+    return [...formats];
+}
+// The hosted gateway caps synchronous requests at 30s. A failure at/after this
+// threshold on the blocking execute is the timeout, not a transient outage —
+// the threshold guards against mislabelling a fast 503 (runner genuinely down)
+// as a timeout.
+const GATEWAY_TIMEOUT_THRESHOLD_MS = 28_000;
+function isGatewayTimeout(err, elapsedMs) {
+    if (elapsedMs < GATEWAY_TIMEOUT_THRESHOLD_MS)
+        return false;
+    if (err instanceof ApiResponseError)
+        return err.status === 503 || err.status === 504;
+    if (err instanceof ApiUnreachableError)
+        return err.code === "ABORT_TIMEOUT";
+    return false;
+}
+function extractNetworkErrorCode(err) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+        return "ABORT_TIMEOUT";
+    }
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause && typeof cause === "object" && "code" in cause) {
+            const code = cause.code;
+            if (typeof code === "string")
+                return code;
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether a 404 is an unmatched-route 404 (no platform deployed) rather than
+ * the platform's structured run-not-found 404. The platform wraps its 404s in
+ * a structured envelope with a stable `code`; a bare runner returns
+ * Starlette's default `{"detail": "Not Found"}` (no `code`).
+ */
+function isMissingRoute404(body) {
+    if (!body)
+        return true;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return true;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return true;
+    return !("code" in parsed);
+}
+/** Parse the `Retry-After` header (seconds form, which the platform uses). */
+function parseRetryAfter(headers) {
+    const raw = headers.get("retry-after");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+const KNOWN_RUN_STATUSES = [
+    "PENDING",
+    "STARTED",
+    "RUNNING",
+    "COMPLETED",
+    "FAILED",
+    "CANCELLED",
+    "TERMINATED",
+    "TIMED_OUT",
+];
+/**
+ * The 409 detail reads "Run finished with status FAILED; no result available".
+ * Pull the status word out; default to FAILED if the shape ever changes.
+ */
+function extractRunStatusFromMessage(message) {
+    const match = message.match(/status\s+([A-Z_]+)/);
+    const candidate = match?.[1];
+    if (candidate && KNOWN_RUN_STATUSES.includes(candidate)) {
+        return candidate;
+    }
+    return "FAILED";
+}
+/**
+ * The API serializes errors as `{"detail": {"error_type": ..., "message": ...}}`
+ * (HTTPException with dict detail) or `{"detail": "..."}` (auth 401s and RFC
+ * 7807 problems). Both shapes are extracted here. An invalid-bundle 422 problem
+ * additionally carries a top-level `validation_errors[]` list (the
+ * `ValidateBundleError` extension projected onto the envelope). Falls through
+ * silently on non-JSON bodies.
+ */
+function parseErrorBody(body) {
+    const empty = {
+        errorType: undefined,
+        serverMessage: undefined,
+        validationErrors: undefined,
+        code: undefined,
+    };
+    if (!body)
+        return empty;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return empty;
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return empty;
+    }
+    const root = parsed;
+    const detail = root.detail;
+    let errorType;
+    let serverMessage;
+    if (detail && typeof detail === "object") {
+        const d = detail;
+        if (typeof d.error_type === "string")
+            errorType = d.error_type;
+        if (typeof d.message === "string")
+            serverMessage = d.message;
+    }
+    else if (typeof detail === "string") {
+        serverMessage = detail;
+    }
+    if (errorType === undefined && typeof root.error_type === "string")
+        errorType = root.error_type;
+    if (serverMessage === undefined && typeof root.message === "string")
+        serverMessage = root.message;
+    // `validation_errors` rides the problem envelope as a top-level array (the
+    // VERBOSE projection of `ErrorReport.validation_errors`, retained under STRICT
+    // too — it describes the caller's own bundle, not server internals). Kept as a
+    // shallow array guard; per-item shape is the typed `ValidationErrorItem` contract.
+    const validationErrors = Array.isArray(root.validation_errors)
+        ? root.validation_errors
+        : undefined;
+    // The product routes' RFC 9457 `problem+json` carries a stable top-level
+    // `code` discriminant (`conflict`, `not_found`, …) — the field consumers
+    // branch on, decoupled from the HTTP status.
+    const code = typeof root.code === "string" ? root.code : undefined;
+    return { errorType, serverMessage, validationErrors, code };
+}
+//# sourceMappingURL=client.js.map