@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

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

Usage

Initialize Client

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

addCredits

Add credits to a user's account.

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'

getUserCreditsByEntityId

Retrieve user credits by entity ID.

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

Parameters:

• client: AIMA client instance
• entityId: User UUID

getInvoiceById

Get invoice details by ID.

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

Parameters:

• client: AIMA client instance
• invoiceId: Invoice identifier

chargeProduct

Charge a product to a user.

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

Credit

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

Complete Billing Workflow

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);
    }
}