specli 0.0.21 → 0.0.23

package/README.md

@@ -310,6 +310,64 @@ Prints equivalent curl command without sending the request.
 
 Prints method, URL, headers, and body without sending.
 
+## Programmatic API
+
+Use specli as a library to execute OpenAPI operations programmatically:
+
+```typescript
+import { specli } from "specli";
+
+const api = await specli({
+  spec: "https://api.example.com/openapi.json",
+  bearerToken: process.env.API_TOKEN,
+});
+
+// List available resources and actions
+const resources = api.list();
+
+// Get help for a specific action
+const help = api.help("users", "get");
+
+// Execute an API call
+const result = await api.exec("users", "get", ["123"], { include: "profile" });
+if (result.ok) {
+  console.log(result.body);
+}
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `spec` | OpenAPI spec URL or file path (required) |
+| `server` | Override server/base URL |
+| `serverVars` | Server URL template variables (`Record<string, string>`) |
+| `bearerToken` | Bearer token for authentication |
+| `apiKey` | API key for authentication |
+| `basicAuth` | Basic auth credentials (`{ username, password }`) |
+| `authScheme` | Auth scheme to use (if multiple are available) |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `list()` | Returns all resources and their actions |
+| `help(resource, action)` | Get detailed info about an action |
+| `exec(resource, action, args?, flags?)` | Execute an API call |
+
+### ExecuteResult
+
+The `exec()` method returns:
+
+```typescript
+{
+  ok: boolean;     // true if status 2xx
+  status: number;  // HTTP status code
+  body: unknown;   // Parsed response body
+  curl: string;    // Equivalent curl command
+}
+```
+
 ## AI SDK Integration
 
 specli exports an AI SDK tool for use with LLM agents:

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Specli - Convert OpenAPI specs to executables, built to be agent-first
+ *
+ * @example
+ * ```ts
+ * import { specli } from "specli";
+ *
+ * const api = await specli({ spec: "https://api.example.com/openapi.json" });
+ *
+ * // List available resources and actions
+ * const resources = api.list();
+ *
+ * // Execute an API call
+ * const result = await api.exec("users", "get", ["123"]);
+ * console.log(result.body);
+ * ```
+ */
+import type { AuthScheme } from "./cli/parse/auth-schemes.js";
+import type { ServerInfo } from "./cli/parse/servers.js";
+import { type ExecuteResult } from "./cli/runtime/execute.js";
+export type SpecliOptions = {
+    /** The OpenAPI spec URL or file path */
+    spec: string;
+    /** Override the server/base URL */
+    server?: string;
+    /** Server URL template variables */
+    serverVars?: Record<string, string>;
+    /** Bearer token for authentication */
+    bearerToken?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Basic auth credentials */
+    basicAuth?: {
+        username: string;
+        password: string;
+    };
+    /** Auth scheme to use (if multiple are available) */
+    authScheme?: string;
+};
+export type ResourceInfo = {
+    name: string;
+    actions: ActionInfo[];
+};
+export type ActionInfo = {
+    name: string;
+    summary?: string;
+    method: string;
+    path: string;
+    args: string[];
+    requiredFlags: string[];
+    optionalFlags: string[];
+};
+export type ActionDetail = {
+    action: string;
+    method: string;
+    path: string;
+    summary?: string;
+    args: Array<{
+        name: string;
+        description?: string;
+    }>;
+    flags: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        description?: string;
+    }>;
+};
+export type SpecliClient = {
+    /** List all available resources and their actions */
+    list(): ResourceInfo[];
+    /** Get detailed help for a specific action */
+    help(resource: string, action: string): ActionDetail | undefined;
+    /** Execute an API action */
+    exec(resource: string, action: string, args?: string[], flags?: Record<string, unknown>): Promise<ExecuteResult>;
+    /** Get server information */
+    servers: ServerInfo[];
+    /** Get authentication schemes */
+    authSchemes: AuthScheme[];
+};
+/**
+ * Create a specli client for interacting with an OpenAPI spec.
+ *
+ * @example
+ * ```ts
+ * import { specli } from "specli";
+ *
+ * const api = await specli({
+ *   spec: "https://api.example.com/openapi.json",
+ *   bearerToken: process.env.API_TOKEN,
+ * });
+ *
+ * // List resources
+ * const resources = api.list();
+ *
+ * // Execute a call
+ * const result = await api.exec("users", "list");
+ * if (result.ok) {
+ *   console.log(result.body);
+ * }
+ * ```
+ */
+export declare function specli(options: SpecliOptions): Promise<SpecliClient>;
+export type { AuthScheme } from "./cli/parse/auth-schemes.js";
+export type { ServerInfo } from "./cli/parse/servers.js";
+export type { ExecuteResult } from "./cli/runtime/execute.js";

package/dist/index.js

@@ -0,0 +1,114 @@
+/**
+ * Specli - Convert OpenAPI specs to executables, built to be agent-first
+ *
+ * @example
+ * ```ts
+ * import { specli } from "specli";
+ *
+ * const api = await specli({ spec: "https://api.example.com/openapi.json" });
+ *
+ * // List available resources and actions
+ * const resources = api.list();
+ *
+ * // Execute an API call
+ * const result = await api.exec("users", "get", ["123"]);
+ * console.log(result.body);
+ * ```
+ */
+import { buildRuntimeContext } from "./cli/runtime/context.js";
+import { execute } from "./cli/runtime/execute.js";
+function findAction(ctx, resource, action) {
+    const r = ctx.commands.resources.find((r) => r.resource.toLowerCase() === resource.toLowerCase());
+    return r?.actions.find((a) => a.action.toLowerCase() === action.toLowerCase());
+}
+/**
+ * Create a specli client for interacting with an OpenAPI spec.
+ *
+ * @example
+ * ```ts
+ * import { specli } from "specli";
+ *
+ * const api = await specli({
+ *   spec: "https://api.example.com/openapi.json",
+ *   bearerToken: process.env.API_TOKEN,
+ * });
+ *
+ * // List resources
+ * const resources = api.list();
+ *
+ * // Execute a call
+ * const result = await api.exec("users", "list");
+ * if (result.ok) {
+ *   console.log(result.body);
+ * }
+ * ```
+ */
+export async function specli(options) {
+    const { spec, server, serverVars, bearerToken, apiKey, basicAuth, authScheme, } = options;
+    const ctx = await buildRuntimeContext({ spec });
+    const globals = {
+        server,
+        serverVar: serverVars
+            ? Object.entries(serverVars).map(([k, v]) => `${k}=${v}`)
+            : undefined,
+        auth: authScheme,
+        bearerToken,
+        apiKey,
+        username: basicAuth?.username,
+        password: basicAuth?.password,
+    };
+    return {
+        list() {
+            return ctx.commands.resources.map((r) => ({
+                name: r.resource,
+                actions: r.actions.map((a) => ({
+                    name: a.action,
+                    summary: a.summary,
+                    method: a.method,
+                    path: a.path,
+                    args: a.positionals.map((p) => p.name),
+                    requiredFlags: a.flags.filter((f) => f.required).map((f) => f.flag),
+                    optionalFlags: a.flags.filter((f) => !f.required).map((f) => f.flag),
+                })),
+            }));
+        },
+        help(resource, action) {
+            const actionDef = findAction(ctx, resource, action);
+            if (!actionDef)
+                return undefined;
+            return {
+                action: actionDef.action,
+                method: actionDef.method,
+                path: actionDef.path,
+                summary: actionDef.summary,
+                args: actionDef.positionals.map((p) => ({
+                    name: p.name,
+                    description: p.description,
+                })),
+                flags: actionDef.flags.map((f) => ({
+                    name: f.flag,
+                    type: f.type,
+                    required: f.required,
+                    description: f.description,
+                })),
+            };
+        },
+        async exec(resource, action, args = [], flags = {}) {
+            const actionDef = findAction(ctx, resource, action);
+            if (!actionDef) {
+                throw new Error(`Unknown action: ${resource} ${action}`);
+            }
+            return execute({
+                specId: ctx.loaded.id,
+                action: actionDef,
+                positionalValues: args,
+                flagValues: flags,
+                globals,
+                servers: ctx.servers,
+                authSchemes: ctx.authSchemes,
+            });
+        },
+        servers: ctx.servers,
+        authSchemes: ctx.authSchemes,
+    };
+}

package/package.json

@@ -1,23 +1,33 @@
 {
 	"name": "specli",
-	"version": "0.0.21",
+	"version": "0.0.23",
+	"description": "Run any OpenAPI spec as a CLI. Built for Agents.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/AndrewBarba/specli.git"
+	},
 	"type": "module",
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
-	"bin": {
-		"specli": "./bin/cli.sh"
-	},
 	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
 		"./ai/tools": {
 			"import": "./dist/ai/tools.js",
 			"types": "./dist/ai/tools.d.ts"
 		}
 	},
+	"bin": {
+		"specli": "./bin/cli.sh"
+	},
 	"files": [
 		"bin",
 		"dist",
 		"README.md",
-		"package.json"
+		"package.json",
+		"!**/*.test.*"
 	],
 	"scripts": {
 		"build": "tsc",
@@ -27,14 +37,6 @@
 		"lint:format": "biome format --write",
 		"typecheck": "tsgo"
 	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.3.11",
-		"@tsconfig/node22": "^22.0.5",
-		"@types/bun": "^1.3.6",
-		"@types/node": "^22.19.7",
-		"@typescript/native-preview": "^7.0.0-dev.20260122.3",
-		"typescript": "^5.9.3"
-	},
 	"dependencies": {
 		"@apidevtools/swagger-parser": "^12.1.0",
 		"ajv": "^8.17.1",
@@ -47,8 +49,12 @@
 		"ai": "^6.0.0",
 		"zod": "^4.0.0"
 	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/AndrewBarba/specli.git"
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.11",
+		"@tsconfig/node22": "^22.0.5",
+		"@types/bun": "^1.3.6",
+		"@types/node": "^22.19.7",
+		"@typescript/native-preview": "^7.0.0-dev.20260122.3",
+		"typescript": "^5.9.3"
 	}
 }

package/dist/ai/tools.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/ai/tools.test.js

@@ -1,49 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { specli } from "./tools.js";
-const mockOptions = {
-    toolCallId: "test-call-id",
-    abortSignal: new AbortController().signal,
-    messages: [],
-};
-describe("specli tool", () => {
-    test("creates a tool with correct structure", async () => {
-        const tool = await specli({
-            spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-        });
-        expect(tool).toHaveProperty("description");
-        expect(tool).toHaveProperty("inputSchema");
-        expect(tool).toHaveProperty("execute");
-        expect(typeof tool.execute).toBe("function");
-    });
-    test("list command returns resources", async () => {
-        const tool = await specli({
-            spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-        });
-        const result = (await tool.execute?.({ command: "list" }, mockOptions));
-        expect(result).toHaveProperty("resources");
-        expect(Array.isArray(result.resources)).toBe(true);
-    });
-    test("help command returns action details", async () => {
-        const tool = await specli({
-            spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-        });
-        const result = (await tool.execute?.({ command: "help", resource: "pets", action: "get" }, mockOptions));
-        expect(result).toHaveProperty("action");
-        expect(result.action).toBe("get");
-    });
-    test("help command with missing resource returns error", async () => {
-        const tool = await specli({
-            spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-        });
-        const result = (await tool.execute?.({ command: "help" }, mockOptions));
-        expect(result).toHaveProperty("error");
-    });
-    test("exec command with missing args returns error", async () => {
-        const tool = await specli({
-            spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-        });
-        const result = (await tool.execute?.({ command: "exec", resource: "pets", action: "get" }, mockOptions));
-        expect(result).toHaveProperty("error");
-        expect(result.error).toContain("Missing args");
-    });
-});

package/dist/cli/model/capabilities.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/model/capabilities.test.js

@@ -1,84 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { deriveCapabilities } from "./capabilities.js";
-describe("deriveCapabilities", () => {
-    test("reports requestBody + server vars", () => {
-        const doc = {
-            openapi: "3.0.3",
-            security: [{ bearerAuth: [] }],
-        };
-        const servers = [
-            {
-                url: "https://{region}.api.example.com",
-                variables: [],
-                variableNames: ["region"],
-            },
-        ];
-        const authSchemes = [
-            { key: "bearerAuth", kind: "http-bearer" },
-        ];
-        const operations = [
-            {
-                key: "POST /contacts",
-                method: "POST",
-                path: "/contacts",
-                tags: [],
-                parameters: [],
-                requestBody: {
-                    required: true,
-                    contentTypes: ["application/json"],
-                    schemasByContentType: { "application/json": { type: "object" } },
-                },
-            },
-        ];
-        const commands = {
-            resources: [
-                {
-                    resource: "contacts",
-                    actions: [
-                        {
-                            id: "x",
-                            key: "POST /contacts",
-                            action: "create",
-                            pathArgs: [],
-                            method: "POST",
-                            path: "/contacts",
-                            tags: [],
-                            style: "rest",
-                            positionals: [],
-                            flags: [],
-                            params: [],
-                            auth: { alternatives: [] },
-                            requestBody: {
-                                required: true,
-                                content: [
-                                    {
-                                        contentType: "application/json",
-                                        required: true,
-                                        schemaType: "object",
-                                    },
-                                ],
-                                hasJson: true,
-                                hasFormUrlEncoded: false,
-                                hasMultipart: false,
-                                bodyFlags: ["--data", "--file"],
-                                preferredContentType: "application/json",
-                            },
-                        },
-                    ],
-                },
-            ],
-        };
-        const caps = deriveCapabilities({
-            doc,
-            servers,
-            authSchemes,
-            operations,
-            commands,
-        });
-        expect(caps.servers.hasVariables).toBe(true);
-        expect(caps.operations.hasRequestBodies).toBe(true);
-        expect(caps.commands.hasRequestBodies).toBe(true);
-        expect(caps.auth.hasSecurityRequirements).toBe(true);
-        expect(caps.auth.kinds).toEqual(["http-bearer"]);
-    });
-});

package/dist/cli/model/command-id.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/model/command-id.test.js

@@ -1,27 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { buildCommandId } from "./command-id.js";
-describe("buildCommandId", () => {
-    test("includes spec/resource/action/op", () => {
-        expect(buildCommandId({
-            specId: "contacts-api",
-            resource: "contacts",
-            action: "get",
-            operationKey: "GET /contacts/{id}",
-        })).toBe("contacts-api:contacts:get:get-contacts-id");
-    });
-    test("disambiguates by operationKey", () => {
-        const a = buildCommandId({
-            specId: "x",
-            resource: "contacts",
-            action: "list",
-            operationKey: "GET /contacts",
-        });
-        const b = buildCommandId({
-            specId: "x",
-            resource: "contacts",
-            action: "list",
-            operationKey: "GET /contacts/search",
-        });
-        expect(a).not.toBe(b);
-    });
-});

package/dist/cli/model/command-model.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/model/command-model.test.js

@@ -1,40 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { buildCommandModel } from "./command-model.js";
-describe("buildCommandModel", () => {
-    test("groups operations by resource", () => {
-        const planned = [
-            {
-                key: "GET /contacts",
-                method: "GET",
-                path: "/contacts",
-                tags: ["Contacts"],
-                parameters: [],
-                resource: "contacts",
-                action: "list",
-                canonicalAction: "list",
-                pathArgs: [],
-                style: "rest",
-            },
-            {
-                key: "GET /contacts/{id}",
-                method: "GET",
-                path: "/contacts/{id}",
-                tags: ["Contacts"],
-                parameters: [],
-                resource: "contacts",
-                action: "get",
-                canonicalAction: "get",
-                pathArgs: ["id"],
-                style: "rest",
-            },
-        ];
-        const model = buildCommandModel(planned, { specId: "contacts-api" });
-        expect(model.resources).toHaveLength(1);
-        expect(model.resources[0]?.resource).toBe("contacts");
-        expect(model.resources[0]?.actions).toHaveLength(2);
-        expect(model.resources[0]?.actions.map((a) => a.action)).toEqual([
-            "get",
-            "list",
-        ]);
-    });
-});

package/dist/cli/model/naming.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/model/naming.test.js

@@ -1,75 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { planOperation } from "./naming.js";
-describe("planOperation", () => {
-    test("REST: GET /contacts -> contacts list", () => {
-        const op = {
-            key: "GET /contacts",
-            method: "GET",
-            path: "/contacts",
-            operationId: "Contacts.List",
-            tags: ["Contacts"],
-            parameters: [],
-        };
-        const planned = planOperation(op);
-        expect(planned.style).toBe("rest");
-        expect(planned.resource).toBe("contacts");
-        expect(planned.action).toBe("list");
-        expect(planned.pathArgs).toEqual([]);
-    });
-    test("REST: singleton /ping stays ping and prefers operationId action", () => {
-        const op = {
-            key: "GET /ping",
-            method: "GET",
-            path: "/ping",
-            operationId: "Ping.Get",
-            tags: [],
-            parameters: [],
-        };
-        const planned = planOperation(op);
-        expect(planned.style).toBe("rest");
-        expect(planned.resource).toBe("ping");
-        expect(planned.action).toBe("get");
-    });
-    test("REST: singular path pluralizes to contacts", () => {
-        const op = {
-            key: "GET /contact/{id}",
-            method: "GET",
-            path: "/contact/{id}",
-            tags: [],
-            parameters: [],
-        };
-        const planned = planOperation(op);
-        expect(planned.style).toBe("rest");
-        expect(planned.resource).toBe("contacts");
-        expect(planned.action).toBe("get");
-        expect(planned.pathArgs).toEqual(["id"]);
-    });
-    test("RPC: POST /Contacts.List -> contacts list", () => {
-        const op = {
-            key: "POST /Contacts.List",
-            method: "POST",
-            path: "/Contacts.List",
-            operationId: "Contacts.List",
-            tags: [],
-            parameters: [],
-        };
-        const planned = planOperation(op);
-        expect(planned.style).toBe("rpc");
-        expect(planned.resource).toBe("contacts");
-        expect(planned.action).toBe("list");
-    });
-    test("RPC: Retrieve canonicalizes to get", () => {
-        const op = {
-            key: "POST /Contacts.Retrieve",
-            method: "POST",
-            path: "/Contacts.Retrieve",
-            operationId: "Contacts.Retrieve",
-            tags: [],
-            parameters: [],
-        };
-        const planned = planOperation(op);
-        expect(planned.style).toBe("rpc");
-        expect(planned.resource).toBe("contacts");
-        expect(planned.action).toBe("get");
-    });
-});

package/dist/cli/parse/auth-requirements.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/parse/auth-requirements.test.js

@@ -1,16 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { summarizeAuth } from "./auth-requirements.js";
-describe("summarizeAuth", () => {
-    test("uses operation-level security when present", () => {
-        const schemes = [{ key: "oauth", kind: "oauth2" }];
-        const summary = summarizeAuth([{ oauth: ["read:ping"] }], [{ oauth: ["read:other"] }], schemes);
-        expect(summary.alternatives).toEqual([
-            [{ key: "oauth", scopes: ["read:ping"] }],
-        ]);
-    });
-    test("empty operation security disables auth", () => {
-        const schemes = [{ key: "oauth", kind: "oauth2" }];
-        const summary = summarizeAuth([], [{ oauth: ["read:other"] }], schemes);
-        expect(summary.alternatives).toEqual([]);
-    });
-});

package/dist/cli/parse/auth-schemes.test.d.ts

@@ -1 +0,0 @@
-export {};