@slates-integrations/zoho 0.2.0-rc.5

package/README.md

@@ -0,0 +1,11 @@
+# <img src="logo.png" height="20"> Zoho
+
+Manage core Zoho workflows across CRM, Desk, Books, People, and Projects with one OAuth connection. Retrieve, search, create, update, delete, and inspect related CRM records; manage Desk tickets and contacts; work with Books organizations, invoices, contacts, and expenses; list People forms and manage form/employee, leave, and attendance data; and discover Projects portals while managing projects, tasks, and milestones.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,155 @@
+# Slates Specification for Zoho
+
+## Overview
+
+Zoho is an Indian multinational technology company offering a suite of over 55 cloud-based software products covering CRM, accounting, HR, project management, helpdesk, email, marketing, analytics, and more. Zoho has over 45 integrated applications, mainly designed for small and medium-sized businesses (SMBs), but scalable for larger enterprises, spanning categories including customer relationship management, marketing, sales, customer support, finance, human resources, collaboration, productivity, operations, IT management, and analytics. All Zoho products share a unified authentication system through Zoho Accounts.
+
+## Authentication
+
+Zoho uses **OAuth 2.0** as its authentication protocol across all products. OAuth 2.0 allows you to grant a third-party application delegated access to the protected resources of Zoho via Zoho APIs.
+
+### Registration
+
+To access the resources of Zoho using the various Zoho APIs, you will need to register your application with Zoho first. On successful registration, you will get a Client ID and Client secret, which you can use to get the access token needed to make API calls.
+
+Register at the **Zoho API Console**: `https://api-console.zoho.com/`
+
+Client types supported:
+
+- **Server-based Applications**: Web apps running on a dedicated HTTP server (standard for integrations).
+- **Client-based Applications**: Browser-only apps independent of a web server.
+- **Mobile Applications**: Apps installed on smartphones and tablets.
+- **Non-browser Mobile Applications**: Devices without browser provisioning (smart TVs, printers).
+- **Self Client**: Stand-alone applications that perform only back-end jobs (without any manual intervention) like data sync.
+
+### OAuth 2.0 Flow (Authorization Code Grant)
+
+Zoho uses the **authorization code grant type**. The flow is:
+
+1. **Authorization Request**: Redirect user to:
+
+   ```
+   https://accounts.zoho.com/oauth/v2/auth?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&scope={scope}&access_type=offline
+   ```
+
+2. **Exchange Code for Tokens**: POST to:
+
+   ```
+   https://accounts.zoho.com/oauth/v2/token
+   ```
+
+   With parameters: `client_id`, `client_secret`, `grant_type=authorization_code`, `code`, `redirect_uri`.
+
+3. **Use Access Token**: Zoho's OAuth implementation uses Bearer authentication scheme; the access token must be passed in the Authorization header with the prefix `Zoho-oauthtoken`.
+
+   ```
+   Authorization: Zoho-oauthtoken {access_token}
+   ```
+
+4. **Refresh Token**: Access tokens are valid for only 1 hour. A refresh token can be retrieved and stored, and allows the app to generate a new access token whenever required. A refresh token does not expire. Set `access_type=offline` in the authorization request to receive a refresh token.
+
+### Scopes
+
+Scope limits the level of access the application can have. For example, if the client only needs to access the Invoices module in Zoho Books, that can be defined in the scope. The resource server will provide access only to that module. It can also be defined what kind of operations (create/read/update/delete) are permissible.
+
+Scope format: `ServiceName.ScopeName.OperationType`
+
+- **ServiceName**: The Zoho product (e.g., `ZohoCRM`, `ZohoBooks`, `ZohoDesk`, `ZohoPeople`, `ZohoProjects`, `ZohoMail`, etc.)
+- **ScopeName**: The module within the service (e.g., `modules`, `contacts`, `users`, `settings`)
+- **OperationType**: Can be ALL, READ, UPDATE, DELETE (ALL gives access to perform all operations).
+
+Examples: `ZohoCRM.modules.leads.READ`, `ZohoBooks.purchaseorders.UPDATE`, `ZohoCRM.settings.ALL`
+
+Multiple scopes should be separated by commas.
+
+### Data Centers / Multi-DC
+
+Data protection and privacy laws in multiple countries state that user data can only be stored in data centers located on that country's soil. In compliance, Zoho has set up data centers in multiple countries. Each data center only holds the data of users who have registered at that domain.
+
+The authorization and API base URLs differ by data center:
+
+| Region    | Accounts URL           | API Domain            |
+| --------- | ---------------------- | --------------------- |
+| US        | `accounts.zoho.com`    | `www.zohoapis.com`    |
+| EU        | `accounts.zoho.eu`     | `www.zohoapis.eu`     |
+| India     | `accounts.zoho.in`     | `www.zohoapis.in`     |
+| Australia | `accounts.zoho.com.au` | `www.zohoapis.com.au` |
+| Japan     | `accounts.zoho.jp`     | `www.zohoapis.jp`     |
+| Canada    | `accounts.zoho.ca`     | `www.zohoapis.ca`     |
+
+In the authorization request, you send calls to `https://accounts.zoho.com`. In the response, the location of the user's DC will be included as the parameter `location`. Once you have identified the user's data center, you need to make the access token request to the server URL corresponding to that location. For example, if location=eu, you will need to make access token request to `https://accounts.zoho.eu`.
+
+## Features
+
+### CRM (Zoho CRM)
+
+Manage the full sales lifecycle including leads, contacts, accounts, deals, tasks, events, and calls. Access and work with almost all of Zoho CRM's components using REST API. Fetch, create, update or delete any sort of information stored in your account. Use simple HTTP methods to fetch components like records, modules, and custom views.
+
+- Supports custom modules and fields.
+- CRM Object Query Language (COQL) allows constructing queries to fetch data, similar to MySQL SELECT queries.
+- Bulk API for retrieving or uploading large amounts of data asynchronously, useful for migration, data backup, and initial sync.
+
+### Helpdesk (Zoho Desk)
+
+Manage support tickets, contacts, accounts, tasks, calls, and events. A webhook pushes relevant information to the callback URL whenever an event, such as adding a ticket or updating a contact, occurs in the help desk.
+
+- Supports department-based filtering.
+- Includes instant messaging session and message management.
+
+### Accounting & Finance (Zoho Books)
+
+The Zoho Books API allows you to perform many accounting operations that you do with the web client. This generic Zoho package currently implements organizations, invoices, contacts, and expenses.
+
+- There are 8 different domains for Zoho Books' APIs, and you must use the one applicable to your organization.
+- Requires an Organization ID for API calls.
+
+### HR Management (Zoho People)
+
+Manage employee records, forms, leave, attendance, timesheets, and HR processes. Zoho People APIs use selected scopes, which control the type of resource that the client application can access.
+
+- Supports custom forms and fields.
+
+### Project Management (Zoho Projects)
+
+Zoho Projects provides REST APIs to manage projects, connect third party applications, and transfer or retrieve data. This generic Zoho package currently implements portal discovery, project management, task management, and milestone listing.
+
+- Supports custom modules with configurable layouts.
+- Requires a Portal ID in API calls.
+
+### Out Of Scope For This Generic Package
+
+Zoho Mail, Campaigns, Analytics, Creator, Billing, Sign, ZeptoMail, and other product-specific APIs are not implemented in this package. Use dedicated Zoho service integrations when those surfaces are needed.
+
+## Events
+
+Zoho supports webhooks and notification subscriptions across several products, though the mechanism varies by product. This package implements CRM notification registration and Desk event request handling.
+
+### Zoho CRM — Notification API (Watch API)
+
+On trigger of any notification-enabled event in a module, Zoho CRM sends a notification to the user through the notify URL. You can set up webhooks for most CRM primary modules, such as Leads, Accounts, Contacts, Potentials (Opportunities), Events, and Tasks.
+
+- Events: Record creation, update, deletion (subscribe using `.all`, `.create`, `.edit`, `.delete` suffixes per module).
+- Supports field-level notification conditions to filter which field changes trigger notifications.
+- Channel subscriptions expire and must be renewed periodically.
+- Optionally return affected field values in the notification payload.
+
+### Zoho CRM — Workflow Webhooks
+
+Webhooks in Zoho CRM allow you to send real-time data from Zoho CRM to external applications or services when specific events occur such as record creation, update, or deletion.
+
+- Configured per module (Leads, Contacts, etc.) and tied to workflow rules.
+- You can associate up to 6 (1 Instant Action and 5 Time-Based Actions) webhooks per workflow rule.
+
+### Zoho Desk — Webhook Subscriptions
+
+These APIs help you programmatically create, view, update, or delete webhooks that subscribe to event information from Zoho Desk.
+
+- **Ticket events**: Add, update, delete, attachment update. Supports department ID filtering and field-level tracking (up to 5 fields).
+- **Contact events**: Add, update.
+- **Account events**: Add, update.
+- **Task events**: Add, update, delete.
+- **Call events**: Add, update, delete. Supports department ID filtering.
+- **Event events**: Add, update, delete.
+- **IM events**: Message add, session status, message status.
+- **Department events**: Add, update.
+- Optionally include previous state of resource in update payloads.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@slates-integrations/zoho",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
+    "@types/node": "^20",
+    "slates": "1.0.0-rc.10",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "version": "0.2.0-rc.5"
+}

