digital-tools 2.0.2 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # digital-tools
 
+## 2.1.1
+
+### Patch Changes
+
+- Updated dependencies [6beb531]
+  - ai-functions@2.1.1
+  - ai-database@2.1.1
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - rpc.do@0.2.0
+  - ai-database@2.0.3
+  - ai-functions@2.0.3
+
 ## 2.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "digital-tools",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Tools that can be used by both humans and AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -28,9 +28,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "ai-database": "2.0.2",
-    "ai-functions": "2.0.2",
-    "rpc.do": "^0.1.0",
+    "ai-database": "2.1.1",
+    "ai-functions": "2.1.1",
     "zod": "^3.23.0"
   },
   "keywords": [

package/src/define.js

@@ -0,0 +1,267 @@
+/**
+ * Tool Definition Utilities
+ *
+ * Provides helpers for defining tools with type safety
+ * and automatic schema conversion.
+ *
+ * @packageDocumentation
+ */
+import { registry } from './registry.js';
+/**
+ * Check if a schema is a Zod schema
+ */
+function isZodSchema(schema) {
+    return (typeof schema === 'object' &&
+        schema !== null &&
+        '_def' in schema &&
+        'parse' in schema);
+}
+/**
+ * Convert a schema to JSON Schema format
+ */
+function toJSONSchema(schema) {
+    if (isZodSchema(schema)) {
+        // For Zod schemas, we'd use zod-to-json-schema in production
+        // For now, return a basic representation
+        return {
+            type: 'object',
+            description: 'Zod schema (convert with zod-to-json-schema)',
+        };
+    }
+    return schema;
+}
+/**
+ * Convert a schema definition to tool parameters
+ */
+function schemaToParameters(schema) {
+    const jsonSchema = toJSONSchema(schema);
+    if (jsonSchema.type !== 'object' || !jsonSchema.properties) {
+        // Single parameter
+        return [
+            {
+                name: 'input',
+                description: jsonSchema.description || 'Input value',
+                schema: jsonSchema,
+                required: true,
+            },
+        ];
+    }
+    const required = jsonSchema.required || [];
+    return Object.entries(jsonSchema.properties).map(([name, propSchema]) => ({
+        name,
+        description: propSchema.description || `Parameter: ${name}`,
+        schema: propSchema,
+        required: required.includes(name),
+        default: propSchema.default,
+    }));
+}
+/**
+ * Define a new tool with type safety
+ *
+ * @example
+ * ```ts
+ * const sendEmail = defineTool({
+ *   id: 'communication.email.send',
+ *   name: 'Send Email',
+ *   description: 'Send an email to one or more recipients',
+ *   category: 'communication',
+ *   subcategory: 'email',
+ *   input: {
+ *     type: 'object',
+ *     properties: {
+ *       to: { type: 'array', items: { type: 'string' }, description: 'Recipients' },
+ *       subject: { type: 'string', description: 'Email subject' },
+ *       body: { type: 'string', description: 'Email body' },
+ *     },
+ *     required: ['to', 'subject', 'body'],
+ *   },
+ *   handler: async (input) => {
+ *     // Send email logic
+ *     return { success: true, messageId: 'msg_123' }
+ *   },
+ * })
+ * ```
+ */
+export function defineTool(options) {
+    const tool = {
+        id: options.id,
+        name: options.name,
+        description: options.description,
+        category: options.category,
+        subcategory: options.subcategory,
+        parameters: schemaToParameters(options.input),
+        output: options.output
+            ? {
+                description: 'Tool output',
+                schema: options.output,
+            }
+            : undefined,
+        handler: options.handler,
+        ...options.options,
+    };
+    return tool;
+}
+/**
+ * Define and register a tool in one step
+ */
+export function defineAndRegister(options) {
+    const tool = defineTool(options);
+    registry.register(tool);
+    return tool;
+}
+/**
+ * Create a tool executor with context
+ *
+ * @example
+ * ```ts
+ * const executor = createToolExecutor({
+ *   executor: { type: 'agent', id: 'agent_123', name: 'Research Agent' },
+ *   environment: 'production',
+ * })
+ *
+ * const result = await executor.execute('communication.email.send', {
+ *   to: ['user@example.com'],
+ *   subject: 'Hello',
+ *   body: 'World',
+ * })
+ * ```
+ */
+export function createToolExecutor(context) {
+    return {
+        /**
+         * Execute a tool by ID with context tracking
+         */
+        async execute(toolId, input) {
+            const tool = registry.get(toolId);
+            if (!tool) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'TOOL_NOT_FOUND',
+                        message: `Tool "${toolId}" not found`,
+                    },
+                };
+            }
+            // Check audience restrictions
+            if (tool.audience &&
+                tool.audience !== 'both' &&
+                tool.audience !== context.executor.type) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'ACCESS_DENIED',
+                        message: `Tool "${toolId}" is not available for ${context.executor.type}`,
+                    },
+                };
+            }
+            const startTime = Date.now();
+            try {
+                const data = (await tool.handler(input));
+                const duration = Date.now() - startTime;
+                return {
+                    success: true,
+                    data,
+                    metadata: {
+                        duration,
+                        requestId: context.requestId,
+                    },
+                };
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                return {
+                    success: false,
+                    error: {
+                        code: 'EXECUTION_ERROR',
+                        message: error instanceof Error ? error.message : String(error),
+                        details: error,
+                    },
+                    metadata: {
+                        duration,
+                        requestId: context.requestId,
+                    },
+                };
+            }
+        },
+        /**
+         * List available tools for this executor
+         */
+        listAvailable() {
+            return registry.query({
+                audience: context.executor.type,
+            });
+        },
+    };
+}
+/**
+ * Tool builder for fluent API
+ *
+ * @example
+ * ```ts
+ * const tool = toolBuilder('web.fetch')
+ *   .name('Fetch URL')
+ *   .description('Fetch content from a URL')
+ *   .category('web')
+ *   .subcategory('fetch')
+ *   .input({
+ *     type: 'object',
+ *     properties: {
+ *       url: { type: 'string', description: 'URL to fetch' },
+ *     },
+ *     required: ['url'],
+ *   })
+ *   .handler(async ({ url }) => {
+ *     const response = await fetch(url)
+ *     return response.text()
+ *   })
+ *   .build()
+ * ```
+ */
+export function toolBuilder(id) {
+    const config = { id };
+    return {
+        name(name) {
+            config.name = name;
+            return this;
+        },
+        description(description) {
+            config.description = description;
+            return this;
+        },
+        category(category) {
+            config.category = category;
+            return this;
+        },
+        subcategory(subcategory) {
+            config.subcategory = subcategory;
+            return this;
+        },
+        input(schema) {
+            config.input = schema;
+            return this;
+        },
+        output(schema) {
+            config.output = schema;
+            return this;
+        },
+        handler(fn) {
+            config.handler = fn;
+            return this;
+        },
+        options(opts) {
+            config.options = opts;
+            return this;
+        },
+        build() {
+            if (!config.name || !config.description || !config.category || !config.input || !config.handler) {
+                throw new Error('Tool requires id, name, description, category, input, and handler');
+            }
+            return defineTool(config);
+        },
+        register() {
+            const tool = this.build();
+            registry.register(tool);
+            return tool;
+        },
+    };
+}