@wanasapps/zoho-auth

Zoho OAuth, token lifecycle and session storage — one implementation shared by every tool that talks to Zoho.

Built so a CLI, an editor extension and a background service can sign in once and see the same tokens, rather than each keeping its own copy and drifting.

npm install @wanasapps/zoho-auth

What it handles

Grants shared across services. Zoho caps a refresh token at 10 live access tokens. Storing one grant and pointing many services at it means a refresh updates all of them at once, instead of 44 services each racing to refresh and tripping the accounts rate limiter.

Project-local sessions, found the way git finds .git. zoneHome() walks up from the working directory looking for a .zone folder, falling back to ~/.zone, with ZONE_HOME overriding both. That lets one machine hold a different Zoho identity per project directory — a real need when you work across client orgs.

Safe writes. Session files are written to a random temp name in the same directory and renamed into place, so a concurrent reader never sees a half-written file, and they are chmod'd 0600.

Datacenter resolution. com, eu, in, com.au, jp, uk, ca, sa, ae, cn — including the odd ones, where Canada authenticates at accounts.zohocloud.ca but calls www.zohoapis.ca.

Usage

const auth = require('@wanasapps/zoho-auth');

const { token, session } = await auth.getAccessTokenWithSession('crm');
auth.setContext('books', { organization_id: '123456' });
auth.dc.zohoapisDomain('eu');   // https://www.zohoapis.eu

Wording the sign-in error

This package deliberately knows nothing about which Zoho products exist, or what your CLI is called. Inject that:

auth.setSignInHint((service) => `Run "zone login ${service}"`);

Without it you get a generic Sign in to <service> first.

Errors

Failures throw an AuthError carrying a code and an actionable hint. Map on code, never on the class — that is what lets one error work inside a CLI's exit-code table, an extension's notification and a server's response.

Codes: NOT_AUTHENTICATED, AUTH_FAILED, AUTH_TIMEOUT, BAD_INPUT.

Scope

This package does not know which Zoho services exist — see @wanasapps/zoho-api for the service registry and REST client built on top of it.

License

MIT © Wanas Apps FZ-LLC