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.7.2)8.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.js

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

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

---

Related Topics

• Activities
• API keys