@wanasapps/zoho-api

The Zoho service registry and REST client — 44 products behind one consistent interface.

Zoho is not one API. It is roughly fifty products that grew up separately: different hosts, different scope vocabularies, different places to put the organisation id, different pagination. This package encodes those differences once so callers stop re-solving them per product.

npm install @wanasapps/zoho-api

The registry

Every service entry carries what you need to call it correctly:

const { SERVICES, SERVICE_KEYS, requireService } = require('@wanasapps/zoho-api');

SERVICE_KEYS.length;                    // 44
SERVICES.crm.base('eu', {});            // https://www.zohoapis.eu/crm/v9
SERVICES.desk.context;                  // orgId → injected as a header
SERVICES.books.context;                 // organization_id → injected as a query param
SERVICES.payroll.dcs;                   // ['com','in','ae','sa'] — regional product

• Scopes, copied verbatim from Zoho's documentation. Zoho validates scope names only after sign-in, so one wrong string rejects the entire consent screen — these are never normalised, however inconsistent Zoho's own casing is.
• Datacenter-aware base URLs, so you never build a host.
• Context injection, because Books scopes calls by a query parameter, Desk by a header, and Projects by a path segment.
• Regional restrictions, so a product that does not exist in a datacenter fails up front instead of at request time.

The client

const { request } = require('@wanasapps/zoho-api');

const leads = await request('crm', 'GET', '/Leads', { query: { fields: 'Last_Name' } });

It adds the auth header, injects stored context, validates enveloped responses (some services return failures inside an HTTP 200), retries once on a 401 after a refresh — but never replays a multipart upload, whose body is a single-use stream — and falls back from CRM v9 to v8 when v9 has dropped an endpoint.

Requests are checked against a Zoho host allowlist before the token is attached. Some hosts are built from stored context and some URLs come out of Zoho response bodies; without that check, a poisoned context value could send your access token somewhere else.

Relationship to the other packages

• @wanasapps/zoho-auth — OAuth and session storage. Nothing here stores a credential.
• @wanasapps/deluge-core — Deluge language tooling.
• wanas-zone-cli — the CLI built on all of the above, with 7,726 typed commands.

License

MIT © Wanas Apps FZ-LLC