Node.js Client Library

Complete documentation for the GroupVAN Node.js client library.

Installation

Requirements

  • Node.js 16.0 or higher
  • npm or yarn package manager

Install from npm

# Using npm
npm install @groupvan/client

# Using yarn
yarn add @groupvan/client

Quick Example

const { GroupVANClient } = require('@groupvan/client');

// Initialize client
const client = new GroupVANClient({
    developerId: 'DEV123',
    keyId: 'KEY001',
    privateKeyPath: '/path/to/private_key.pem'
});

// Generate JWT token
const token = client.generateToken();

// Make API call
const response = await client.apiCall({
    method: 'GET',
    endpoint: '/api/v3/users',
    token: token
});

console.log(response.data);

Configuration

Using Environment Variables

// Automatically reads from environment
const client = GroupVANClient.fromEnv();
// Looks for:
// - GROUPVAN_DEVELOPER_ID
// - GROUPVAN_KEY_ID
// - GROUPVAN_PRIVATE_KEY_PATH

Using Configuration Object

const client = new GroupVANClient({
    developerId: 'DEV123',
    keyId: 'KEY001',
    privateKeyPath: '/path/to/private_key.pem',
    baseUrl: 'https://api.groupvan.com', // optional
    timeout: 30000 // optional, in milliseconds
});

API Reference

Constructor Options

OptionTypeRequiredDescription
developerIdstringYesYour GroupVAN developer ID
keyIdstringYesYour key identifier
privateKeyPathstringNo*Path to private key file
privateKeystringNo*Private key content
baseUrlstringNoAPI base URL
timeoutnumberNoRequest timeout in ms

Methods

generateToken(options)

Generate a JWT token for API authentication.

const token = client.generateToken({
    expirationMinutes: 5, // optional, default: 5
    additionalClaims: {} // optional
});

apiCall(options)

Make an authenticated API call.

const response = await client.apiCall({
    method: 'GET',
    endpoint: '/api/v3/users',
    token: token, // optional, auto-generated if not provided
    data: {}, // request body for POST/PUT
    params: {}, // query parameters
    headers: {} // additional headers
});

Error Handling

try {
    const token = client.generateToken();
    const response = await client.apiCall({
        method: 'GET',
        endpoint: '/api/v3/users',
        token
    });
} catch (error) {
    if (error.name === 'AuthenticationError') {
        console.error('Authentication failed:', error.message);
    } else if (error.name === 'APIError') {
        console.error('API call failed:', error.message);
        console.error('Status:', error.statusCode);
    }
}

TypeScript Support

The library includes TypeScript definitions:

import { GroupVANClient, ClientOptions, TokenOptions } from '@groupvan/client';

const options: ClientOptions = {
    developerId: 'DEV123',
    keyId: 'KEY001',
    privateKeyPath: '/path/to/private_key.pem'
};

const client = new GroupVANClient(options);

const tokenOptions: TokenOptions = {
    expirationMinutes: 5
};

const token: string = client.generateToken(tokenOptions);

Resources