digital-tools 2.0.1

package/src/tools/communication.ts

@@ -0,0 +1,256 @@
+/**
+ * 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'
+import type { AnyTool } from '../types.js'
+
+/**
+ * Email input type
+ */
+interface EmailInput {
+  to: string[]
+  cc?: string[]
+  bcc?: string[]
+  subject: string
+  body: string
+  html?: string
+  attachments?: Array<{
+    filename: string
+    content: string
+    contentType?: string
+  }>
+}
+
+/**
+ * Send an email
+ */
+export const sendEmail = defineTool<
+  EmailInput,
+  { success: boolean; messageId?: string; error?: string }
+>({
+  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' }],
+  },
+})
+
+/**
+ * Slack message input
+ */
+interface SlackMessageInput {
+  channel: string
+  text: string
+  blocks?: unknown[]
+  threadTs?: string
+  unfurlLinks?: boolean
+}
+
+/**
+ * Send a Slack message
+ */
+export const sendSlackMessage = defineTool<
+  SlackMessageInput,
+  { success: boolean; ts?: string; channel?: string; error?: string }
+>({
+  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' }],
+  },
+})
+
+/**
+ * Notification input
+ */
+interface NotificationInput {
+  channel: 'email' | 'slack' | 'sms' | 'push' | 'webhook'
+  recipients: string[]
+  title: string
+  message: string
+  priority?: 'low' | 'normal' | 'high' | 'urgent'
+  data?: Record<string, unknown>
+}
+
+/**
+ * Send a notification
+ */
+export const sendNotification = defineTool<
+  NotificationInput,
+  { success: boolean; notificationId: string; delivered: string[] }
+>({
+  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'],
+  },
+})
+
+/**
+ * SMS input
+ */
+interface SmsInput {
+  to: string
+  message: string
+  from?: string
+}
+
+/**
+ * Send an SMS
+ */
+export const sendSms = defineTool<
+  SmsInput,
+  { success: boolean; messageId?: string; error?: string }
+>({
+  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: AnyTool[] = [
+  sendEmail,
+  sendSlackMessage,
+  sendNotification,
+  sendSms,
+]

package/src/tools/data.ts

@@ -0,0 +1,236 @@
+/**
+ * Data Tools - Data manipulation, transformation, validation
+ *
+ * @packageDocumentation
+ */
+
+import { defineTool } from '../define.js'
+import type { AnyTool } from '../types.js'
+
+/**
+ * Parse JSON string
+ */
+export const parseJson = defineTool<
+  { text: string },
+  { data: unknown; valid: boolean; error?: string }
+>({
+  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<
+  { data: unknown; pretty?: boolean },
+  { text: string }
+>({
+  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<
+  { text: string; delimiter?: string; hasHeaders?: boolean },
+  { rows: Record<string, string>[]; headers: string[]; rowCount: number }
+>({
+  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: Record<string, string> = {}
+      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<
+  { data: unknown; transform: Record<string, string> },
+  { result: Record<string, unknown> }
+>({
+  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: Record<string, unknown> = {}
+
+    for (const [outputKey, inputPath] of Object.entries(input.transform)) {
+      const pathParts = inputPath.split('.')
+      let value: unknown = input.data
+
+      for (const part of pathParts) {
+        if (value && typeof value === 'object' && part in (value as Record<string, unknown>)) {
+          value = (value as Record<string, unknown>)[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<
+  { data: unknown[]; filter: Record<string, unknown> },
+  { results: unknown[]; count: number }
+>({
+  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 as Record<string, unknown>)[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: AnyTool[] = [
+  parseJson,
+  stringifyJson,
+  parseCsv,
+  transformData,
+  filterData,
+]

package/src/tools/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.ts

@@ -0,0 +1,161 @@
+/**
+ * Web Tools - HTTP, scraping, browser automation
+ *
+ * @packageDocumentation
+ */
+
+import { defineTool } from '../define.js'
+import type { AnyTool } from '../types.js'
+
+/**
+ * Fetch content from a URL
+ */
+export const fetchUrl = defineTool<
+  { url: string; method?: string; headers?: Record<string, string>; body?: string },
+  { status: number; headers: Record<string, string>; body: string }
+>({
+  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: Record<string, string> = {}
+    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<
+  { html: string; selector?: string },
+  { text: string; links: string[]; images: string[] }
+>({
+  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: string[] = []
+    let match
+    while ((match = linkRegex.exec(input.html)) !== null) {
+      links.push(match[1])
+    }
+
+    // Extract images
+    const imgRegex = /src="([^"]+)"/g
+    const images: string[] = []
+    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<
+  { url: string },
+  { title: string; text: string; links: string[] }
+>({
+  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: string[] = []
+    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: AnyTool[] = [fetchUrl, parseHtml, readUrl]