Billing and credit management module for the AIMA platform. This module provides functionality to manage user credits, invoices, and billing operations.
npm install @vulog/aima-billingBilling and credit management module for the AIMA platform. This module provides functionality to manage user credits, invoices, and billing operations.
``bash`
npm install @vulog/aima-client @vulog/aima-core @vulog/aima-billing
`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',
});
`
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 instancepayload
- : Credit configuration objectinitialAmount
- : Number of credits to addvalidityStartDate
- : Start date in ISO formatvalidityEndDate
- : End date in ISO formatnotes
- : Optional notesdiscountCategory
- : 'CREDITS' or 'PERCENTAGE'oneTimeUsage
- : Boolean for one-time usageentityId
- : User UUIDtype
- : 'LOCAL', 'GLOBAL', or 'PERIODIC'usage
- : 'TRIP', 'REGISTRATION', 'PRODUCTS', or 'ALL'
Retrieve user credits by entity ID.
`javascript`
const userCredits = await getUserCreditsByEntityId(client, 'user-uuid-here');
Parameters:
- client: AIMA client instanceentityId
- : User UUID
Get invoice details by ID.
`javascript`
const invoice = await getInvoiceById(client, 'invoice-id-here');
Parameters:
- client: AIMA client instanceinvoiceId
- : Invoice identifier
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 instancepayload
- : Charge configuration objectentityId
- : User UUIDproductId
- : Product identifieramount
- : Amount to charge
`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;
}
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.
`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);
}
}
``