digital-tools 2.0.1

package/src/index.ts

@@ -0,0 +1,176 @@
+/**
+ * digital-tools - Tools that can be used by both humans and AI agents
+ *
+ * This package provides:
+ * - Core Tool interface and types
+ * - Tool ontology/categories for organization
+ * - Tool registry for registration and discovery
+ * - Tool definition helpers with type safety
+ * - Common pre-built tool implementations
+ * - MCP (Model Context Protocol) compatibility
+ *
+ * @packageDocumentation
+ */
+
+// Export all types
+export type * from './types.js'
+
+// Re-export AnyTool as a convenience value export
+export type { AnyTool, Tool, ToolCategory, ToolSubcategory, ToolRegistry } from './types.js'
+
+// Export entity type definitions (Nouns for digital tools)
+export {
+  // Email
+  Email,
+  EmailThread,
+
+  // Spreadsheet
+  Spreadsheet,
+  Sheet,
+  Cell,
+
+  // Document
+  Document,
+
+  // Presentation
+  Presentation,
+  Slide,
+
+  // Phone
+  PhoneCall,
+  Voicemail,
+
+  // Team Messaging (Slack/Teams/Discord equivalent)
+  Workspace,
+  Channel,
+  Message,
+  Thread,
+  DirectMessage,
+  Member,
+  Reaction,
+
+  // Supporting
+  Attachment,
+  Contact,
+  Comment,
+  Revision,
+
+  // Collections
+  DigitalToolEntities,
+  DigitalToolCategories,
+} from './entities.js'
+
+// Export registry
+export {
+  registry,
+  createRegistry,
+  registerTool,
+  getTool,
+  executeTool,
+  toMCP,
+  listMCPTools,
+} from './registry.js'
+
+// Export tool definition helpers
+export {
+  defineTool,
+  defineAndRegister,
+  createToolExecutor,
+  toolBuilder,
+} from './define.js'
+
+// Export pre-built tools
+export {
+  // Web tools
+  fetchUrl,
+  parseHtml,
+  readUrl,
+  webTools,
+
+  // Data tools
+  parseJson,
+  stringifyJson,
+  parseCsv,
+  transformData,
+  filterData,
+  dataTools,
+
+  // Communication tools
+  sendEmail,
+  sendSlackMessage,
+  sendNotification,
+  sendSms,
+  communicationTools,
+} from './tools/index.js'
+
+// Export providers (concrete implementations using third-party APIs)
+export {
+  // Provider types and registry
+  type EmailProvider,
+  type MessagingProvider,
+  type SmsProvider,
+  type SpreadsheetProvider,
+  type DocumentProvider,
+  type PresentationProvider,
+  type PhoneProvider,
+  type ProviderConfig,
+  type ProviderInfo,
+  type ProviderCategory,
+  type BaseProvider,
+
+  // Provider registry
+  providerRegistry,
+  createProviderRegistry,
+  registerProvider,
+  getProvider,
+  createProvider,
+  listProviders,
+  defineProvider,
+
+  // Email providers
+  sendgridProvider,
+  resendProvider,
+  createSendGridProvider,
+  createResendProvider,
+
+  // Messaging providers
+  slackProvider,
+  twilioSmsProvider,
+  createSlackProvider,
+  createTwilioSmsProvider,
+
+  // Spreadsheet providers
+  xlsxProvider,
+  googleSheetsProvider,
+  createXlsxProvider,
+  createGoogleSheetsProvider,
+
+  // Registration helpers
+  registerAllProviders,
+  registerEmailProviders,
+  registerMessagingProviders,
+  registerSpreadsheetProviders,
+  allProviders,
+} from './providers/index.js'
+
+// Convenience function to register all built-in tools
+import { registry } from './registry.js'
+import { webTools } from './tools/web.js'
+import { dataTools } from './tools/data.js'
+import { communicationTools } from './tools/communication.js'
+
+/**
+ * Register all built-in tools in the global registry
+ */
+export function registerBuiltinTools(): void {
+  for (const tool of [...webTools, ...dataTools, ...communicationTools]) {
+    registry.register(tool)
+  }
+}
+
+/**
+ * Get all built-in tools
+ */
+export function getBuiltinTools() {
+  return [...webTools, ...dataTools, ...communicationTools]
+}

