@vulog/aima-mobility-plans 1.2.45 → 1.2.46

package/README.md

@@ -1,248 +1,121 @@
 # @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.
+Mobility plan subscriptions — list plans, subscribe, and unsubscribe.
 
 ## Installation
 
-```bash
-npm install @vulog/aima-client @vulog/aima-core @vulog/aima-mobility-plans
+```sh
+npm install @vulog/aima-mobility-plans @vulog/aima-client @vulog/aima-core
 ```
 
 ## Usage
 
-### Initialize Client
-
-```javascript
+```ts
 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',
-});
+const client = getClient({ /* client options */ });
+
+const plans = await getPlans(client, 'ACTIVE');
+const userPlans = await getUserPlans(client, 'profile-uuid');
+const result = await subscribe(client, 'plan-uuid', 'profile-uuid');
 ```
 
 ## API Reference
 
 ### getPlans
 
-Retrieve all available mobility plans.
-
-```javascript
-const plans = await getPlans(client);
+```ts
+getPlans(client: Client, status: Status): Promise<Plan[]>
 ```
 
-**Parameters:**
-- `client`: AIMA client instance
+Returns all mobility plans matching the given status. `status` is required.
 
-**Returns:** Array of available mobility plans
+**Params:** `client` — Authenticated AIMA client; `status` — `'ACTIVE'` or `'INACTIVE'`  
+**Returns:** `Promise<Plan[]>`
 
-### getUserPlans
+---
 
-Get mobility plans for a specific user.
+### getUserPlans
 
-```javascript
-const userPlans = await getUserPlans(client, 'user-uuid-here');
+```ts
+getUserPlans(client: Client, entityId: string): Promise<Subscription[]>
 ```
 
-**Parameters:**
-- `client`: AIMA client instance
-- `entityId`: User UUID
+Returns subscriptions for a user profile. `entityId` must be a UUID. Only returns subscriptions with status `ACTIVE`, `PAYMENT_PENDING`, or `ACTIVATION_PENDING`.
 
-**Returns:** Array of user's mobility plans
+**Params:** `client` — Authenticated AIMA client; `entityId` — profile UUID  
+**Returns:** `Promise<Subscription[]>`
 
-### subscribe
+---
 
-Subscribe a user to a mobility plan.
+### subscribe
 
-```javascript
-const subscription = await subscribe(client, {
-    entityId: 'user-uuid-here',
-    planId: 'plan-id-here',
-    startDate: '2024-01-01T00:00:00Z'
-});
+```ts
+subscribe(client: Client, planId: string, profileId: string): Promise<SubscribeResponse>
 ```
 
-**Parameters:**
-- `client`: AIMA client instance
-- `payload`: Subscription configuration object
-  - `entityId`: User UUID
-  - `planId`: Plan identifier
-  - `startDate`: Subscription start date (optional, defaults to current date)
+Subscribes a profile to a plan. Both `planId` and `profileId` must be UUIDs.
 
-### unsubscribe
+**Params:** `client` — Authenticated AIMA client; `planId` — plan UUID; `profileId` — profile UUID  
+**Returns:** `Promise<SubscribeResponse>`
+
+---
 
-Unsubscribe a user from a mobility plan.
+### unsubscribe
 
-```javascript
-const result = await unsubscribe(client, {
-    entityId: 'user-uuid-here',
-    planId: 'plan-id-here',
-    endDate: '2024-12-31T23:59:59Z'
-});
+```ts
+unsubscribe(client: Client, subscriptionId: string, profileId: string): Promise<UnsubscribeResponse>
 ```
 
-**Parameters:**
-- `client`: AIMA client instance
-- `payload`: Unsubscription configuration object
-  - `entityId`: User UUID
-  - `planId`: Plan identifier
-  - `endDate`: Unsubscription end date (optional, defaults to current date)
+Cancels a subscription. The first argument is `subscriptionId` (not `planId`). Both must be UUIDs.
+
+**Params:** `client` — Authenticated AIMA client; `subscriptionId` — subscription UUID; `profileId` — profile UUID  
+**Returns:** `Promise<UnsubscribeResponse>`
 
 ## Types
 
+### Status
+
+```ts
+type Status = 'ACTIVE' | 'INACTIVE';
+```
+
 ### Plan
 
-```typescript
+```ts
 interface Plan {
     id: string;
     name: string;
-    description: string;
+    fleetId: string;
+    period: 'WEEK' | 'MONTH' | 'YEAR';
+    productId: string;
+    systemCreditIncluded: number;
     price: number;
-    currency: string;
-    duration: number; // in days
-    features: string[];
-    isActive: boolean;
-    createdAt: string;
-    updatedAt: string;
+    cities: { cityId: string; serviceIds: string[] }[];
+    status: Status;
+    periodicTimeWallet: {
+        freeMinutes: number;
+        freeMinutesFrequency: 'DAILY' | 'WEEKLY' | 'MONTHLY';
+    };
+    services: string[];
 }
 ```
 
 ### Subscription
 
-```typescript
-interface Subscription {
-    id: string;
-    entityId: string;
-    planId: string;
-    status: 'ACTIVE' | 'INACTIVE' | 'EXPIRED' | 'CANCELLED';
-    startDate: string;
-    endDate: string;
-    autoRenew: boolean;
-    createdAt: string;
-    updatedAt: string;
-}
-```
+A tuple type where each entry contains:
 
-### Status
-
-```typescript
-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
-
-```javascript
-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
-
-```javascript
-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;
-    }
+```ts
+{
+    id: string;
+    profileId: string;
+    plan: Plan;
+    fleetId: string;
+    expiryDate: string;
+    unsubscribeDate: string;
+    activationDate: string;
+    invoiceIds: string[];
+    status: 'ACTIVE' | 'PAYMENT_PENDING' | 'ACTIVATION_PENDING';
 }
 ```
-
-### User Plan Status Check
-
-```javascript
-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;
-    }
-}
-```

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vulog/aima-mobility-plans",
     "type": "module",
-    "version": "1.2.45",
+    "version": "1.2.46",
     "main": "dist/index.cjs",
     "module": "dist/index.mjs",
     "types": "dist/index.d.cts",
@@ -33,8 +33,8 @@
     "author": "Vulog",
     "license": "MIT",
     "dependencies": {
-        "@vulog/aima-client": "1.2.45",
-        "@vulog/aima-core": "1.2.45"
+        "@vulog/aima-client": "1.2.46",
+        "@vulog/aima-core": "1.2.46"
     },
     "peerDependencies": {
         "zod": "^4.3.6"