digital-tools 2.0.2 → 2.1.1

package/src/registry.js

@@ -0,0 +1,128 @@
+/**
+ * Tool Registry - Registration and discovery for tools
+ *
+ * Provides a central registry for tools that can be used by
+ * both humans and AI agents.
+ *
+ * @packageDocumentation
+ */
+/**
+ * In-memory tool registry implementation
+ */
+class InMemoryToolRegistry {
+    tools = new Map();
+    register(tool) {
+        if (this.tools.has(tool.id)) {
+            console.warn(`Tool "${tool.id}" already registered, overwriting`);
+        }
+        this.tools.set(tool.id, tool);
+    }
+    unregister(id) {
+        return this.tools.delete(id);
+    }
+    get(id) {
+        return this.tools.get(id);
+    }
+    has(id) {
+        return this.tools.has(id);
+    }
+    list() {
+        return Array.from(this.tools.keys());
+    }
+    query(options) {
+        let results = Array.from(this.tools.values());
+        // Filter by category
+        if (options.category) {
+            results = results.filter((t) => t.category === options.category);
+        }
+        // Filter by subcategory
+        if (options.subcategory) {
+            results = results.filter((t) => t.subcategory === options.subcategory);
+        }
+        // Filter by tags
+        if (options.tags && options.tags.length > 0) {
+            results = results.filter((t) => t.tags && options.tags.some((tag) => t.tags.includes(tag)));
+        }
+        // Filter by audience
+        if (options.audience) {
+            results = results.filter((t) => t.audience === options.audience ||
+                t.audience === 'both' ||
+                !t.audience);
+        }
+        // Text search
+        if (options.search) {
+            const search = options.search.toLowerCase();
+            results = results.filter((t) => t.name.toLowerCase().includes(search) ||
+                t.description.toLowerCase().includes(search) ||
+                t.id.toLowerCase().includes(search));
+        }
+        // Pagination
+        const offset = options.offset ?? 0;
+        const limit = options.limit ?? results.length;
+        results = results.slice(offset, offset + limit);
+        return results;
+    }
+    byCategory(category) {
+        return this.query({ category });
+    }
+    clear() {
+        this.tools.clear();
+    }
+}
+/**
+ * Global tool registry instance
+ */
+export const registry = new InMemoryToolRegistry();
+/**
+ * Create a new registry instance (for isolated testing or namespacing)
+ */
+export function createRegistry() {
+    return new InMemoryToolRegistry();
+}
+/**
+ * Convert a Tool to MCP format
+ */
+export function toMCP(tool) {
+    return {
+        name: tool.id,
+        description: tool.description,
+        inputSchema: {
+            type: 'object',
+            properties: Object.fromEntries(tool.parameters.map((p) => [
+                p.name,
+                typeof p.schema === 'object' && 'type' in p.schema
+                    ? { ...p.schema, description: p.description }
+                    : { description: p.description },
+            ])),
+            required: tool.parameters.filter((p) => p.required).map((p) => p.name),
+        },
+    };
+}
+/**
+ * Convert all registered tools to MCP format
+ */
+export function listMCPTools(reg = registry) {
+    return reg.list().map((id) => toMCP(reg.get(id)));
+}
+/**
+ * Register a tool in the global registry
+ */
+export function registerTool(tool) {
+    registry.register(tool);
+}
+/**
+ * Get a tool from the global registry
+ */
+export function getTool(id) {
+    return registry.get(id);
+}
+/**
+ * Execute a tool by ID
+ */
+export async function executeTool(id, input) {
+    const tool = registry.get(id);
+    if (!tool) {
+        throw new Error(`Tool "${id}" not found`);
+    }
+    return tool.handler(input);
+}

package/src/tools/communication.js

