@pipelex/sdk 0.3.0 → 0.4.0

package/dist/models.d.ts

@@ -136,19 +136,95 @@ export interface ValidationErrorItem {
     missing_concept_code?: string;
     declared_concepts?: string[];
 }
+/** Which analysis produced a `Diagnostic` — mirror of `pipelex-tools`' closed kind set. */
+export type DiagnosticKind = "syntax" | "semantic" | "schema";
+/** Source span of a `Diagnostic` — byte offsets plus 1-based line/column coordinates. */
+export interface DiagnosticRange {
+    start_offset: number;
+    end_offset: number;
+    start_line: number;
+    start_col: number;
+    end_line: number;
+    end_col: number;
+}
+/**
+ * One structured lint/format diagnostic — mirror of pipelex's `Diagnostic`.
+ * `severity` stays an open string (the server does not close the vocabulary);
+ * `location` and `range` are `null` when the analysis cannot attribute a span.
+ */
+export interface Diagnostic {
+    kind: DiagnosticKind;
+    severity: string;
+    message: string;
+    location: string | null;
+    range: DiagnosticRange | null;
+}
+/** `POST /v1/lint` 200 body — the diagnostics of one linted `.mthds` file. */
+export interface LintResponse {
+    diagnostics: Diagnostic[];
+}
+/**
+ * `POST /v1/format` 200 body — the canonically formatted content, whether it
+ * differs from the submitted one, and any diagnostics found on the way. A syntax
+ * error yields `changed: false` with the content echoed back unchanged.
+ */
+export interface FormatResponse {
+    formatted: string;
+    changed: boolean;
+    diagnostics: Diagnostic[];
+}
 export type ConceptRepresentationFormat = "json" | "python" | "schema";
-export interface BuildInputsRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+/** Encoding of a `/v1/build/inputs` template. Decides which field carries it back. */
+export type InputsTemplateFormat = "json" | "toml";
+/**
+ * One MTHDS file in a build closure. `source` is an optional provenance label (a
+ * filename, a URI) that the server threads onto every diagnostic it raises from
+ * this file, so an invalid verdict can point at the file that caused it.
+ *
+ * NOT the same type as `MthdsFile` (the one `validateFiles()` takes), which the
+ * client adapts into `/v1/validate`'s parallel `mthds_contents` + `mthds_sources`
+ * arrays: that route spells the label `uri`, this envelope spells it `source`. The
+ * two collapse into one only if `/v1/validate` ever migrates onto `files[]` — a
+ * protocol-level change owned by the MTHDS standard, not ours to make here.
+ */
+export interface MthdsFileItem {
+    content: string;
+    source?: string;
 }
-export interface BuildOutputRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+/**
+ * The closure + pipe selector every `/v1/build/*` route shares.
+ *
+ * Supply the closure EITHER as inline `files` OR as a `method_ref` into the method
+ * registry — never both. `method_ref` is reserved: the registry does not exist yet,
+ * so the server answers `501` for it today.
+ */
+export interface BuildRequestBase {
+    files?: MthdsFileItem[];
+    method_ref?: string;
+    /**
+     * The pipe to project, as a QUALIFIED `domain.pipe_code` ref. Omit it to default
+     * to the closure's declared `main_pipe` — which fails (422) when the closure
+     * declares none, or declares several across its domains.
+     */
+    pipe_ref?: string;
+}
+export interface BuildInputsRequest extends BuildRequestBase {
+    /** `json` (default) puts the parsed template in `inputs`; `toml` puts raw text in `inputs_toml`. */
+    format?: InputsTemplateFormat;
+    /** Emit the ceremonial `{concept, content}` envelope per input. Defaults to the light shape. */
+    explicit?: boolean;
+}
+export interface BuildOutputRequest extends BuildRequestBase {
+    /** `schema` (default) and `json` put a parsed object in `output`; `python` puts source in `output_python`. */
     format?: ConceptRepresentationFormat;
 }
