Node SDK

The Node SDK provides a comprehensive TypeScript library for easily integrating with the Mambo API. This client library simplifies development by handling authentication, request formatting, and response parsing, allowing you to focus on your application logic. Built with TypeScript and zero production dependencies, the SDK works seamlessly across Node.js, Bun, Deno, browsers, and edge runtimes.

To connect to the Mambo API, use one of the service classes provided through the client instance. See the code samples below for implementation examples.

Installation

Requirements

• Node.js: 14.0.0 or later
• Supported runtimes: Node.js, Bun, Deno, Edge runtimes (Cloudflare Workers, Vercel Edge)
• Browser support: Modern browsers with Fetch API support

Dependencies

The Mambo Node SDK has zero production dependencies, making it lightweight and easy to integrate into any project. All required functionality is built directly into the SDK.

Manual Installation

The SDK is distributed as a single package containing CommonJS modules, ES Modules, and TypeScript type definitions.

Installation Steps:

1. Download the SDK package
2. Extract the archive to your project's node_modules/ directory

Downloads

Download the Mambo Node SDK:

Version:Latest (8.12.1)8.11.128.10.28.9.08.8.08.7.28.6.58.5.08.4.28.3.18.2.18.1.38.0.47.7.17.6.17.5.07.4.57.3.37.2.17.1.17.0.36.3.66.2.46.1.26.0.1

• Download Node SDK

Documentation

Module Systems

The SDK supports both CommonJS and ES Modules. Choose the appropriate syntax for your project:

TypeScript

ES Modules

CommonJS

import { MamboClient } from '@mambo/sdk';

const client = new MamboClient('public_key', 'private_key');

import { MamboClient } from '@mambo/sdk';

const client = new MamboClient('public_key', 'private_key');

const { MamboClient } = require('@mambo/sdk');

const client = new MamboClient('public_key', 'private_key');

Client Initialisation

To initialise the SDK, you'll need to set your credentials and, if using an on-premise installation, the API endpoint URL.

Node.js initialization with OAuth credentials:

TypeScript

JavaScript

import { MamboClient } from '@mambo/sdk';

// Basic initialisation with client credentials
const client = new MamboClient('public_key', 'private_key');

// Advanced configuration with all options
const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  baseUrl: 'https://api.mambo.io',
  tokenUrl: 'https://api.mambo.io/oauth/token',
  timeout: 60000,
  language: 'en',
  enableLogging: true,
  maxRetries: 2,
  retryDelay: 1000,
  defaultHeaders: {
    'X-Custom-Header': 'value'
  }
});

await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

const { MamboClient } = require('@mambo/sdk');

// Basic initialisation with client credentials
const client = new MamboClient('public_key', 'private_key');

// Advanced configuration with all options
const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  baseUrl: 'https://api.mambo.io',
  tokenUrl: 'https://api.mambo.io/oauth/token',
  timeout: 60000,
  language: 'en',
  enableLogging: true,
  maxRetries: 2,
  retryDelay: 1000,
  defaultHeaders: {
    'X-Custom-Header': 'value'
  }
});

await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

Browser initialization (no credentials):

TypeScript

JavaScript

import { MamboClient } from '@mambo/sdk';

// Browser usage - authentication handled by backend/cookies
const client = new MamboClient({
  baseUrl: 'https://api.mambo.io'
});

await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

import { MamboClient } from '@mambo/sdk';

// Browser usage - authentication handled by backend/cookies
const client = new MamboClient({
  baseUrl: 'https://api.mambo.io'
});

await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

warning

Never include OAuth credentials in browser code. Browser applications should use a backend proxy for authentication or rely on session cookies. See the Browser vs Node.js section for details.

Runtime-Specific Usage

The SDK automatically detects and adapts to different JavaScript runtimes:

Bun

Deno

Cloudflare

Vercel

import { MamboClient } from './mambo-sdk-node/esm';

const client = new MamboClient('public_key', 'private_key');

// Bun automatically uses the Fetch API
await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

import { MamboClient } from './mambo-sdk-node/esm/index.js';

const client = new MamboClient('public_key', 'private_key');

// Deno automatically uses the Fetch API
await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

import { MamboClient } from '@mambo/sdk';

export default {
  async fetch(request: Request): Promise<Response> {
    const client = new MamboClient('public_key', 'private_key');
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' }, 
      data
    );

    return new Response(JSON.stringify(result));
  }
};

