@vulog/aima-search

Search functionality module for the AIMA platform. This module provides search capabilities across various entities in the fleet management system.

Installation

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

Usage

Initialize Client

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

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

search

Perform a search across the AIMA platform.

const results = await search(client, {
    query: 'search term',
    entityType: 'VEHICLE', // or 'USER', 'TRIP', etc.
    filters: {
        status: 'ACTIVE',
        category: 'CAR'
    },
    pagination: {
        page: 0,
        size: 20
    }
});

Parameters:

• client: AIMA client instance
• options: Search configuration object
  • query: Search term or phrase
  • entityType: Type of entity to search ('VEHICLE', 'USER', 'TRIP', 'BOOKING', 'PRODUCT')
  • filters: Optional filters to apply
  • pagination: Optional pagination settings
    • page: Page number (0-based)
    • size: Number of results per page

Returns: Search results object with matching entities

Types

SearchOptions

interface SearchOptions {
    query: string;
    entityType: 'VEHICLE' | 'USER' | 'TRIP' | 'BOOKING' | 'PRODUCT';
    filters?: Record<string, any>;
    pagination?: {
        page: number;
        size: number;
    };
}

SearchResults

interface SearchResults {
    entities: any[];
    totalCount: number;
    page: number;
    size: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
}

Error Handling

The search function will throw appropriate errors if:

• Invalid search parameters are provided
• Unsupported entity types are specified
• Network errors occur

Examples

Basic Search Operations

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

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 basicSearch() {
    try {
        // Search for vehicles
        const vehicleResults = await search(client, {
            query: 'BMW',
            entityType: 'VEHICLE',
            pagination: { page: 0, size: 10 }
        });
        
        console.log(`Found ${vehicleResults.totalCount} vehicles matching "BMW"`);
        console.log('Results:', vehicleResults.entities);
        
        // Search for users
        const userResults = await search(client, {
            query: '[email protected]',
            entityType: 'USER',
            filters: { status: 'ACTIVE' }
        });
        
        console.log(`Found ${userResults.totalCount} users matching email`);
        
        return { vehicleResults, userResults };
    } catch (error) {
        console.error('Search error:', error);
        throw error;
    }
}

Advanced Search with Filters

async function advancedSearch() {
    try {
        // Search for active vehicles with specific filters
        const vehicleResults = await search(client, {
            query: 'electric',
            entityType: 'VEHICLE',
            filters: {
                status: 'ACTIVE',
                energyType: 'ELECTRIC',
                isAvailable: true
            },
            pagination: { page: 0, size: 50 }
        });
        
        console.log('Electric vehicles search results:', vehicleResults);
        
        // Search for trips within date range
        const tripResults = await search(client, {
            query: 'trip',
            entityType: 'TRIP',
            filters: {
                startDate: '2024-01-01T00:00:00Z',
                endDate: '2024-01-31T23:59:59Z',
                status: 'COMPLETED'
            }
        });
        
        console.log('Trip search results:', tripResults);
        
        return { vehicleResults, tripResults };
    } catch (error) {
        console.error('Advanced search error:', error);
        throw error;
    }
}

Search Helper Functions

// Search for vehicles by location
async function searchVehiclesByLocation(client, location, radius) {
    try {
        const results = await search(client, {
            query: location,
            entityType: 'VEHICLE',
            filters: {
                location: {
                    coordinates: location,
                    radius: radius
                },
                isAvailable: true
            }
        });
        
        return results.entities;
    } catch (error) {
        console.error('Location search error:', error);
        throw error;
    }
}

// Search for users by name or email
async function searchUsers(client, searchTerm) {
    try {
        const results = await search(client, {
            query: searchTerm,
            entityType: 'USER',
            filters: {
                status: 'ACTIVE'
            }
        });
        
        return results.entities;
    } catch (error) {
        console.error('User search error:', error);
        throw error;
    }
}

// Search for products by category
async function searchProducts(client, category, searchTerm = '') {
    try {
        const results = await search(client, {
            query: searchTerm,
            entityType: 'PRODUCT',
            filters: {
                category: category,
                isActive: true,
                isAvailable: true
            }
        });
        
        return results.entities;
    } catch (error) {
        console.error('Product search error:', error);
        throw error;
    }
}

Pagination Helper

async function getAllSearchResults(client, searchOptions) {
    try {
        const allResults = [];
        let currentPage = 0;
        let hasMorePages = true;
        
        while (hasMorePages) {
            const results = await search(client, {
                ...searchOptions,
                pagination: {
                    page: currentPage,
                    size: 100 // Use larger page size for efficiency
                }
            });
            
            allResults.push(...results.entities);
            hasMorePages = results.hasNextPage;
            currentPage++;
            
            // Safety check to prevent infinite loops
            if (currentPage > 100) {
                console.warn('Maximum page limit reached');
                break;
            }
        }
        
        console.log(`Retrieved ${allResults.length} total results across ${currentPage} pages`);
        return allResults;
    } catch (error) {
        console.error('Pagination error:', error);
        throw error;
    }
}

// Usage example
async function getAllVehicles() {
    const allVehicles = await getAllSearchResults(client, {
        query: '',
        entityType: 'VEHICLE',
        filters: { status: 'ACTIVE' }
    });
    
    return allVehicles;
}

Search Analytics

async function analyzeSearchResults(client, searchOptions) {
    try {
        const results = await search(client, searchOptions);
        
        const analysis = {
            totalResults: results.totalCount,
            currentPage: results.page,
            pageSize: results.size,
            totalPages: results.totalPages,
            hasNextPage: results.hasNextPage,
            hasPreviousPage: results.hasPreviousPage,
            resultsPerPage: results.entities.length
        };
        
        console.log('Search Analysis:');
        console.log(`Total Results: ${analysis.totalResults}`);
        console.log(`Current Page: ${analysis.currentPage + 1} of ${analysis.totalPages}`);
        console.log(`Results on Current Page: ${analysis.resultsPerPage}`);
        console.log(`Has Next Page: ${analysis.hasNextPage}`);
        console.log(`Has Previous Page: ${analysis.hasPreviousPage}`);
        
        return analysis;
    } catch (error) {
        console.error('Search analysis error:', error);
        throw error;
    }
}