@supertools-ai/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+export { z } from 'zod';
+
+declare const TOOL_BRAND: unique symbol;
+type ZodSchema = z.ZodType;
+type InferInput<T extends ZodSchema> = z.infer<T>;
+type ExecuteFn<T extends ZodSchema> = (params: InferInput<T>) => unknown | Promise<unknown>;
+interface ToolDefinition<T extends ZodSchema> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: T;
+    readonly execute: ExecuteFn<T>;
+}
+interface Tool<T extends ZodSchema = ZodSchema> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: T;
+    readonly execute: ExecuteFn<T>;
+    readonly [TOOL_BRAND]: true;
+}
+interface NormalizedParameter {
+    readonly name: string;
+    readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'any';
+    readonly description: string;
+    readonly required: boolean;
+    readonly default?: unknown;
+}
+interface NormalizedTool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: readonly NormalizedParameter[];
+    readonly execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+/**
+ * Define a tool with type-safe parameters.
+ *
+ * @example
+ * const searchUsers = defineTool({
+ *   name: 'searchUsers',
+ *   description: 'Search users by name or email',
+ *   parameters: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().optional().default(10),
+ *   }),
+ *   execute: async ({ query, limit }) => db.users.search(query).limit(limit),
+ * });
+ */
+declare function defineTool<T extends ZodSchema>(definition: ToolDefinition<T>): Tool<T>;
+declare function isTool(value: unknown): value is Tool;
+declare function normalizeTools(tools: readonly Tool[]): NormalizedTool[];
+
+type ToolCollection = readonly Tool[];
+interface ExecutionResult {
+    readonly success: boolean;
+    readonly output: string;
+    readonly error?: string;
+    readonly executionTimeMs: number;
+    readonly images?: readonly string[];
+}
+interface GeneratedCode {
+    readonly code: string;
+    readonly explanation?: string;
+    readonly rawResponse?: string;
+}
+interface ProgrammaticResult {
+    readonly code: string;
+    readonly explanation?: string;
+    readonly result: ExecutionResult;
+}
+interface ToolCallRequest {
+    readonly tool: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+interface ToolCallResponse {
+    readonly success: boolean;
+    readonly result?: unknown;
+    readonly error?: string;
+}
+interface LLMAdapter {
+    generateCode(userRequest: string, systemPrompt: string): Promise<GeneratedCode>;
+}
+interface ExecutorConfig {
+    readonly tools: ToolCollection;
+    readonly timeout?: number;
+    readonly e2bApiKey?: string;
+    readonly instructions?: string;
+    readonly debug?: boolean;
+}
+
+/**
+ * Programmatic Executor
+ *
+ * Orchestrates the complete flow:
+ * 1. LLM generates JavaScript code
+ * 2. Code executes in secure E2B Bun sandbox
+ * 3. Tool calls relay back to host via WebSocket
+ * 4. Results return to user
+ */
+
+interface CreateExecutorOptions extends ExecutorConfig {
+    readonly llm: LLMAdapter;
+}
+declare function createExecutor(options: CreateExecutorOptions): ProgrammaticExecutor;
+declare class ProgrammaticExecutor {
+    private readonly originalTools;
+    private readonly normalizedTools;
+    private readonly toolsMap;
+    private readonly llm;
+    private readonly timeout;
+    private readonly e2bApiKey?;
+    private readonly instructions?;
+    private readonly debug;
+    constructor(options: CreateExecutorOptions);
+    run(userRequest: string): Promise<ProgrammaticResult>;
+    executeCode(code: string): Promise<ExecutionResult>;
+    getTools(): readonly NormalizedTool[];
+    getToolDocumentation(): string;
+    private generateCode;
+    private createSandbox;
+    private connectRelay;
+    private cleanup;
+    private log;
+}
+
+type ErrorCode = 'CODE_GENERATION_ERROR' | 'EXECUTION_ERROR' | 'TOOL_ERROR' | 'RELAY_CONNECTION_ERROR' | 'RELAY_TIMEOUT_ERROR' | 'PROTOCOL_ERROR' | 'SANDBOX_ERROR' | 'AUTHENTICATION_ERROR' | 'VALIDATION_ERROR' | 'CONFIGURATION_ERROR';
+declare class OPTError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: Error;
+    constructor(message: string, code: ErrorCode, cause?: Error);
+    toJSON(): {
+        name: string;
+        code: ErrorCode;
+        message: string;
+        cause: string | undefined;
+    };
+}
+declare class CodeGenerationError extends OPTError {
+    constructor(message: string, cause?: Error);
+}
+declare class ExecutionError extends OPTError {
+    readonly output?: string;
+    constructor(message: string, output?: string, cause?: Error);
+    toJSON(): {
+        output: string | undefined;
+        name: string;
+        code: ErrorCode;
+        message: string;
+        cause: string | undefined;
+    };
+}
+declare class ToolError extends OPTError {
+    readonly toolName: string;
+    constructor(message: string, toolName: string, cause?: Error);
+    toJSON(): {
+        toolName: string;
+        name: string;
+        code: ErrorCode;
+        message: string;
+        cause: string | undefined;
+    };
+}
+declare class RelayConnectionError extends OPTError {
+    constructor(message: string, cause?: Error);
+}
+declare class RelayTimeoutError extends OPTError {
+    constructor(message: string);
+}
+declare class SandboxError extends OPTError {
+    constructor(message: string, cause?: Error);
+}
+declare class AuthenticationError extends OPTError {
+    constructor(message: string);
+}
+declare class ConfigurationError extends OPTError {
+    constructor(message: string);
+}
+
+declare function buildSystemPrompt(toolDefinitions: string, additionalInstructions?: string): string;
+declare function extractCode(response: string): string;
+
+declare function generateTypeHints(tools: readonly Tool[]): string;
+
+export { AuthenticationError, CodeGenerationError, ConfigurationError, type CreateExecutorOptions, ExecutionError, type ExecutionResult, type ExecutorConfig, type GeneratedCode, type LLMAdapter, type NormalizedParameter, type NormalizedTool, OPTError, ProgrammaticExecutor, type ProgrammaticResult, RelayConnectionError, RelayTimeoutError, SandboxError, type Tool, type ToolCallRequest, type ToolCallResponse, type ToolCollection, type ToolDefinition, ToolError, buildSystemPrompt, createExecutor, defineTool, extractCode, generateTypeHints, isTool, normalizeTools };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Supertools
+ *
+ * Let any LLM write code that calls your tools.
+ * 10x faster. 90% cheaper.
+ *
+ * @example
+ * ```ts
+ * import { supertools, defineTool, z } from '@supertools-ai/core';
+ * import { Sandbox } from 'e2b';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const queryDb = defineTool({
+ *   name: 'queryDatabase',
+ *   description: 'Execute a SQL query',
+ *   parameters: z.object({
+ *     sql: z.string().describe('The SQL query to execute'),
+ *   }),
+ *   execute: async ({ sql }) => db.query(sql),
+ * });
+ *
+ * // Create sandbox and wrap your SDK client
+ * const sandbox = await Sandbox.create('supertools-bun');
+ * const client = supertools(new Anthropic(), { tools: [queryDb], sandbox });
+ *
+ * // Use exactly like normal - tools execute automatically
+ * const response = await client.messages.create({
+ *   model: 'claude-haiku-4-5-20251001',
+ *   max_tokens: 1024,
+ *   messages: [{ role: 'user', content: 'List all admin users' }],
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { supertools, detectProvider } from './supertools';
+export type { SupertoolsConfig, SupportedProvider } from './supertools';
+export { defineTool, z } from './tool';
+export type { Tool, ToolDefinition } from './tool';
+export { createExecutor, ProgrammaticExecutor } from './executor';
+export type { CreateExecutorOptions } from './executor';
+export type { ToolCollection, ExecutionResult, GeneratedCode, ProgrammaticResult, ToolCallRequest, ToolCallResponse, LLMAdapter, ExecutorConfig, ExecutionEvent, } from './types';
+export { OPTError, CodeGenerationError, ExecutionError, ToolError, RelayConnectionError, RelayTimeoutError, SandboxError, ConfigurationError, } from './utils/errors';
+export { buildSystemPrompt, extractCode } from './prompts';
+export { generateTypeHints } from './utils/type-hints';
+export { normalizeTools, isTool } from './tool';
+export type { NormalizedTool, NormalizedParameter } from './tool';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AACvC,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC"}