package/slate.json

@@ -0,0 +1,17 @@
+{
+  "name": "@metorial/zoho",
+  "description": "Manage core Zoho workflows across CRM, Desk, Books, People, and Projects. Retrieve, search, create, update, delete, and inspect related CRM records. Manage Desk tickets and contacts. Work with Books organizations, invoices, contacts, and expenses. List People forms and manage form/employee, leave, and attendance data. Discover Projects portals and manage projects, tasks, and milestones.",
+  "categories": ["crm-and-sales-tools", "financial-data-and-stock-market"],
+  "skills": [
+    "manage CRM records",
+    "create and track invoices",
+    "manage support tickets",
+    "manage employee HR records",
+    "organize projects and tasks",
+    "discover Zoho organization and portal IDs",
+    "query CRM data using COQL",
+    "subscribe to CRM and Desk event webhooks"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/zoho.png",
+  "version": "0.1.2"
+}

package/src/auth.ts

@@ -0,0 +1,339 @@
+import { SlateAuth, axios } from 'slates';
+import { z } from 'zod';
+import { getAccountsUrl, datacenterFromLocation, datacenterFromApiDomain } from './lib/urls';
+import type { Datacenter } from './lib/urls';
+import { zohoApiError, zohoServiceError } from './lib/errors';
+
+let scopes = [
+  // CRM scopes
+  {
+    title: 'CRM - Full Access',
+    description: 'Full access to all CRM modules',
+    scope: 'ZohoCRM.modules.ALL'
+  },
+  {
+    title: 'CRM - Read Records',
+    description: 'Read access to CRM records',
+    scope: 'ZohoCRM.modules.READ'
+  },
+  {
+    title: 'CRM - Settings',
+    description: 'Access CRM settings including modules metadata',
+    scope: 'ZohoCRM.settings.ALL'
+  },
+  {
+    title: 'CRM - Notifications',
+    description: 'Manage CRM notification/watch subscriptions',
+    scope: 'ZohoCRM.notifications.ALL'
+  },
+  {
+    title: 'CRM - COQL',
+    description: 'Execute COQL queries against CRM data',
+    scope: 'ZohoCRM.coql.READ'
+  },
+  {
+    title: 'CRM - Secure Search',
+    description: 'Search CRM records using the current secure search scope',
+    scope: 'ZohoSearch.securesearch.READ'
+  },
+  { title: 'CRM - Bulk Read', description: 'Bulk read CRM data', scope: 'ZohoCRM.bulk.READ' },
+  {
+    title: 'CRM - Users',
+    description: 'Access CRM user information',
+    scope: 'ZohoCRM.users.READ'
+  },
+
+  // Desk scopes
+  {
+    title: 'Desk - Tickets',
+    description: 'Full access to support tickets',
+    scope: 'Desk.tickets.ALL'
+  },
+  {
+    title: 'Desk - Read Tickets',
+    description: 'Read access to support tickets',
+    scope: 'Desk.tickets.READ'
+  },
+  {
+    title: 'Desk - Contacts',
+    description: 'Full access to Desk contacts',
+    scope: 'Desk.contacts.ALL'
+  },
+  {
+    title: 'Desk - Settings',
+    description: 'Access Desk settings and departments',
+    scope: 'Desk.settings.ALL'
+  },
+  {
+    title: 'Desk - Events',
+    description: 'Manage Desk webhook subscriptions',
+    scope: 'Desk.events.ALL'
+  },
+  {
+    title: 'Desk - Search',
+    description: 'Search across Desk resources',
+    scope: 'Desk.search.READ'
+  },
+  { title: 'Desk - Basic', description: 'Basic Desk access', scope: 'Desk.basic.ALL' },
+
+  // Books scopes
+  {
+    title: 'Books - Full Access',
+    description: 'Full access to Zoho Books',
+    scope: 'ZohoBooks.fullaccess.all'
+  },
+  {
+    title: 'Books - Invoices',
+    description: 'Manage invoices in Zoho Books',
+    scope: 'ZohoBooks.invoices.ALL'
+  },
+  {
+    title: 'Books - Read Invoices',
+    description: 'Read invoices in Zoho Books',
+    scope: 'ZohoBooks.invoices.READ'
+  },
+  {
+    title: 'Books - Contacts',
+    description: 'Manage contacts in Zoho Books',
+    scope: 'ZohoBooks.contacts.ALL'
+  },
+  {
+    title: 'Books - Expenses',
+    description: 'Manage expenses in Zoho Books',
+    scope: 'ZohoBooks.expenses.ALL'
+  },
+  {
+    title: 'Books - Settings',
+    description: 'Access Zoho Books settings and organizations',
+    scope: 'ZohoBooks.settings.READ'
+  },
+
+  // People scopes
+  {
+    title: 'People - Full Access',
+    description: 'Full access to Zoho People data',
+    scope: 'ZOHOPEOPLE.forms.ALL'
+  },
+  {
+    title: 'People - Read',
+    description: 'Read access to Zoho People data',
+    scope: 'ZOHOPEOPLE.forms.READ'
+  },
+  {
+    title: 'People - Attendance',
+    description: 'Manage attendance records',
+    scope: 'ZOHOPEOPLE.attendance.ALL'
+  },
+  {
+    title: 'People - Leave',
+    description: 'Manage leave records',
+    scope: 'ZOHOPEOPLE.leave.ALL'
+  },
+  {
+    title: 'People - Timesheet',
+    description: 'Manage timesheets',
+    scope: 'ZOHOPEOPLE.timetracker.ALL'
+  },
+
+  // Projects scopes
+  {
+    title: 'Projects - Full Access',
+    description: 'Full access to Zoho Projects',
+    scope: 'ZohoProjects.portals.ALL'
+  },
+  {
+    title: 'Projects - Manage Projects',
+    description: 'Create, read, update, and delete Zoho Projects projects',
+    scope: 'ZohoProjects.projects.ALL'
+  },
+  {
+    title: 'Projects - Read',
+    description: 'Read access to Zoho Projects',
+    scope: 'ZohoProjects.portals.READ'
+  },
+  {
+    title: 'Projects - Tasks',
+    description: 'Manage tasks in Zoho Projects',
+    scope: 'ZohoProjects.tasks.ALL'
+  },
+  {
+    title: 'Projects - Timesheets',
+    description: 'Manage project timesheets',
+    scope: 'ZohoProjects.timesheets.ALL'
+  },
+  {
+    title: 'Projects - Bugs',
+    description: 'Manage bugs in Zoho Projects',
+    scope: 'ZohoProjects.bugs.ALL'
+  },
+
+  // Profile scope
+  {
+    title: 'Profile',
+    description: 'Access user profile information',
+    scope: 'AaaServer.profile.READ'
+  }
+];
+
+function createZohoOauth(name: string, key: string, dc: Datacenter) {
+  return {
+    type: 'auth.oauth' as const,
+    name,
+    key,
+    scopes,
+
+    getAuthorizationUrl: async (ctx: any) => {
+      let accountsUrl = getAccountsUrl(dc);
+      let scopeString = ctx.scopes.join(',');
+
+      let params = new URLSearchParams({
+        client_id: ctx.clientId,
+        response_type: 'code',
+        redirect_uri: ctx.redirectUri,
+        scope: scopeString,
+        access_type: 'offline',
+        state: ctx.state,
+        prompt: 'consent'
+      });
+
+      return {
+        url: `${accountsUrl}/oauth/v2/auth?${params.toString()}`
+      };
+    },
+
+    handleCallback: async (ctx: any) => {
+      let accountsUrl = getAccountsUrl(dc);
+
+      let response;
+      try {
+        response = await axios.post(`${accountsUrl}/oauth/v2/token`, null, {
+          params: {
+            client_id: ctx.clientId,
+            client_secret: ctx.clientSecret,
+            grant_type: 'authorization_code',
+            code: ctx.code,
+            redirect_uri: ctx.redirectUri
+          }
+        });
+      } catch (error) {
+        throw zohoApiError(error, 'OAuth token exchange');
+      }
+
+      let data = response.data;
+
+      // Prefer the location returned by Zoho -- user may have picked a different DC for login.
+      let resolvedDc: Datacenter = data.location
+        ? datacenterFromLocation(data.location)
+        : (datacenterFromApiDomain(data.api_domain) ?? dc);
+
+      let expiresAt = data.expires_in
+        ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+        : undefined;
+
+      if (!data.access_token) {
+        throw zohoServiceError('Zoho OAuth token response did not include an access token.');
+      }
+
+      if (!data.refresh_token) {
+        throw zohoServiceError(
+          'Zoho OAuth token response did not include a refresh token. Reconnect and approve offline access.'
+        );
+      }
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: data.refresh_token,
+          expiresAt,
+          datacenter: resolvedDc
+        }
+      };
+    },
+
+    handleTokenRefresh: async (ctx: any) => {
+      let resolvedDc = (ctx.output.datacenter || dc) as Datacenter;
+      let accountsUrl = getAccountsUrl(resolvedDc);
+
+      if (!ctx.output.refreshToken) {
+        throw zohoServiceError(
+          'Zoho OAuth profile is missing a refresh token. Reconnect the Zoho account to restore automatic refresh.'
+        );
+      }
+
+      let response;
+      try {
+        response = await axios.post(`${accountsUrl}/oauth/v2/token`, null, {
+          params: {
+            client_id: ctx.clientId,
+            client_secret: ctx.clientSecret,
+            grant_type: 'refresh_token',
+            refresh_token: ctx.output.refreshToken
+          }
+        });
+      } catch (error) {
+        throw zohoApiError(error, 'OAuth token refresh');
+      }
+
+      let data = response.data;
+
+      let expiresAt = data.expires_in
+        ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+        : undefined;
+
+      if (!data.access_token) {
+        throw zohoServiceError('Zoho OAuth refresh response did not include an access token.');
+      }
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: data.refresh_token || ctx.output.refreshToken,
+          expiresAt,
+          datacenter: resolvedDc
+        }
+      };
+    },
+
+    getProfile: async (ctx: any) => {
+      let resolvedDc = (ctx.output.datacenter || dc) as Datacenter;
+      let accountsUrl = getAccountsUrl(resolvedDc);
+
+      let response;
+      try {
+        response = await axios.get(`${accountsUrl}/oauth/user/info`, {
+          headers: {
+            Authorization: `Zoho-oauthtoken ${ctx.output.token}`
+          }
+        });
+      } catch (error) {
+        throw zohoApiError(error, 'profile request');
+      }
+
+      let data = response.data;
+
+      return {
+        profile: {
+          id: data.ZUID?.toString(),
+          email: data.Email,
+          name: data.Display_Name || `${data.First_Name || ''} ${data.Last_Name || ''}`.trim()
+        }
+      };
+    }
+  };
+}
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      token: z.string(),
+      refreshToken: z.string().optional(),
+      expiresAt: z.string().optional(),
+      datacenter: z.string()
+    })
+  )
+  .addOauth(createZohoOauth('United States (zoho.com)', 'oauth_us', 'us'))
+  .addOauth(createZohoOauth('Europe (zoho.eu)', 'oauth_eu', 'eu'))
+  .addOauth(createZohoOauth('India (zoho.in)', 'oauth_in', 'in'))
+  .addOauth(createZohoOauth('Australia (zoho.com.au)', 'oauth_au', 'au'))
+  .addOauth(createZohoOauth('Japan (zoho.jp)', 'oauth_jp', 'jp'))
+  .addOauth(createZohoOauth('Canada (zoho.ca)', 'oauth_ca', 'ca'));

