specli 0.0.22 → 0.0.24

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/ai/tools.d.ts

@@ -5,70 +5,36 @@
  *
  * @example
  * ```ts
- * import { specli } from "specli/ai";
+ * import { specliTool } from "specli/ai/tools";
  * import { generateText } from "ai";
  *
  * const result = await generateText({
  *   model: yourModel,
  *   tools: {
- *     api: await specli({ spec: "https://api.example.com/openapi.json" }),
+ *     api: await specliTool({ spec: "https://api.example.com/openapi.json" }),
  *   },
  *   prompt: "List all users",
  * });
  * ```
  */
-export type SpecliToolOptions = {
-    /** 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;
-};
+import { type SpecliOptions } from "../client/index.js";
 /**
  * Create an AI SDK tool for interacting with an OpenAPI spec.
  *
  * The spec is fetched once when this function is called, so the returned
  * tool already has the spec loaded and ready to use.
  */
-export declare function specli(options: SpecliToolOptions): Promise<import("ai").Tool<{
+export declare function specliTool(options: SpecliOptions): Promise<import("ai").Tool<{
     command: "list" | "exec" | "help";
     resource?: string | undefined;
     action?: string | undefined;
     args?: string[] | undefined;
     flags?: Record<string, unknown> | undefined;
-}, {
-    resources: {
-        name: string;
-        actions: {
-            name: string;
-            summary: string | undefined;
-            method: string;
-            path: string;
-            args: string[];
-            requiredFlags: string[];
-        }[];
-    }[];
+}, import("../client/index.js").ActionDetail | {
+    resources: import("../client/index.js").ResourceInfo[];
     error?: undefined;
     resource?: undefined;
     actions?: undefined;
-    action?: undefined;
-    method?: undefined;
-    path?: undefined;
-    summary?: undefined;
-    args?: undefined;
-    flags?: undefined;
     status?: undefined;
     ok?: undefined;
     body?: undefined;
@@ -77,12 +43,6 @@ export declare function specli(options: SpecliToolOptions): Promise<import("ai")
     resources?: undefined;
     resource?: undefined;
     actions?: undefined;
-    action?: undefined;
-    method?: undefined;
-    path?: undefined;
-    summary?: undefined;
-    args?: undefined;
-    flags?: undefined;
     status?: undefined;
     ok?: undefined;
     body?: undefined;
@@ -91,34 +51,6 @@ export declare function specli(options: SpecliToolOptions): Promise<import("ai")
     actions: string[];
     resources?: undefined;
     error?: undefined;
-    action?: undefined;
-    method?: undefined;
-    path?: undefined;
-    summary?: undefined;
-    args?: undefined;
-    flags?: undefined;
-    status?: undefined;
-    ok?: undefined;
-    body?: undefined;
-} | {
-    action: string;
-    method: string;
-    path: string;
-    summary: string | undefined;
-    args: {
-        name: string;
-        description: string | undefined;
-    }[];
-    flags: {
-        name: string;
-        type: import("../cli/parse/schema-shape.js").ParamType;
-        required: boolean;
-        description: string | undefined;
-    }[];
-    resources?: undefined;
-    error?: undefined;
-    resource?: undefined;
-    actions?: undefined;
     status?: undefined;
     ok?: undefined;
     body?: undefined;
@@ -130,10 +62,6 @@ export declare function specli(options: SpecliToolOptions): Promise<import("ai")
     error?: undefined;
     resource?: undefined;
     actions?: undefined;
-    action?: undefined;
-    method?: undefined;
-    path?: undefined;
-    summary?: undefined;
-    args?: undefined;
-    flags?: undefined;
 }>>;
+export { specliTool as specli };
+export type { SpecliOptions as SpecliToolOptions } from "../client/index.js";

package/dist/ai/tools.js

@@ -5,13 +5,13 @@
  *
  * @example
  * ```ts
- * import { specli } from "specli/ai";
+ * import { specliTool } from "specli/ai/tools";
  * import { generateText } from "ai";
  *
  * const result = await generateText({
  *   model: yourModel,
  *   tools: {
- *     api: await specli({ spec: "https://api.example.com/openapi.json" }),
+ *     api: await specliTool({ spec: "https://api.example.com/openapi.json" }),
  *   },
  *   prompt: "List all users",
  * });
@@ -19,22 +19,15 @@
  */
 import { tool } from "ai";
 import { z } from "zod";
-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());
-}
+import { createClient } from "../client/index.js";
 /**
  * Create an AI SDK tool for interacting with an OpenAPI spec.
  *
  * The spec is fetched once when this function is called, so the returned
  * tool already has the spec loaded and ready to use.
  */
-export async function specli(options) {
-    const { spec, server, serverVars, bearerToken, apiKey, basicAuth, authScheme, } = options;
-    // Fetch and parse the spec upfront
-    const ctx = await buildRuntimeContext({ spec });
+export async function specliTool(options) {
+    const client = await createClient(options);
     return tool({
         description: `Execute API operations. Commands: "list" (show resources/actions), "help" (action details), "exec" (call API).`,
         inputSchema: z.object({
@@ -52,90 +45,32 @@ export async function specli(options) {
         }),
         execute: async ({ command, resource, action, args, flags }) => {
             if (command === "list") {
-                return {
-                    resources: 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),
-                        })),
-                    })),
-                };
+                return { resources: client.list() };
             }
             if (command === "help") {
                 if (!resource)
                     return { error: "Missing resource" };
-                const r = ctx.commands.resources.find((r) => r.resource.toLowerCase() === resource.toLowerCase());
-                if (!r)
-                    return { error: `Unknown resource: ${resource}` };
                 if (!action) {
+                    // List actions for a resource
+                    const resources = client.list();
+                    const r = resources.find((r) => r.name.toLowerCase() === resource.toLowerCase());
+                    if (!r)
+                        return { error: `Unknown resource: ${resource}` };
                     return {
-                        resource: r.resource,
-                        actions: r.actions.map((a) => a.action),
+                        resource: r.name,
+                        actions: r.actions.map((a) => a.name),
                     };
                 }
-                const a = r.actions.find((a) => a.action.toLowerCase() === action.toLowerCase());
-                if (!a)
-                    return { error: `Unknown action: ${action}` };
-                return {
-                    action: a.action,
-                    method: a.method,
-                    path: a.path,
-                    summary: a.summary,
-                    args: a.positionals.map((p) => ({
-                        name: p.name,
-                        description: p.description,
-                    })),
-                    flags: a.flags.map((f) => ({
-                        name: f.flag,
-                        type: f.type,
-                        required: f.required,
-                        description: f.description,
-                    })),
-                };
+                const detail = client.help(resource, action);
+                if (!detail)
+                    return { error: `Unknown: ${resource} ${action}` };
+                return detail;
             }
             if (command === "exec") {
                 if (!resource || !action)
                     return { error: "Missing resource or action" };
-                const actionDef = findAction(ctx, resource, action);
-                if (!actionDef)
-                    return { error: `Unknown: ${resource} ${action}` };
-                const positionalValues = args ?? [];
-                if (positionalValues.length < actionDef.positionals.length) {
-                    return {
-                        error: `Missing args: ${actionDef.positionals
-                            .slice(positionalValues.length)
-                            .map((p) => p.name)
-                            .join(", ")}`,
-                    };
-                }
-                const globals = {
-                    server,
-                    serverVar: serverVars
-                        ? Object.entries(serverVars).map(([k, v]) => `${k}=${v}`)
-                        : undefined,
-                    auth: authScheme,
-                    bearerToken,
-                    apiKey,
-                    username: basicAuth?.username,
-                    password: basicAuth?.password,
-                };
                 try {
-                    const result = await execute({
-                        specId: ctx.loaded.id,
-                        action: actionDef,
-                        positionalValues,
-                        flagValues: flags ?? {},
-                        globals,
-                        servers: ctx.servers,
-                        authSchemes: ctx.authSchemes,
-                    });
+                    const result = await client.exec(resource, action, args ?? [], flags ?? {});
                     return { status: result.status, ok: result.ok, body: result.body };
                 }
                 catch (err) {
@@ -146,3 +81,5 @@ export async function specli(options) {
         },
     });
 }
+// Re-export for backwards compatibility
+export { specliTool as specli };

package/dist/client/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Specli Client - Core programmatic API for OpenAPI specs
+ */
+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.
+ */
+export declare function createClient(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/client/index.js

@@ -0,0 +1,81 @@
+/**
+ * Specli Client - Core programmatic API for OpenAPI specs
+ */
+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.
+ */
+export async function createClient(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/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 SpecliClient, type SpecliOptions } from "./client/index.js";
+/**
+ * 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 { ActionDetail, ActionInfo, AuthScheme, ExecuteResult, ResourceInfo, ServerInfo, SpecliClient, SpecliOptions, } from "./client/index.js";

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * 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 { createClient, } from "./client/index.js";
+/**
+ * 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) {
+    return createClient(options);
+}

package/package.json

@@ -1,18 +1,27 @@
 {
 	"name": "specli",
-	"version": "0.0.22",
+	"version": "0.0.24",
+	"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",
@@ -28,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",
@@ -48,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"
 	}
 }