@vulog/aima-mobility-plans

Mobility plans and subscription management module for the AIMA platform. This module provides functionality to manage mobility plans, user subscriptions, and plan-related operations.

Installation

npm install @vulog/aima-client @vulog/aima-core @vulog/aima-mobility-plans

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { getPlans, getUserPlans, subscribe, unsubscribe } from '@vulog/aima-mobility-plans';

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

getPlans

Retrieve all available mobility plans.

const plans = await getPlans(client);

Parameters:

• client: AIMA client instance

Returns: Array of available mobility plans

getUserPlans

Get mobility plans for a specific user.

const userPlans = await getUserPlans(client, 'user-uuid-here');

Parameters:

• client: AIMA client instance
• entityId: User UUID

Returns: Array of user's mobility plans

subscribe

Subscribe a user to a mobility plan.

const subscription = await subscribe(client, {
    entityId: 'user-uuid-here',
    planId: 'plan-id-here',
    startDate: '2024-01-01T00:00:00Z'
});

Parameters:

• client: AIMA client instance
• payload: Subscription configuration object
  • entityId: User UUID
  • planId: Plan identifier
  • startDate: Subscription start date (optional, defaults to current date)

unsubscribe

Unsubscribe a user from a mobility plan.

const result = await unsubscribe(client, {
    entityId: 'user-uuid-here',
    planId: 'plan-id-here',
    endDate: '2024-12-31T23:59:59Z'
});

Parameters:

• client: AIMA client instance
• payload: Unsubscription configuration object
  • entityId: User UUID
  • planId: Plan identifier
  • endDate: Unsubscription end date (optional, defaults to current date)

Types

Plan

interface Plan {
    id: string;
    name: string;
    description: string;
    price: number;
    currency: string;
    duration: number; // in days
    features: string[];
    isActive: boolean;
    createdAt: string;
    updatedAt: string;
}

Subscription

interface Subscription {
    id: string;
    entityId: string;
    planId: string;
    status: 'ACTIVE' | 'INACTIVE' | 'EXPIRED' | 'CANCELLED';
    startDate: string;
    endDate: string;
    autoRenew: boolean;
    createdAt: string;
    updatedAt: string;
}

Status

type Status = 'ACTIVE' | 'INACTIVE' | 'EXPIRED' | 'CANCELLED';

Error Handling

All functions include validation and will throw appropriate errors if:

• Required parameters are missing
• Invalid plan or user IDs are provided
• Subscription conflicts occur
• Network errors occur

Examples

Complete Mobility Plan Management

import { getClient } from '@vulog/aima-client';
import { getPlans, getUserPlans, subscribe, unsubscribe } from '@vulog/aima-mobility-plans';

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 mobilityPlanWorkflow() {
    try {
        // Get all available plans
        const plans = await getPlans(client);
        console.log('Available plans:', plans);
        
        // Get user's current plans
        const userPlans = await getUserPlans(client, 'user-uuid-here');
        console.log('User plans:', userPlans);
        
        // Subscribe user to a plan
        const subscription = await subscribe(client, {
            entityId: 'user-uuid-here',
            planId: 'premium-plan-id',
            startDate: '2024-01-01T00:00:00Z'
        });
        console.log('User subscribed:', subscription);
        
        // Later, unsubscribe user from plan
        const unsubscription = await unsubscribe(client, {
            entityId: 'user-uuid-here',
            planId: 'premium-plan-id',
            endDate: '2024-12-31T23:59:59Z'
        });
        console.log('User unsubscribed:', unsubscription);
        
    } catch (error) {
        console.error('Mobility plan error:', error);
    }
}

Plan Comparison Helper

async function comparePlans(client) {
    try {
        const plans = await getPlans(client);
        
        // Sort plans by price
        const sortedPlans = plans.sort((a, b) => a.price - b.price);
        
        console.log('Plans sorted by price:');
        sortedPlans.forEach(plan => {
            console.log(`${plan.name}: ${plan.price} ${plan.currency} (${plan.duration} days)`);
            console.log(`Features: ${plan.features.join(', ')}`);
            console.log('---');
        });
        
        return sortedPlans;
    } catch (error) {
        console.error('Plan comparison error:', error);
        throw error;
    }
}

User Plan Status Check

async function checkUserPlanStatus(client, entityId) {
    try {
        const userPlans = await getUserPlans(client, entityId);
        
        const activePlans = userPlans.filter(plan => plan.status === 'ACTIVE');
        const expiredPlans = userPlans.filter(plan => plan.status === 'EXPIRED');
        
        console.log(`User ${entityId} has:`);
        console.log(`- ${activePlans.length} active plans`);
        console.log(`- ${expiredPlans.length} expired plans`);
        
        if (activePlans.length > 0) {
            console.log('Active plans:');
            activePlans.forEach(plan => {
                console.log(`  - ${plan.planId} (until ${plan.endDate})`);
            });
        }
        
        return {
            activePlans,
            expiredPlans,
            totalPlans: userPlans.length
        };
    } catch (error) {
        console.error('Plan status check error:', error);
        throw error;
    }
}