@vulog/aima-ticket

Ticket management module for the AIMA platform. This module provides functionality to create, retrieve, and manage support tickets and user groups.

Installation

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

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { getTickets, getUserGroupById, createTicket } from '@vulog/aima-ticket';

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

getTickets

Retrieve tickets with optional filtering.

const tickets = await getTickets(client, {
    status: 'OPEN',
    priority: 'HIGH',
    assignedTo: 'agent-id-here'
});

Parameters:

• client: AIMA client instance
• filters: Optional filter object
  • status: Ticket status ('OPEN', 'IN_PROGRESS', 'CLOSED', 'RESOLVED')
  • priority: Priority level ('LOW', 'MEDIUM', 'HIGH', 'URGENT')
  • assignedTo: Agent ID
  • createdBy: User ID who created the ticket
  • category: Ticket category

Returns: Array of tickets matching the filters

getUserGroupById

Retrieve user group information by ID.

const userGroup = await getUserGroupById(client, 'group-id-here');

Parameters:

• client: AIMA client instance
• groupId: User group identifier

Returns: User group object with details

createTicket

Create a new support ticket.

const ticket = await createTicket(client, {
    title: 'Vehicle not starting',
    description: 'The vehicle with ID xyz is not responding to unlock commands',
    priority: 'HIGH',
    category: 'TECHNICAL',
    entityId: 'user-uuid-here',
    relatedEntityType: 'VEHICLE',
    relatedEntityId: 'vehicle-id-here'
});

Parameters:

• client: AIMA client instance
• ticketData: Ticket creation data
  • title: Ticket title
  • description: Detailed description
  • priority: Priority level ('LOW', 'MEDIUM', 'HIGH', 'URGENT')
  • category: Ticket category ('TECHNICAL', 'BILLING', 'GENERAL', 'VEHICLE')
  • entityId: User ID creating the ticket
  • relatedEntityType: Type of related entity ('VEHICLE', 'TRIP', 'BOOKING')
  • relatedEntityId: ID of related entity

Returns: Created ticket object

Types

Ticket

interface Ticket {
    id: string;
    title: string;
    description: string;
    status: 'OPEN' | 'IN_PROGRESS' | 'CLOSED' | 'RESOLVED';
    priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
    category: 'TECHNICAL' | 'BILLING' | 'GENERAL' | 'VEHICLE';
    entityId: string;
    assignedTo?: string;
    createdBy: string;
    createdAt: string;
    updatedAt: string;
    resolvedAt?: string;
    relatedEntityType?: string;
    relatedEntityId?: string;
    comments: TicketComment[];
}

TicketComment

interface TicketComment {
    id: string;
    ticketId: string;
    authorId: string;
    content: string;
    isInternal: boolean;
    createdAt: string;
    updatedAt: string;
}

UserGroup

interface UserGroup {
    id: string;
    name: string;
    description: string;
    memberCount: number;
    permissions: string[];
    createdAt: string;
    updatedAt: string;
}

Error Handling

All functions include validation and will throw appropriate errors if:

• Required parameters are missing
• Invalid ticket or group IDs are provided
• Invalid priority or category values are used
• Network errors occur

Examples

Basic Ticket Operations

import { getClient } from '@vulog/aima-client';
import { getTickets, createTicket, getUserGroupById } from '@vulog/aima-ticket';

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 ticketOperations() {
    try {
        // Get all open tickets
        const openTickets = await getTickets(client, { status: 'OPEN' });
        console.log(`Found ${openTickets.length} open tickets`);
        
        // Create a new ticket
        const newTicket = await createTicket(client, {
            title: 'Vehicle Issue',
            description: 'Vehicle not responding to commands',
            priority: 'HIGH',
            category: 'TECHNICAL',
            entityId: 'user-uuid-here',
            relatedEntityType: 'VEHICLE',
            relatedEntityId: 'vehicle-id-here'
        });
        
        console.log('Created ticket:', newTicket);
        
        // Get user group
        const userGroup = await getUserGroupById(client, 'group-id-here');
        console.log('User group:', userGroup);
        
        return { openTickets, newTicket, userGroup };
    } catch (error) {
        console.error('Ticket operation error:', error);
        throw error;
    }
}

Ticket Management Dashboard

