@slates-integrations/zoho 0.2.0-rc.5

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

@@ -0,0 +1,109 @@
+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 crmSearchRecords = SlateTool.create(spec, {
+  name: 'CRM Search Records',
+  key: 'crm_search_records',
+  description: `Search for records in a Zoho CRM module using criteria, email, phone, or keyword. Also supports executing COQL (CRM Object Query Language) queries for more complex data retrieval similar to SQL SELECT statements.`,
+  instructions: [
+    'For basic search, provide one of: criteria, email, phone, or word.',
+    'Criteria format: `((field_api_name:operator:value))` — operators include equals, not_equal, starts_with, contains, greater_than, less_than, between, in.',
+    'Multiple criteria can be combined with `and`/`or`: `((Last_Name:equals:Smith)and(Company:equals:Acme))`.',
+    "For COQL queries, provide a coqlQuery string like `select Last_Name, Email from Leads where Company = 'Acme' limit 10`.",
+    'Search results are indexed asynchronously — newly created records may not appear immediately. Use COQL for real-time results.'
+  ],
+  constraints: [
+    'Search returns a maximum of 2000 records.',
+    'Only one search parameter (criteria, email, phone, word) is used at a time, with priority: criteria > email > phone > word.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      module: z
+        .string()
+        .optional()
+        .describe('CRM module API name (required for search, not needed for COQL)'),
+      criteria: z
+        .string()
+        .optional()
+        .describe('Search criteria expression, e.g., ((Last_Name:equals:Smith))'),
+      email: z.string().optional().describe('Search by email address across all email fields'),
+      phone: z.string().optional().describe('Search by phone number across all phone fields'),
+      word: z.string().optional().describe('Keyword search across all text fields'),
+      coqlQuery: z
+        .string()
+        .optional()
+        .describe(
+          'COQL query string (e.g., "select Last_Name, Email from Leads where Company = \'Acme\'")'
+        ),
+      fields: z.string().optional().describe('Comma-separated field API names to return'),
+      converted: z
+        .enum(['true', 'false', 'both'])
+        .optional()
+        .describe('Converted-record filter'),
+      approved: z.enum(['true', 'false', 'both']).optional().describe('Approval-state filter'),
+      userType: z
+        .string()
+        .optional()
+        .describe('Users module type filter, such as "ActiveUsers" or "CurrentUser"'),
+      page: z.number().optional().describe('Page number for pagination'),
+      perPage: z.number().optional().describe('Records per page (max 200)')
+    })
+  )
+  .output(
+    z.object({
+      records: z.array(z.record(z.string(), z.any())).describe('Matching records'),
+      count: z.number().optional().describe('Number of records returned'),
+      moreRecords: z.boolean().optional().describe('Whether more records are available')
+    })
+  )
+  .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.coqlQuery) {
+      let result = await client.executeCoql(ctx.input.coqlQuery);
+      let records = result?.data || [];
+      return {
+        output: {
+          records,
+          count: result?.info?.count ?? records.length,
+          moreRecords: result?.info?.more_records ?? false
+        },
+        message: `COQL query returned **${records.length}** records.`
+      };
+    }
+
+    if (!ctx.input.module) throw zohoServiceError('module is required when not using COQL');
+
+    let result = await client.searchRecords(ctx.input.module, {
+      criteria: ctx.input.criteria,
+      email: ctx.input.email,
+      phone: ctx.input.phone,
+      word: ctx.input.word,
+      page: ctx.input.page,
+      perPage: ctx.input.perPage,
+      fields: ctx.input.fields,
+      converted: ctx.input.converted,
+      approved: ctx.input.approved,
+      userType: ctx.input.userType
+    });
+
+    let records = result?.data || [];
+    return {
+      output: {
+        records,
+        count: result?.info?.count ?? records.length,
+        moreRecords: result?.info?.more_records ?? false
+      },
+      message: `Search in **${ctx.input.module}** returned **${records.length}** records.`
+    };
+  })
+  .build();