package/src/config.ts

@@ -0,0 +1,11 @@
+import { SlateConfig } from 'slates';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(
+  z.object({
+    datacenter: z
+      .enum(['us', 'eu', 'in', 'au', 'jp', 'ca'])
+      .default('us')
+      .describe('Zoho data center region. Determines the API base URL and accounts URL.')
+  })
+);

package/src/index.ts

@@ -0,0 +1,44 @@
+import { Slate } from 'slates';
+import { spec } from './spec';
+import {
+  crmGetRecords,
+  crmManageRecord,
+  crmSearchRecords,
+  crmGetModules,
+  crmGetRelatedRecords,
+  deskGetTickets,
+  deskManageTicket,
+  deskManageContact,
+  booksGetInvoices,
+  booksManageInvoice,
+  booksManageContact,
+  booksManageExpense,
+  peopleManageEmployee,
+  projectsGetPortals,
+  projectsManageProject,
+  projectsManageTask
+} from './tools';
+import { crmRecordEvents, deskEvents } from './triggers';
+
+export let provider = Slate.create({
+  spec,
+  tools: [
+    crmGetRecords,
+    crmManageRecord,
+    crmSearchRecords,
+    crmGetModules,
+    crmGetRelatedRecords,
+    deskGetTickets,
+    deskManageTicket,
+    deskManageContact,
+    booksGetInvoices,
+    booksManageInvoice,
+    booksManageContact,
+    booksManageExpense,
+    peopleManageEmployee,
+    projectsGetPortals,
+    projectsManageProject,
+    projectsManageTask
+  ],
+  triggers: [crmRecordEvents, deskEvents]
+});