A 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
pnpm add odoo-xmlrpc-ts
Using npm:
npm install odoo-xmlrpc-ts
Using yarn:
yarn add odoo-xmlrpc-ts
import { OdooClient } from 'odoo-xmlrpc-ts';
const { OdooClient } = require('odoo-xmlrpc-ts');
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<Partner>('res.partner', [['is_company', '=', true]], {
fields: ['name', 'email'],
limit: 10,
});
console.log('Partners:', partners);
} catch (error) {
if (error instanceof OdooError) {
console.error('Odoo Error:', error.message);
}
}
}
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<Partial<CustomPartner>>('res.partner', {
name: 'Test Company',
is_company: true,
email: '[email protected]',
});
// Read the created partner
const [partner] = await client.read<CustomPartner>('res.partner', [partnerId]);
// Update the partner
await client.write<Partial<CustomPartner>>('res.partner', [partnerId], {
phone: '+1234567890',
});
// Delete the partner
await client.unlink('res.partner', [partnerId]);
}
const client = new OdooClient({
url: string; // Odoo instance URL
db: string; // Database name
username: string;
password: string;
});
Get Odoo server version information.
Authenticate with the Odoo server. Called automatically when needed.
Search for record IDs.
interface SearchOptions {
offset?: number;
limit?: number;
order?: string;
}
Search and read records in one call.
interface SearchReadOptions extends SearchOptions {
fields?: string[];
}
Read specific records by ID.
Create a new record.
Update existing records.
Delete records.
Get field information for a model.
Execute any method on an Odoo model. This is useful for calling custom methods or workflow actions.
// 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'
});
## Error Handling
The client includes built-in error classes:
- `OdooError`: Base error class for all Odoo-related errors
- `OdooAuthenticationError`: Authentication-specific errors
```typescript
try {
await client.authenticate();
} catch (error) {
if (error instanceof OdooAuthenticationError) {
console.error('Authentication failed:', error.message);
}
}
# Install dependencies
pnpm install
# Build
pnpm run build
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverage
# Lint
pnpm run lint
# Format code
pnpm run format
# Type check
pnpm run type-check
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'feat: add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
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.
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.
Thanks 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