@vulog/aima-pricing

Pricing management module for the AIMA platform. This module provides functionality to retrieve and manage pricing information for trips, products, and services.

Installation

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

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { getPricingById } from '@vulog/aima-pricing';

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

getPricingById

Retrieve pricing information by pricing ID.

const pricing = await getPricingById(client, 'pricing-id-here');

Parameters:

• client: AIMA client instance
• pricingId: Pricing identifier

Returns: Pricing object with detailed pricing information

Types

Pricing

interface Pricing {
    id: string;
    name: string;
    description: string;
    isActive: boolean;
    parameters: PricingParameters;
    plans: PricingPlan[];
    taxRates: PricingTaxRate[];
    createdAt: string;
    updatedAt: string;
}

PricingParameters

interface PricingParameters {
    basePrice: number;
    currency: string;
    timeUnit: 'MINUTE' | 'HOUR' | 'DAY';
    distanceUnit: 'KM' | 'MILE';
    minimumCharge: number;
    maximumCharge?: number;
    freeTimeMinutes?: number;
    freeDistanceKm?: number;
}

PricingPlan

interface PricingPlan {
    id: string;
    name: string;
    pricePerTimeUnit: number;
    pricePerDistanceUnit: number;
    timeThreshold: number; // in minutes
    distanceThreshold: number; // in km
    isDefault: boolean;
}

PricingTaxRate

interface PricingTaxRate {
    id: string;
    name: string;
    rate: number; // percentage (e.g., 20 for 20%)
    type: 'VAT' | 'SALES_TAX' | 'CUSTOM';
    isInclusive: boolean; // true if tax is included in base price
}

Error Handling

The function will throw appropriate errors if:

• Invalid pricing ID is provided
• Pricing not found
• Network errors occur

Examples

Basic Pricing Retrieval

import { getClient } from '@vulog/aima-client';
import { getPricingById } from '@vulog/aima-pricing';

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 getPricingInfo() {
    try {
        const pricing = await getPricingById(client, 'standard-pricing-id');
        
        console.log('Pricing Information:');
        console.log(`Name: ${pricing.name}`);
        console.log(`Description: ${pricing.description}`);
        console.log(`Base Price: ${pricing.parameters.basePrice} ${pricing.parameters.currency}`);
        console.log(`Time Unit: ${pricing.parameters.timeUnit}`);
        console.log(`Distance Unit: ${pricing.parameters.distanceUnit}`);
        
        return pricing;
    } catch (error) {
        console.error('Pricing retrieval error:', error);
        throw error;
    }
}

Pricing Calculation Helper

function calculateTripCost(pricing, durationMinutes, distanceKm) {
    const { parameters, plans, taxRates } = pricing;
    
    // Find applicable pricing plan
    const applicablePlan = plans.find(plan => 
        durationMinutes >= plan.timeThreshold && 
        distanceKm >= plan.distanceThreshold
    ) || plans.find(plan => plan.isDefault);
    
    if (!applicablePlan) {
        throw new Error('No applicable pricing plan found');
    }
    
    // Calculate base cost
    const timeCost = (durationMinutes / 60) * applicablePlan.pricePerTimeUnit;
    const distanceCost = distanceKm * applicablePlan.pricePerDistanceUnit;
    let baseCost = timeCost + distanceCost;
    
    // Apply minimum/maximum charges
    if (baseCost < parameters.minimumCharge) {
        baseCost = parameters.minimumCharge;
    }
    if (parameters.maximumCharge && baseCost > parameters.maximumCharge) {
        baseCost = parameters.maximumCharge;
    }
    
    // Apply taxes
    let totalCost = baseCost;
    const taxes = [];
    
    taxRates.forEach(taxRate => {
        if (!taxRate.isInclusive) {
            const taxAmount = (baseCost * taxRate.rate) / 100;
            totalCost += taxAmount;
            taxes.push({
                name: taxRate.name,
                rate: taxRate.rate,
                amount: taxAmount
            });
        }
    });
    
    return {
        baseCost,
        totalCost,
        taxes,
        currency: parameters.currency,
        breakdown: {
            timeCost,
            distanceCost,
            applicablePlan: applicablePlan.name
        }
    };
}

// Usage example
async function calculateCost(pricingId, durationMinutes, distanceKm) {
    try {
        const pricing = await getPricingById(client, pricingId);
        const cost = calculateTripCost(pricing, durationMinutes, distanceKm);
        
        console.log('Trip Cost Calculation:');
        console.log(`Duration: ${durationMinutes} minutes`);
        console.log(`Distance: ${distanceKm} km`);
        console.log(`Base Cost: ${cost.baseCost} ${cost.currency}`);
        console.log(`Total Cost: ${cost.totalCost} ${cost.currency}`);
        
        if (cost.taxes.length > 0) {
            console.log('Taxes:');
            cost.taxes.forEach(tax => {
                console.log(`  ${tax.name}: ${tax.amount} ${cost.currency} (${tax.rate}%)`);
            });
        }
        
        return cost;
    } catch (error) {
        console.error('Cost calculation error:', error);
        throw error;
    }
}

Pricing Comparison

async function comparePricing(pricingIds) {
    try {
        const pricingList = await Promise.all(
            pricingIds.map(id => getPricingById(client, id))
        );
        
        console.log('Pricing Comparison:');
        console.log('==================');
        
        pricingList.forEach(pricing => {
            console.log(`\n${pricing.name}:`);
            console.log(`  Base Price: ${pricing.parameters.basePrice} ${pricing.parameters.currency}`);
            console.log(`  Time Unit: ${pricing.parameters.timeUnit}`);
            console.log(`  Distance Unit: ${pricing.parameters.distanceUnit}`);
            console.log(`  Minimum Charge: ${pricing.parameters.minimumCharge} ${pricing.parameters.currency}`);
            
            if (pricing.parameters.maximumCharge) {
                console.log(`  Maximum Charge: ${pricing.parameters.maximumCharge} ${pricing.parameters.currency}`);
            }
            
            console.log(`  Plans: ${pricing.plans.length}`);
            pricing.plans.forEach(plan => {
                console.log(`    - ${plan.name}: ${plan.pricePerTimeUnit}/${pricing.parameters.timeUnit}, ${plan.pricePerDistanceUnit}/${pricing.parameters.distanceUnit}`);
            });
        });
        
        return pricingList;
    } catch (error) {
        console.error('Pricing comparison error:', error);
        throw error;
    }
}