digital-tools 2.0.2 → 2.1.1

package/src/providers/support/zendesk.js

@@ -0,0 +1,373 @@
+/**
+ * Zendesk Support Provider
+ *
+ * Concrete implementation of SupportProvider using Zendesk API v2.
+ *
+ * @packageDocumentation
+ */
+import { defineProvider } from '../registry.js';
+/**
+ * Zendesk provider info
+ */
+export const zendeskInfo = {
+    id: 'support.zendesk',
+    name: 'Zendesk',
+    description: 'Zendesk customer support and ticketing platform',
+    category: 'support',
+    website: 'https://www.zendesk.com',
+    docsUrl: 'https://developer.zendesk.com/api-reference/',
+    requiredConfig: ['subdomain', 'apiKey', 'email'],
+    optionalConfig: ['apiVersion'],
+};
+/**
+ * Create Zendesk support provider
+ */
+export function createZendeskProvider(config) {
+    let subdomain;
+    let apiKey;
+    let email;
+    let baseUrl;
+    return {
+        info: zendeskInfo,
+        async initialize(cfg) {
+            subdomain = cfg.subdomain;
+            apiKey = cfg.apiKey;
+            email = cfg.email;
+            if (!subdomain || !apiKey || !email) {
+                throw new Error('Zendesk subdomain, API key, and email are required');
+            }
+            baseUrl = `https://${subdomain}.zendesk.com/api/v2`;
+        },
+        async healthCheck() {
+            const start = Date.now();
+            try {
+                const response = await fetch(`${baseUrl}/users/me.json`, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                return {
+                    healthy: response.ok,
+                    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 createTicket(ticket) {
+            const body = {
+                ticket: {
+                    subject: ticket.subject,
+                    comment: { body: ticket.description },
+                    priority: ticket.priority || 'normal',
+                    type: ticket.type || 'question',
+                    ...(ticket.requesterId && { requester_id: ticket.requesterId }),
+                    ...(ticket.assigneeId && { assignee_id: ticket.assigneeId }),
+                    ...(ticket.tags && { tags: ticket.tags }),
+                    ...(ticket.customFields && { custom_fields: ticket.customFields }),
+                },
+            };
+            try {
+                const response = await fetch(`${baseUrl}/tickets.json`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({}));
+                    throw new Error(error?.error || `HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return mapZendeskTicket(data.ticket);
+            }
+            catch (error) {
+                throw new Error(`Failed to create ticket: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+        async getTicket(ticketId) {
+            try {
+                const response = await fetch(`${baseUrl}/tickets/${ticketId}.json`, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    if (response.status === 404)
+                        return null;
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return mapZendeskTicket(data.ticket);
+            }
+            catch {
+                return null;
+            }
+        },
+        async updateTicket(ticketId, updates) {
+            const body = {
+                ticket: {
+                    ...(updates.subject && { subject: updates.subject }),
+                    ...(updates.priority && { priority: updates.priority }),
+                    ...(updates.type && { type: updates.type }),
+                    ...(updates.assigneeId && { assignee_id: updates.assigneeId }),
+                    ...(updates.tags && { tags: updates.tags }),
+                    ...(updates.customFields && { custom_fields: updates.customFields }),
+                },
+            };
+            // Add comment if description is provided
+            if (updates.description) {
+                body.ticket.comment = { body: updates.description };
+            }
+            try {
+                const response = await fetch(`${baseUrl}/tickets/${ticketId}.json`, {
+                    method: 'PUT',
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({}));
+                    throw new Error(error?.error || `HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return mapZendeskTicket(data.ticket);
+            }
+            catch (error) {
+                throw new Error(`Failed to update ticket: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+        async listTickets(options) {
+            const params = new URLSearchParams();
+            if (options?.limit)
+                params.append('per_page', options.limit.toString());
+            if (options?.cursor)
+                params.append('page[after]', options.cursor);
+            if (options?.status)
+                params.append('status', options.status);
+            if (options?.priority)
+                params.append('priority', options.priority);
+            if (options?.assigneeId)
+                params.append('assignee_id', options.assigneeId);
+            if (options?.requesterId)
+                params.append('requester_id', options.requesterId);
+            const url = `${baseUrl}/tickets.json${params.toString() ? `?${params.toString()}` : ''}`;
+            try {
+                const response = await fetch(url, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                const tickets = (data.tickets || []).map(mapZendeskTicket);
+                return {
+                    items: tickets,
+                    total: data.count,
+                    hasMore: data.next_page !== null,
+                    nextCursor: data.after_cursor,
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to list tickets: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+        async closeTicket(ticketId) {
+            try {
+                const response = await fetch(`${baseUrl}/tickets/${ticketId}.json`, {
+                    method: 'PUT',
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        ticket: {
+                            status: 'closed',
+                        },
+                    }),
+                });
+                return response.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+        async addTicketComment(ticketId, body, isPublic = true) {
+            try {
+                const response = await fetch(`${baseUrl}/tickets/${ticketId}.json`, {
+                    method: 'PUT',
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        ticket: {
+                            comment: {
+                                body,
+                                public: isPublic,
+                            },
+                        },
+                    }),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({}));
+                    throw new Error(error?.error || `HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                const audit = data.audit || {};
+                const comment = audit.events?.find((e) => e.type === 'Comment');
+                return {
+                    id: audit.id?.toString() || '',
+                    ticketId,
+                    body,
+                    authorId: audit.author_id?.toString() || '',
+                    isPublic,
+                    createdAt: new Date(audit.created_at || Date.now()),
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to add comment: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+        async listTicketComments(ticketId) {
+            try {
+                const response = await fetch(`${baseUrl}/tickets/${ticketId}/comments.json`, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return (data.comments || []).map((comment) => ({
+                    id: comment.id.toString(),
+                    ticketId,
+                    body: comment.body || comment.plain_body || '',
+                    authorId: comment.author_id?.toString() || '',
+                    isPublic: comment.public !== false,
+                    createdAt: new Date(comment.created_at),
+                }));
+            }
+            catch (error) {
+                throw new Error(`Failed to list comments: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+        async getUser(userId) {
+            try {
+                const response = await fetch(`${baseUrl}/users/${userId}.json`, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    if (response.status === 404)
+                        return null;
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return mapZendeskUser(data.user);
+            }
+            catch {
+                return null;
+            }
+        },
+        async searchUsers(query) {
+            try {
+                const params = new URLSearchParams({ query });
+                const response = await fetch(`${baseUrl}/users/search.json?${params.toString()}`, {
+                    headers: {
+                        Authorization: `Basic ${Buffer.from(`${email}/token:${apiKey}`).toString('base64')}`,
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                const data = (await response.json());
+                return (data.users || []).map(mapZendeskUser);
+            }
+            catch (error) {
+                throw new Error(`Failed to search users: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        },
+    };
+}
+/**
+ * Map Zendesk ticket to TicketData
+ */
+function mapZendeskTicket(ticket) {
+    return {
+        id: ticket.id.toString(),
+        subject: ticket.subject || '',
+        description: ticket.description || '',
+        status: mapZendeskStatus(ticket.status),
+        priority: ticket.priority || 'normal',
+        type: ticket.type,
+        requesterId: ticket.requester_id?.toString(),
+        assigneeId: ticket.assignee_id?.toString(),
+        tags: ticket.tags || [],
+        createdAt: new Date(ticket.created_at),
+        updatedAt: new Date(ticket.updated_at),
+        solvedAt: ticket.solved_at ? new Date(ticket.solved_at) : undefined,
+    };
+}
+/**
+ * Map Zendesk status to standard status
+ */
+function mapZendeskStatus(status) {
+    switch (status) {
+        case 'new':
+            return 'new';
+        case 'open':
+            return 'open';
+        case 'pending':
+            return 'pending';
+        case 'hold':
+            return 'hold';
+        case 'solved':
+            return 'solved';
+        case 'closed':
+            return 'closed';
+        default:
+            return 'open';
+    }
+}
+/**
+ * Map Zendesk user to SupportUserData
+ */
+function mapZendeskUser(user) {
+    return {
+        id: user.id.toString(),
+        name: user.name || '',
+        email: user.email || '',
+        role: user.role || 'end-user',
+        createdAt: new Date(user.created_at),
+    };
+}
+/**
+ * Zendesk provider definition
+ */
+export const zendeskProvider = defineProvider(zendeskInfo, async (config) => createZendeskProvider(config));

package/src/providers/tasks/index.js

@@ -0,0 +1,17 @@
+/**
+ * Task Providers
+ *
+ * @packageDocumentation
+ */
+export { todoistInfo, todoistProvider, createTodoistProvider } from './todoist.js';
+import { todoistProvider } from './todoist.js';
+/**
+ * Register all task providers
+ */
+export function registerTaskProviders() {
+    todoistProvider.register();
+}
+/**
+ * All task providers
+ */
+export const taskProviders = [todoistProvider];

package/src/providers/tasks/todoist.js

@@ -0,0 +1,286 @@
+/**
+ * Todoist Task Provider
+ *
+ * Concrete implementation of TaskProvider using Todoist REST API v2.
+ *
+ * @packageDocumentation
+ */
+import { defineProvider } from '../registry.js';
+const TODOIST_API_URL = 'https://api.todoist.com/rest/v2';
+/**
+ * Todoist provider info
+ */
+export const todoistInfo = {
+    id: 'tasks.todoist',
+    name: 'Todoist',
+    description: 'Todoist task management service',
+    category: 'tasks',
+    website: 'https://todoist.com',
+    docsUrl: 'https://developer.todoist.com/rest/v2',
+    requiredConfig: ['apiKey'],
+    optionalConfig: [],
+};
+/**
+ * Create Todoist task provider
+ */
+export function createTodoistProvider(config) {
+    let apiKey;
+    /**
+     * Make authenticated request to Todoist API
+     */
+    async function todoistRequest(endpoint, options = {}) {
+        const response = await fetch(`${TODOIST_API_URL}${endpoint}`, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Todoist API error (${response.status}): ${errorText}`);
+        }
+        // Handle 204 No Content responses
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    /**
+     * Convert Todoist project to ProjectData
+     */
+    function toProjectData(project) {
+        return {
+            id: project.id,
+            name: project.name,
+            color: project.color,
+            parentId: project.parent_id,
+        };
+    }
+    /**
+     * Convert Todoist task to TaskData
+     */
+    function toTaskData(task) {
+        let dueDate;
+        if (task.due?.datetime) {
+            dueDate = new Date(task.due.datetime);
+        }
+        else if (task.due?.date) {
+            dueDate = new Date(task.due.date);
+        }
+        return {
+            id: task.id,
+            content: task.content,
+            description: task.description,
+            projectId: task.project_id,
+            parentId: task.parent_id,
+            priority: task.priority,
+            dueDate,
+            completed: task.is_completed,
+            labels: task.labels,
+            createdAt: new Date(task.created_at),
+        };
+    }
+    /**
+     * Convert Todoist comment to CommentData
+     */
+    function toCommentData(comment) {
+        return {
+            id: comment.id,
+            taskId: comment.task_id || '',
+            content: comment.content,
+            authorId: '', // Todoist doesn't provide author_id in v2 API
+            createdAt: new Date(comment.posted_at),
+        };
+    }
+    return {
+        info: todoistInfo,
+        async initialize(cfg) {
+            apiKey = cfg.apiKey;
+            if (!apiKey) {
+                throw new Error('Todoist API key is required');
+            }
+        },
+        async healthCheck() {
+            const start = Date.now();
+            try {
+                // Try to fetch projects to verify connectivity
+                await todoistRequest('/projects');
+                return {
+                    healthy: true,
+                    latencyMs: Date.now() - start,
+                    message: 'Connected',
+                    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 listProjects() {
+            const projects = await todoistRequest('/projects');
+            return projects.map(toProjectData);
+        },
+        async createTask(task) {
+            const body = {
+                content: task.content,
+            };
+            if (task.description) {
+                body.description = task.description;
+            }
+            if (task.projectId) {
+                body.project_id = task.projectId;
+            }
+            if (task.parentId) {
+                body.parent_id = task.parentId;
+            }
+            if (task.priority) {
+                body.priority = task.priority;
+            }
+            if (task.dueDate) {
+                body.due_date = task.dueDate.toISOString().split('T')[0];
+            }
+            else if (task.dueString) {
+                body.due_string = task.dueString;
+            }
+            if (task.labels && task.labels.length > 0) {
+                body.labels = task.labels;
+            }
+            if (task.assigneeId) {
+                body.assignee_id = task.assigneeId;
+            }
+            const created = await todoistRequest('/tasks', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            return toTaskData(created);
+        },
+        async getTask(taskId) {
+            try {
+                const task = await todoistRequest(`/tasks/${taskId}`);
+                return toTaskData(task);
+            }
+            catch (error) {
+                // Return null if task not found
+                if (error instanceof Error && error.message.includes('404')) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async updateTask(taskId, updates) {
+            const body = {};
+            if (updates.content !== undefined) {
+                body.content = updates.content;
+            }
+            if (updates.description !== undefined) {
+                body.description = updates.description;
+            }
+            if (updates.priority !== undefined) {
+                body.priority = updates.priority;
+            }
+            if (updates.dueDate) {
+                body.due_date = updates.dueDate.toISOString().split('T')[0];
+            }
+            else if (updates.dueString) {
+                body.due_string = updates.dueString;
+            }
+            if (updates.labels !== undefined) {
+                body.labels = updates.labels;
+            }
+            if (updates.assigneeId !== undefined) {
+                body.assignee_id = updates.assigneeId;
+            }
+            await todoistRequest(`/tasks/${taskId}`, {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            // Fetch and return the updated task
+            const updated = await todoistRequest(`/tasks/${taskId}`);
+            return toTaskData(updated);
+        },
+        async deleteTask(taskId) {
+            try {
+                await todoistRequest(`/tasks/${taskId}`, {
+                    method: 'DELETE',
+                });
+                return true;
+            }
+            catch (error) {
+                return false;
+            }
+        },
+        async completeTask(taskId) {
+            try {
+                await todoistRequest(`/tasks/${taskId}/close`, {
+                    method: 'POST',
+                });
+                return true;
+            }
+            catch (error) {
+                return false;
+            }
+        },
+        async reopenTask(taskId) {
+            try {
+                await todoistRequest(`/tasks/${taskId}/reopen`, {
+                    method: 'POST',
+                });
+                return true;
+            }
+            catch (error) {
+                return false;
+            }
+        },
+        async listTasks(options) {
+            const params = new URLSearchParams();
+            if (options?.projectId) {
+                params.append('project_id', options.projectId);
+            }
+            if (options?.filter) {
+                params.append('filter', options.filter);
+            }
+            const queryString = params.toString();
+            const endpoint = `/tasks${queryString ? `?${queryString}` : ''}`;
+            const tasks = await todoistRequest(endpoint);
+            // Filter by completed status if specified
+            let filteredTasks = tasks;
+            if (options?.completed !== undefined) {
+                filteredTasks = tasks.filter((t) => t.is_completed === options.completed);
+            }
+            // Apply pagination
+            const limit = options?.limit || 50;
+            const offset = options?.offset || 0;
+            const paginatedTasks = filteredTasks.slice(offset, offset + limit);
+            return {
+                items: paginatedTasks.map(toTaskData),
+                total: filteredTasks.length,
+                hasMore: offset + limit < filteredTasks.length,
+            };
+        },
+        async addComment(taskId, content) {
+            const body = {
+                task_id: taskId,
+                content,
+            };
+            const comment = await todoistRequest('/comments', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            return toCommentData(comment);
+        },
+    };
+}
+/**
+ * Todoist provider definition
+ */
+export const todoistProvider = defineProvider(todoistInfo, async (config) => createTodoistProvider(config));

package/src/providers/types.js

@@ -0,0 +1,9 @@
+/**
+ * Provider Interface Types
+ *
+ * Defines the contract that concrete providers must implement.
+ * Each provider binds abstract entity types (Nouns) to real APIs/services.
+ *
+ * @packageDocumentation
+ */
+export {};