@slates-integrations/zoho 0.2.0-rc.5

package/src/tools/books-manage-invoice.ts

@@ -0,0 +1,190 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoBooksClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+let lineItemSchema = z.object({
+  itemId: z.string().optional().describe('Item ID from Zoho Books inventory'),
+  name: z.string().optional().describe('Item name'),
+  description: z.string().optional().describe('Item description'),
+  rate: z.number().optional().describe('Unit price'),
+  quantity: z.number().optional().describe('Quantity'),
+  discount: z.string().optional().describe('Discount percentage or flat amount'),
+  taxId: z.string().optional().describe('Tax ID to apply')
+});
+
+export let booksManageInvoice = SlateTool.create(spec, {
+  name: 'Books Manage Invoice',
+  key: 'books_manage_invoice',
+  description: `Create, update, delete, or change the status of invoices in Zoho Books. Supports setting customer, line items, payment terms, notes, and more. Can also mark invoices as sent, void, or draft.`,
+  instructions: [
+    'The organizationId is required for all Zoho Books operations.',
+    'For create, provide customerId and at least one line item.',
+    'For status changes (sent, void, draft), use the statusAction parameter.',
+    'Use the "list" action with a Books contact ID in customerId to list invoices for a specific customer.'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      organizationId: z.string().describe('Zoho Books organization ID'),
+      action: z
+        .enum(['create', 'update', 'delete', 'status'])
+        .describe('Operation to perform'),
+      invoiceId: z
+        .string()
+        .optional()
+        .describe('Invoice ID (required for update, delete, status)'),
+      customerId: z.string().optional().describe('Customer/contact ID (required for create)'),
+      invoiceNumber: z.string().optional().describe('Custom invoice number'),
+      date: z.string().optional().describe('Invoice date (YYYY-MM-DD)'),
+      dueDate: z.string().optional().describe('Due date (YYYY-MM-DD)'),
+      lineItems: z.array(lineItemSchema).optional().describe('Invoice line items'),
+      notes: z.string().optional().describe('Notes to appear on the invoice'),
+      terms: z.string().optional().describe('Terms and conditions'),
+      discount: z
+        .string()
+        .optional()
+        .describe('Discount at the invoice level (e.g., "10%" or "50.00")'),
+      statusAction: z
+        .enum(['sent', 'void', 'draft'])
+        .optional()
+        .describe('Status action to apply (for action="status")'),
+      customFields: z
+        .array(
+          z.object({
+            label: z.string(),
+            value: z.string()
+          })
+        )
+        .optional()
+        .describe('Custom field values')
+    })
+  )
+  .output(
+    z.object({
+      invoiceId: z.string().optional(),
+      invoiceNumber: z.string().optional(),
+      status: z.string().optional(),
+      total: z.number().optional(),
+      balance: z.number().optional(),
+      message: z.string().optional(),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoBooksClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      organizationId: ctx.input.organizationId
+    });
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.customerId) throw zohoServiceError('customerId is required for create');
+      if (!ctx.input.lineItems?.length)
+        throw zohoServiceError('lineItems is required for create');
+      let data: Record<string, any> = {};
+      if (ctx.input.customerId) data.customer_id = ctx.input.customerId;
+      if (ctx.input.invoiceNumber) data.invoice_number = ctx.input.invoiceNumber;
+      if (ctx.input.date) data.date = ctx.input.date;
+      if (ctx.input.dueDate) data.due_date = ctx.input.dueDate;
+      if (ctx.input.notes) data.notes = ctx.input.notes;
+      if (ctx.input.terms) data.terms = ctx.input.terms;
+      if (ctx.input.discount) data.discount = ctx.input.discount;
+      if (ctx.input.lineItems) {
+        data.line_items = ctx.input.lineItems.map(item => ({
+          item_id: item.itemId,
+          name: item.name,
+          description: item.description,
+          rate: item.rate,
+          quantity: item.quantity,
+          discount: item.discount,
+          tax_id: item.taxId
+        }));
+      }
+      if (ctx.input.customFields) data.custom_fields = ctx.input.customFields;
+
+      let result = await client.createInvoice(data);
+      let inv = result?.invoice;
+      return {
+        output: {
+          invoiceId: inv?.invoice_id,
+          invoiceNumber: inv?.invoice_number,
+          status: inv?.status,
+          total: inv?.total,
+          balance: inv?.balance,
+          message: result?.message
+        },
+        message: `Created invoice **${inv?.invoice_number}** for **${inv?.total}** (${inv?.status}).`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.invoiceId) throw zohoServiceError('invoiceId is required for update');
+      let data: Record<string, any> = {};
+      if (ctx.input.customerId) data.customer_id = ctx.input.customerId;
+      if (ctx.input.date) data.date = ctx.input.date;
+      if (ctx.input.dueDate) data.due_date = ctx.input.dueDate;
+      if (ctx.input.notes) data.notes = ctx.input.notes;
+      if (ctx.input.terms) data.terms = ctx.input.terms;
+      if (ctx.input.discount) data.discount = ctx.input.discount;
+      if (ctx.input.lineItems) {
+        data.line_items = ctx.input.lineItems.map(item => ({
+          item_id: item.itemId,
+          name: item.name,
+          description: item.description,
+          rate: item.rate,
+          quantity: item.quantity,
+          discount: item.discount,
+          tax_id: item.taxId
+        }));
+      }
+
+      let result = await client.updateInvoice(ctx.input.invoiceId, data);
+      let inv = result?.invoice;
+      return {
+        output: {
+          invoiceId: inv?.invoice_id,
+          invoiceNumber: inv?.invoice_number,
+          status: inv?.status,
+          total: inv?.total,
+          balance: inv?.balance,
+          message: result?.message
+        },
+        message: `Updated invoice **${inv?.invoice_number || ctx.input.invoiceId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.invoiceId) throw zohoServiceError('invoiceId is required for delete');
+      let result = await client.deleteInvoice(ctx.input.invoiceId);
+      return {
+        output: { invoiceId: ctx.input.invoiceId, deleted: true, message: result?.message },
+        message: `Deleted invoice **${ctx.input.invoiceId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'status') {
+      if (!ctx.input.invoiceId)
+        throw zohoServiceError('invoiceId is required for status change');
+      if (!ctx.input.statusAction)
+        throw zohoServiceError('statusAction is required for status change');
+      let result = await client.markInvoiceStatus(ctx.input.invoiceId, ctx.input.statusAction);
+      return {
+        output: {
+          invoiceId: ctx.input.invoiceId,
+          status: ctx.input.statusAction,
+          message: result?.message
+        },
+        message: `Marked invoice **${ctx.input.invoiceId}** as **${ctx.input.statusAction}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Books invoice action.');
+  })
+  .build();

package/src/tools/crm-get-modules.ts

@@ -0,0 +1,93 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoCrmClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+
+export let crmGetModules = SlateTool.create(spec, {
+  name: 'CRM Get Modules',
+  key: 'crm_get_modules',
+  description: `List all available modules in Zoho CRM along with their metadata. Returns module API names, labels, capabilities (creatable, viewable, editable, deletable), and status. Also supports listing CRM users.`,
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      status: z
+        .string()
+        .optional()
+        .describe('Filter modules by status, e.g. "visible" or "user_hidden,system_hidden"'),
+      includeUsers: z.boolean().optional().describe('Also fetch and include CRM user list'),
+      userType: z
+        .string()
+        .optional()
+        .describe('Filter users by type (e.g., "AllUsers", "ActiveUsers", "AdminUsers")')
+    })
+  )
+  .output(
+    z.object({
+      modules: z
+        .array(
+          z.object({
+            moduleId: z.string().optional(),
+            apiName: z.string(),
+            pluralLabel: z.string().optional(),
+            singularLabel: z.string().optional(),
+            creatable: z.boolean().optional(),
+            viewable: z.boolean().optional(),
+            editable: z.boolean().optional(),
+            deletable: z.boolean().optional(),
+            apiSupported: z.boolean().optional()
+          })
+        )
+        .describe('Available CRM modules'),
+      users: z
+        .array(
+          z.object({
+            userId: z.string().optional(),
+            fullName: z.string().optional(),
+            email: z.string().optional(),
+            role: z.string().optional(),
+            status: z.string().optional()
+          })
+        )
+        .optional()
+        .describe('CRM users (if includeUsers is true)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+    let modulesResult = await client.getModules({ status: ctx.input.status });
+    let modules = (modulesResult?.modules || []).map((m: any) => ({
+      moduleId: m.id,
+      apiName: m.api_name,
+      pluralLabel: m.plural_label,
+      singularLabel: m.singular_label,
+      creatable: m.creatable,
+      viewable: m.viewable,
+      editable: m.editable,
+      deletable: m.deletable,
+      apiSupported: m.api_supported
+    }));
+
+    let users: any[] | undefined;
+    if (ctx.input.includeUsers) {
+      let usersResult = await client.getUsers({ type: ctx.input.userType });
+      users = (usersResult?.users || []).map((u: any) => ({
+        userId: u.id,
+        fullName: u.full_name,
+        email: u.email,
+        role: u.role?.name,
+        status: u.status
+      }));
+    }
+
+    return {
+      output: { modules, users },
+      message: `Found **${modules.length}** CRM modules${users ? ` and **${users.length}** users` : ''}.`
+    };
+  })
+  .build();

package/src/tools/crm-get-records.ts

@@ -0,0 +1,137 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoCrmClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let crmGetRecords = SlateTool.create(spec, {
+  name: 'CRM Get Records',
+  key: 'crm_get_records',
+  description: `Retrieve records from any Zoho CRM module (Leads, Contacts, Accounts, Deals, Tasks, etc.). Supports pagination, field selection, sorting, and filtering by custom view ID. Can also fetch a single record by ID.`,
+  instructions: [
+    'Specify the module API name (e.g., "Leads", "Contacts", "Accounts", "Deals").',
+    'To fetch a single record, provide the recordId. To list records, omit recordId.',
+    'Use the fields parameter to limit which fields are returned (comma-separated API field names, max 50).'
+  ],
+  constraints: [
+    'Maximum 200 records per page.',
+    'Maximum 2000 records accessible via page-based pagination.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      module: z
+        .string()
+        .describe(
+          'CRM module API name (e.g., "Leads", "Contacts", "Accounts", "Deals", "Tasks")'
+        ),
+      recordId: z
+        .string()
+        .optional()
+        .describe('Specific record ID to fetch. If provided, returns a single record.'),
+      fields: z
+        .string()
+        .optional()
+        .describe('Comma-separated field API names to return (max 50)'),
+      ids: z
+        .string()
+        .optional()
+        .describe('Comma-separated record IDs to fetch from the module'),
+      page: z.number().optional().describe('Page number for pagination (default 1)'),
+      perPage: z.number().optional().describe('Number of records per page (max 200)'),
+      pageToken: z
+        .string()
+        .optional()
+        .describe('Page token for retrieving records after 2000'),
+      sortBy: z
+        .string()
+        .optional()
+        .describe('Field to sort by (e.g., "Created_Time", "Modified_Time")'),
+      sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort order'),
+      customViewId: z.string().optional().describe('Custom view ID to filter records'),
+      converted: z
+        .enum(['true', 'false', 'both'])
+        .optional()
+        .describe('Converted-record filter for supported modules'),
+      territoryId: z.string().optional().describe('Territory ID filter for supported modules'),
+      includeChild: z
+        .boolean()
+        .optional()
+        .describe('Include child territory records when territoryId is provided')
+    })
+  )
+  .output(
+    z.object({
+      records: z.array(z.record(z.string(), z.any())).describe('Array of CRM records'),
+      moreRecords: z.boolean().optional().describe('Whether more records are available'),
+      count: z.number().optional().describe('Number of records returned'),
+      nextPageToken: z.string().nullable().optional().describe('Token for the next page'),
+      previousPageToken: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Token for the previous page'),
+      pageTokenExpiry: z.string().nullable().optional().describe('Page token expiry timestamp')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+    if (ctx.input.recordId) {
+      let result = await client.getRecord(
+        ctx.input.module,
+        ctx.input.recordId,
+        ctx.input.fields
+      );
+      let records = result?.data || [];
+      return {
+        output: { records, moreRecords: false, count: records.length },
+        message: `Fetched record **${ctx.input.recordId}** from **${ctx.input.module}**.`
+      };
+    }
+
+    if (!ctx.input.fields) {
+      throw zohoServiceError('fields is required when listing CRM records.');
+    }
+    if (ctx.input.pageToken && ctx.input.page) {
+      throw zohoServiceError('pageToken cannot be used with page.');
+    }
+    if (ctx.input.customViewId && ctx.input.sortBy) {
+      throw zohoServiceError('customViewId cannot be used with sortBy.');
+    }
+
+    let result = await client.getRecords(ctx.input.module, {
+      fields: ctx.input.fields,
+      ids: ctx.input.ids,
+      page: ctx.input.page,
+      perPage: ctx.input.perPage,
+      pageToken: ctx.input.pageToken,
+      sortBy: ctx.input.sortBy,
+      sortOrder: ctx.input.sortOrder,
+      cvid: ctx.input.customViewId,
+      converted: ctx.input.converted,
+      territoryId: ctx.input.territoryId,
+      includeChild: ctx.input.includeChild
+    });
+
+    let records = result?.data || [];
+    let info = result?.info;
+
+    return {
+      output: {
+        records,
+        moreRecords: info?.more_records ?? false,
+        count: info?.count ?? records.length,
+        nextPageToken: info?.next_page_token,
+        previousPageToken: info?.previous_page_token,
+        pageTokenExpiry: info?.page_token_expiry
+      },
+      message: `Retrieved **${records.length}** records from **${ctx.input.module}**${info?.more_records ? ' (more available)' : ''}.`
+    };
+  })
+  .build();

package/src/tools/crm-get-related-records.ts

@@ -0,0 +1,104 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoCrmClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let crmGetRelatedRecords = SlateTool.create(spec, {
+  name: 'CRM Get Related Records',
+  key: 'crm_get_related_records',
+  description:
+    'Retrieve related records for a Zoho CRM record, such as Notes, Attachments, Emails, Deals, Contacts, or custom related lists. Supports field selection, pagination, sorting, and ID filtering.',
+  instructions: [
+    'Provide the parent module API name, parent record ID, and related list API name.',
+    'Use relatedListApiName values from CRM related list metadata, such as "Notes", "Attachments", or a custom related list API name.',
+    'The fields parameter is required by Zoho CRM for related-record list retrieval.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      module: z.string().describe('Parent CRM module API name, e.g. "Leads" or "Contacts"'),
+      recordId: z.string().describe('Parent CRM record ID'),
+      relatedListApiName: z.string().describe('Related list API name, e.g. "Notes"'),
+      fields: z
+        .string()
+        .describe('Comma-separated field API names to return from the related records'),
+      ids: z.string().optional().describe('Comma-separated related record IDs to fetch'),
+      page: z.number().optional().describe('Page number for pagination'),
+      perPage: z.number().optional().describe('Records per page, max 200'),
+      pageToken: z
+        .string()
+        .optional()
+        .describe('Page token for retrieving records after 2000'),
+      sortBy: z
+        .string()
+        .optional()
+        .describe('Sort field, typically id, Created_Time, or Modified_Time'),
+      sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort order'),
+      converted: z
+        .enum(['true', 'false', 'both'])
+        .optional()
+        .describe('Converted-record filter for supported modules')
+    })
+  )
+  .output(
+    z.object({
+      records: z.array(z.record(z.string(), z.any())).describe('Related CRM records'),
+      moreRecords: z
+        .boolean()
+        .optional()
+        .describe('Whether more related records are available'),
+      count: z.number().optional().describe('Number of records returned'),
+      nextPageToken: z.string().nullable().optional().describe('Token for the next page'),
+      previousPageToken: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Token for the previous page'),
+      pageTokenExpiry: z.string().nullable().optional().describe('Page token expiry timestamp')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+    if (ctx.input.pageToken && ctx.input.page) {
+      throw zohoServiceError('pageToken cannot be used with page.');
+    }
+
+    let result = await client.getRelatedRecords(
+      ctx.input.module,
+      ctx.input.recordId,
+      ctx.input.relatedListApiName,
+      {
+        fields: ctx.input.fields,
+        ids: ctx.input.ids,
+        page: ctx.input.page,
+        perPage: ctx.input.perPage,
+        pageToken: ctx.input.pageToken,
+        sortBy: ctx.input.sortBy,
+        sortOrder: ctx.input.sortOrder,
+        converted: ctx.input.converted
+      }
+    );
+
+    let records = result?.data || [];
+    let info = result?.info;
+
+    return {
+      output: {
+        records,
+        moreRecords: info?.more_records ?? false,
+        count: info?.count ?? records.length,
+        nextPageToken: info?.next_page_token,
+        previousPageToken: info?.previous_page_token,
+        pageTokenExpiry: info?.page_token_expiry
+      },
+      message: `Retrieved **${records.length}** related records from **${ctx.input.relatedListApiName}**.`
+    };
+  })
+  .build();

package/src/tools/crm-manage-record.ts

@@ -0,0 +1,117 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoCrmClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let crmManageRecord = SlateTool.create(spec, {
+  name: 'CRM Manage Record',
+  key: 'crm_manage_record',
+  description: `Create, update, or delete records in any Zoho CRM module (Leads, Contacts, Accounts, Deals, etc.). Supports creating single or multiple records, updating fields on existing records, and deleting records by ID.`,
+  instructions: [
+    'Set action to "create" to insert new records, "update" to modify existing, or "delete" to remove.',
+    'For create, provide recordData as an array of objects with field API names as keys.',
+    'For update, provide recordId and recordData with fields to change.',
+    'For delete, provide recordId.',
+    'Field names must be CRM API field names (e.g., "Last_Name", "Email", "Company").'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      module: z
+        .string()
+        .describe('CRM module API name (e.g., "Leads", "Contacts", "Accounts", "Deals")'),
+      action: z.enum(['create', 'update', 'delete']).describe('Operation to perform'),
+      recordId: z.string().optional().describe('Record ID (required for update and delete)'),
+      recordData: z
+        .union([z.array(z.record(z.string(), z.any())), z.record(z.string(), z.any())])
+        .optional()
+        .describe(
+          'Record data: an object for update, or array of objects for create. Field API names as keys.'
+        ),
+      triggers: z
+        .array(z.enum(['workflow', 'approval', 'blueprint']))
+        .optional()
+        .describe('Workflow triggers to execute on this operation')
+    })
+  )
+  .output(
+    z.object({
+      results: z
+        .array(
+          z.object({
+            recordId: z.string().optional(),
+            status: z.string(),
+            message: z.string().optional(),
+            code: z.string().optional()
+          })
+        )
+        .describe('Result for each record in the operation')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoCrmClient({ token: ctx.auth.token, datacenter: dc });
+
+    if (ctx.input.action === 'create') {
+      let records = Array.isArray(ctx.input.recordData)
+        ? ctx.input.recordData
+        : [ctx.input.recordData || {}];
+      let result = await client.createRecords(ctx.input.module, records, ctx.input.triggers);
+      let results = (result?.data || []).map((r: any) => ({
+        recordId: r?.details?.id,
+        status: r?.status || 'unknown',
+        message: r?.message,
+        code: r?.code
+      }));
+      return {
+        output: { results },
+        message: `Created **${results.filter((r: any) => r.status === 'success').length}** record(s) in **${ctx.input.module}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.recordId) throw zohoServiceError('recordId is required for update');
+      let data = Array.isArray(ctx.input.recordData)
+        ? ctx.input.recordData[0] || {}
+        : ctx.input.recordData || {};
+      let result = await client.updateRecord(
+        ctx.input.module,
+        ctx.input.recordId,
+        data,
+        ctx.input.triggers
+      );
+      let results = (result?.data || []).map((r: any) => ({
+        recordId: r?.details?.id || ctx.input.recordId,
+        status: r?.status || 'unknown',
+        message: r?.message,
+        code: r?.code
+      }));
+      return {
+        output: { results },
+        message: `Updated record **${ctx.input.recordId}** in **${ctx.input.module}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.recordId) throw zohoServiceError('recordId is required for delete');
+      let result = await client.deleteRecord(ctx.input.module, ctx.input.recordId);
+      let results = (result?.data || []).map((r: any) => ({
+        recordId: r?.details?.id || ctx.input.recordId,
+        status: r?.status || 'unknown',
+        message: r?.message,
+        code: r?.code
+      }));
+      return {
+        output: { results },
+        message: `Deleted record **${ctx.input.recordId}** from **${ctx.input.module}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid CRM record action.');
+  })
+  .build();