@@ -0,0 +1,184 @@
+/**
+ * Communication Tools - Email, messaging, notifications
+ *
+ * These tools define the interface for communication.
+ * Actual implementations would integrate with email services,
+ * Slack, etc. in production.
+ *
+ * @packageDocumentation
+ */
+import { defineTool } from '../define.js';
+/**
+ * Send an email
+ */
+export 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: 'Recipient email addresses' },
+            cc: { type: 'array', items: { type: 'string' }, description: 'CC recipients' },
+            bcc: { type: 'array', items: { type: 'string' }, description: 'BCC recipients' },
+            subject: { type: 'string', description: 'Email subject' },
+            body: { type: 'string', description: 'Plain text body' },
+            html: { type: 'string', description: 'HTML body (optional)' },
+            attachments: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        filename: { type: 'string' },
+                        content: { type: 'string' },
+                        contentType: { type: 'string' },
+                    },
+                },
+                description: 'File attachments',
+            },
+        },
+        required: ['to', 'subject', 'body'],
+    },
+    handler: async (input) => {
+        // In production, this would integrate with an email service
+        // (SendGrid, SES, Postmark, etc.)
+        console.log('[Email] Sending to:', input.to.join(', '));
+        console.log('[Email] Subject:', input.subject);
+        // Simulate sending
+        return {
+            success: true,
+            messageId: `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+        };
+    },
+    options: {
+        audience: 'both',
+        tags: ['email', 'send', 'notify'],
+        requiresConfirmation: true,
+        permissions: [{ type: 'execute', resource: 'email' }],
+    },
+});
+/**
+ * Send a Slack message
+ */
+export const sendSlackMessage = defineTool({
+    id: 'communication.slack.send',
+    name: 'Send Slack Message',
+    description: 'Send a message to a Slack channel or thread',
+    category: 'communication',
+    subcategory: 'slack',
+    input: {
+        type: 'object',
+        properties: {
+            channel: { type: 'string', description: 'Channel ID or name (e.g., #general)' },
+            text: { type: 'string', description: 'Message text' },
+            blocks: { type: 'array', description: 'Slack Block Kit blocks' },
+            threadTs: { type: 'string', description: 'Thread timestamp for replies' },
+            unfurlLinks: { type: 'boolean', description: 'Unfurl URLs in the message' },
+        },
+        required: ['channel', 'text'],
+    },
+    handler: async (input) => {
+        // In production, this would integrate with Slack API
+        console.log('[Slack] Sending to:', input.channel);
+        console.log('[Slack] Message:', input.text);
+        return {
+            success: true,
+            ts: `${Date.now()}.000001`,
+            channel: input.channel,
+        };
+    },
+    options: {
+        audience: 'both',
+        tags: ['slack', 'message', 'chat'],
+        permissions: [{ type: 'execute', resource: 'slack' }],
+    },
+});
+/**
+ * Send a notification
+ */
+export const sendNotification = defineTool({
+    id: 'communication.notify',
+    name: 'Send Notification',
+    description: 'Send a notification through various channels',
+    category: 'communication',
+    subcategory: 'notification',
+    input: {
+        type: 'object',
+        properties: {
+            channel: {
+                type: 'string',
+                enum: ['email', 'slack', 'sms', 'push', 'webhook'],
+                description: 'Notification channel',
+            },
+            recipients: { type: 'array', items: { type: 'string' }, description: 'Recipients' },
+            title: { type: 'string', description: 'Notification title' },
+            message: { type: 'string', description: 'Notification message' },
+            priority: {
+                type: 'string',
+                enum: ['low', 'normal', 'high', 'urgent'],
+                description: 'Priority level',
+            },
+            data: { type: 'object', description: 'Additional data' },
+        },
+        required: ['channel', 'recipients', 'title', 'message'],
+    },
+    handler: async (input) => {
+        console.log(`[Notification] [${input.channel}] ${input.title}`);
+        console.log(`[Notification] Recipients:`, input.recipients);
+        console.log(`[Notification] Priority:`, input.priority || 'normal');
+        return {
+            success: true,
+            notificationId: `notif_${Date.now()}`,
+            delivered: input.recipients,
+        };
+    },
+    options: {
+        audience: 'both',
+        tags: ['notify', 'alert', 'message'],
+    },
+});
+/**
+ * Send an SMS
+ */
+export const sendSms = defineTool({
+    id: 'communication.sms.send',
+    name: 'Send SMS',
+    description: 'Send an SMS text message',
+    category: 'communication',
+    subcategory: 'sms',
+    input: {
+        type: 'object',
+        properties: {
+            to: { type: 'string', description: 'Phone number (E.164 format)' },
+            message: { type: 'string', description: 'SMS message (max 160 chars recommended)' },
+            from: { type: 'string', description: 'Sender phone number or ID' },
+        },
+        required: ['to', 'message'],
+    },
+    handler: async (input) => {
+        // In production, this would integrate with Twilio, etc.
+        console.log('[SMS] Sending to:', input.to);
+        console.log('[SMS] Message:', input.message.slice(0, 160));
+        return {
+            success: true,
+            messageId: `sms_${Date.now()}`,
+        };
+    },
+    options: {
+        audience: 'both',
+        tags: ['sms', 'text', 'mobile'],
+        requiresConfirmation: true,
+        permissions: [{ type: 'execute', resource: 'sms' }],
+    },
+});
+/**
+ * All communication tools
+ */
+export const communicationTools = [
+    sendEmail,
+    sendSlackMessage,
+    sendNotification,
+    sendSms,
+];

package/src/tools/data.js

@@ -0,0 +1,205 @@
+/**
+ * Data Tools - Data manipulation, transformation, validation
+ *
+ * @packageDocumentation
+ */
+import { defineTool } from '../define.js';
+/**
+ * Parse JSON string
+ */
+export const parseJson = defineTool({
+    id: 'data.json.parse',
+    name: 'Parse JSON',
+    description: 'Parse a JSON string into an object',
+    category: 'data',
+    subcategory: 'transform',
+    input: {
+        type: 'object',
+        properties: {
+            text: { type: 'string', description: 'JSON string to parse' },
+        },
+        required: ['text'],
+    },
+    handler: async (input) => {
+        try {
+            const data = JSON.parse(input.text);
+            return { data, valid: true };
+        }
+        catch (e) {
+            return {
+                data: null,
+                valid: false,
+                error: e instanceof Error ? e.message : 'Invalid JSON',
+            };
+        }
+    },
+    options: {
+        audience: 'both',
+        tags: ['json', 'parse', 'transform'],
+        idempotent: true,
+    },
+});
+/**
+ * Stringify object to JSON
+ */
+export const stringifyJson = defineTool({
+    id: 'data.json.stringify',
+    name: 'Stringify JSON',
+    description: 'Convert an object to a JSON string',
+    category: 'data',
+    subcategory: 'transform',
+    input: {
+        type: 'object',
+        properties: {
+            data: { description: 'Data to stringify' },
+            pretty: { type: 'boolean', description: 'Pretty print with indentation' },
+        },
+        required: ['data'],
+    },
+    handler: async (input) => {
+        const text = input.pretty
+            ? JSON.stringify(input.data, null, 2)
+            : JSON.stringify(input.data);
+        return { text };
+    },
+    options: {
+        audience: 'both',
+        tags: ['json', 'stringify', 'transform'],
+        idempotent: true,
+    },
+});
+/**
+ * Parse CSV to array of objects
+ */
+export const parseCsv = defineTool({
+    id: 'data.csv.parse',
+    name: 'Parse CSV',
+    description: 'Parse CSV text into an array of objects',
+    category: 'data',
+    subcategory: 'transform',
+    input: {
+        type: 'object',
+        properties: {
+            text: { type: 'string', description: 'CSV text to parse' },
+            delimiter: { type: 'string', description: 'Column delimiter (default: comma)' },
+            hasHeaders: { type: 'boolean', description: 'First row is headers (default: true)' },
+        },
+        required: ['text'],
+    },
+    handler: async (input) => {
+        const delimiter = input.delimiter || ',';
+        const hasHeaders = input.hasHeaders !== false;
+        const lines = input.text.split('\n').filter((line) => line.trim());
+        if (lines.length === 0) {
+            return { rows: [], headers: [], rowCount: 0 };
+        }
+        const headers = hasHeaders
+            ? lines[0].split(delimiter).map((h) => h.trim())
+            : lines[0].split(delimiter).map((_, i) => `column${i + 1}`);
+        const dataLines = hasHeaders ? lines.slice(1) : lines;
+        const rows = dataLines.map((line) => {
+            const values = line.split(delimiter).map((v) => v.trim());
+            const row = {};
+            headers.forEach((header, i) => {
+                row[header] = values[i] || '';
+            });
+            return row;
+        });
+        return { rows, headers, rowCount: rows.length };
+    },
+    options: {
+        audience: 'both',
+        tags: ['csv', 'parse', 'transform'],
+        idempotent: true,
+    },
+});
+/**
+ * Transform data using JSONPath-like expressions
+ */
+export const transformData = defineTool({
+    id: 'data.transform',
+    name: 'Transform Data',
+    description: 'Transform data by mapping fields to new structure',
+    category: 'data',
+    subcategory: 'transform',
+    input: {
+        type: 'object',
+        properties: {
+            data: { description: 'Source data to transform' },
+            transform: {
+                type: 'object',
+                description: 'Mapping of output fields to input paths (e.g., { "name": "user.firstName" })',
+            },
+        },
+        required: ['data', 'transform'],
+    },
+    handler: async (input) => {
+        const result = {};
+        for (const [outputKey, inputPath] of Object.entries(input.transform)) {
+            const pathParts = inputPath.split('.');
+            let value = input.data;
+            for (const part of pathParts) {
+                if (value && typeof value === 'object' && part in value) {
+                    value = value[part];
+                }
+                else {
+                    value = undefined;
+                    break;
+                }
+            }
+            result[outputKey] = value;
+        }
+        return { result };
+    },
+    options: {
+        audience: 'both',
+        tags: ['transform', 'map', 'extract'],
+        idempotent: true,
+    },
+});
+/**
+ * Filter array of objects
+ */
+export const filterData = defineTool({
+    id: 'data.filter',
+    name: 'Filter Data',
+    description: 'Filter an array of objects by field values',
+    category: 'data',
+    subcategory: 'transform',
+    input: {
+        type: 'object',
+        properties: {
+            data: { type: 'array', description: 'Array of objects to filter' },
+            filter: { type: 'object', description: 'Filter criteria (e.g., { "status": "active" })' },
+        },
+        required: ['data', 'filter'],
+    },
+    handler: async (input) => {
+        const results = input.data.filter((item) => {
+            if (typeof item !== 'object' || item === null)
+                return false;
+            for (const [key, value] of Object.entries(input.filter)) {
+                if (item[key] !== value) {
+                    return false;
+                }
+            }
+            return true;
+        });
+        return { results, count: results.length };
+    },
+    options: {
+        audience: 'both',
+        tags: ['filter', 'query', 'search'],
+        idempotent: true,
+    },
+});
+/**
+ * All data tools
+ */
+export const dataTools = [
+    parseJson,
+    stringifyJson,
+    parseCsv,
+    transformData,
+    filterData,
+];

package/src/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * Common tool implementations
+ *
+ * Pre-built tools for common operations that can be used
+ * out of the box by both humans and AI agents.
+ *
+ * @packageDocumentation
+ */
+export * from './web.js';
+export * from './data.js';
+export * from './communication.js';

package/src/tools/web.js

@@ -0,0 +1,137 @@
+/**
+ * Web Tools - HTTP, scraping, browser automation
+ *
+ * @packageDocumentation
+ */
+import { defineTool } from '../define.js';
+/**
+ * Fetch content from a URL
+ */
+export const fetchUrl = defineTool({
+    id: 'web.fetch',
+    name: 'Fetch URL',
+    description: 'Fetch content from a URL using HTTP',
+    category: 'web',
+    subcategory: 'fetch',
+    input: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'URL to fetch' },
+            method: { type: 'string', description: 'HTTP method (default: GET)', enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] },
+            headers: { type: 'object', description: 'Request headers' },
+            body: { type: 'string', description: 'Request body (for POST/PUT/PATCH)' },
+        },
+        required: ['url'],
+    },
+    handler: async (input) => {
+        const response = await fetch(input.url, {
+            method: input.method || 'GET',
+            headers: input.headers,
+            body: input.body,
+        });
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        return {
+            status: response.status,
+            headers,
+            body: await response.text(),
+        };
+    },
+    options: {
+        audience: 'both',
+        tags: ['http', 'network', 'api'],
+    },
+});
+/**
+ * Parse HTML and extract content
+ */
+export const parseHtml = defineTool({
+    id: 'web.parse-html',
+    name: 'Parse HTML',
+    description: 'Parse HTML content and extract text, links, and images',
+    category: 'web',
+    subcategory: 'scrape',
+    input: {
+        type: 'object',
+        properties: {
+            html: { type: 'string', description: 'HTML content to parse' },
+            selector: { type: 'string', description: 'CSS selector to filter content (optional)' },
+        },
+        required: ['html'],
+    },
+    handler: async (input) => {
+        // Basic HTML parsing without DOM (would use cheerio or jsdom in production)
+        const text = input.html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+        // Extract links
+        const linkRegex = /href="([^"]+)"/g;
+        const links = [];
+        let match;
+        while ((match = linkRegex.exec(input.html)) !== null) {
+            links.push(match[1]);
+        }
+        // Extract images
+        const imgRegex = /src="([^"]+)"/g;
+        const images = [];
+        while ((match = imgRegex.exec(input.html)) !== null) {
+            if (match[1].match(/\.(jpg|jpeg|png|gif|webp|svg)/i)) {
+                images.push(match[1]);
+            }
+        }
+        return { text, links, images };
+    },
+    options: {
+        audience: 'both',
+        tags: ['html', 'parse', 'extract'],
+    },
+});
+/**
+ * Read content from a URL (combines fetch + parse)
+ */
+export const readUrl = defineTool({
+    id: 'web.read',
+    name: 'Read URL',
+    description: 'Read and extract content from a webpage',
+    category: 'web',
+    subcategory: 'scrape',
+    input: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'URL to read' },
+        },
+        required: ['url'],
+    },
+    handler: async (input) => {
+        const response = await fetch(input.url);
+        const html = await response.text();
+        // Extract title
+        const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+        const title = titleMatch ? titleMatch[1].trim() : '';
+        // Extract body text
+        const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+        const body = bodyMatch ? bodyMatch[1] : html;
+        const text = body.replace(/<script[\s\S]*?<\/script>/gi, '')
+            .replace(/<style[\s\S]*?<\/style>/gi, '')
+            .replace(/<[^>]*>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        // Extract links
+        const linkRegex = /href="(https?:\/\/[^"]+)"/g;
+        const links = [];
+        let match;
+        while ((match = linkRegex.exec(html)) !== null) {
+            links.push(match[1]);
+        }
+        return { title, text: text.slice(0, 10000), links: [...new Set(links)] };
+    },
+    options: {
+        audience: 'both',
+        tags: ['read', 'scrape', 'extract'],
+        idempotent: true,
+    },
+});
+/**
+ * All web tools
+ */
+export const webTools = [fetchUrl, parseHtml, readUrl];

package/src/types.js

@@ -0,0 +1,10 @@
+/**
+ * Types for digital-tools
+ *
+ * Core types for tools that can be used by both humans and AI agents.
+ * This package provides the foundational tool primitives used across
+ * autonomous-agents, human-in-the-loop, and services-as-software.
+ *
+ * @packageDocumentation
+ */
+export {};