@pipelex/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evotis S.A.S.
+
+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/README.md

@@ -0,0 +1,75 @@
+# @pipelex/sdk
+
+TypeScript SDK for the **Pipelex hosted API** — execute MTHDS methods, manage runs, and call the product surface (methods catalog, organizations, billing, API keys, storage) from Node.
+
+> Pipelex is the runtime/product. [MTHDS](https://mthds.ai) is the open standard it implements. This SDK speaks to the hosted Pipelex API; the pure protocol wire types it builds on come from the [`mthds`](https://www.npmjs.com/package/mthds) package via its `mthds/protocol` subpath.
+
+## Status
+
+Early. `PipelexApiClient` implements the MTHDS protocol-execution routes (`execute` / `start` / `validate` / `models` / `version`), the build helpers (`/v1/build/*`), the durable run lifecycle (`start` → poll → result), and the Pipelex product routes (user profile, methods catalog, organizations, billing, API keys, gateway key, onboarding, storage, runs list/update).
+
+## Install
+
+```bash
+npm install @pipelex/sdk
+```
+
+## Usage
+
+```ts
+import { PipelexApiClient } from "@pipelex/sdk";
+
+// Base URL + token from PIPELEX_API_URL / PIPELEX_API_KEY, or pass them explicitly.
+const client = new PipelexApiClient({
+  baseUrl: "https://api.pipelex.com",
+  apiToken: process.env.PIPELEX_API_KEY,
+});
+
+// Validate an MTHDS bundle (a 200-diagnostic verdict, discriminated on `is_valid`).
+const report = await client.validate(["domain = 'demo'"]);
+if (report.is_valid) {
+  // Run it and wait for the result (durable start + poll on the hosted API).
+  const result = await client.startAndWaitForResult({ pipe_code: "demo.greet" });
+  console.log(result.main_stuff ?? result.pipe_output);
+}
+```
+
+### Product routes
+
+The hosted management surface (catalog, account, billing) hangs off the same client. Every product route maps a non-2xx `problem+json` to a typed `ApiResponseError` — branch on the structured `code`, not the HTTP status:
+
+```ts
+import { PipelexApiClient, ApiResponseError } from "@pipelex/sdk";
+
+const client = new PipelexApiClient({ apiToken: process.env.PIPELEX_API_KEY });
+
+const me = await client.getMe(); // GET /v1/me
+const methods = await client.listMethods(); // GET /v1/methods
+const created = await client.createMethod({ name: "Greeter", mthds: "domain = 'demo'" });
+
+try {
+  const { portal_url } = await client.getBillingPortal();
+  // open portal_url ...
+} catch (err) {
+  if (err instanceof ApiResponseError && err.code === "conflict") {
+    // no subscription yet — start one via createCheckout(...)
+  }
+}
+```
+
+The full client surface is documented in [`docs/architecture.md`](./docs/architecture.md).
+
+## Develop
+
+```bash
+make install    # Install dependencies
+make check      # Lint + format check + typecheck + build + depcruise (alias: make c)
+make test       # Run the test suite (alias: make t)
+make all        # Clean, check, and test
+```
+
+Always run `make check` before committing.
+
+## License
+
+[MIT](./LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,297 @@
+import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, RunResultStart, StartOptions, VersionInfo } from "mthds/protocol";
+import type { BuildInputsRequest, BuildOutputRequest, BuildRunnerRequest, BuildRunnerResponse, ConceptRequest, ConceptResponse, DictPipeOutput, DictRunResultExecute, PipeSpecRequest, PipeSpecResponse, PipelexValidationResult } from "./models.js";
+import { type RunRead, type RunResults, type RunResultState, type WaitForResultOptions } from "./runs.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, GatewayApiKey, GatewayApiKeyStatus, InvoiceView, Membership, MembershipsResponse, MethodData, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, PipelineRun, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+export interface MthdsFile {
+    /** File contents to validate. */
+    content: string;
+    /** Optional provenance URI threaded into validation diagnostics. */
+    uri?: string;
+}
+export interface ValidateFilesOptions {
+    /** Whether unresolved pipe signatures are accepted as pending instead of invalid. */
+    allowSignatures?: boolean;
+    /** Optional validate presentation hints, e.g. ["markdown"]. */
+    render?: string[];
+}
+export interface PipelexApiClientOptions {
+    /** API token (Bearer). Falls back to `PIPELEX_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 `PIPELEX_API_URL`, then the hosted
+     * default.
+     */
+    baseUrl?: string;
+}
+/** Hosted default — the client composes every endpoint as `{base}/v1/{endpoint}`. */
+export declare const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
+/**
+ * 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 declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
+    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?: PipelexApiClientOptions);
+    /** 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;
+    /**
+     * 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.
+     */
+    private requestProduct;
+    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`.
+     *
+     * `/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).
+     */
+    validate(mthdsContents: string[], allowSignatures?: boolean, mthdsSources?: string[], render?: string[]): Promise<PipelexValidationResult>;
+    /**
+     * 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.
+     */
+    validateFiles(files: MthdsFile[], options?: ValidateFilesOptions): Promise<PipelexValidationResult>;
+    /** 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>;
+    /** Poll an already-started run (by id) until it reaches a terminal state. */
+    waitForResult(runId: string, options?: WaitForResultOptions): Promise<RunResults>;
+    /**
+     * 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.
+     */
+    private supportsRunLifecycle;
+    /**
+     * 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`.
+     */
+    startAndWaitForResult(options: StartOptions, pollOptions?: WaitForResultOptions): Promise<RunResults>;
+    /** The authenticated user's profile — `GET /v1/me`. */
+    getMe(): Promise<UserProfile>;
+    /** List the caller's saved methods — `GET /v1/methods`. */
+    listMethods(): Promise<MethodData[]>;
+    /** Fetch one method by id — `GET /v1/methods/{id}`. */
+    getMethod(methodId: string): Promise<MethodData>;
+    /** Create a method — `POST /v1/methods`. */
+    createMethod(input: MethodWriteInput): Promise<MethodData>;
+    /** Replace a method (rename = changed `name`) — `PUT /v1/methods/{id}`. */
+    updateMethod(methodId: string, input: MethodWriteInput): Promise<MethodData>;
+    /** Delete a method — `DELETE /v1/methods/{id}`. */
+    deleteMethod(methodId: string): Promise<void>;
+    /** The caller's org memberships + active-org feature flags — `GET /v1/organizations/memberships`. */
+    listMemberships(): Promise<MembershipsResponse>;
+    /** Create an organization — `POST /v1/organizations`. */
+    createOrganization(input: {
+        name: string;
+    }): Promise<Membership>;
+    /** Rename an organization — `PATCH /v1/organizations/{org_id}`. */
+    renameOrganization(orgId: string, input: {
+        name: string;
+    }): Promise<Membership>;
+    /** The active org's subscription state — `GET /v1/billing/subscription`. */
+    getSubscription(): Promise<SubscriptionResponse>;
+    /** Available plans (with `is_current`) — `GET /v1/billing/plans`. */
+    listPlans(): Promise<PlanView[]>;
+    /** Past invoices — `GET /v1/billing/invoices`. */
+    listInvoices(): Promise<InvoiceView[]>;
+    /** Open a Stripe checkout for a plan — `POST /v1/billing/checkout`. */
+    createCheckout(input: {
+        plan: string;
+    }): Promise<CheckoutResponse>;
+    /**
+     * 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.
+     */
+    changePlan(input: {
+        plan: string;
+    }): Promise<ChangePlanResponse>;
+    /**
+     * A Stripe billing-portal session URL — `GET /v1/billing/portal`. A 409
+     * `conflict` (`ApiResponseError.code`) means there is no subscription yet.
+     */
+    getBillingPortal(): Promise<BillingPortalResponse>;
+    /** List the caller's Pipelex API keys — `GET /v1/pipelex-api-keys`. */
+    listPipelexApiKeys(): Promise<PipelexApiKeyList>;
+    /**
+     * 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.
+     */
+    createPipelexApiKey(input: {
+        label: string;
+    }): Promise<PipelexApiKeyCreated>;
+    /** Revoke a Pipelex API key — `DELETE /v1/pipelex-api-keys/{id}`. */
+    revokePipelexApiKey(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    rotatePipelexApiKey(id: string): Promise<PipelexApiKeyCreated>;
+    /**
+     * 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.
+     */
+    createGatewayApiKey(input: {
+        promo_code: string | null;
+    }): Promise<GatewayApiKey>;
+    /** The gateway key status (`null` until provisioned) — `GET /v1/gateway-api-key`. */
+    getGatewayApiKey(): Promise<GatewayApiKeyStatus>;
+    /** Submit the onboarding questionnaire — `POST /v1/onboarding/submit`. */
+    submitOnboarding(input: OnboardingSubmission): Promise<void>;
+    /** Resolve a storage URI to a presigned URL — `POST /v1/resolve-storage-url`. */
+    resolveStorageUrl(input: {
+        uri: string;
+    }): Promise<ResolvedStorageUrl>;
+    /** Upload a base64 file — `POST /v1/upload`. */
+    upload(input: UploadInput): Promise<UploadedFile>;
+    /** List a method's runs — `GET /v1/runs?method_id={methodId}`. */
+    listRuns(methodId: string): Promise<PipelineRun[]>;
+    /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
+    updateRun(runId: string, input: UpdateRunInput): Promise<void>;
+    /**
+     * 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;
+}