package/src/tools/desk-get-tickets.ts

@@ -0,0 +1,146 @@
+import { SlateTool } 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 deskGetTickets = SlateTool.create(spec, {
+  name: 'Desk Get Tickets',
+  key: 'desk_get_tickets',
+  description: `List, search, or retrieve support tickets from Zoho Desk. Supports filtering by department, status, and keyword search. Can also list departments for reference.`,
+  instructions: [
+    'The orgId is required for all Zoho Desk operations.',
+    'Provide ticketId to fetch a single ticket, or omit to list/search tickets.',
+    'Use searchQuery for keyword-based search.',
+    'Set includeDepartments to true to also return department list.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      orgId: z
+        .string()
+        .optional()
+        .describe('Zoho Desk organization ID (required unless listOrganizations is true)'),
+      listOrganizations: z
+        .boolean()
+        .optional()
+        .describe('If true, list Desk organizations instead of tickets'),
+      ticketId: z.string().optional().describe('Specific ticket ID to fetch'),
+      searchQuery: z.string().optional().describe('Search keyword to find tickets'),
+      departmentId: z.string().optional().describe('Filter by department ID'),
+      status: z.string().optional().describe('Filter by ticket status'),
+      from: z.number().optional().describe('Starting index for pagination (default 0)'),
+      limit: z.number().optional().describe('Number of tickets to return (max 100)'),
+      sortBy: z
+        .string()
+        .optional()
+        .describe('Field to sort by (e.g., "modifiedTime", "createdTime")'),
+      sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort order'),
+      includeDepartments: z
+        .boolean()
+        .optional()
+        .describe('Also return the list of departments')
+    })
+  )
+  .output(
+    z.object({
+      tickets: z.array(z.record(z.string(), z.any())).describe('Support tickets'),
+      organizations: z
+        .array(
+          z.object({
+            organizationId: z.string(),
+            name: z.string().optional(),
+            isDefault: z.boolean().optional()
+          })
+        )
+        .optional()
+        .describe('Desk organizations (if listOrganizations is true)'),
+      departments: z
+        .array(
+          z.object({
+            departmentId: z.string(),
+            name: z.string()
+          })
+        )
+        .optional()
+        .describe('Departments (if includeDepartments is true)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+
+    if (ctx.input.listOrganizations) {
+      let result = await ZohoDeskClient.listOrganizations(ctx.auth.token, dc);
+      let organizationRecords = result?.data || result?.organizations || result || [];
+      if (!Array.isArray(organizationRecords)) organizationRecords = [];
+      let organizations = organizationRecords.map((org: any) => ({
+        organizationId: String(org.id),
+        name: org.companyName || org.portalName,
+        isDefault: org.isDefault === true || org.isDefault === 'true'
+      }));
+      return {
+        output: { tickets: [], organizations },
+        message: `Found **${organizations.length}** Zoho Desk organizations.`
+      };
+    }
+
+    if (!ctx.input.orgId) {
+      throw zohoServiceError('orgId is required unless listOrganizations is true');
+    }
+
+    let client = new ZohoDeskClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      orgId: ctx.input.orgId
+    });
+
+    if (ctx.input.ticketId) {
+      let ticket = await client.getTicket(ctx.input.ticketId);
+      return {
+        output: { tickets: [ticket] },
+        message: `Fetched ticket **#${ticket?.ticketNumber || ctx.input.ticketId}**.`
+      };
+    }
+
+    let tickets: any[];
+    if (ctx.input.searchQuery) {
+      let result = await client.searchTickets({
+        searchStr: ctx.input.searchQuery,
+        departmentId: ctx.input.departmentId,
+        from: ctx.input.from,
+        limit: ctx.input.limit,
+        statusType: ctx.input.status
+      });
+      tickets = result?.data || [];
+    } else {
+      let result = await client.listTickets({
+        departmentId: ctx.input.departmentId,
+        status: ctx.input.status,
+        from: ctx.input.from,
+        limit: ctx.input.limit,
+        sortBy: ctx.input.sortBy,
+        sortOrder: ctx.input.sortOrder
+      });
+      tickets = result?.data || result || [];
+      if (!Array.isArray(tickets)) tickets = [];
+    }
+
+    let departments: any[] | undefined;
+    if (ctx.input.includeDepartments) {
+      let deptResult = await client.getDepartments();
+      departments = (deptResult?.data || deptResult || []).map((d: any) => ({
+        departmentId: String(d.id),
+        name: d.name
+      }));
+    }
+
+    return {
+      output: { tickets, departments },
+      message: `Retrieved **${tickets.length}** tickets${departments ? ` and **${departments.length}** departments` : ''}.`
+    };
+  })
+  .build();

