zohobooks-sdk

A TypeScript-first SDK for seamless interaction with the Zoho Books API. Designed for Node.js environments with full type safety and modern async/await support.

✨ Features

• Full TypeScript Support - Type-safe API interactions with auto-completion
• Global API Host Options - Support for all Zoho Books regions (US, EU, India, etc.)
• Automatic Token Management - Handles OAuth token refresh automatically
• Modular API Structure - Organized resources (Contacts, Invoices, Items etc.)
• Axios-based Client - With interceptors for error handling and logging
• Comprehensive Documentation - JSDoc comments and type definitions

📦 Installation

Install the package using your preferred package manager:

# Using pnpm (recommended)
pnpm add zohobooks-sdk

# Using npm
npm install zohobooks-sdk

# Using yarn
yarn add zohobooks-sdk

⚡ Quick Start

Initialization

import { ZohoBooks, APIHost } from "zohobooks-sdk";

const zohoBooks = new ZohoBooks({
  host: APIHost.India, // Choose from available regions
  clientId: "1000.XXXXXX", // From Zoho Developer Console
  clientSecret: "1632...8a5f13", // From Zoho Developer Console
  organizationId: "1234567", // Your Zoho Books Organization ID
  refreshToken: "1000.XXXXXXX.XXXXXX", // OAuth refresh token
  logger: true, // Optional: Enable request/response logging
});

Basic Usage Examples

Create a Contact

const newContact = await zohoBooks.contacts.create({
  contact_name: "Acme Corp",
  company_name: "Acme Corporation",
  contact_type: "customer",
  email: "[e-mail]",
  billing_address: {
    address: "123 Main St",
    city: "New York",
    state: "NY",
    zip: "10001",
    country: "USA",
  },
});

Create an Invoice

const invoice = await zohoBooks.invoices.create({
  customer_id: "460000000026049",
  date: "2023-11-15",
  line_items: [
    {
      name: "Annual Subscription",
      description: "Premium Plan (Yearly)",
      rate: 299,
      quantity: 1,
    },
  ],
});

📚 API Resources

The SDK provides access to all major Zoho Books API resources:

Resource	Methods Available
Contacts	create, get, update, list, delete
Invoices	create, get, update, list, delete, email
Estimates	create, get, update, list, delete
Items	create, get, update, list, delete
Organizations	get, list
Payments	create, get, list, delete
...and more	Full list in documentation

🔐 Authentication

The SDK handles OAuth 2.0 authentication automatically. You'll need to:

• Register your app in the Zoho Developer Console
• Generate a refresh token (see Zoho OAuth docs)
• Provide these credentials during initialization

🌐 Region Support

Choose from these available API hosts:

enum APIHost {
  UnitedStates = "https://www.zohoapis.com/books/v3",
  Europe = "https://www.zohoapis.eu/books/v3",
  India = "https://www.zohoapis.in/books/v3",
  Australia = "https://www.zohoapis.com.au/books/v3",
  Japan = "https://www.zohoapis.jp/books/v3",
  China = "https://www.zohoapis.com.cn/books/v3",
}

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Useful Links

• Zoho Books API Documentation
• Zoho Developer Console
• Report an Issue