async function getTicketDashboard(client) {
    try {
        // Get tickets by status
        const [openTickets, inProgressTickets, closedTickets] = await Promise.all([
            getTickets(client, { status: 'OPEN' }),
            getTickets(client, { status: 'IN_PROGRESS' }),
            getTickets(client, { status: 'CLOSED' })
        ]);
        
        // Get tickets by priority
        const highPriorityTickets = await getTickets(client, { priority: 'HIGH' });
        const urgentTickets = await getTickets(client, { priority: 'URGENT' });
        
        const dashboard = {
            summary: {
                total: openTickets.length + inProgressTickets.length + closedTickets.length,
                open: openTickets.length,
                inProgress: inProgressTickets.length,
                closed: closedTickets.length,
                highPriority: highPriorityTickets.length,
                urgent: urgentTickets.length
            },
            tickets: {
                open: openTickets,
                inProgress: inProgressTickets,
                closed: closedTickets,
                highPriority: highPriorityTickets,
                urgent: urgentTickets
            }
        };
        
        console.log('Ticket Dashboard:');
        console.log(`Total Tickets: ${dashboard.summary.total}`);
        console.log(`Open: ${dashboard.summary.open}`);
        console.log(`In Progress: ${dashboard.summary.inProgress}`);
        console.log(`Closed: ${dashboard.summary.closed}`);
        console.log(`High Priority: ${dashboard.summary.highPriority}`);
        console.log(`Urgent: ${dashboard.summary.urgent}`);
        
        return dashboard;
    } catch (error) {
        console.error('Dashboard error:', error);
        throw error;
    }
}

Ticket Analytics

async function analyzeTickets(client, dateRange) {
    try {
        const allTickets = await getTickets(client);
        
        // Filter by date range
        const filteredTickets = allTickets.filter(ticket => {
            const ticketDate = new Date(ticket.createdAt);
            return ticketDate >= dateRange.start && ticketDate <= dateRange.end;
        });
        
        // Analyze by category
        const categoryAnalysis = filteredTickets.reduce((acc, ticket) => {
            const category = ticket.category || 'UNCATEGORIZED';
            if (!acc[category]) {
                acc[category] = { count: 0, tickets: [] };
            }
            acc[category].count++;
            acc[category].tickets.push(ticket);
            return acc;
        }, {});
        
        // Analyze by priority
        const priorityAnalysis = filteredTickets.reduce((acc, ticket) => {
            const priority = ticket.priority || 'UNKNOWN';
            if (!acc[priority]) {
                acc[priority] = { count: 0, tickets: [] };
            }
            acc[priority].count++;
            acc[priority].tickets.push(ticket);
            return acc;
        }, {});
        
        // Calculate resolution time for closed tickets
        const closedTickets = filteredTickets.filter(t => t.status === 'CLOSED' && t.resolvedAt);
        const resolutionTimes = closedTickets.map(ticket => {
            const created = new Date(ticket.createdAt);
            const resolved = new Date(ticket.resolvedAt);
            return resolved.getTime() - created.getTime();
        });
        
        const avgResolutionTime = resolutionTimes.length > 0 
            ? resolutionTimes.reduce((sum, time) => sum + time, 0) / resolutionTimes.length
            : 0;
        
        const analysis = {
            totalTickets: filteredTickets.length,
            categoryBreakdown: categoryAnalysis,
            priorityBreakdown: priorityAnalysis,
            resolutionStats: {
                closedTickets: closedTickets.length,
                averageResolutionTimeMs: avgResolutionTime,
                averageResolutionTimeHours: avgResolutionTime / (1000 * 60 * 60)
            }
        };
        
        console.log('Ticket Analysis:');
        console.log(`Total Tickets: ${analysis.totalTickets}`);
        console.log('Category Breakdown:', analysis.categoryBreakdown);
        console.log('Priority Breakdown:', analysis.priorityBreakdown);
        console.log('Resolution Stats:', analysis.resolutionStats);
        
        return analysis;
    } catch (error) {
        console.error('Ticket analysis error:', error);
        throw error;
    }
}

Automated Ticket Creation

async function createVehicleIssueTicket(client, vehicleId, issueType, description, userId) {
    try {
        const ticketCategories = {
            'NOT_STARTING': 'TECHNICAL',
            'UNLOCK_ISSUE': 'TECHNICAL',
            'BATTERY_LOW': 'TECHNICAL',
            'DAMAGE': 'VEHICLE',
            'CLEANLINESS': 'GENERAL'
        };
        
        const ticketPriorities = {
            'NOT_STARTING': 'HIGH',
            'UNLOCK_ISSUE': 'HIGH',
            'BATTERY_LOW': 'MEDIUM',
            'DAMAGE': 'MEDIUM',
            'CLEANLINESS': 'LOW'
        };
        
        const category = ticketCategories[issueType] || 'TECHNICAL';
        const priority = ticketPriorities[issueType] || 'MEDIUM';
        
        const ticket = await createTicket(client, {
            title: `Vehicle ${issueType}: ${vehicleId}`,
            description: `Vehicle ID: ${vehicleId}\nIssue Type: ${issueType}\nDescription: ${description}`,
            priority: priority,
            category: category,
            entityId: userId,
            relatedEntityType: 'VEHICLE',
            relatedEntityId: vehicleId
        });
        
        console.log(`Created ${priority} priority ticket for vehicle ${vehicleId}:`, ticket.id);
        return ticket;
    } catch (error) {
        console.error('Automated ticket creation error:', error);
        throw error;
    }
}