TypeScript SDK

The official TypeScript SDK provides a type-safe, easy-to-use client for the MLM Platform API.

Installation

npm install @mlm-platform/sdk

yarn add @mlm-platform/sdk

pnpm add @mlm-platform/sdk

Quick Start

import { MLMPlatformClient } from '@mlm-platform/sdk';

const client = new MLMPlatformClient({
  apiKey: 'mlm_live_your_api_key_here'
});

// Create a user
const user = await client.createUser({
  email: 'user@example.com',
  membershipTier: 'ORDINARY'
});

// Record a purchase
const result = await client.recordPurchase({
  userId: user.id,
  amount: 99.99
});

Configuration

const client = new MLMPlatformClient({
  apiKey: 'mlm_live_your_api_key_here',
  baseUrl: 'https://app.mlm-platform.com',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000
});

Option	Type	Default	Description
`apiKey`	`string`	Required	Your tenant API key
`baseUrl`	`string`	Production URL	API base URL
`timeout`	`number`	`30000`	Request timeout (ms)
`retries`	`number`	`3`	Retry attempts for failed requests
`retryDelay`	`number`	`1000`	Initial retry delay (ms)

Methods

Users

createUser

Create a new member in the hierarchy.

const user = await client.createUser({
  email: 'user@example.com',
  membershipTier: 'ORDINARY',
  parentId: 'sponsor-uuid',
  referralCode: 'ABC123'
});

Parameters:

email (required): User’s email address
membershipTier: 'ORDINARY' | 'SENIOR' | 'MANAGER' | 'DIRECTOR'
parentId: Sponsor’s user ID
referralCode: Referral code for attribution
isActive: Whether user is active (default: true)
canRecruit: Whether user can recruit (default: true)
metadata: Custom metadata object

getUserStatus

Get user status and commission balance.

const status = await client.getUserStatus('user-uuid');

console.log(status.commissionBalance);
// { pending: 100, cleared: 500, paid: 1000, total: 1600 }

Purchases

recordPurchase

Record a purchase event and trigger commission calculation.

const result = await client.recordPurchase({
  userId: 'buyer-uuid',
  amount: 99.99,
  currency: 'USD',
  idempotencyKey: 'order_123'
});

console.log(result.commissionsCreated); // 3
console.log(result.commissionDetails);
// [{ beneficiaryId: '...', level: 1, rate: 0.1, amount: 9.99 }]

Leads

captureLead

Capture a lead with optional referral attribution.

const lead = await client.captureLead({
  email: 'lead@example.com',
  name: 'John Doe',
  referralCode: 'ABC123',
  source: 'landing_page'
});

Referrals

getReferralLink

Get a user’s referral link and code.

const referral = await client.getReferralLink('user-uuid');

console.log(referral.referralCode);  // 'ABC123'
console.log(referral.referralUrl);   // 'https://...'

Widgets

createWidgetSession

Create a widget access token for embedding.

const session = await client.createWidgetSession({
  userId: 'user-uuid'
});

// Use token in iframe src
const src = `https://widget.mlm-platform.example.com/referral?token=${session.token}`;

Error Handling

The SDK provides typed error classes:

import {
  MLMPlatformError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
  ConflictError,
  ForbiddenError
} from '@mlm-platform/sdk';

try {
  await client.createUser({ email: 'invalid' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.details);
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof MLMPlatformError) {
    console.log(`Error: ${error.code} - ${error.message}`);
  }
}

Error Class	Status Code	When Thrown
`AuthenticationError`	401	Invalid or missing API key
`ForbiddenError`	403	Action not allowed
`NotFoundError`	404	Resource not found
`ValidationError`	400	Invalid request data
`ConflictError`	409	Resource already exists
`RateLimitError`	429	Rate limit exceeded

TypeScript Types

All types are exported for use in your application:

import type {
  User,
  Lead,
  Commission,
  CreateUserRequest,
  RecordPurchaseRequest,
  PurchaseEventResponse,
  MembershipTier,
  CommissionStatus
} from '@mlm-platform/sdk';

function processUser(user: User) {
  // Fully typed
}

Request Cancellation

Cancel requests using AbortController:

const controller = new AbortController();

setTimeout(() => controller.abort(), 5000);

try {
  const user = await client.createUser(
    { email: 'user@example.com' },
    { signal: controller.signal }
  );
} catch (error) {
  if (error.message === 'Request timeout') {
    console.log('Request was cancelled');
  }
}

Environment Variables

Store API keys securely:

# .env
MLM_LIVE_API_KEY=mlm_live_abc123...
MLM_SANDBOX_API_KEY=mlm_sandbox_xyz789...

const client = new MLMPlatformClient({
  apiKey: process.env.NODE_ENV === 'production'
    ? process.env.MLM_LIVE_API_KEY!
    : process.env.MLM_SANDBOX_API_KEY!
});

Get Started

Guides

SDKs

TypeScript SDK

TypeScript SDK

Installation

Quick Start

Configuration

Methods

Users

Purchases

Leads

Referrals

Widgets

Error Handling

TypeScript Types

Request Cancellation

Environment Variables

​TypeScript SDK

​Installation

​Quick Start

​Configuration

​Methods

​Users

​Purchases

​Leads

​Referrals

​Widgets

​Error Handling

​TypeScript Types

​Request Cancellation

​Environment Variables

TypeScript SDK

Installation

Quick Start

Configuration

Methods

Users

Purchases

Leads

Referrals

Widgets

Error Handling

TypeScript Types

Request Cancellation

Environment Variables