@vulog/aima-billing

Billing and credit management module for the AIMA platform. This module provides functionality to manage user credits, invoices, and billing operations.

Installation

``bash
npm install @vulog/aima-client @vulog/aima-core @vulog/aima-billing
`

Usage

$3

`javascript
import { getClient } from '@vulog/aima-client';
import { addCredits, getUserCreditsByEntityId, getInvoiceById, chargeProduct } from '@vulog/aima-billing';

const client = getClient({
apiKey: 'your-api-key',
baseUrl: 'https://your-api-base-url',
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
fleetId: 'your-fleet-id',
});
`

API Reference

$3

Add credits to a user's account.

`javascript
const credits = await addCredits(client, {
initialAmount: 100,
validityStartDate: '2024-01-01T00:00:00Z',
validityEndDate: '2024-12-31T23:59:59Z',
notes: 'Welcome bonus',
discountCategory: 'CREDITS',
oneTimeUsage: false,
entityId: 'user-uuid-here',
type: 'LOCAL',
usage: 'ALL'
});
`

Parameters:
- client: AIMA client instance
- payload: Credit configuration object
- initialAmount: Number of credits to add
- validityStartDate: Start date in ISO format
- validityEndDate: End date in ISO format
- notes: Optional notes
- discountCategory: 'CREDITS' or 'PERCENTAGE'
- oneTimeUsage: Boolean for one-time usage
- entityId: User UUID
- type: 'LOCAL', 'GLOBAL', or 'PERIODIC'
- usage: 'TRIP', 'REGISTRATION', 'PRODUCTS', or 'ALL'

$3

Retrieve user credits by entity ID.

`javascript
const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
`

Parameters:
- client: AIMA client instance
- entityId: User UUID

$3

Get invoice details by ID.

`javascript
const invoice = await getInvoiceById(client, 'invoice-id-here');
`

Parameters:
- client: AIMA client instance
- invoiceId: Invoice identifier

$3

Charge a product to a user.

`javascript
const charge = await chargeProduct(client, {
entityId: 'user-uuid-here',
productId: 'product-id-here',
amount: 50
});
`

Parameters:
- client: AIMA client instance
- payload: Charge configuration object
- entityId: User UUID
- productId: Product identifier
- amount: Amount to charge

Types

$3

`typescript
interface Credit {
id: string;
initialAmount: number;
availableAmount: number;
usedAmount: number;
originId: string;
creditAlreadyUsed: boolean;
validityStartDate: string;
validityEndDate: string;
notes: string | null;
discountCategory: 'CREDITS' | 'PERCENTAGE';
oneTimeUsage: boolean;
entityId: string;
type: 'LOCAL' | 'GLOBAL' | 'PERIODIC';
usage: 'TRIP' | 'REGISTRATION' | 'PRODUCTS' | 'ALL';
updateDate: string;
}
`

Error Handling

All functions include validation using Zod schemas and will throw TypeError with detailed error information if validation fails. Network errors are handled by the underlying client.

Examples

$3

`javascript
import { getClient } from '@vulog/aima-client';
import { addCredits, getUserCreditsByEntityId, chargeProduct } from '@vulog/aima-billing';

const client = getClient({
apiKey: 'your-api-key',
baseUrl: 'https://your-api-base-url',
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
fleetId: 'your-fleet-id',
});

async function billingWorkflow() {
try {
// Add credits to user
const credits = await addCredits(client, {
initialAmount: 100,
validityStartDate: '2024-01-01T00:00:00Z',
validityEndDate: '2024-12-31T23:59:59Z',
notes: 'Welcome bonus',
discountCategory: 'CREDITS',
oneTimeUsage: false,
entityId: 'user-uuid-here',
type: 'LOCAL',
usage: 'ALL'
});

console.log('Credits added:', credits);

// Check user credits
const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
console.log('User credits:', userCredits);

// Charge a product
const charge = await chargeProduct(client, {
entityId: 'user-uuid-here',
productId: 'product-id-here',
amount: 25
});

console.log('Product charged:', charge);

} catch (error) {
console.error('Billing error:', error);
}
}
``