mthds 0.0.3 → 0.0.4

package/README.md

@@ -1,12 +1,14 @@
 # mthds
 
-CLI for installing and managing **methods** — reusable workflows for AI coding agents.
+CLI and SDK for **methods** — reusable workflows for AI coding agents.
 
 ## What is a method?
 
 A method is a packaged workflow that an AI agent (like Claude Code) can use. Methods are stored in a registry and installed locally via their unique slug.
 
-## Install a method
+## CLI Usage
+
+### Install a method
 
 ```bash
 npx mthds install <slug>
@@ -27,7 +29,7 @@ The CLI will:
 | Local | `<cwd>/.claude/methods/<slug>/` |
 | Global | `~/.claude/methods/<slug>/` |
 
-## Install software runtime
+### Install software runtime
 
 ```bash
 npx mthds setup software pipelex
@@ -35,6 +37,81 @@ npx mthds setup software pipelex
 
 Installs [uv](https://docs.astral.sh/uv/) and [pipelex](https://pipelex.dev) so methods that depend on them can run.
 
+## SDK Usage
+
+Install the package:
+
+```bash
+npm install mthds
+```
+
+### Basic example
+
+```typescript
+import { MthdsApiClient } from "mthds";
+
+const client = new MthdsApiClient({
+  apiBaseUrl: "https://api.pipelex.com",
+  apiToken: "your-api-key",
+});
+
+const result = await client.executePipeline({
+  pipe_code: "my-pipeline",
+  inputs: {
+    topic: "quantum computing",
+  },
+});
+
+console.log(result.pipe_output);
+```
+
+The hosted API at `https://api.pipelex.com` is coming soon. In the meantime, you can run the API yourself.
+
+### Self-hosted API
+
+Point the client to your own server:
+
+```typescript
+const client = new MthdsApiClient({
+  apiBaseUrl: "http://localhost:8081",
+  apiToken: "your-api-key",
+});
+```
+
+### Environment variables
+
+Instead of passing options to the constructor, you can set environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `MTHDS_API_BASE_URL` | Base URL of the API |
+| `MTHDS_API_KEY` | API authentication token |
+
+```typescript
+// Reads MTHDS_API_BASE_URL and MTHDS_API_KEY from the environment
+const client = new MthdsApiClient();
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `executePipeline(options)` | Execute a pipeline and wait for the result |
+| `startPipeline(options)` | Start a pipeline asynchronously |
+
+### Pipeline options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `pipe_code` | `string` | Pipeline code to execute |
+| `mthds_content` | `string` | Raw method content (alternative to `pipe_code`) |
+| `inputs` | `Record<string, string \| string[] \| object>` | Pipeline input variables |
+| `output_name` | `string` | Name of the output to return |
+| `output_multiplicity` | `boolean \| number` | Expected output multiplicity |
+| `dynamic_output_concept_code` | `string` | Dynamic output concept code |
+
+Either `pipe_code` or `mthds_content` must be provided.
+
 ## Telemetry
 
 Anonymous usage data (method slug + timestamp) is collected to help rank methods on the leaderboard. No personal or device information is collected.

package/dist/client/client.d.ts

@@ -0,0 +1,15 @@
+import type { RunnerProtocol } from "./protocol.js";
+import type { ExecutePipelineOptions, PipelineExecuteResponse, PipelineStartResponse } from "./pipeline.js";
+interface MthdsApiClientOptions {
+    apiToken?: string;
+    apiBaseUrl?: string;
+}
+export declare class MthdsApiClient implements RunnerProtocol {
+    private readonly apiToken;
+    private readonly apiBaseUrl;
+    constructor(options?: MthdsApiClientOptions);
+    private makeApiCall;
+    executePipeline(options: ExecutePipelineOptions): Promise<PipelineExecuteResponse>;
+    startPipeline(options: ExecutePipelineOptions): Promise<PipelineStartResponse>;
+}
+export {};

package/dist/client/client.js

@@ -0,0 +1,64 @@
+import { ClientAuthenticationError, PipelineRequestError, } from "./exceptions.js";
+export class MthdsApiClient {
+    apiToken;
+    apiBaseUrl;
+    constructor(options = {}) {
+        this.apiToken = options.apiToken ?? process.env.MTHDS_API_KEY;
+        const resolvedBaseUrl = options.apiBaseUrl ?? process.env.MTHDS_API_BASE_URL;
+        if (!resolvedBaseUrl) {
+            throw new ClientAuthenticationError("API base URL is required for API execution");
+        }
+        this.apiBaseUrl = resolvedBaseUrl.replace(/\/+$/, "");
+    }
+    async makeApiCall(endpoint, pipelineRequest) {
+        const url = `${this.apiBaseUrl}/${endpoint}`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiToken) {
+            headers["Authorization"] = `Bearer ${this.apiToken}`;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(pipelineRequest),
+            signal: AbortSignal.timeout(1_200_000),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new PipelineRequestError(`API POST /${endpoint} failed (${response.status}): ${text || response.statusText}`);
+        }
+        return response.json();
+    }
+    async executePipeline(options) {
+        if (!options.pipe_code && !options.mthds_content) {
+            throw new PipelineRequestError("Either pipe_code or mthds_content must be provided to executePipeline.");
+        }
+        const request = {
+            pipe_code: options.pipe_code,
+            mthds_content: options.mthds_content,
+            inputs: options.inputs,
+            output_name: options.output_name,
+            output_multiplicity: options.output_multiplicity,
+            dynamic_output_concept_code: options.dynamic_output_concept_code,
+        };
+        const data = await this.makeApiCall("api/v1/pipeline/execute", request);
+        return data;
+    }
+    async startPipeline(options) {
+        if (!options.pipe_code && !options.mthds_content) {
+            throw new PipelineRequestError("Either pipe_code or mthds_content must be provided to startPipeline.");
+        }
+        const request = {
+            pipe_code: options.pipe_code,
+            mthds_content: options.mthds_content,
+            inputs: options.inputs,
+            output_name: options.output_name,
+            output_multiplicity: options.output_multiplicity,
+            dynamic_output_concept_code: options.dynamic_output_concept_code,
+        };
+        const data = await this.makeApiCall("api/v1/pipeline/start", request);
+        return data;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client/client.js.map

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

package/dist/client/exceptions.d.ts

@@ -0,0 +1,6 @@
+export declare class ClientAuthenticationError extends Error {
+    constructor(message: string);
+}
+export declare class PipelineRequestError extends Error {
+    constructor(message: string);
+}

package/dist/client/exceptions.js

@@ -0,0 +1,13 @@
+export class ClientAuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClientAuthenticationError";
+    }
+}
+export class PipelineRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PipelineRequestError";
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/client/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/client/exceptions.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { MthdsApiClient } from "./client.js";
+export type { RunnerProtocol } from "./protocol.js";
+export { ClientAuthenticationError, PipelineRequestError, } from "./exceptions.js";
+export type { PipelineState, PipelineRequest, PipelineExecuteResponse, PipelineStartResponse, ExecutePipelineOptions, } from "./pipeline.js";
+export type { DictStuff, DictWorkingMemory, DictPipeOutput, VariableMultiplicity, StuffContentOrData, PipelineInputs, } from "./models/index.js";

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { MthdsApiClient } from "./client.js";
+export { ClientAuthenticationError, PipelineRequestError, } from "./exceptions.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/client/models/index.d.ts

@@ -0,0 +1,4 @@
+export type { DictStuff } from "./stuff.js";
+export type { DictWorkingMemory } from "./working_memory.js";
+export type { DictPipeOutput, VariableMultiplicity } from "./pipe_output.js";
+export type { StuffContentOrData, PipelineInputs } from "./pipeline_inputs.js";

package/dist/client/models/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/client/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/models/index.ts"],"names":[],"mappings":""}

package/dist/client/models/pipe_output.d.ts

@@ -0,0 +1,2 @@
+export type { DictPipeOutput } from "../../runners/types.js";
+export type VariableMultiplicity = boolean | number;

package/dist/client/models/pipe_output.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipe_output.js.map

package/dist/client/models/pipe_output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe_output.js","sourceRoot":"","sources":["../../../src/client/models/pipe_output.ts"],"names":[],"mappings":""}

package/dist/client/models/pipeline_inputs.d.ts

@@ -0,0 +1,3 @@
+import type { DictStuff } from "./stuff.js";
+export type StuffContentOrData = string | string[] | Record<string, unknown> | DictStuff;
+export type PipelineInputs = Record<string, StuffContentOrData>;

package/dist/client/models/pipeline_inputs.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline_inputs.js.map

package/dist/client/models/pipeline_inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline_inputs.js","sourceRoot":"","sources":["../../../src/client/models/pipeline_inputs.ts"],"names":[],"mappings":""}

package/dist/client/models/stuff.d.ts

@@ -0,0 +1 @@
+export type { DictStuff } from "../../runners/types.js";

package/dist/client/models/stuff.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stuff.js.map

package/dist/client/models/stuff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuff.js","sourceRoot":"","sources":["../../../src/client/models/stuff.ts"],"names":[],"mappings":""}

package/dist/client/models/working_memory.d.ts

@@ -0,0 +1 @@
+export type { DictWorkingMemory } from "../../runners/types.js";

package/dist/client/models/working_memory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=working_memory.js.map

package/dist/client/models/working_memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"working_memory.js","sourceRoot":"","sources":["../../../src/client/models/working_memory.ts"],"names":[],"mappings":""}

package/dist/client/pipeline.d.ts

@@ -0,0 +1,36 @@
+import type { DictPipeOutput } from "./models/pipe_output.js";
+import type { VariableMultiplicity } from "./models/pipe_output.js";
+import type { PipelineInputs } from "./models/pipeline_inputs.js";
+export type { PipelineState } from "../runners/types.js";
+export interface PipelineRequest {
+    pipe_code?: string | null;
+    mthds_content?: string | null;
+    inputs?: PipelineInputs | null;
+    output_name?: string | null;
+    output_multiplicity?: VariableMultiplicity | null;
+    dynamic_output_concept_code?: string | null;
+}
+export interface PipelineExecuteResponse {
+    pipeline_run_id: string;
+    created_at: string;
+    pipeline_state: string;
+    finished_at?: string | null;
+    main_stuff_name?: string | null;
+    pipe_output: DictPipeOutput;
+}
+export interface PipelineStartResponse {
+    pipeline_run_id: string;
+    created_at: string;
+    pipeline_state: string;
+    finished_at?: string | null;
+    main_stuff_name?: string | null;
+    pipe_output?: DictPipeOutput | null;
+}
+export interface ExecutePipelineOptions {
+    pipe_code?: string | null;
+    mthds_content?: string | null;
+    inputs?: PipelineInputs | null;
+    output_name?: string | null;
+    output_multiplicity?: VariableMultiplicity | null;
+    dynamic_output_concept_code?: string | null;
+}

package/dist/client/pipeline.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline.js.map

package/dist/client/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/client/pipeline.ts"],"names":[],"mappings":""}

package/dist/client/protocol.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutePipelineOptions, PipelineExecuteResponse, PipelineStartResponse } from "./pipeline.js";
+export interface RunnerProtocol {
+    executePipeline(options: ExecutePipelineOptions): Promise<PipelineExecuteResponse>;
+    startPipeline(options: ExecutePipelineOptions): Promise<PipelineStartResponse>;
+}

package/dist/client/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/client/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/client/protocol.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./client/index.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./client/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "mthds",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "CLI for composable methods for AI agents. Turn your knowledge processes into executable methods.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Pipelex/mthds-js"
+    "url": "https://github.com/mthds-ai/mthds-js"
   },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "bin": {
     "mthds": "./dist/cli.js"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "example": "npx tsx examples/call_api.ts"
   },
   "files": [
     "dist/"
@@ -30,6 +39,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.12.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.3"
   }
 }