Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iraycd/odoo-xmlrpc-ts
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.
https://github.com/iraycd/odoo-xmlrpc-ts
Last synced: about 1 month ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/iraycd/odoo-xmlrpc-ts
- Owner: iraycd
- Created: 2024-11-06T09:44:08.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2024-11-06T14:20:09.000Z (about 2 months ago)
- Last Synced: 2024-11-06T15:28:31.617Z (about 2 months ago)
- Language: TypeScript
- Size: 46.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# odoo-xmlrpc-ts
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.
## Features
- ✨ 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
## Prerequisites
- Node.js >= 18
- pnpm >= 8
- Odoo instance with XML-RPC enabled
- API access enabled in your Odoo instance
## Installation
```bash
pnpm add odoo-xmlrpc-ts
```
Using npm:
```bash
npm install odoo-xmlrpc-ts
```
Using yarn:
```bash
yarn add odoo-xmlrpc-ts
```
## Usage
### ESM Import
```typescript
import { OdooClient } from 'odoo-xmlrpc-ts';
```
### CommonJS Require
```javascript
const { OdooClient } = require('odoo-xmlrpc-ts');
```
### Basic Example
```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('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);
}
}
}
```
### Advanced Usage
```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>('res.partner', {
name: 'Test Company',
is_company: true,
email: '[email protected]',
});
// Read the created partner
const [partner] = await client.read('res.partner', [partnerId]);
// Update the partner
await client.write>('res.partner', [partnerId], {
phone: '+1234567890',
});
// Delete the partner
await client.unlink('res.partner', [partnerId]);
}
```
## API Reference
### Constructor
```typescript
const client = new OdooClient({
url: string; // Odoo instance URL
db: string; // Database name
username: string;
password: string;
});
```
### Methods
#### `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(model: string, domain: OdooDomain, options?: SearchReadOptions): Promise`
Search and read records in one call.
```typescript
interface SearchReadOptions extends SearchOptions {
fields?: string[];
}
```
#### `async read(model: string, ids: number[], fields?: string[]): Promise`
Read specific records by ID.
#### `async create(model: string, values: T): Promise`
Create a new record.
#### `async write(model: string, ids: number[], values: T): Promise`
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.
## 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);
}
}
```
## Development
```bash
# 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
```
## 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 Request
## Common Issues
### CORS Issues
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.
### Authentication Issues
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.
## License
MIT © Dilip Ray Ch