-export interface BuildRunnerRequest {
-    mthds_contents: string[];
-    pipe_code: string;
+export interface BuildRunnerRequest extends BuildRequestBase {
+    /**
+     * Accept unresolved pipe signatures as pending rather than invalid. Alone among
+     * the build routes this one still runs the dry-run sweep, and the flag only ever
+     * parameterized that sweep.
+     */
+    allow_signatures?: boolean;
 }
 export interface ConceptRequest {
     spec: Record<string, unknown>;
@@ -157,12 +233,92 @@ export interface PipeSpecRequest {
     pipe_type: string;
     spec: Record<string, unknown>;
 }
-export interface BuildRunnerResponse {
-    python_code: string;
-    pipe_code: string;
-    success: boolean;
+/**
+ * The `is_valid: false` arm shared by every `/v1/build/*` route.
+ *
+ * The build routes follow `/validate`'s discipline: an unresolvable closure is the
+ * *successful product* of the call (the request was well-formed, the library was
+ * not), so it rides a **200** discriminated on `is_valid` — never a 4xx. Only a
+ * no-verdict condition (an unknown `pipe_ref`, `method_ref`, auth, a server fault)
+ * throws `ApiResponseError`. Branch on `is_valid`, never on the transport.
+ */
+export interface CrateInvalidReport {
+    is_valid: false;
+    validation_errors: ValidationErrorItem[];
     message: string;
 }
+/** Fields the valid arm of every `/v1/build/*` route carries. */
+interface BuildValidReportBase {
+    is_valid: true;
+    /** The qualified pipe that was projected — the RESOLVED selector, always `domain.pipe_code`. */
+    pipe_ref: string;
+    /** The `pipe_ref` as submitted. Absent when it was omitted and defaulted to `main_pipe`. */
+    requested_pipe_ref?: string;
+    message: string;
+}
+/**
+ * The `/v1/build/inputs` valid arm. The template rides ONE of two fields, chosen by
+ * `format`: `inputs` (a parsed object) for `json`, `inputs_toml` (raw text) for
+ * `toml`. TOML cannot be carried as a parsed object without losing what makes it
+ * worth asking for — its concept comments and key order — so the two are separate
+ * fields and the unused one is absent from the body entirely.
+ *
+ * That "absent entirely" is why this is a union rather than one interface with two
+ * optional fields: `format` is a real discriminant, so narrowing on it hands you the
+ * field it selected as REQUIRED, with the other one statically unreachable.
+ */
+interface BuildInputsJsonReport extends BuildValidReportBase {
+    format: "json";
+    explicit: boolean;
+    inputs: Record<string, unknown>;
+    inputs_toml?: never;
+}
+interface BuildInputsTomlReport extends BuildValidReportBase {
+    format: "toml";
+    explicit: boolean;
+    inputs?: never;
+    inputs_toml: string;
+}
+export type BuildInputsValidReport = BuildInputsJsonReport | BuildInputsTomlReport;
+export type BuildInputsResponse = BuildInputsValidReport | CrateInvalidReport;
+/**
+ * The `/v1/build/output` valid arm. Same two-field split as the inputs template, for
+ * the same reason: `schema` and `json` are objects, `python` is source text — and so
+ * it is a discriminated union for the same reason too.
+ */
+interface BuildOutputObjectReport extends BuildValidReportBase {
+    format: "schema" | "json";
+    output: Record<string, unknown>;
+    output_python?: never;
+}
+interface BuildOutputPythonReport extends BuildValidReportBase {
+    format: "python";
+    output?: never;
+    output_python: string;
+}
+export type BuildOutputValidReport = BuildOutputObjectReport | BuildOutputPythonReport;
+export type BuildOutputResponse = BuildOutputValidReport | CrateInvalidReport;
+/** One stamped generated file in the structures projection. */
+export interface GeneratedArtifact {
+    path: string;
+    content: string;
+}
+/**
+ * The typed-structures projection the runner script imports from. Write `artifacts`
+ * and `lock` (as `lock_filename`) under `directory`, relative to the runner script,
+ * and the returned `python_code` runs against them.
+ */
+export interface RunnerStructures {
+    directory: string;
+    artifacts: GeneratedArtifact[];
+    lock: string;
+    lock_filename: string;
+}
+export interface BuildRunnerValidReport extends BuildValidReportBase {
+    python_code: string;
+    structures: RunnerStructures;
+}
+export type BuildRunnerResponse = BuildRunnerValidReport | CrateInvalidReport;
 export interface ConceptResponse {
     success: boolean;
     concept_code: string;
@@ -174,3 +330,4 @@ export interface PipeSpecResponse {
     pipe_type: string;
     toml: string;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for the Pipelex hosted API — execute methods, manage runs, and call the product surface.",
   "license": "MIT",
   "repository": {
@@ -19,8 +19,10 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:hook": "node scripts/build-hook.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "typecheck": "tsc --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
     "lint": "eslint src/ tests/",
@@ -41,9 +43,11 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@pipelex/tools-wasm": "^0.1.0",
     "@types/node": "^22.12.0",
     "@vitest/coverage-v8": "^4.1.9",
     "dependency-cruiser": "^17.4.3",
+    "esbuild": "^0.25.12",
     "eslint": "^9.39.4",
     "globals": "^16.5.0",
     "prettier": "^3.8.4",
@@ -52,6 +56,6 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "mthds": "^0.16.0"
+    "mthds": "^0.19.0"
   }
 }