import { MamboClient } from '@mambo/sdk';
import { NextRequest, NextResponse } from 'next/server';

export const config = {
  runtime: 'edge'
};

export default async function handler(req: NextRequest) {
  const client = new MamboClient('public_key', 'private_key');

  const result = await client.activities.createAsync(
    { siteUrl: 'acmeinc' }, 
    data
  );

  return NextResponse.json(result);
}

Path and Query Parameters

Use parameter objects to provide path and query parameters to endpoint methods. TypeScript provides full type safety and autocomplete for all parameters.

TypeScript

JavaScript

const params = {
  siteUrl: 'acmeinc',
  uuid: 'user_uuid',
  pageSize: 10,
  page: 1
};

const wallets = await client.users.points.getPointWallets(params);

const params = {
  siteUrl: 'acmeinc',
  uuid: 'user_uuid',
  pageSize: 10,
  page: 1
};

const wallets = await client.users.points.getPointWallets(params);

Request Options

Use the request options object to provide configuration on a per-request basis. This object can be used to provide idempotency keys, custom headers, or request-specific timeouts.

TypeScript

JavaScript

import { v4 as uuidv4 } from 'uuid';

const requestOptions = {
  idempotencyKey: uuidv4(),
  language: 'en',
  timeout: 45000,
  headers: {
    'X-Request-ID': 'custom-id'
  }
};

const result = await client.activities.createAsync(
  { siteUrl: 'acmeinc' },
  data,
  requestOptions
);

const { v4: uuidv4 } = require('uuid');

const requestOptions = {
  idempotencyKey: uuidv4(),
  language: 'en',
  timeout: 45000,
  headers: {
    'X-Request-ID': 'custom-id'
  }
};

const result = await client.activities.createAsync(
  { siteUrl: 'acmeinc' },
  data,
  requestOptions
);

Working with Promises

The SDK uses async/await and native JavaScript Promises. All API methods return Promises that can be used with async/await or chained.

Async/await pattern:

TypeScript

JavaScript

async function createActivity() {
  try {
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' },
      data
    );
    console.log('Activity created:', result.id);
  } catch (error) {
    console.error('Error creating activity:', error);
  }
}

async function createActivity() {
  try {
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' },
      data
    );
    console.log('Activity created:', result.id);
  } catch (error) {
    console.error('Error creating activity:', error);
  }
}

Promise chaining:

TypeScript

JavaScript

client.activities
  .createAsync({ siteUrl: 'acmeinc' }, data)
  .then(result => {
    console.log('Activity created:', result.id);
    return client.activities.get({ activityId: result.id });
  })
  .then(activity => {
    console.log('Activity details:', activity);
  })
  .catch(error => {
    console.error('Error:', error);
  });

