Skip to main content

Quick Start Guide

This guide walks you through integrating MAES Platform into your Node.js application using the official SDK.

Prerequisites​

  • MAES Platform account with a project created
  • API key (sandbox or production)
  • Node.js >= 18.0.0

Installation​

npm install @nuvoni/maes-sdk
# or
yarn add @nuvoni/maes-sdk
# or
pnpm add @nuvoni/maes-sdk

Basic Setup​

import { MaesClient } from '@nuvoni/maes-sdk';

const client = new MaesClient({
  apiKey: process.env.MAES_API_KEY!, // Your API key
  projectId: process.env.MAES_PROJECT_ID!, // Your project ID
});

// SDK automatically detects environment from API key prefix
console.log(client.environment); // 'sandbox' or 'production'

Common Operations​

List All Cards​

const { docs, total } = await client.cards.list();
console.log(`Found ${total} cards`);

for (const card of docs) {
  console.log(`${card.cardNumber} - ${card.status}`);
}

List with Filters​

// Filter by status
const { docs } = await client.cards.list({ status: 'active' });

// With pagination
const { docs } = await client.cards.list({ page: 2, limit: 20 });

// Search by license plate
const { docs } = await client.cards.list({ licensePlate: 'AB-123' });

Get Card Details​

const card = await client.cards.get('card-id');

console.log(`Card: ${card.cardNumber}`);
console.log(`Status: ${card.status}`);
console.log(`Driver: ${card.driver}`);
console.log(`Gasoline: ${card.authGasoline ? '✅' : '❌'}`);
console.log(`Diesel: ${card.authDiesel ? '✅' : '❌'}`);

Enable a Card​

const card = await client.cards.enable('card-id');
console.log('Card enabled:', card.status); // 'active'

Disable a Card​

const card = await client.cards.disable('card-id');
console.log('Card disabled:', card.status); // 'inactive'

Activate a New Card​

const card = await client.cards.activate('card-id', {
  licensePlate: 'AB-123-CD',
  driver: 'John Doe',
});
console.log('Card activated:', card.status); // 'active'

Error Handling​

The SDK provides typed errors for different scenarios:

import {
  MaesClient,
  MaesNotFoundError,
  MaesAuthenticationError,
  MaesRateLimitError,
  MaesValidationError,
} from '@nuvoni/maes-sdk';

try {
  await client.cards.enable('card-id');
} catch (error) {
  if (error instanceof MaesNotFoundError) {
    console.log('Card not found');
  } else if (error instanceof MaesAuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof MaesRateLimitError) {
    console.log('Rate limited, try again later');
  } else if (error instanceof MaesValidationError) {
    console.log('Invalid request:', error.message);
  }
}

Pagination​

Fetch all cards with pagination:

async function getAllCards() {
  const allCards = [];
  let page = 1;
  const limit = 50;

  while (true) {
    const { docs, total } = await client.cards.list({ page, limit });
    allCards.push(...docs);

    if (allCards.length >= total) break;
    page++;
  }

  return allCards;
}

Environment Variables​

Recommended setup for your application:

# .env
MAES_API_KEY=sk_sandbox_xxxxx
MAES_PROJECT_ID=your-project-id
// Load environment variables
import 'dotenv/config';
import { MaesClient } from '@nuvoni/maes-sdk';

const client = new MaesClient({
  apiKey: process.env.MAES_API_KEY!,
  projectId: process.env.MAES_PROJECT_ID!,
});

Next Steps​