Type-safe Odoo XML-RPC client for Node.js written in TypeScript
npm install odoo-xmlrpc-tsA type-safe Odoo XML-RPC client for Node.js written in TypeScript. This package provides a robust interface to interact with Odoo's external API through XML-RPC.
- ✨ Full TypeScript support with type definitions
- 🔄 Promise-based API
- 🔐 Automatic authentication handling
- 🛡️ Comprehensive error handling
- 🎯 Support for all major Odoo operations
- 📝 Built-in TypeScript interfaces for Odoo models
- 🔍 Type-safe domain builders
- 📦 Zero external dependencies except xmlrpc
- 🔄 Supports both ESM and CommonJS
- Node.js >= 18
- pnpm >= 8
- Odoo instance with XML-RPC enabled
- API access enabled in your Odoo instance
``bash`
pnpm add odoo-xmlrpc-ts
Using npm:
`bash`
npm install odoo-xmlrpc-ts
Using yarn:
`bash`
yarn add odoo-xmlrpc-ts
`typescript`
import { OdooClient } from 'odoo-xmlrpc-ts';
`javascript`
const { OdooClient } = require('odoo-xmlrpc-ts');
`typescript
import { OdooClient } from 'odoo-xmlrpc-ts';
// Or for CommonJS:
// const { OdooClient } = require('odoo-xmlrpc-ts');
// Define your model interfaces
interface Partner {
id: number;
name: string;
email?: string;
is_company: boolean;
}
async function example() {
// Initialize client
const client = new OdooClient({
url: 'https://your-odoo-instance.com',
db: 'your-database',
username: 'admin',
password: 'admin',
});
try {
// Search and read partners
const partners = await client.searchRead
fields: ['name', 'email'],
limit: 10,
});
console.log('Partners:', partners);
} catch (error) {
if (error instanceof OdooError) {
console.error('Odoo Error:', error.message);
}
}
}
`
You can configure custom HTTP agents for advanced network configurations such as custom SSL settings, or connection pooling:
> Note: Odoo doesn't support HTTPS natively. For production deployments, place Odoo behind a reverse proxy (Nginx/Apache) with SSL termination. The agent configuration below is useful when connecting to such HTTPS-enabled Odoo instances.
`typescript
import { OdooClient } from 'odoo-xmlrpc-ts';
import https from 'node:https';
import fs from 'node:fs';
// Example: Custom HTTPS agent with specific SSL options
const httpsAgent = new https.Agent({
ca: fs.readFileSync('/path/to/ca-certificate.pem'), // Custom CA certificate
keepAlive: true,
maxSockets: 10,
});
// Alternative: For development/testing only (not recommended for production)
const httpsAgent = new https.Agent({
rejectUnauthorized: false, // Disables SSL verification (use only for testing)
keepAlive: true,
maxSockets: 10,
});
const client = new OdooClient({
url: 'https://your-odoo-instance.com', // HTTPS URL (via reverse proxy)
db: 'your-database',
username: 'admin',
password: 'admin',
agent: httpsAgent,
});
`
`typescript
import { OdooClient, OdooBaseModel } from 'odoo-xmlrpc-ts';
// Extend the base model interface
interface CustomPartner extends OdooBaseModel {
name: string;
email: string;
phone?: string;
is_company: boolean;
child_ids: number[];
}
async function advancedExample() {
const client = new OdooClient({
url: 'https://your-odoo-instance.com',
db: 'your-database',
username: 'admin',
password: 'admin',
});
// Create a new partner
const partnerId = await client.create
name: 'Test Company',
is_company: true,
email: 'test@example.com',
});
// Read the created partner
const [partner] = await client.read
// Update the partner
await client.write
phone: '+1234567890',
});
// Delete the partner
await client.unlink('res.partner', [partnerId]);
}
`
`typescript`
const client = new OdooClient({
url: string; // Odoo instance URL
db: string; // Database name
username: string;
password: string;
agent?: https.Agent | http.Agent; // Optional HTTP agent for custom network configuration
});
#### async version(): Promise
Get Odoo server version information.
#### async authenticate(): Promise
Authenticate with the Odoo server. Called automatically when needed.
#### async search(model: string, domain: OdooDomain, options?: SearchOptions): Promise
Search for record IDs.
`typescript`
interface SearchOptions {
offset?: number;
limit?: number;
order?: string;
}
#### async searchRead
Search and read records in one call.
`typescript`
interface SearchReadOptions extends SearchOptions {
fields?: string[];
}
#### async read
Read specific records by ID.
#### async create
Create a new record.
#### async write
Update existing records.
#### async unlink(model: string, ids: number[]): Promise
Delete records.
#### async fieldsGet(model: string, attributes?: string[]): Promise
Get field information for a model.
#### async execute
Execute any method on an Odoo model. This is useful for calling custom methods or workflow actions.
`typescript
// Example: Confirm a sale order
await client.execute('sale.order', 'action_confirm', [orderId]);
// Example: Send email using template
await client.execute('mail.template', 'send_mail', [templateId, recordId]);
// Example: Custom method with keyword arguments
await client.execute('your.model', 'your_method', [arg1, arg2], {
kwarg1: 'value1',
kwarg2: 'value2'
});
The client includes built-in error classes:
- OdooError: Base error class for all Odoo-related errorsOdooAuthenticationError
- : Authentication-specific errors
`typescript`
try {
await client.authenticate();
} catch (error) {
if (error instanceof OdooAuthenticationError) {
console.error('Authentication failed:', error.message);
}
}
`bashInstall dependencies
pnpm install
Contributing
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull RequestCommon Issues
$3
If you're using this client in a browser environment, you might encounter CORS issues. This client is intended for Node.js usage. For browser environments, consider using Odoo's JSON-RPC interface instead.
$3
Make sure your Odoo instance has XML-RPC enabled and your user has the necessary access rights. For Odoo.sh or Odoo Online instances, you might need to whitelist your IP address.
Notes & Considerations
$3
- Odoo doesn't provide native HTTPS support (removed since ~v6.1)
- Production deployments require a reverse proxy (Nginx/Apache) for SSL termination
- Use proxy_mode = 1 in Odoo configuration when behind a proxy
- The HTTP agent configuration is useful for custom SSL certificates and corporate environments$3
- This library uses Odoo's XML-RPC endpoints (/xmlrpc/2/common, /xmlrpc/2/object)
- Odoo also provides JSON-RPC endpoints (/jsonrpc`) - these are separate protocolsThanks to all the amazing contributors who have made this project possible:
Ray Ch 29 contributions | Haris565 3 contributions | Xavier Stouder 1 contribution | ven 1 contribution |
MIT © Dilip Ray Ch