@slates-integrations/zoho 0.2.0-rc.5

package/src/tools/projects-get-portals.ts

@@ -0,0 +1,50 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoProjectsClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+
+export let projectsGetPortals = SlateTool.create(spec, {
+  name: 'Projects Get Portals',
+  key: 'projects_get_portals',
+  description:
+    'List Zoho Projects portals available to the authenticated user so project and task tools can be called with the correct portalId.',
+  tags: {
+    readOnly: true
+  }
+})
+  .input(z.object({}))
+  .output(
+    z.object({
+      portals: z
+        .array(
+          z.object({
+            portalId: z.string(),
+            name: z.string().optional(),
+            role: z.string().optional()
+          })
+        )
+        .describe('Available Zoho Projects portals')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let result = await ZohoProjectsClient.listPortals(ctx.auth.token, dc);
+    let portals = (result?.portals || [])
+      .map((portal: any) => ({
+        portalId: portal.id || portal.portal_id || portal.portalId,
+        name: portal.name || portal.portal_name,
+        role: portal.role
+      }))
+      .filter((portal: { portalId?: unknown }) => portal.portalId)
+      .map((portal: { portalId: unknown; name?: string; role?: string }) => ({
+        ...portal,
+        portalId: String(portal.portalId)
+      }));
+
+    return {
+      output: { portals },
+      message: `Found **${portals.length}** Zoho Projects portals.`
+    };
+  })
+  .build();

package/src/tools/projects-manage-project.ts

@@ -0,0 +1,164 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoProjectsClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let projectsManageProject = SlateTool.create(spec, {
+  name: 'Projects Manage Project',
+  key: 'projects_manage_project',
+  description: `Create, update, delete, or list projects in Zoho Projects. Manage project names, descriptions, status, start/end dates, and owners. Also supports listing tasks and milestones within a project.`,
+  instructions: [
+    'The portalId is required for all Zoho Projects operations.',
+    'Use action "list_tasks" or "list_milestones" with a projectId to view items within a project.'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      portalId: z.string().describe('Zoho Projects portal ID'),
+      action: z
+        .enum(['list', 'get', 'create', 'update', 'delete', 'list_tasks', 'list_milestones'])
+        .describe('Operation to perform'),
+      projectId: z
+        .string()
+        .optional()
+        .describe(
+          'Project ID (required for get, update, delete, list_tasks, list_milestones)'
+        ),
+      name: z.string().optional().describe('Project name (required for create)'),
+      description: z.string().optional().describe('Project description'),
+      status: z.string().optional().describe('Project status (e.g., "active", "archived")'),
+      startDate: z.string().optional().describe('Start date (MM-dd-yyyy)'),
+      endDate: z.string().optional().describe('End date (MM-dd-yyyy)'),
+      ownerId: z.string().optional().describe('Project owner user ID'),
+      index: z.number().optional().describe('Start index for pagination'),
+      range: z.number().optional().describe('Number of records to return')
+    })
+  )
+  .output(
+    z.object({
+      projects: z.array(z.record(z.string(), z.any())).optional().describe('List of projects'),
+      project: z.record(z.string(), z.any()).optional().describe('Single project'),
+      tasks: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Tasks within a project'),
+      milestones: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Milestones within a project'),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoProjectsClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      portalId: ctx.input.portalId
+    });
+
+    if (ctx.input.action === 'list') {
+      let result = await client.listProjects({
+        index: ctx.input.index,
+        range: ctx.input.range,
+        status: ctx.input.status
+      });
+      let projects = result?.projects || [];
+      return {
+        output: { projects },
+        message: `Retrieved **${projects.length}** projects.`
+      };
+    }
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.projectId) throw zohoServiceError('projectId is required for get');
+      let result = await client.getProject(ctx.input.projectId);
+      let project = result?.projects?.[0] || result;
+      return {
+        output: { project },
+        message: `Fetched project **${project?.name || ctx.input.projectId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.name) throw zohoServiceError('name is required for create');
+      let data: Record<string, any> = {};
+      if (ctx.input.name) data.name = ctx.input.name;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.status) data.status = ctx.input.status;
+      if (ctx.input.startDate) data.start_date = ctx.input.startDate;
+      if (ctx.input.endDate) data.end_date = ctx.input.endDate;
+      if (ctx.input.ownerId) data.owner = ctx.input.ownerId;
+
+      let result = await client.createProject(data);
+      let project = result?.projects?.[0] || result;
+      return {
+        output: { project },
+        message: `Created project **${project?.name}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.projectId) throw zohoServiceError('projectId is required for update');
+      let data: Record<string, any> = {};
+      if (ctx.input.name) data.name = ctx.input.name;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.status) data.status = ctx.input.status;
+      if (ctx.input.startDate) data.start_date = ctx.input.startDate;
+      if (ctx.input.endDate) data.end_date = ctx.input.endDate;
+      if (ctx.input.ownerId) data.owner = ctx.input.ownerId;
+
+      let result = await client.updateProject(ctx.input.projectId, data);
+      let project = result?.projects?.[0] || result;
+      return {
+        output: { project },
+        message: `Updated project **${ctx.input.projectId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.projectId) throw zohoServiceError('projectId is required for delete');
+      await client.deleteProject(ctx.input.projectId);
+      return {
+        output: { deleted: true },
+        message: `Deleted project **${ctx.input.projectId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'list_tasks') {
+      if (!ctx.input.projectId) throw zohoServiceError('projectId is required for list_tasks');
+      let result = await client.listTasks(ctx.input.projectId, {
+        index: ctx.input.index,
+        range: ctx.input.range,
+        status: ctx.input.status
+      });
+      let tasks = result?.tasks || [];
+      return {
+        output: { tasks },
+        message: `Retrieved **${tasks.length}** tasks from project **${ctx.input.projectId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'list_milestones') {
+      if (!ctx.input.projectId)
+        throw zohoServiceError('projectId is required for list_milestones');
+      let result = await client.listMilestones(ctx.input.projectId, {
+        index: ctx.input.index,
+        range: ctx.input.range,
+        status: ctx.input.status
+      });
+      let milestones = result?.milestones || [];
+      return {
+        output: { milestones },
+        message: `Retrieved **${milestones.length}** milestones from project **${ctx.input.projectId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Projects project action.');
+  })
+  .build();

package/src/tools/projects-manage-task.ts

@@ -0,0 +1,108 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoProjectsClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let projectsManageTask = SlateTool.create(spec, {
+  name: 'Projects Manage Task',
+  key: 'projects_manage_task',
+  description: `Create, update, delete, or retrieve tasks within a Zoho Projects project. Set task names, descriptions, owners, priority, start/end dates, and status.`,
+  instructions: ['Both portalId and projectId are required.', 'For create, name is required.'],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      portalId: z.string().describe('Zoho Projects portal ID'),
+      projectId: z.string().describe('Project ID containing the task'),
+      action: z.enum(['get', 'create', 'update', 'delete']).describe('Operation to perform'),
+      taskId: z.string().optional().describe('Task ID (required for get, update, delete)'),
+      name: z.string().optional().describe('Task name (required for create)'),
+      description: z.string().optional().describe('Task description'),
+      startDate: z.string().optional().describe('Start date (MM-dd-yyyy)'),
+      endDate: z.string().optional().describe('End date (MM-dd-yyyy)'),
+      priority: z
+        .string()
+        .optional()
+        .describe('Task priority (e.g., "None", "Low", "Medium", "High")'),
+      status: z.string().optional().describe('Task status'),
+      owners: z
+        .string()
+        .optional()
+        .describe('Comma-separated user IDs to assign as task owners'),
+      percentComplete: z.number().optional().describe('Completion percentage (0-100)')
+    })
+  )
+  .output(
+    z.object({
+      task: z.record(z.string(), z.any()).optional().describe('Task record'),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoProjectsClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      portalId: ctx.input.portalId
+    });
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.taskId) throw zohoServiceError('taskId is required for get');
+      let result = await client.getTask(ctx.input.projectId, ctx.input.taskId);
+      let task = result?.tasks?.[0] || result;
+      return {
+        output: { task },
+        message: `Fetched task **${task?.name || ctx.input.taskId}**.`
+      };
+    }
+
+    let buildData = () => {
+      let data: Record<string, any> = {};
+      if (ctx.input.name) data.name = ctx.input.name;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.startDate) data.start_date = ctx.input.startDate;
+      if (ctx.input.endDate) data.end_date = ctx.input.endDate;
+      if (ctx.input.priority) data.priority = ctx.input.priority;
+      if (ctx.input.status) data.status_name = ctx.input.status;
+      if (ctx.input.owners) data.persons = ctx.input.owners;
+      if (ctx.input.percentComplete !== undefined)
+        data.percent_complete = ctx.input.percentComplete;
+      return data;
+    };
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.name) throw zohoServiceError('name is required for create');
+      let result = await client.createTask(ctx.input.projectId, buildData());
+      let task = result?.tasks?.[0] || result;
+      return {
+        output: { task },
+        message: `Created task **${task?.name}** in project **${ctx.input.projectId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.taskId) throw zohoServiceError('taskId is required for update');
+      let result = await client.updateTask(ctx.input.projectId, ctx.input.taskId, buildData());
+      let task = result?.tasks?.[0] || result;
+      return {
+        output: { task },
+        message: `Updated task **${ctx.input.taskId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.taskId) throw zohoServiceError('taskId is required for delete');
+      await client.deleteTask(ctx.input.projectId, ctx.input.taskId);
+      return {
+        output: { deleted: true },
+        message: `Deleted task **${ctx.input.taskId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Projects task action.');
+  })
+  .build();

package/src/triggers/crm-record-events.ts

@@ -0,0 +1,143 @@
+import { SlateTrigger } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoCrmClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+
+export let crmRecordEvents = SlateTrigger.create(spec, {
+  name: 'CRM Record Events',
+  key: 'crm_record_events',
+  description:
+    'Triggers when CRM records are created, updated, or deleted in Zoho CRM. Uses the CRM Notification/Watch API to receive real-time push notifications.'
+})
+  .input(
+    z.object({
+      module: z.string().describe('CRM module name (e.g., Leads, Contacts, Deals)'),
+      operation: z.string().describe('Operation type (insert, update, delete)'),
+      recordIds: z.array(z.string()).describe('Affected record IDs'),
+      channelId: z.string().describe('Notification channel ID'),
+      token: z.string().optional().describe('Verification token'),
+      serverTime: z.string().optional().describe('Server timestamp of the event'),
+      affectedFields: z.record(z.string(), z.any()).optional().describe('Changed field values')
+    })
+  )
+  .output(
+    z.object({
+      module: z.string().describe('CRM module name'),
+      recordIds: z.array(z.string()).describe('Affected record IDs'),
+      operation: z.string().describe('Operation performed (insert, update, delete)'),
+      channelId: z.string().describe('Notification channel ID'),
+      serverTime: z.string().optional().describe('Server timestamp'),
+      affectedFields: z.record(z.string(), z.any()).optional().describe('Changed field values')
+    })
+  )
+  .webhook({
+    autoRegisterWebhook: async ctx => {
+      let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+      let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+      let channelId = `${Date.now()}`;
+
+      // Subscribe to all events for major modules
+      let modules = ['Leads', 'Contacts', 'Accounts', 'Deals', 'Tasks', 'Events', 'Calls'];
+      let events = modules.flatMap(m => [`${m}.all`]);
+
+      // Channel expiry max is 1 week
+      let expiry = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
+
+      let result = await client.enableNotifications([
+        {
+          channelId,
+          events,
+          notifyUrl: ctx.input.webhookBaseUrl,
+          channelExpiry: expiry,
+          returnAffectedFieldValues: true
+        }
+      ]);
+
+      return {
+        registrationDetails: {
+          channelId,
+          events,
+          result
+        }
+      };
+    },
+
+    autoUnregisterWebhook: async ctx => {
+      let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+      let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+      let channelId = ctx.input.registrationDetails?.channelId;
+      if (channelId) {
+        await client.disableNotifications([channelId]);
+      }
+    },
+
+    handleRequest: async ctx => {
+      let body: any = await ctx.request.json();
+
+      // Zoho CRM sends notifications as a JSON body with module, operation, ids, etc.
+      let inputs: Array<{
+        module: string;
+        operation: string;
+        recordIds: string[];
+        channelId: string;
+        token?: string;
+        serverTime?: string;
+        affectedFields?: Record<string, any>;
+      }> = [];
+
+      // The body can be a single notification or contain query_map
+      if (body?.module) {
+        inputs.push({
+          module: body.module,
+          operation: body.operation || 'unknown',
+          recordIds: body.ids || [],
+          channelId: body.channel_id?.toString() || '',
+          token: body.token,
+          serverTime: body.server_time,
+          affectedFields: body.affected_fields
+        });
+      } else if (body?.query_map) {
+        // Some CRM webhooks send via query_map format
+        let qm =
+          typeof body.query_map === 'string' ? JSON.parse(body.query_map) : body.query_map;
+        inputs.push({
+          module: qm.module || '',
+          operation: qm.operation || 'unknown',
+          recordIds: qm.ids || [],
+          channelId: qm.channel_id?.toString() || '',
+          token: qm.token,
+          serverTime: qm.server_time,
+          affectedFields: qm.affected_fields
+        });
+      }
+
+      return { inputs };
+    },
+
+    handleEvent: async ctx => {
+      let operationMap: Record<string, string> = {
+        insert: 'created',
+        update: 'updated',
+        delete: 'deleted'
+      };
+
+      let eventType = operationMap[ctx.input.operation] || ctx.input.operation;
+
+      return {
+        type: `crm.${ctx.input.module.toLowerCase()}.${eventType}`,
+        id: `${ctx.input.channelId}-${ctx.input.module}-${ctx.input.operation}-${ctx.input.recordIds.join(',')}`,
+        output: {
+          module: ctx.input.module,
+          recordIds: ctx.input.recordIds,
+          operation: ctx.input.operation,
+          channelId: ctx.input.channelId,
+          serverTime: ctx.input.serverTime,
+          affectedFields: ctx.input.affectedFields
+        }
+      };
+    }
+  })
+  .build();

package/src/triggers/desk-events.ts

@@ -0,0 +1,121 @@
+import { SlateTrigger } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoDeskClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let deskEvents = SlateTrigger.create(spec, {
+  name: 'Desk Events',
+  key: 'desk_events',
+  description:
+    'Triggers when tickets, contacts, accounts, tasks, or other resources are created, updated, or deleted in Zoho Desk. Uses Zoho Desk webhook subscriptions for real-time notifications.'
+})
+  .input(
+    z.object({
+      eventType: z
+        .string()
+        .describe('Desk event type (e.g., Ticket_Add, Ticket_Update, Contact_Add)'),
+      resourceId: z.string().describe('ID of the affected resource'),
+      payload: z.record(z.string(), z.any()).describe('Full event payload from Zoho Desk')
+    })
+  )
+  .output(
+    z.object({
+      eventType: z.string().describe('Event type (e.g., Ticket_Add, Ticket_Update)'),
+      resourceType: z.string().describe('Resource type (e.g., ticket, contact, account)'),
+      resourceId: z.string().describe('ID of the affected resource'),
+      ticketNumber: z.string().optional().describe('Ticket number (for ticket events)'),
+      subject: z.string().optional().describe('Ticket subject (for ticket events)'),
+      status: z.string().optional().describe('Current status'),
+      departmentId: z.string().optional().describe('Department ID'),
+      payload: z.record(z.string(), z.any()).describe('Full event payload')
+    })
+  )
+  .webhook({
+    autoRegisterWebhook: async ctx => {
+      let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+      // We need an orgId - we'll try to extract from existing config or require it
+      // For auto-registration, the orgId must be available; we'll use a default approach
+      // The orgId should be provided as part of trigger configuration
+      // For now, we register the webhook if we can determine the orgId
+
+      // Since we don't have orgId from config, we'll try to retrieve from Desk API
+      // This is a limitation - the user should configure orgId in trigger setup
+      // We'll need to accept that the trigger may need manual configuration
+
+      // Note: This auto-registration requires orgId. In practice, the user should
+      // provide it. We'll throw an informative error if not available.
+      throw zohoServiceError(
+        'Zoho Desk webhooks require an organization ID (orgId). Please configure the webhook manually in Zoho Desk settings, pointing to the webhook URL.'
+      );
+    },
+
+    handleRequest: async ctx => {
+      let body: any;
+      try {
+        body = await ctx.request.json();
+      } catch {
+        return { inputs: [] };
+      }
+
+      if (!body || typeof body !== 'object') return { inputs: [] };
+
+      // Zoho Desk webhook payloads include event info and the affected resource
+      let eventType = body.eventType || body.event_type || '';
+      let payload = body.payload || body;
+
+      // Extract resource ID based on event type
+      let resourceId =
+        payload.id ||
+        payload.ticketId ||
+        payload.contactId ||
+        payload.accountId ||
+        payload.taskId ||
+        '';
+
+      let inputs = [
+        {
+          eventType: eventType.toString(),
+          resourceId: resourceId.toString(),
+          payload
+        }
+      ];
+
+      return { inputs };
+    },
+
+    handleEvent: async ctx => {
+      let payload = ctx.input.payload;
+      let eventType = ctx.input.eventType;
+
+      // Determine resource type from event type
+      let resourceType = 'unknown';
+      if (eventType.startsWith('Ticket')) resourceType = 'ticket';
+      else if (eventType.startsWith('Contact')) resourceType = 'contact';
+      else if (eventType.startsWith('Account')) resourceType = 'account';
+      else if (eventType.startsWith('Task')) resourceType = 'task';
+      else if (eventType.startsWith('Call')) resourceType = 'call';
+      else if (eventType.startsWith('Event')) resourceType = 'event';
+      else if (eventType.startsWith('IM')) resourceType = 'im';
+      else if (eventType.startsWith('Department')) resourceType = 'department';
+
+      let normalizedType = eventType.toLowerCase().replace(/_/g, '.');
+
+      return {
+        type: `desk.${normalizedType}`,
+        id: `${eventType}-${ctx.input.resourceId}-${Date.now()}`,
+        output: {
+          eventType,
+          resourceType,
+          resourceId: ctx.input.resourceId,
+          ticketNumber: payload.ticketNumber,
+          subject: payload.subject,
+          status: payload.status || payload.statusType,
+          departmentId: payload.departmentId,
+          payload
+        }
+      };
+    }
+  })
+  .build();

package/src/triggers/index.ts

@@ -0,0 +1,2 @@
+export { crmRecordEvents } from './crm-record-events';
+export { deskEvents } from './desk-events';

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src"]
+}