digital-tools 2.0.2 → 2.1.1

package/src/index.js

@@ -0,0 +1,74 @@
+/**
+ * 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 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 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() {
+    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.js

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

package/src/providers/analytics/mixpanel.js

@@ -0,0 +1,255 @@
+/**
+ * Mixpanel Analytics Provider
+ *
+ * Concrete implementation of AnalyticsProvider using Mixpanel API.
+ *
+ * @packageDocumentation
+ */
+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 = {
+    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) {
+    let projectToken;
+    let apiSecret;
+    return {
+        info: mixpanelInfo,
+        async initialize(cfg) {
+            projectToken = cfg.projectToken;
+            apiSecret = cfg.apiSecret;
+            if (!projectToken) {
+                throw new Error('Mixpanel project token is required');
+            }
+        },
+        async healthCheck() {
+            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();
+                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() {
+            // No cleanup needed
+        },
+        async track(event) {
+            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();
+                return response.ok && result.status === 1;
+            }
+            catch (error) {
+                console.error('Mixpanel track error:', error);
+                return false;
+            }
+        },
+        async identify(userId, traits) {
+            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();
+                return response.ok && result.status === 1;
+            }
+            catch (error) {
+                console.error('Mixpanel identify error:', error);
+                return false;
+            }
+        },
+        async page(name, properties) {
+            return this.track({
+                event: 'Page Viewed',
+                properties: {
+                    page_name: name,
+                    ...properties,
+                },
+            });
+        },
+        async alias(userId, previousId) {
+            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();
+                return response.ok && result.status === 1;
+            }
+            catch (error) {
+                console.error('Mixpanel alias error:', error);
+                return false;
+            }
+        },
+        async getReport(reportId) {
+            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();
+                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) {
+            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();
+                // Transform Mixpanel response to our format
+                const rows = [];
+                const totals = {};
+                if (data.data) {
+                    Object.entries(data.data).forEach(([key, values]) => {
+                        const row = { 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));

package/src/providers/calendar/cal-com.js

@@ -0,0 +1,303 @@
+/**
+ * Cal.com Provider
+ *
+ * Concrete implementation of CalendarProvider using Cal.com API v1.
+ * Cal.com is an open-source Calendly alternative for scheduling.
+ *
+ * @packageDocumentation
+ */
+import { defineProvider } from '../registry.js';
+const DEFAULT_BASE_URL = 'https://api.cal.com/v1';
+/**
+ * Cal.com provider info
+ */
+export const calComInfo = {
+    id: 'calendar.cal-com',
+    name: 'Cal.com',
+    description: 'Cal.com API for scheduling and calendar management (open-source Calendly alternative)',
+    category: 'calendar',
+    website: 'https://cal.com',
+    docsUrl: 'https://cal.com/docs/api-reference',
+    requiredConfig: ['apiKey'],
+    optionalConfig: ['baseUrl'],
+};
+/**
+ * Create Cal.com provider
+ */
+export function createCalComProvider(config) {
+    let apiKey;
+    let baseUrl;
+    /**
+     * Helper to make authenticated API requests
+     */
+    async function apiRequest(endpoint, options = {}) {
+        try {
+            const url = `${baseUrl}${endpoint}`;
+            const params = new URLSearchParams();
+            // Cal.com uses apiKey query parameter for authentication
+            params.append('apiKey', apiKey);
+            const fullUrl = `${url}${url.includes('?') ? '&' : '?'}${params}`;
+            const response = await fetch(fullUrl, {
+                ...options,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...options.headers,
+                },
+            });
+            if (response.ok) {
+                const data = (await response.json());
+                return { ok: true, status: response.status, data };
+            }
+            const errorData = await response.json().catch(() => ({}));
+            return {
+                ok: false,
+                status: response.status,
+                error: errorData?.message || response.statusText,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                status: 0,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    return {
+        info: calComInfo,
+        async initialize(cfg) {
+            apiKey = cfg.apiKey;
+            baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
+            if (!apiKey) {
+                throw new Error('Cal.com API key is required');
+            }
+        },
+        async healthCheck() {
+            const start = Date.now();
+            const result = await apiRequest('/me', { method: 'GET' });
+            return {
+                healthy: result.ok,
+                latencyMs: Date.now() - start,
+                message: result.ok ? 'Connected' : result.error || `HTTP ${result.status}`,
+                checkedAt: new Date(),
+            };
+        },
+        async dispose() {
+            // No cleanup needed
+        },
+        async listCalendars(options) {
+            // Cal.com uses "event types" as calendar configurations
+            const params = new URLSearchParams();
+            if (options?.limit)
+                params.append('take', String(options.limit));
+            if (options?.cursor)
+                params.append('skip', String(options.cursor));
+            const result = await apiRequest(`/event-types?${params}`);
+            if (!result.ok || !result.data) {
+                return { items: [], hasMore: false };
+            }
+            const items = result.data.event_types
+                .filter((et) => !et.hidden)
+                .map((et) => ({
+                id: String(et.id),
+                name: et.title,
+                description: et.description,
+                timeZone: 'UTC', // Cal.com handles timezone per user
+                primary: et.position === 0,
+                accessRole: 'owner',
+            }));
+            return {
+                items,
+                hasMore: result.data.event_types.length >= (options?.limit || 10),
+            };
+        },
+        async getCalendar(calendarId) {
+            const result = await apiRequest(`/event-types/${calendarId}`);
+            if (!result.ok || !result.data) {
+                return null;
+            }
+            const et = result.data.event_type;
+            return {
+                id: String(et.id),
+                name: et.title,
+                description: et.description,
+                timeZone: 'UTC',
+                primary: et.position === 0,
+                accessRole: 'owner',
+            };
+        },
+        async createEvent(calendarId, event) {
+            // In Cal.com, creating a booking is done through the booking endpoint
+            const body = {
+                eventTypeId: parseInt(calendarId, 10),
+                start: event.start.toISOString(),
+                end: event.end.toISOString(),
+                responses: {
+                    name: event.summary,
+                    email: event.attendees?.[0] || 'guest@example.com',
+                    notes: event.description,
+                    location: event.location,
+                },
+                timeZone: 'UTC',
+                language: 'en',
+                metadata: {},
+            };
+            const result = await apiRequest('/bookings', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            if (!result.ok || !result.data) {
+                throw new Error(result.error || 'Failed to create booking');
+            }
+            const booking = result.data.booking;
+            return {
+                id: booking.uid,
+                calendarId,
+                summary: booking.title,
+                description: booking.description,
+                location: booking.location,
+                start: new Date(booking.startTime),
+                end: new Date(booking.endTime),
+                attendees: booking.attendees.map((a) => ({
+                    email: a.email,
+                    responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
+                })),
+                status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed'),
+                htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
+            };
+        },
+        async getEvent(calendarId, eventId) {
+            const result = await apiRequest(`/bookings/${eventId}`);
+            if (!result.ok || !result.data) {
+                return null;
+            }
+            const booking = result.data.booking;
+            return {
+                id: booking.uid,
+                calendarId: String(booking.eventTypeId),
+                summary: booking.title,
+                description: booking.description,
+                location: booking.location,
+                start: new Date(booking.startTime),
+                end: new Date(booking.endTime),
+                attendees: booking.attendees.map((a) => ({
+                    email: a.email,
+                    responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
+                })),
+                status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed'),
+                htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
+            };
+        },
+        async updateEvent(calendarId, eventId, updates) {
+            // Cal.com bookings are typically rescheduled rather than updated
+            const body = {};
+            if (updates.start && updates.end) {
+                body.start = updates.start.toISOString();
+                body.end = updates.end.toISOString();
+            }
+            if (updates.summary) {
+                body.title = updates.summary;
+            }
+            if (updates.description) {
+                body.description = updates.description;
+            }
+            const result = await apiRequest(`/bookings/${eventId}`, {
+                method: 'PATCH',
+                body: JSON.stringify(body),
+            });
+            if (!result.ok || !result.data) {
+                throw new Error(result.error || 'Failed to update booking');
+            }
+            const booking = result.data.booking;
+            return {
+                id: booking.uid,
+                calendarId: String(booking.eventTypeId),
+                summary: booking.title,
+                description: booking.description,
+                location: booking.location,
+                start: new Date(booking.startTime),
+                end: new Date(booking.endTime),
+                attendees: booking.attendees.map((a) => ({
+                    email: a.email,
+                    responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
+                })),
+                status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed'),
+                htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
+            };
+        },
+        async deleteEvent(calendarId, eventId) {
+            // Cancel the booking
+            const result = await apiRequest(`/bookings/${eventId}`, {
+                method: 'DELETE',
+            });
+            return result.ok;
+        },
+        async listEvents(calendarId, options) {
+            const params = new URLSearchParams();
+            if (options?.limit)
+                params.append('take', String(options.limit));
+            if (options?.cursor)
+                params.append('skip', String(options.cursor));
+            // Filter by event type (calendar)
+            params.append('eventTypeId', calendarId);
+            if (options?.timeMin)
+                params.append('afterStart', options.timeMin.toISOString());
+            if (options?.timeMax)
+                params.append('beforeEnd', options.timeMax.toISOString());
+            const result = await apiRequest(`/bookings?${params}`);
+            if (!result.ok || !result.data) {
+                return { items: [], hasMore: false };
+            }
+            const items = result.data.bookings.map((booking) => ({
+                id: booking.uid,
+                calendarId: String(booking.eventTypeId),
+                summary: booking.title,
+                description: booking.description,
+                location: booking.location,
+                start: new Date(booking.startTime),
+                end: new Date(booking.endTime),
+                attendees: booking.attendees.map((a) => ({
+                    email: a.email,
+                    responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
+                })),
+                status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed'),
+                htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
+            }));
+            return {
+                items,
+                hasMore: result.data.bookings.length >= (options?.limit || 10),
+            };
+        },
+        async findAvailability(calendarIds, timeMin, timeMax) {
+            // Cal.com's availability endpoint
+            const results = [];
+            for (const calendarId of calendarIds) {
+                const params = new URLSearchParams();
+                params.append('eventTypeId', calendarId);
+                params.append('dateFrom', timeMin.toISOString());
+                params.append('dateTo', timeMax.toISOString());
+                const result = await apiRequest(`/availability?${params}`);
+                if (result.ok && result.data) {
+                    results.push({
+                        calendarId,
+                        busy: result.data.busy.map((slot) => ({
+                            start: new Date(slot.start),
+                            end: new Date(slot.end),
+                        })),
+                    });
+                }
+                else {
+                    results.push({
+                        calendarId,
+                        busy: [],
+                    });
+                }
+            }
+            return results;
+        },
+    };
+}
+/**
+ * Cal.com provider definition
+ */
+export const calComProvider = defineProvider(calComInfo, async (config) => createCalComProvider(config));