mthds 0.8.1 → 0.10.0

package/dist/runners/api/client.d.ts

@@ -0,0 +1,170 @@
+import { BaseRunner } from "../base-runner.js";
+import type { Runner, RunnerType, BuildInputsRequest, BuildOutputRequest, BuildRunnerRequest, BuildRunnerResponse, ConceptRequest, ConceptResponse, PipeSpecRequest, PipeSpecResponse } from "../types.js";
+import type { RunOptions, StartOptions } from "../../protocol/options.js";
+import type { ModelCategory, ModelDeck, RunResultStart, ValidationReport, VersionInfo } from "../../protocol/models.js";
+import type { DictRunResultExecute } from "./models.js";
+import type { RunRead, RunResults, RunResultState, WaitForResultOptions } from "./runs.js";
+interface MthdsApiClientOptions {
+    /** API token (Bearer). Falls back to `MTHDS_API_KEY`. Optional for anonymous bare runners. */
+    apiToken?: string;
+    /**
+     * API base URL — host only, NO version prefix (e.g. `https://api.pipelex.com`
+     * or `http://localhost:8081`). Every endpoint composes as
+     * `{baseUrl}/v1/{endpoint}`. Falls back to `MTHDS_API_URL`, then the hosted
+     * default.
+     */
+    baseUrl?: string;
+}
+/** Hosted default — the SDK composes every endpoint as `{base}/v1/{endpoint}`. */
+export declare const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
+/**
+ * Client for any MTHDS runner — and THE API runner (parity D8). One class,
+ * two consumers: `pipelex-app` instantiates it directly as a protocol client,
+ * the CLI gets it via `createRunner()` as a full `Runner`. `extends BaseRunner
+ * implements Runner` so it carries the protocol surface, the Pipelex build
+ * extensions, and the lifecycle composites (`waitForResult` /
+ * `startAndWaitForResult`, inherited from `BaseRunner`).
+ *
+ * One base URL (`MTHDS_API_URL`); every endpoint is `<base>/v1/<endpoint>`:
+ * - **protocol** (`execute` / `start` / `validate` / `models` / `version`) — works
+ *   against any MTHDS-compliant runner, hosted or bare.
+ * - **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 hosted
+ *   MTHDS API); a bare `pipelex-api` runner 404s those routes, which the lifecycle
+ *   methods translate into a clear `RunLifecycleUnavailableError`.
+ */
+export declare class MthdsApiClient extends BaseRunner implements Runner {
+    readonly type: RunnerType;
+    private readonly apiToken;
+    private readonly baseUrl;
+    /** Origin root derived from the base URL — `/health` lives here, not under `/v1`. */
+    private readonly originUrl;
+    /** Cached `/v1/version` handshake outcome — whether the durable lifecycle is served. */
+    private lifecycleAvailable;
+    constructor(options?: MthdsApiClientOptions);
+    /** Build an API URL: `<base>/v1/<endpoint>`. */
+    private url;
+    /**
+     * 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.
+     */
+    private requestRaw;
+    /**
+     * 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.
+     */
+    private requestJson;
+    private postApi;
+    private throwApiResponseError;
+    /**
+     * 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.
+     */
+    private throwIfLifecycleUnavailable;
+    /**
+     * 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.
+     */
+    private throwIfExecuteDegraded;
+    health(): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    execute(options: RunOptions): Promise<DictRunResultExecute>;
+    /**
+     * 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`.
+     */
+    start(options: StartOptions): Promise<RunResultStart>;
+    /**
+     * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
+     *
+     * Returns the structural artifacts of a valid bundle; an invalid bundle is
+     * an HTTP 422 problem, surfaced as `ApiResponseError`.
+     */
+    validate(mthdsContents: string[], allowSignatures?: boolean): Promise<ValidationReport>;
+    /** The model deck the runner can route to — `GET /v1/models[?type=]`. */
+    models(category?: ModelCategory): Promise<ModelDeck>;
+    /**
+     * Protocol + implementation versions — `GET /v1/version` (always public).
+     * The handshake for feature detection (hosted extensions or not).
+     */
+    version(): Promise<VersionInfo>;
+    buildInputs(request: BuildInputsRequest): Promise<unknown>;
+    buildOutput(request: BuildOutputRequest): Promise<unknown>;
+    buildRunner(request: BuildRunnerRequest): Promise<BuildRunnerResponse>;
+    concept(request: ConceptRequest): Promise<ConceptResponse>;
+    pipeSpec(request: PipeSpecRequest): Promise<PipeSpecResponse>;
+    /**
+     * 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).
+     */
+    getRunStatus(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RunRead>;
+    /**
+     * 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).
+     */
+    getRunResult(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RunResultState>;
+    /**
+     * Whether the configured server serves the durable run lifecycle, decided
+     * via the `GET /v1/version` handshake (master D2) 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.
+     */
+    private supportsRunLifecycle;
+    /**
+     * Start a run and wait for its result.
+     *
+     * - **Hosted** (per the `/v1/version` handshake): durable start + poll (the
+     *   `BaseRunner` composite), 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`.
+     */
+    startAndWaitForResult(options: StartOptions, pollOptions?: WaitForResultOptions): Promise<RunResults>;
+    /**
+     * 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.
+     */
+    private executeBlocking;
+}
+export {};