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