Zoho Creator SDK v2

A fully-typed TypeScript/JavaScript SDK for the Zoho Creator API v2. Works with Node.js ≥ 18, TypeScript, and modern JavaScript projects.

Generated from the Zoho Creator OpenAPI 3.0 specification.

Features

• Full API coverage — Data, Meta, File, Bulk Read, and Publish APIs
• TypeScript-first — Complete type definitions and type guards
• Dual module support — CommonJS and ESM outputs
• Zero dependencies — Uses native fetch (Node.js 18+)
• Async token refresh — Pass a function that returns a fresh OAuth token
• Multi-region — Supports all 8 Zoho data centers (US, IN, EU, JP, SA, CA, AU, CN)

Installation

npm i zoho-creator-sdk-v2

# From within the monorepo (local dependency)
npm install ./sdk/zoho-creator-sdk-v2

# Or link it
cd sdk/zoho-creator-sdk-v2
npm install
npm run build
npm link
# Then in your project:
npm link zoho-creator-sdk-v2

Quick Start

TypeScript

import { ZohoCreatorClient } from "zoho-creator-sdk-v2";

const client = new ZohoCreatorClient(
  {
    accessToken: "your-oauth2-access-token",
    dataCenter: "IN", // US | IN | EU | JP | SA | CA | AU | CN
    timeout: 30000,
  },
  {
    accountOwnerName: "your_workspace",
    appLinkName: "your-app",
  },
);

// Fetch records
const { data } = await client.data.getRecords("All_Orders", {
  limit: 50,
  criteria: '(Status == "Active")',
});
console.log(data);

JavaScript (CommonJS)

const { ZohoCreatorClient } = require("zoho-creator-sdk-v2");

const client = new ZohoCreatorClient(
  {
    accessToken: async () => {
      // Return a fresh token (e.g. from Zoho OAuth refresh)
      return await getAccessToken();
    },
    dataCenter: "US",
  },
  {
    accountOwnerName: "jason18",
    appLinkName: "zylker-store",
  },
);

API Reference

new ZohoCreatorClient(config, appContext)

| Parameter | Type | Description | | ----------------------------- | --------------------------------- | ---------------------------------------- | | config.accessToken | string \| () => Promise<string> | OAuth2 access token or async provider | | config.dataCenter | ZohoDataCenter | Data center region (default: 'US') | | config.baseUrl | string | Custom base URL (overrides dataCenter) | | config.timeout | number | Request timeout in ms (default: 30000) | | config.fetch | typeof fetch | Custom fetch implementation | | appContext.accountOwnerName | string | Workspace / account owner name | | appContext.appLinkName | string | Application link name |

client.data — Data APIs

| Method | Description | | ----------------------------------------- | ------------------------------- | | addRecords(form, request) | Add records to a form (max 200) | | getRecords(report, params?) | Get records quick view | | getRecordById(report, id) | Get single record detail view | | updateRecords(report, request, params?) | Update records by criteria | | updateRecordById(report, id, request) | Update a single record | | deleteRecords(report, request, params?) | Delete records by criteria | | deleteRecordById(report, id, request?) | Delete a single record |

client.meta — Meta APIs

| Method | Description | | ------------------------------------ | -------------------------------- | | getApplications() | List all accessible applications | | getApplicationsByWorkspace(owner?) | List applications in a workspace | | getForms() | List forms in the application | | getReports() | List reports in the application | | getPages() | List pages in the application | | getSections() | List sections and components | | getFields(form) | List fields in a form |

client.files — File APIs

| Method | Description | | ----------------------------- | ------------------------------------- | | downloadFile(params) | Download a file from a record field | | downloadSubformFile(params) | Download a file from a subform record | | uploadFile(params) | Upload a file to a record field |

client.bulk — Bulk Read APIs

| Method | Description | | -------------------------------------- | ----------------------------------- | | createReadJob(report, request) | Create a bulk export job | | getReadJobStatus(report, jobId) | Check job status | | downloadReadResult(report, jobId) | Download result as ZIP (CSV inside) | | waitForReadJob(report, jobId, opts?) | Poll until job completes |

client.publish — Publish APIs

| Method | Description | | ---------------------------------------- | --------------------------------- | | addRecords(form, request, privatelink) | Add records via published form | | getRecords(report, params) | Get records from published report | | getRecordById(report, id, privatelink) | Get record from published report |

Error Handling

All API errors throw typed error classes:

import {
  ZohoCreatorApiResponseError,
  ZohoCreatorNetworkError,
  ZohoCreatorTimeoutError,
} from "zoho-creator-sdk-v2";

try {
  await client.data.getRecords("Missing_Report");
} catch (error) {
  if (error instanceof ZohoCreatorApiResponseError) {
    console.error(
      "API Error:",
      error.statusCode,
      error.zohoCode,
      error.message,
    );
  } else if (error instanceof ZohoCreatorTimeoutError) {
    console.error("Timeout:", error.timeoutMs);
  } else if (error instanceof ZohoCreatorNetworkError) {
    console.error("Network Error:", error.message);
  }
}

| Error Class | When | | ----------------------------- | ------------------------- | | ZohoCreatorApiResponseError | HTTP 4xx/5xx from the API | | ZohoCreatorNetworkError | Connection/DNS failures | | ZohoCreatorTimeoutError | Request timeout exceeded | | ZohoCreatorValidationError | Invalid SDK configuration |

Type Guards

Validate unknown data at runtime:

import { isZohoApplication, isZohoCreatorApiError } from "zoho-creator-sdk-v2";

if (isZohoApplication(someObj)) {
  console.log(someObj.application_name); // typed!
}

Available guards: isZohoApplication, isZohoForm, isZohoReport, isZohoPage, isZohoField, isZohoSection, isRecordMutationResult, isBulkReadJobDetails, isZohoCreatorApiError.

Data Centers

| Code | Base URL | | ---- | ------------------------- | | US | https://zohoapis.com | | IN | https://zohoapis.in | | EU | https://zohoapis.eu | | JP | https://zohoapis.jp | | SA | https://zohoapis.sa | | CA | https://zohoapis.ca | | AU | https://zohoapis.com.au | | CN | https://zohoapis.com.cn |

Building

cd sdk/zoho-creator-sdk-v2
npm install
npm run build

Output:

• dist/cjs/ — CommonJS modules
• dist/esm/ — ES modules
• dist/types/ — TypeScript declarations

License

MIT