package/src/providers/analytics/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Analytics Providers
+ *
+ * @packageDocumentation
+ */
+
+export { mixpanelInfo, mixpanelProvider, createMixpanelProvider } from './mixpanel.js'
+
+import { mixpanelProvider } from './mixpanel.js'
+
+/**
+ * Register all analytics providers
+ */
+export function registerAnalyticsProviders(): void {
+  mixpanelProvider.register()
+}
+
+/**
+ * All analytics providers
+ */
+export const analyticsProviders = [mixpanelProvider]

package/src/providers/analytics/mixpanel.ts

@@ -0,0 +1,311 @@
+/**
+ * Mixpanel Analytics Provider
+ *
+ * Concrete implementation of AnalyticsProvider using Mixpanel API.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AnalyticsProvider,
+  ProviderConfig,
+  ProviderHealth,
+  ProviderInfo,
+  TrackEventOptions,
+  AnalyticsQueryOptions,
+  AnalyticsQueryResult,
+  AnalyticsReportData,
+} from '../types.js'
+import { defineProvider } from '../registry.js'
+
+const MIXPANEL_TRACK_URL = 'https://api.mixpanel.com/track'
+const MIXPANEL_ENGAGE_URL = 'https://api.mixpanel.com/engage'
+const MIXPANEL_QUERY_URL = 'https://mixpanel.com/api/2.0'
+
+/**
+ * Mixpanel provider info
+ */
+export const mixpanelInfo: ProviderInfo = {
+  id: 'analytics.mixpanel',
+  name: 'Mixpanel',
+  description: 'Mixpanel product analytics and user engagement platform',
+  category: 'analytics',
+  website: 'https://mixpanel.com',
+  docsUrl: 'https://developer.mixpanel.com/docs',
+  requiredConfig: ['projectToken'],
+  optionalConfig: ['apiSecret'],
+}
+
+/**
+ * Create Mixpanel analytics provider
+ */
+export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvider {
+  let projectToken: string
+  let apiSecret: string | undefined
+
+  return {
+    info: mixpanelInfo,
+
+    async initialize(cfg: ProviderConfig): Promise<void> {
+      projectToken = cfg.projectToken as string
+      apiSecret = cfg.apiSecret as string | undefined
+
+      if (!projectToken) {
+        throw new Error('Mixpanel project token is required')
+      }
+    },
+
+    async healthCheck(): Promise<ProviderHealth> {
+      const start = Date.now()
+      try {
+        // Try to track a test event to verify connectivity
+        const testEvent = {
+          event: 'health_check',
+          properties: {
+            token: projectToken,
+            time: Math.floor(Date.now() / 1000),
+            $insert_id: `health_check_${Date.now()}`,
+          },
+        }
+
+        const response = await fetch(MIXPANEL_TRACK_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify([testEvent]),
+        })
+
+        const result = await response.json() as { status: number }
+
+        return {
+          healthy: response.ok && result.status === 1,
+          latencyMs: Date.now() - start,
+          message: response.ok ? 'Connected' : `HTTP ${response.status}`,
+          checkedAt: new Date(),
+        }
+      } catch (error) {
+        return {
+          healthy: false,
+          latencyMs: Date.now() - start,
+          message: error instanceof Error ? error.message : 'Unknown error',
+          checkedAt: new Date(),
+        }
+      }
+    },
+
+    async dispose(): Promise<void> {
+      // No cleanup needed
+    },
+
+    async track(event: TrackEventOptions): Promise<boolean> {
+      try {
+        const eventData = {
+          event: event.event,
+          properties: {
+            token: projectToken,
+            distinct_id: event.userId || event.anonymousId || 'unknown',
+            time: event.timestamp ? Math.floor(event.timestamp.getTime() / 1000) : Math.floor(Date.now() / 1000),
+            $insert_id: `${event.event}_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+            ...event.properties,
+          },
+        }
+
+        const response = await fetch(MIXPANEL_TRACK_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify([eventData]),
+        })
+
+        const result = await response.json() as { status: number }
+        return response.ok && result.status === 1
+      } catch (error) {
+        console.error('Mixpanel track error:', error)
+        return false
+      }
+    },
+
+    async identify(userId: string, traits?: Record<string, unknown>): Promise<boolean> {
+      try {
+        const engageData = {
+          $token: projectToken,
+          $distinct_id: userId,
+          $set: traits || {},
+        }
+
+        const response = await fetch(MIXPANEL_ENGAGE_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify([engageData]),
+        })
+
+        const result = await response.json() as { status: number }
+        return response.ok && result.status === 1
+      } catch (error) {
+        console.error('Mixpanel identify error:', error)
+        return false
+      }
+    },
+
+    async page(name: string, properties?: Record<string, unknown>): Promise<boolean> {
+      return this.track({
+        event: 'Page Viewed',
+        properties: {
+          page_name: name,
+          ...properties,
+        },
+      })
+    },
+
+    async alias(userId: string, previousId: string): Promise<boolean> {
+      try {
+        const aliasEvent = {
+          event: '$create_alias',
+          properties: {
+            token: projectToken,
+            distinct_id: previousId,
+            alias: userId,
+          },
+        }
+
+        const response = await fetch(MIXPANEL_TRACK_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify([aliasEvent]),
+        })
+
+        const result = await response.json() as { status: number }
+        return response.ok && result.status === 1
+      } catch (error) {
+        console.error('Mixpanel alias error:', error)
+        return false
+      }
+    },
+
+    async getReport(reportId: string): Promise<AnalyticsReportData | null> {
+      if (!apiSecret) {
+        throw new Error('Mixpanel API secret is required for querying reports')
+      }
+
+      try {
+        const auth = Buffer.from(`${apiSecret}:`).toString('base64')
+        const response = await fetch(`${MIXPANEL_QUERY_URL}/reports/${reportId}`, {
+          headers: {
+            Authorization: `Basic ${auth}`,
+          },
+        })
+
+        if (!response.ok) {
+          return null
+        }
+
+        const data = await response.json() as {
+          name?: string
+          description?: string
+          query?: AnalyticsQueryOptions
+          result?: AnalyticsQueryResult
+          created?: string
+          updated?: string
+        }
+        return {
+          id: reportId,
+          name: data.name || reportId,
+          description: data.description,
+          query: data.query || { metrics: [], dateRange: { start: new Date(), end: new Date() } },
+          result: data.result,
+          createdAt: data.created ? new Date(data.created) : new Date(),
+          updatedAt: data.updated ? new Date(data.updated) : new Date(),
+        }
+      } catch (error) {
+        console.error('Mixpanel getReport error:', error)
+        return null
+      }
+    },
+
+    async runQuery(query: AnalyticsQueryOptions): Promise<AnalyticsQueryResult> {
+      if (!apiSecret) {
+        throw new Error('Mixpanel API secret is required for running queries')
+      }
+
+      try {
+        const auth = Buffer.from(`${apiSecret}:`).toString('base64')
+
+        // Construct query parameters
+        const params = new URLSearchParams({
+          from_date: query.dateRange.start.toISOString().split('T')[0],
+          to_date: query.dateRange.end.toISOString().split('T')[0],
+        })
+
+        if (query.metrics.length > 0) {
+          params.append('event', query.metrics.join(','))
+        }
+
+        if (query.limit) {
+          params.append('limit', query.limit.toString())
+        }
+
+        // Use the segmentation endpoint for queries
+        const endpoint = query.dimensions && query.dimensions.length > 0
+          ? 'segmentation'
+          : 'events'
+
+        const response = await fetch(`${MIXPANEL_QUERY_URL}/${endpoint}?${params.toString()}`, {
+          headers: {
+            Authorization: `Basic ${auth}`,
+          },
+        })
+
+        if (!response.ok) {
+          throw new Error(`Query failed: ${response.statusText}`)
+        }
+
+        const data = await response.json() as {
+          data?: Record<string, Record<string, number>>
+        }
+
+        // Transform Mixpanel response to our format
+        const rows: Array<Record<string, unknown>> = []
+        const totals: Record<string, number> = {}
+
+        if (data.data) {
+          Object.entries(data.data).forEach(([key, values]) => {
+            const row: Record<string, unknown> = { metric: key }
+
+            if (typeof values === 'object' && values !== null) {
+              Object.entries(values).forEach(([date, value]) => {
+                row[date] = value
+                if (typeof value === 'number') {
+                  totals[key] = (totals[key] || 0) + value
+                }
+              })
+            }
+
+            rows.push(row)
+          })
+        }
+
+        return {
+          rows,
+          totals,
+          rowCount: rows.length,
+        }
+      } catch (error) {
+        console.error('Mixpanel runQuery error:', error)
+        throw error
+      }
+    },
+  }
+}
+
+/**
+ * Mixpanel provider definition
+ */
+export const mixpanelProvider = defineProvider(mixpanelInfo, async (config) =>
+  createMixpanelProvider(config)
+)