client.activities
  .createAsync({ siteUrl: 'acmeinc' }, data)
  .then(result => {
    console.log('Activity created:', result.id);
    return client.activities.get({ activityId: result.id });
  })
  .then(activity => {
    console.log('Activity details:', activity);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Multiple async operations:

TypeScript

JavaScript

async function performMultipleOperations() {
  try {
    // Sequential operations
    const user = await client.users.get({ siteUrl: 'acmeinc', uuid: 'user_uuid' });
    const wallets = await client.users.points.getPointWallets({
      siteUrl: 'acmeinc',
      uuid: user.uuid
    });
  
    // Parallel operations
    const [rewards, achievements] = await Promise.all([
      client.users.rewards.getRewards({ siteUrl: 'acmeinc', uuid: user.uuid }),
      client.users.rewards.getAchievements({ siteUrl: 'acmeinc', uuid: user.uuid })
    ]);
  
    return { user, wallets, rewards, achievements };
  } catch (error) {
    console.error('Operation failed:', error);
    throw error;
  }
}

async function performMultipleOperations() {
  try {
    // Sequential operations
    const user = await client.users.get({ siteUrl: 'acmeinc', uuid: 'user_uuid' });
    const wallets = await client.users.points.getPointWallets({
      siteUrl: 'acmeinc',
      uuid: user.uuid
    });
  
    // Parallel operations
    const [rewards, achievements] = await Promise.all([
      client.users.rewards.getRewards({ siteUrl: 'acmeinc', uuid: user.uuid }),
      client.users.rewards.getAchievements({ siteUrl: 'acmeinc', uuid: user.uuid })
    ]);
  
    return { user, wallets, rewards, achievements };
  } catch (error) {
    console.error('Operation failed:', error);
    throw error;
  }
}

TypeScript Support

The Mambo Node SDK is built with TypeScript and includes comprehensive type definitions. No additional @types packages are needed.

Type inference:

TypeScript

import { MamboClient, BehaviourDto, UserDto } from '@mambo/sdk';

const client = new MamboClient('public_key', 'private_key');

// TypeScript automatically infers the return type
const behaviour: BehaviourDto = await client.behaviours.get({
  behaviourId: 'behaviour_id'
});

// Full autocomplete and type checking
const user: UserDto = await client.users.get({
  siteUrl: 'acmeinc',
  uuid: 'user_uuid'
});

// Type-safe parameter objects
const params = {
  siteUrl: 'acmeinc',
  uuid: user.uuid,
  pageSize: 10
};

const wallets = await client.users.points.getPointWallets(params);

Custom interfaces with SDK types:

TypeScript

import { ActivityRequestData, UserDto, RewardDto } from '@mambo/sdk';

interface UserProgress {
  user: UserDto;
  totalPoints: number;
  earnedRewards: RewardDto[];
}

async function getUserProgress(uuid: string): Promise<UserProgress> {
  const user = await client.users.get({ siteUrl: 'acmeinc', uuid });
  const wallets = await client.users.points.getPointWallets({
    siteUrl: 'acmeinc',
    uuid
  });
  const rewards = await client.users.rewards.getRewards({
    siteUrl: 'acmeinc',
    uuid
  });

  const totalPoints = wallets.items.reduce((sum, wallet) => sum + wallet.balance, 0);

  return {
    user,
    totalPoints,
    earnedRewards: rewards
  };
}

Getting Started

Here's a complete example showing how to initialise the client and make a basic API call:

TypeScript

ES Modules

CommonJS

import { MamboClient, ActivityRequestData } from '@mambo/sdk';

async function quickStart() {
  // Create client with your API credentials
  const client = new MamboClient('your_public_key', 'your_private_key');

  // Prepare activity data
  const data: ActivityRequestData = {
    uuid: 'user_uuid',
    verb: 'purchase',
    metadata: {
      productId: 'prod_123',
      amount: '99.99'
    }
  };

  try {
    // Call API and handle response
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' },
      data
    );
    console.log('Activity created with ID:', result.id);
  
    // Get activity details
    const activity = await client.activities.get({ 
      activityId: result.id 
    });
    console.log('Activity details:', activity);
  } catch (error) {
    console.error('Error creating activity:', error);
  }
}

quickStart();

import { MamboClient } from '@mambo/sdk';

async function quickStart() {
  // Create client with your API credentials
  const client = new MamboClient('your_public_key', 'your_private_key');

  // Prepare activity data
  const data = {
    uuid: 'user_uuid',
    verb: 'purchase',
    metadata: {
      productId: 'prod_123',
      amount: '99.99'
    }
  };

  try {
    // Call API and handle response
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' },
      data
    );
    console.log('Activity created with ID:', result.id);
  
    // Get activity details
    const activity = await client.activities.get({ 
      activityId: result.id 
    });
    console.log('Activity details:', activity);
  } catch (error) {
    console.error('Error creating activity:', error);
  }
}

quickStart();

const { MamboClient } = require('@mambo/sdk');

async function quickStart() {
  // Create client with your API credentials
  const client = new MamboClient('your_public_key', 'your_private_key');

  // Prepare activity data
  const data = {
    uuid: 'user_uuid',
    verb: 'purchase',
    metadata: {
      productId: 'prod_123',
      amount: '99.99'
    }
  };

  try {
    // Call API and handle response
    const result = await client.activities.createAsync(
      { siteUrl: 'acmeinc' },
      data
    );
    console.log('Activity created with ID:', result.id);
  
    // Get activity details
    const activity = await client.activities.get({ 
      activityId: result.id 
    });
    console.log('Activity details:', activity);
  } catch (error) {
    console.error('Error creating activity:', error);
  }
}

quickStart();

Browser vs Node.js

The SDK adapts automatically to different environments, but there are important differences in authentication and HTTP client usage.

Authentication Differences

Node.js (OAuth with credentials):

In server-side Node.js applications, you provide OAuth credentials directly to the SDK. The SDK handles token management automatically.

Node

import { MamboClient } from '@mambo/sdk';

