@vulog/aima-product

Product management module for the AIMA platform. This module provides functionality to retrieve and manage products available in the fleet.

Installation

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

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { getProductById, getProducts } from '@vulog/aima-product';

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

getProductById

Retrieve a specific product by its ID.

const product = await getProductById(client, 'product-id-here');

Parameters:

• client: AIMA client instance
• productId: Product identifier

Returns: Product object with detailed information

getProducts

Retrieve all available products.

const products = await getProducts(client);

Parameters:

• client: AIMA client instance

Returns: Array of all available products

Types

Product

interface Product {
    id: string;
    name: string;
    description: string;
    price: number;
    currency: string;
    category: string;
    isActive: boolean;
    isAvailable: boolean;
    taxes: ProductTaxe[];
    metadata: Record<string, any>;
    createdAt: string;
    updatedAt: string;
}

ProductTaxe

interface ProductTaxe {
    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

Functions will throw appropriate errors if:

• Invalid product ID is provided
• Product not found
• Network errors occur

Examples

Basic Product Operations

import { getClient } from '@vulog/aima-client';
import { getProductById, getProducts } from '@vulog/aima-product';

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 productOperations() {
    try {
        // Get all products
        const products = await getProducts(client);
        console.log(`Found ${products.length} products`);
        
        // Get specific product
        const product = await getProductById(client, 'premium-insurance-id');
        console.log('Product details:', product);
        
        return { products, product };
    } catch (error) {
        console.error('Product operation error:', error);
        throw error;
    }
}

Product Search and Filtering

async function searchProducts(client, searchTerm, category) {
    try {
        const allProducts = await getProducts(client);
        
        let filteredProducts = allProducts;
        
        // Filter by search term
        if (searchTerm) {
            filteredProducts = filteredProducts.filter(product =>
                product.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
                product.description.toLowerCase().includes(searchTerm.toLowerCase())
            );
        }
        
        // Filter by category
        if (category) {
            filteredProducts = filteredProducts.filter(product =>
                product.category === category
            );
        }
        
        // Filter only active and available products
        filteredProducts = filteredProducts.filter(product =>
            product.isActive && product.isAvailable
        );
        
        console.log(`Found ${filteredProducts.length} products matching criteria`);
        
        return filteredProducts;
    } catch (error) {
        console.error('Product search error:', error);
        throw error;
    }
}

// Usage examples
async function searchExamples() {
    // Search for insurance products
    const insuranceProducts = await searchProducts(client, 'insurance', 'INSURANCE');
    
    // Search for products containing "premium"
    const premiumProducts = await searchProducts(client, 'premium');
    
    // Get all active products
    const activeProducts = await searchProducts(client);
}

Product Price Calculation

function calculateProductPrice(product, quantity = 1) {
    const basePrice = product.price * quantity;
    let totalPrice = basePrice;
    const taxes = [];
    
    // Calculate taxes
    product.taxes.forEach(tax => {
        if (!tax.isInclusive) {
            const taxAmount = (basePrice * tax.rate) / 100;
            totalPrice += taxAmount;
            taxes.push({
                name: tax.name,
                rate: tax.rate,
                amount: taxAmount
            });
        }
    });
    
    return {
        basePrice,
        totalPrice,
        taxes,
        currency: product.currency,
        quantity,
        breakdown: {
            unitPrice: product.price,
            subtotal: basePrice,
            taxTotal: taxes.reduce((sum, tax) => sum + tax.amount, 0)
        }
    };
}

// Usage example
async function calculateProductCost(productId, quantity) {
    try {
        const product = await getProductById(client, productId);
        const cost = calculateProductPrice(product, quantity);
        
        console.log(`Product: ${product.name}`);
        console.log(`Quantity: ${quantity}`);
        console.log(`Unit Price: ${product.price} ${product.currency}`);
        console.log(`Subtotal: ${cost.basePrice} ${product.currency}`);
        console.log(`Total: ${cost.totalPrice} ${product.currency}`);
        
        if (cost.taxes.length > 0) {
            console.log('Taxes:');
            cost.taxes.forEach(tax => {
                console.log(`  ${tax.name}: ${tax.amount} ${product.currency} (${tax.rate}%)`);
            });
        }
        
        return cost;
    } catch (error) {
        console.error('Product cost calculation error:', error);
        throw error;
    }
}

Product Categories Analysis

async function analyzeProductCategories(client) {
    try {
        const products = await getProducts(client);
        
        // Group products by category
        const categories = products.reduce((acc, product) => {
            const category = product.category || 'UNCATEGORIZED';
            if (!acc[category]) {
                acc[category] = {
                    count: 0,
                    products: [],
                    totalValue: 0,
                    averagePrice: 0
                };
            }
            
            acc[category].count++;
            acc[category].products.push(product);
            acc[category].totalValue += product.price;
            
            return acc;
        }, {});
        
        // Calculate averages
        Object.keys(categories).forEach(category => {
            const cat = categories[category];
            cat.averagePrice = cat.totalValue / cat.count;
        });
        
        console.log('Product Categories Analysis:');
        console.log('============================');
        
        Object.entries(categories).forEach(([category, data]) => {
            console.log(`\n${category}:`);
            console.log(`  Count: ${data.count} products`);
            console.log(`  Total Value: ${data.totalValue} ${products[0]?.currency || 'N/A'}`);
            console.log(`  Average Price: ${data.averagePrice.toFixed(2)} ${products[0]?.currency || 'N/A'}`);
            console.log(`  Active Products: ${data.products.filter(p => p.isActive).length}`);
            console.log(`  Available Products: ${data.products.filter(p => p.isAvailable).length}`);
        });
        
        return categories;
    } catch (error) {
        console.error('Category analysis error:', error);
        throw error;
    }
}