@slates-integrations/zoho 0.2.0-rc.5

package/src/lib/errors.ts

@@ -0,0 +1,90 @@
+import { ServiceError, badRequestError } from '@lowerdeck/error';
+
+type ErrorResponse = {
+  status?: number;
+  statusText?: string;
+  data?: unknown;
+};
+
+let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+let pushMessage = (messages: string[], value: unknown) => {
+  if (typeof value !== 'string') return;
+
+  let trimmed = value.trim();
+  if (trimmed && !messages.includes(trimmed)) {
+    messages.push(trimmed);
+  }
+};
+
+let collectZohoMessages = (value: unknown, messages: string[]) => {
+  if (!isRecord(value)) {
+    pushMessage(messages, value);
+    return;
+  }
+
+  for (let key of ['message', 'error', 'error_description', 'code']) {
+    pushMessage(messages, value[key]);
+  }
+
+  if (isRecord(value.details)) {
+    for (let [key, detailValue] of Object.entries(value.details)) {
+      if (typeof detailValue === 'string') {
+        pushMessage(messages, `${key}: ${detailValue}`);
+      }
+    }
+  }
+
+  if (Array.isArray(value.data)) {
+    for (let item of value.data) {
+      collectZohoMessages(item, messages);
+    }
+  }
+};
+
+let extractZohoMessage = (error: unknown) => {
+  let response = isRecord(error) ? (error.response as ErrorResponse | undefined) : undefined;
+  let messages: string[] = [];
+
+  collectZohoMessages(response?.data, messages);
+
+  if (messages.length > 0) {
+    return messages.join(' - ');
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Unknown error';
+};
+
+export let zohoServiceError = (message: string) =>
+  new ServiceError(badRequestError({ message }));
+
+export let zohoApiError = (error: unknown, operation = 'request') => {
+  if (error instanceof ServiceError) {
+    return error;
+  }
+
+  let response = isRecord(error) ? (error.response as ErrorResponse | undefined) : undefined;
+  let status = response?.status;
+  let statusLabel =
+    status !== undefined
+      ? `HTTP ${status}${response?.statusText ? ` ${response.statusText}` : ''}: `
+      : '';
+
+  let serviceError = zohoServiceError(
+    `Zoho API ${operation} failed: ${statusLabel}${extractZohoMessage(error)}`
+  );
+
+  serviceError.data.reason = 'zoho_api_error';
+  serviceError.data.upstreamStatus = status;
+
+  if (error instanceof Error) {
+    serviceError.setParent(error);
+  }
+
+  return serviceError;
+};

package/src/lib/urls.ts

@@ -0,0 +1,77 @@
+export type Datacenter = 'us' | 'eu' | 'in' | 'au' | 'jp' | 'ca';
+
+let accountsUrls: Record<Datacenter, string> = {
+  us: 'https://accounts.zoho.com',
+  eu: 'https://accounts.zoho.eu',
+  in: 'https://accounts.zoho.in',
+  au: 'https://accounts.zoho.com.au',
+  jp: 'https://accounts.zoho.jp',
+  ca: 'https://accounts.zoho.ca'
+};
+
+let apiBaseUrls: Record<Datacenter, string> = {
+  us: 'https://www.zohoapis.com',
+  eu: 'https://www.zohoapis.eu',
+  in: 'https://www.zohoapis.in',
+  au: 'https://www.zohoapis.com.au',
+  jp: 'https://www.zohoapis.jp',
+  ca: 'https://www.zohoapis.ca'
+};
+
+let deskBaseUrls: Record<Datacenter, string> = {
+  us: 'https://desk.zoho.com',
+  eu: 'https://desk.zoho.eu',
+  in: 'https://desk.zoho.in',
+  au: 'https://desk.zoho.com.au',
+  jp: 'https://desk.zoho.jp',
+  ca: 'https://desk.zoho.ca'
+};
+
+let peopleBaseUrls: Record<Datacenter, string> = {
+  us: 'https://people.zoho.com',
+  eu: 'https://people.zoho.eu',
+  in: 'https://people.zoho.in',
+  au: 'https://people.zoho.com.au',
+  jp: 'https://people.zoho.jp',
+  ca: 'https://people.zoho.ca'
+};
+
+let projectsBaseUrls: Record<Datacenter, string> = {
+  us: 'https://projectsapi.zoho.com',
+  eu: 'https://projectsapi.zoho.eu',
+  in: 'https://projectsapi.zoho.in',
+  au: 'https://projectsapi.zoho.com.au',
+  jp: 'https://projectsapi.zoho.jp',
+  ca: 'https://projectsapi.zoho.ca'
+};
+
+let locationToDatacenter: Record<string, Datacenter> = {
+  us: 'us',
+  eu: 'eu',
+  in: 'in',
+  au: 'au',
+  jp: 'jp',
+  ca: 'ca'
+};
+
+export let getAccountsUrl = (dc: Datacenter): string => accountsUrls[dc];
+export let getApiBaseUrl = (dc: Datacenter): string => apiBaseUrls[dc];
+export let getDeskBaseUrl = (dc: Datacenter): string => deskBaseUrls[dc];
+export let getPeopleBaseUrl = (dc: Datacenter): string => peopleBaseUrls[dc];
+export let getProjectsBaseUrl = (dc: Datacenter): string => projectsBaseUrls[dc];
+
+export let datacenterFromLocation = (location: string): Datacenter => {
+  return locationToDatacenter[location] ?? 'us';
+};
+
+export let datacenterFromApiDomain = (apiDomain?: string): Datacenter | undefined => {
+  if (!apiDomain) return undefined;
+
+  for (let [dc, baseUrl] of Object.entries(apiBaseUrls)) {
+    if (apiDomain.startsWith(baseUrl)) {
+      return dc as Datacenter;
+    }
+  }
+
+  return undefined;
+};

package/src/spec.ts

@@ -0,0 +1,12 @@
+import { SlateSpecification } from 'slates';
+import { auth } from './auth';
+import { config } from './config';
+
+export let spec = SlateSpecification.create({
+  key: 'zoho',
+  name: 'Zoho',
+  description: undefined,
+  metadata: {},
+  config,
+  auth
+});

package/src/tools/books-get-invoices.ts

@@ -0,0 +1,114 @@
+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';
+
+export let booksGetInvoices = SlateTool.create(spec, {
+  name: 'Books Get Invoices',
+  key: 'books_get_invoices',
+  description: `List or retrieve invoices from Zoho Books. Supports filtering by status, customer, and pagination. Can also list organizations to find the organization ID needed for all Books operations.`,
+  instructions: [
+    'The organizationId is required. Use listOrganizations=true to discover available organizations.',
+    'Provide invoiceId to fetch a single invoice with full details.',
+    'Filter by status: "sent", "draft", "overdue", "paid", "void", "unpaid", "partially_paid".'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      organizationId: z
+        .string()
+        .optional()
+        .describe('Zoho Books organization ID (required unless listing organizations)'),
+      invoiceId: z.string().optional().describe('Specific invoice ID to fetch'),
+      status: z
+        .string()
+        .optional()
+        .describe('Filter by status (e.g., "sent", "draft", "overdue", "paid", "void")'),
+      customerId: z.string().optional().describe('Filter invoices by customer ID'),
+      page: z.number().optional().describe('Page number'),
+      perPage: z.number().optional().describe('Records per page (max 200)'),
+      sortColumn: z
+        .string()
+        .optional()
+        .describe('Sort by column (e.g., "date", "invoice_number", "total")'),
+      sortOrder: z.enum(['ascending', 'descending']).optional().describe('Sort order'),
+      listOrganizations: z
+        .boolean()
+        .optional()
+        .describe('If true, lists available organizations instead of invoices')
+    })
+  )
+  .output(
+    z.object({
+      invoices: z.array(z.record(z.string(), z.any())).optional().describe('Invoice records'),
+      organizations: z
+        .array(
+          z.object({
+            organizationId: z.string(),
+            name: z.string(),
+            isDefault: z.boolean().optional(),
+            currencyCode: z.string().optional()
+          })
+        )
+        .optional()
+        .describe('Available organizations (if listOrganizations is true)'),
+      hasMorePages: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let dc = (ctx.auth.datacenter || ctx.config.datacenter || 'us') as Datacenter;
+
+    if (ctx.input.listOrganizations) {
+      let result = await ZohoBooksClient.listOrganizations(ctx.auth.token, dc);
+      let orgs = (result?.organizations || []).map((o: any) => ({
+        organizationId: o.organization_id,
+        name: o.name,
+        isDefault: o.is_default_org,
+        currencyCode: o.currency_code
+      }));
+      return {
+        output: { organizations: orgs },
+        message: `Found **${orgs.length}** Zoho Books organizations.`
+      };
+    }
+
+    if (!ctx.input.organizationId) throw zohoServiceError('organizationId is required');
+    let client = new ZohoBooksClient({
+      token: ctx.auth.token,
+      datacenter: dc,
+      organizationId: ctx.input.organizationId
+    });
+
+    if (ctx.input.invoiceId) {
+      let result = await client.getInvoice(ctx.input.invoiceId);
+      return {
+        output: { invoices: [result?.invoice || result] },
+        message: `Fetched invoice **${result?.invoice?.invoice_number || ctx.input.invoiceId}**.`
+      };
+    }
+
+    let result = await client.listInvoices({
+      page: ctx.input.page,
+      perPage: ctx.input.perPage,
+      status: ctx.input.status,
+      customerId: ctx.input.customerId,
+      sortColumn: ctx.input.sortColumn,
+      sortOrder: ctx.input.sortOrder
+    });
+
+    let invoices = result?.invoices || [];
+    let pageContext = result?.page_context;
+    return {
+      output: {
+        invoices,
+        hasMorePages: pageContext?.has_more_page ?? false
+      },
+      message: `Retrieved **${invoices.length}** invoices.`
+    };
+  })
+  .build();

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

@@ -0,0 +1,168 @@
+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 addressSchema = z.object({
+  attention: z.string().optional(),
+  address: z.string().optional().describe('Street 1 address'),
+  street: z.string().optional().describe('Deprecated alias for address'),
+  street2: z.string().optional().describe('Street 2 address'),
+  city: z.string().optional(),
+  state: z.string().optional(),
+  stateCode: z.string().optional(),
+  zip: z.string().optional(),
+  country: z.string().optional(),
+  fax: z.string().optional(),
+  phone: z.string().optional()
+});
+
+export let booksManageContact = SlateTool.create(spec, {
+  name: 'Books Manage Contact',
+  key: 'books_manage_contact',
+  description: `Create, update, or delete contacts (customers/vendors) in Zoho Books. Manage contact details, billing/shipping addresses, payment terms, and contact persons.`,
+  instructions: [
+    'The organizationId is required for all Zoho Books operations.',
+    'For create, contactName is required.',
+    'Use contactType to specify "customer" or "vendor".'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      organizationId: z.string().describe('Zoho Books organization ID'),
+      action: z
+        .enum(['create', 'update', 'delete', 'get', 'list'])
+        .describe('Operation to perform'),
+      contactId: z
+        .string()
+        .optional()
+        .describe('Contact ID (required for get, update, delete)'),
+      contactName: z
+        .string()
+        .optional()
+        .describe('Contact/company name (required for create)'),
+      contactType: z.enum(['customer', 'vendor']).optional().describe('Type of contact'),
+      companyName: z.string().optional().describe('Company name'),
+      email: z.string().optional().describe('Contact email address'),
+      phone: z.string().optional().describe('Contact phone number'),
+      website: z.string().optional().describe('Contact website'),
+      billingAddress: addressSchema.optional().describe('Billing address'),
+      shippingAddress: addressSchema.optional().describe('Shipping address'),
+      paymentTerms: z.number().optional().describe('Net payment terms in days'),
+      notes: z.string().optional().describe('Notes about the contact'),
+      page: z.number().optional().describe('Page number (for list action)'),
+      perPage: z.number().optional().describe('Records per page (for list action)')
+    })
+  )
+  .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('List of contacts (for list action)'),
+      deleted: z.boolean().optional(),
+      hasMorePages: 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 === 'list') {
+      let result = await client.listContacts({
+        page: ctx.input.page,
+        perPage: ctx.input.perPage,
+        contactType: ctx.input.contactType
+      });
+      return {
+        output: {
+          contacts: result?.contacts || [],
+          hasMorePages: result?.page_context?.has_more_page ?? false
+        },
+        message: `Retrieved **${(result?.contacts || []).length}** contacts.`
+      };
+    }
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.contactId) throw zohoServiceError('contactId is required for get');
+      let result = await client.getContact(ctx.input.contactId);
+      return {
+        output: { contact: result?.contact || result },
+        message: `Fetched contact **${result?.contact?.contact_name || ctx.input.contactId}**.`
+      };
+    }
+
+    let buildAddress = (address: z.infer<typeof addressSchema>) => ({
+      attention: address.attention,
+      address: address.address || address.street,
+      street2: address.street2,
+      city: address.city,
+      state: address.state,
+      state_code: address.stateCode,
+      zip: address.zip,
+      country: address.country,
+      fax: address.fax,
+      phone: address.phone
+    });
+
+    let buildData = () => {
+      let data: Record<string, any> = {};
+      if (ctx.input.contactName) data.contact_name = ctx.input.contactName;
+      if (ctx.input.contactType) data.contact_type = ctx.input.contactType;
+      if (ctx.input.companyName) data.company_name = ctx.input.companyName;
+      if (ctx.input.email) data.email = ctx.input.email;
+      if (ctx.input.phone) data.phone = ctx.input.phone;
+      if (ctx.input.website) data.website = ctx.input.website;
+      if (ctx.input.paymentTerms !== undefined) data.payment_terms = ctx.input.paymentTerms;
+      if (ctx.input.notes) data.notes = ctx.input.notes;
+      if (ctx.input.billingAddress) {
+        data.billing_address = buildAddress(ctx.input.billingAddress);
+      }
+      if (ctx.input.shippingAddress) {
+        data.shipping_address = buildAddress(ctx.input.shippingAddress);
+      }
+      return data;
+    };
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.contactName) throw zohoServiceError('contactName is required for create');
+      let result = await client.createContact(buildData());
+      let contact = result?.contact;
+      return {
+        output: { contact },
+        message: `Created contact **${contact?.contact_name}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.contactId) throw zohoServiceError('contactId is required for update');
+      let result = await client.updateContact(ctx.input.contactId, buildData());
+      let contact = result?.contact;
+      return {
+        output: { contact },
+        message: `Updated contact **${contact?.contact_name || 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: { contact: { contact_id: ctx.input.contactId }, deleted: true },
+        message: `Deleted contact **${ctx.input.contactId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Books contact action.');
+  })
+  .build();

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

@@ -0,0 +1,142 @@
+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';
+
+export let booksManageExpense = SlateTool.create(spec, {
+  name: 'Books Manage Expense',
+  key: 'books_manage_expense',
+  description: `Create, update, delete, or list expenses in Zoho Books. Track business expenses with account categorization, amounts, dates, vendors, and custom fields.`,
+  instructions: [
+    'The organizationId is required for all Zoho Books operations.',
+    'For create, accountId, date, and amount are required.'
+  ],
+  tags: {
+    destructive: true
+  }
+})
+  .input(
+    z.object({
+      organizationId: z.string().describe('Zoho Books organization ID'),
+      action: z
+        .enum(['create', 'update', 'delete', 'get', 'list'])
+        .describe('Operation to perform'),
+      expenseId: z
+        .string()
+        .optional()
+        .describe('Expense ID (required for update, delete, get)'),
+      accountId: z.string().optional().describe('Expense account ID (required for create)'),
+      date: z.string().optional().describe('Expense date (YYYY-MM-DD, required for create)'),
+      amount: z.number().optional().describe('Expense amount (required for create)'),
+      paidThroughAccountId: z
+        .string()
+        .optional()
+        .describe('Account ID through which payment was made'),
+      vendorId: z.string().optional().describe('Vendor ID'),
+      description: z.string().optional().describe('Expense description'),
+      referenceNumber: z.string().optional().describe('Reference number'),
+      taxId: z.string().optional().describe('Tax ID to apply'),
+      isBillable: z.boolean().optional().describe('Whether the expense is billable'),
+      customerId: z.string().optional().describe('Customer ID (for billable expenses)'),
+      projectId: z.string().optional().describe('Project ID'),
+      currencyId: z.string().optional().describe('Currency ID'),
+      page: z.number().optional().describe('Page number (for list action)'),
+      perPage: z.number().optional().describe('Records per page (for list action)'),
+      status: z.string().optional().describe('Filter by status (for list action)')
+    })
+  )
+  .output(
+    z.object({
+      expense: z.record(z.string(), z.any()).optional().describe('Expense record'),
+      expenses: z.array(z.record(z.string(), z.any())).optional().describe('List of expenses'),
+      deleted: z.boolean().optional(),
+      hasMorePages: z.boolean().optional(),
+      apiMessage: z.string().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 === 'list') {
+      let result = await client.listExpenses({
+        page: ctx.input.page,
+        perPage: ctx.input.perPage,
+        status: ctx.input.status
+      });
+      return {
+        output: {
+          expenses: result?.expenses || [],
+          hasMorePages: result?.page_context?.has_more_page ?? false
+        },
+        message: `Retrieved **${(result?.expenses || []).length}** expenses.`
+      };
+    }
+
+    if (ctx.input.action === 'get') {
+      if (!ctx.input.expenseId) throw zohoServiceError('expenseId is required for get');
+      let result = await client.getExpense(ctx.input.expenseId);
+      return {
+        output: { expense: result?.expense || result },
+        message: `Fetched expense **${ctx.input.expenseId}**.`
+      };
+    }
+
+    let buildData = () => {
+      let data: Record<string, any> = {};
+      if (ctx.input.accountId) data.account_id = ctx.input.accountId;
+      if (ctx.input.date) data.date = ctx.input.date;
+      if (ctx.input.amount !== undefined) data.amount = ctx.input.amount;
+      if (ctx.input.paidThroughAccountId)
+        data.paid_through_account_id = ctx.input.paidThroughAccountId;
+      if (ctx.input.vendorId) data.vendor_id = ctx.input.vendorId;
+      if (ctx.input.description) data.description = ctx.input.description;
+      if (ctx.input.referenceNumber) data.reference_number = ctx.input.referenceNumber;
+      if (ctx.input.taxId) data.tax_id = ctx.input.taxId;
+      if (ctx.input.isBillable !== undefined) data.is_billable = ctx.input.isBillable;
+      if (ctx.input.customerId) data.customer_id = ctx.input.customerId;
+      if (ctx.input.projectId) data.project_id = ctx.input.projectId;
+      if (ctx.input.currencyId) data.currency_id = ctx.input.currencyId;
+      return data;
+    };
+
+    if (ctx.input.action === 'create') {
+      if (!ctx.input.accountId) throw zohoServiceError('accountId is required for create');
+      if (!ctx.input.date) throw zohoServiceError('date is required for create');
+      if (ctx.input.amount === undefined)
+        throw zohoServiceError('amount is required for create');
+      let result = await client.createExpense(buildData());
+      let expense = result?.expense;
+      return {
+        output: { expense, apiMessage: result?.message },
+        message: `Created expense of **${expense?.total || ctx.input.amount}** on **${expense?.date || ctx.input.date}**.`
+      };
+    }
+
+    if (ctx.input.action === 'update') {
+      if (!ctx.input.expenseId) throw zohoServiceError('expenseId is required for update');
+      let result = await client.updateExpense(ctx.input.expenseId, buildData());
+      return {
+        output: { expense: result?.expense, apiMessage: result?.message },
+        message: `Updated expense **${ctx.input.expenseId}**.`
+      };
+    }
+
+    if (ctx.input.action === 'delete') {
+      if (!ctx.input.expenseId) throw zohoServiceError('expenseId is required for delete');
+      let result = await client.deleteExpense(ctx.input.expenseId);
+      return {
+        output: { deleted: true, apiMessage: result?.message },
+        message: `Deleted expense **${ctx.input.expenseId}**.`
+      };
+    }
+
+    throw zohoServiceError('Invalid Books expense action.');
+  })
+  .build();