package/src/tools/desk-manage-contact.ts

@@ -0,0 +1,125 @@
+import { SlateTool } 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 deskManageContact = SlateTool.create(spec, {
+  name: 'Desk Manage Contact',
+  key: 'desk_manage_contact',
+  description:
+    'List, get, create, update, or delete Zoho Desk contacts. Useful for managing requesters before creating support tickets.',
+  instructions: [
+    'The orgId parameter is required for all contact operations.',
+    'For create, provide at least lastName or email depending on your Desk portal requirements.',
+    'For update, get, and delete, provide contactId.'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      orgId: z.string().describe('Zoho Desk organization ID'),
+      action: z.enum(['list', 'get', 'create', 'update', 'delete']).describe('Operation'),
+      contactId: z.string().optional().describe('Contact ID for get, update, and delete'),
+      firstName: z.string().optional().describe('Contact first name'),
+      lastName: z.string().optional().describe('Contact last name'),
+      email: z.string().optional().describe('Contact email address'),
+      phone: z.string().optional().describe('Contact phone number'),
+      mobile: z.string().optional().describe('Contact mobile number'),
+      accountId: z.string().optional().describe('Associated Desk account ID'),
+      description: z.string().optional().describe('Contact description'),
+      customFields: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe('Custom field values as key-value pairs'),
+      from: z.number().optional().describe('Starting index for list pagination'),
+      limit: z.number().optional().describe('Number of contacts to list, max 100'),
+      sortBy: z
+        .string()
+        .optional()
+        .describe('Sort field, e.g. "firstName", "lastName", "email", or "modifiedTime"')
+    })
+  )
+  .output(
+    z.object({
+      contact: z.record(z.string(), z.any()).optional().describe('Contact record'),
+      contacts: z.array(z.record(z.string(), z.any())).optional().describe('Contact records'),
+      contactId: z.string().optional().describe('Contact ID'),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoDeskClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      orgId: ctx.input.orgId
+    });
+
+    if (ctx.input.action === 'list') {
+      let result = await client.listContacts({
+        from: ctx.input.from,
+        limit: ctx.input.limit,
+        sortBy: ctx.input.sortBy
+      });
+      let contacts = result?.data || result || [];
+      return {
+        output: { contacts: Array.isArray(contacts) ? contacts : [] },
+        message: `Retrieved **${Array.isArray(contacts) ? contacts.length : 0}** Desk contacts.`
+      };
+    }
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.contactId) throw zohoServiceError('contactId is required for get');
+      let contact = await client.getContact(ctx.input.contactId);
+      return {
+        output: { contact, contactId: contact?.id || ctx.input.contactId },
+        message: `Fetched Desk contact **${contact?.lastName || ctx.input.contactId}**.`
+      };
+    }
+
+    let buildData = () => {
+      let data: Record<string, any> = {};
+      if (ctx.input.firstName) data.firstName = ctx.input.firstName;
+      if (ctx.input.lastName) data.lastName = ctx.input.lastName;
+      if (ctx.input.email) data.email = ctx.input.email;
+      if (ctx.input.phone) data.phone = ctx.input.phone;
+      if (ctx.input.mobile) data.mobile = ctx.input.mobile;
+      if (ctx.input.accountId) data.accountId = ctx.input.accountId;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.customFields) data.cf = ctx.input.customFields;
+      return data;
+    };
+
+    if (ctx.input.action === 'create') {
+      let contact = await client.createContact(buildData());
+      return {
+        output: { contact, contactId: contact?.id },
+        message: `Created Desk contact **${contact?.lastName || contact?.email || contact?.id}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.contactId) throw zohoServiceError('contactId is required for update');
+      let contact = await client.updateContact(ctx.input.contactId, buildData());
+      return {
+        output: { contact, contactId: contact?.id || ctx.input.contactId },
+        message: `Updated Desk contact **${ctx.input.contactId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.contactId) throw zohoServiceError('contactId is required for delete');
+      await client.deleteContact(ctx.input.contactId);
+      return {
+        output: { contactId: ctx.input.contactId, deleted: true },
+        message: `Deleted Desk contact **${ctx.input.contactId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Desk contact action.');
+  })
+  .build();

package/src/tools/desk-manage-ticket.ts

@@ -0,0 +1,126 @@
+import { SlateTool } 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 deskManageTicket = SlateTool.create(spec, {
+  name: 'Desk Manage Ticket',
+  key: 'desk_manage_ticket',
+  description: `Create, update, or delete support tickets in Zoho Desk. Supports setting subject, description, priority, status, assignee, department, and custom fields.`,
+  instructions: [
+    'The orgId parameter is required for all Zoho Desk operations.',
+    'For create, provide subject and optionally departmentId, contactId, description, priority, status, etc.',
+    'For update, provide ticketId and the fields to change.',
+    'For delete, provide ticketId.'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      orgId: z.string().describe('Zoho Desk organization ID'),
+      action: z.enum(['create', 'update', 'delete']).describe('Operation to perform'),
+      ticketId: z.string().optional().describe('Ticket ID (required for update and delete)'),
+      subject: z.string().optional().describe('Ticket subject (required for create)'),
+      description: z.string().optional().describe('Ticket description/content'),
+      departmentId: z.string().optional().describe('Department ID to assign the ticket to'),
+      contactId: z.string().optional().describe('Contact ID associated with the ticket'),
+      email: z.string().optional().describe('Email of the requester'),
+      priority: z
+        .string()
+        .optional()
+        .describe('Ticket priority (e.g., "High", "Medium", "Low")'),
+      status: z
+        .string()
+        .optional()
+        .describe('Ticket status (e.g., "Open", "On Hold", "Escalated", "Closed")'),
+      assigneeId: z.string().optional().describe('Agent ID to assign the ticket to'),
+      category: z.string().optional().describe('Ticket category'),
+      customFields: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe('Custom field values as key-value pairs')
+    })
+  )
+  .output(
+    z.object({
+      ticketId: z.string().optional(),
+      ticketNumber: z.string().optional(),
+      subject: z.string().optional(),
+      status: z.string().optional(),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoDeskClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      orgId: ctx.input.orgId
+    });
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.subject) throw zohoServiceError('subject is required for create');
+      let data: Record<string, any> = {};
+      if (ctx.input.subject) data.subject = ctx.input.subject;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.departmentId) data.departmentId = ctx.input.departmentId;
+      if (ctx.input.contactId) data.contactId = ctx.input.contactId;
+      if (ctx.input.email) data.email = ctx.input.email;
+      if (ctx.input.priority) data.priority = ctx.input.priority;
+      if (ctx.input.status) data.status = ctx.input.status;
+      if (ctx.input.assigneeId) data.assigneeId = ctx.input.assigneeId;
+      if (ctx.input.category) data.category = ctx.input.category;
+      if (ctx.input.customFields) data.cf = ctx.input.customFields;
+
+      let result = await client.createTicket(data);
+      return {
+        output: {
+          ticketId: result?.id,
+          ticketNumber: result?.ticketNumber,
+          subject: result?.subject,
+          status: result?.status
+        },
+        message: `Created ticket **#${result?.ticketNumber}**: "${result?.subject}".`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.ticketId) throw zohoServiceError('ticketId is required for update');
+      let data: Record<string, any> = {};
+      if (ctx.input.subject) data.subject = ctx.input.subject;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.departmentId) data.departmentId = ctx.input.departmentId;
+      if (ctx.input.priority) data.priority = ctx.input.priority;
+      if (ctx.input.status) data.status = ctx.input.status;
+      if (ctx.input.assigneeId) data.assigneeId = ctx.input.assigneeId;
+      if (ctx.input.category) data.category = ctx.input.category;
+      if (ctx.input.customFields) data.cf = ctx.input.customFields;
+
+      let result = await client.updateTicket(ctx.input.ticketId, data);
+      return {
+        output: {
+          ticketId: result?.id,
+          ticketNumber: result?.ticketNumber,
+          subject: result?.subject,
+          status: result?.status
+        },
+        message: `Updated ticket **${ctx.input.ticketId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.ticketId) throw zohoServiceError('ticketId is required for delete');
+      await client.deleteTicket(ctx.input.ticketId);
+      return {
+        output: { ticketId: ctx.input.ticketId, deleted: true },
+        message: `Deleted ticket **${ctx.input.ticketId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Desk ticket action.');
+  })
+  .build();

package/src/tools/index.ts

@@ -0,0 +1,16 @@
+export { crmGetRecords } from './crm-get-records';
+export { crmManageRecord } from './crm-manage-record';
+export { crmSearchRecords } from './crm-search-records';
+export { crmGetModules } from './crm-get-modules';
+export { crmGetRelatedRecords } from './crm-get-related-records';
+export { deskGetTickets } from './desk-get-tickets';
+export { deskManageTicket } from './desk-manage-ticket';
+export { deskManageContact } from './desk-manage-contact';
+export { booksGetInvoices } from './books-get-invoices';
+export { booksManageInvoice } from './books-manage-invoice';
+export { booksManageContact } from './books-manage-contact';
+export { booksManageExpense } from './books-manage-expense';
+export { peopleManageEmployee } from './people-manage-employee';
+export { projectsGetPortals } from './projects-get-portals';
+export { projectsManageProject } from './projects-manage-project';
+export { projectsManageTask } from './projects-manage-task';

package/src/tools/people-manage-employee.ts

@@ -0,0 +1,163 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { ZohoPeopleClient } from '../lib/client';
+import type { Datacenter } from '../lib/urls';
+import { zohoServiceError } from '../lib/errors';
+
+export let peopleManageEmployee = SlateTool.create(spec, {
+  name: 'People Manage Employee',
+  key: 'people_manage_employee',
+  description: `List, search, create, or update employee records in Zoho People. Works with any form in Zoho People (employee, department, etc.). Also supports fetching attendance and leave information.`,
+  instructions: [
+    'Use formLinkName "P_Employee" or "employee" for the employee form.',
+    'For search, provide searchColumn and searchValue (e.g., searchColumn="EMPLOYEEMAILALIAS", searchValue="john@example.com").',
+    'For attendance, provide startDate and endDate in "dd-MMM-yyyy" format (e.g., "01-Jan-2024").'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['forms', 'list', 'get', 'create', 'update', 'attendance', 'leave_types'])
+        .describe('Operation to perform'),
+      formLinkName: z
+        .string()
+        .optional()
+        .describe(
+          'Form link name (e.g., "P_Employee", "employee"). Required for list/get/create/update.'
+        ),
+      recordId: z.string().optional().describe('Record ID (required for get, update)'),
+      recordData: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe('Record field data as key-value pairs (for create/update)'),
+      searchColumn: z
+        .string()
+        .optional()
+        .describe('Column to search by (e.g., "EMPLOYEEMAILALIAS")'),
+      searchValue: z.string().optional().describe('Value to search for'),
+      startIndex: z.number().optional().describe('Start index for pagination (default 1)'),
+      limit: z.number().optional().describe('Number of records to return (max 200)'),
+      startDate: z
+        .string()
+        .optional()
+        .describe('Start date for attendance query (dd-MMM-yyyy)'),
+      endDate: z.string().optional().describe('End date for attendance query (dd-MMM-yyyy)'),
+      employeeId: z.string().optional().describe('Employee ID for attendance query')
+    })
+  )
+  .output(
+    z.object({
+      records: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Employee/form records'),
+      forms: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Available Zoho People forms'),
+      record: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe('Single record (for get/create/update)'),
+      leaveTypes: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .describe('Leave type details'),
+      attendance: z.any().optional().describe('Attendance entries'),
+      apiResponse: z.any().optional().describe('Raw API response for complex results')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+    let client = new ZohoPeopleClient({ token: ctx.auth.token, datacenter: dc });
+
+    if (ctx.input.action === 'forms') {
+      let result = await client.listForms();
+      let forms = result?.response?.result || result?.forms || result || [];
+      return {
+        output: { forms: Array.isArray(forms) ? forms : [], apiResponse: result },
+        message: `Retrieved **${Array.isArray(forms) ? forms.length : 0}** Zoho People forms.`
+      };
+    }
+
+    if (ctx.input.action === 'list') {
+      if (!ctx.input.formLinkName) throw zohoServiceError('formLinkName is required for list');
+      let result = await client.getFormRecords(ctx.input.formLinkName, {
+        sIndex: ctx.input.startIndex,
+        limit: ctx.input.limit,
+        searchColumn: ctx.input.searchColumn,
+        searchValue: ctx.input.searchValue
+      });
+      let records = Array.isArray(result) ? result : result?.data || [];
+      return {
+        output: { records, apiResponse: result },
+        message: `Retrieved **${records.length}** records from **${ctx.input.formLinkName}**.`
+      };
+    }
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.formLinkName) throw zohoServiceError('formLinkName is required for get');
+      if (!ctx.input.recordId) throw zohoServiceError('recordId is required for get');
+      let result = await client.getFormRecordById(ctx.input.formLinkName, ctx.input.recordId);
+      return {
+        output: { record: result },
+        message: `Fetched record **${ctx.input.recordId}** from **${ctx.input.formLinkName}**.`
+      };
+    }
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.formLinkName)
+        throw zohoServiceError('formLinkName is required for create');
+      if (!ctx.input.recordData) throw zohoServiceError('recordData is required for create');
+      let result = await client.insertFormRecord(ctx.input.formLinkName, ctx.input.recordData);
+      return {
+        output: { record: result, apiResponse: result },
+        message: `Created record in **${ctx.input.formLinkName}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.formLinkName)
+        throw zohoServiceError('formLinkName is required for update');
+      if (!ctx.input.recordId) throw zohoServiceError('recordId is required for update');
+      if (!ctx.input.recordData) throw zohoServiceError('recordData is required for update');
+      let result = await client.updateFormRecord(
+        ctx.input.formLinkName,
+        ctx.input.recordId,
+        ctx.input.recordData
+      );
+      return {
+        output: { record: result, apiResponse: result },
+        message: `Updated record **${ctx.input.recordId}** in **${ctx.input.formLinkName}**.`
+      };
+    }
+
+    if (ctx.input.action === 'leave_types') {
+      let result = await client.getLeaveTypes();
+      return {
+        output: { leaveTypes: result?.response?.result || result },
+        message: `Retrieved leave types.`
+      };
+    }
+
+    if (ctx.input.action === 'attendance') {
+      if (!ctx.input.startDate || !ctx.input.endDate)
+        throw zohoServiceError('startDate and endDate are required for attendance');
+      let result = await client.getAttendanceEntries({
+        sdate: ctx.input.startDate,
+        edate: ctx.input.endDate,
+        empId: ctx.input.employeeId
+      });
+      return {
+        output: { attendance: result },
+        message: `Retrieved attendance entries from **${ctx.input.startDate}** to **${ctx.input.endDate}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid People action.');
+  })
+  .build();