specli 0.0.23 → 0.0.24

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

@@ -15,69 +15,7 @@
  * 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[];
-};
+import { type SpecliClient, type SpecliOptions } from "./client/index.js";
 /**
  * Create a specli client for interacting with an OpenAPI spec.
  *
@@ -101,6 +39,4 @@ export type SpecliClient = {
  * ```
  */
 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";
+export type { ActionDetail, ActionInfo, AuthScheme, ExecuteResult, ResourceInfo, ServerInfo, SpecliClient, SpecliOptions, } from "./client/index.js";

package/dist/index.js

@@ -15,12 +15,7 @@
  * 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());
-}
+import { createClient, } from "./client/index.js";
 /**
  * Create a specli client for interacting with an OpenAPI spec.
  *
@@ -44,71 +39,5 @@ function findAction(ctx, resource, action) {
  * ```
  */
 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,
-    };
+    return createClient(options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "specli",
-	"version": "0.0.23",
+	"version": "0.0.24",
 	"description": "Run any OpenAPI spec as a CLI. Built for Agents.",
 	"repository": {
 		"type": "git",