// Server-side: OAuth credentials are safe
const client = new MamboClient('public_key', 'private_key');

await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

Browser (No credentials):

Browser applications must never include OAuth credentials in client-side code. Instead, use one of these patterns:

1. Backend Proxy: Route API calls through your backend server
2. Session Cookies: Let your backend set session cookies that authenticate requests

For a ready-to-run backend proxy that holds the keys and forwards requests, see the Backend proxy guide.

Browser (Backend Proxy)

Browser (Custom Authenticator)

import { MamboClient } from '@mambo/sdk';

// Browser: No credentials - authentication via backend/cookies
const client = new MamboClient({
  baseUrl: 'https://your-backend.com/api/mambo'
});

// Requests go through your backend proxy
await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

import { MamboClient, NoAuthAuthenticator } from '@mambo/sdk';

// Explicitly use NoAuthAuthenticator
const client = new MamboClient({
  baseUrl: 'https://api.mambo.io',
  authenticator: new NoAuthAuthenticator()
});

// Your backend must set authentication cookies
await client.activities.createAsync({ siteUrl: 'acmeinc' }, data);

Security Warning

Never expose OAuth credentials in browser code. Anyone with access to your client-side JavaScript can extract and misuse your credentials. Always use a backend proxy or session-based authentication for browser applications.

HTTP Client Differences

The SDK automatically selects the appropriate HTTP client:

• Node.js: Uses NodeHttpClient with native http/https modules
• Browser/Deno/Bun/Edge: Uses FetchHttpClient with the Fetch API

You can also provide a custom HTTP client:

TypeScript

import { MamboClient, FetchHttpClient } from '@mambo/sdk';

// Force use of Fetch client in Node.js (if needed)
const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  httpClient: new FetchHttpClient()
});

When to Use Each Environment

Use Node.js when:

• Building server-side APIs or backend services
• You need OAuth authentication with full credentials
• Working with sensitive data that shouldn't be exposed to browsers
• Building CLI tools or automation scripts

Use Browser when:

• Building client-side web applications
• User authentication is handled by your backend
• You have a backend proxy for API requests
• You're using session cookies for authentication

---

Troubleshooting

Common issues

Error handling

Every failure raised by the SDK rejects the promise returned by the service method, so errors are caught with a standard try/catch around await. The SDK exports the error classes below, all of which extend MamboError:

Error	Raised when
MamboApiError	The API returned an error response. Extends MamboError.
AuthenticationError	The request was rejected with a 401 or 403. Extends MamboApiError.
IdempotencyError	The idempotency key was invalid, already used, or its request is still in progress. Extends MamboApiError.
OAuthError	The OAuth token could not be obtained. Extends MamboError.
ApiConnectionError	The API could not be reached. Extends MamboError.
TimeoutError	The request did not complete within the configured timeout. Extends MamboError.
ConfigurationError	The client configuration is invalid. Thrown by the MamboClient constructor.

Because JavaScript has a single catch block, you discriminate between them with instanceof, ordering the checks from most to least specific:

Node

import { AuthenticationError, MamboApiError, MamboError } from '@mambo/sdk';

try {
  const wallets = await client.users.points.getPointWallets({
    siteUrl: 'acmeinc',
    uuid: 'user_uuid'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Check your API keys');
  } else if (error instanceof MamboApiError) {
    console.error(error.getDetailedMessage(), error.status, error.requestId);
  } else if (error instanceof MamboError) {
    console.error(error.toJSON());
  } else {
    throw error;
  }
}

You do not need to handle expired access tokens. When the API rejects a token, the SDK obtains a new one and replays the request transparently.

See Errors for the full list of error types returned by the API.

Connection timeouts

If you experience connection timeouts, you can increase the timeout when initialising the client. The Node SDK applies a single timeout to the whole request, expressed in milliseconds, which defaults to 30 seconds and cannot exceed 5 minutes:

Node

const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  timeout: 60000 // 1 minute
});

Retries

The SDK does not retry failed requests by default. Set maxRetries to retry connection failures, timeouts, and the responses that are safe to replay (408, 409, 429 and 5xx):

Node

const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  maxRetries: 3 // retried with an exponential backoff
});

Logging

Enable debug logging to troubleshoot issues:

Node

const client = new MamboClient({
  clientId: 'public_key',
  clientSecret: 'private_key',
  enableLogging: true
});

---

Related Topics

• Activities
• API keys