Skip to main content

​
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

​
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://api.mlm-platform.example.com/functions/v1',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000
});
OptionTypeDefaultDescription
apiKeystringRequiredYour tenant API key
baseUrlstringProduction URLAPI base URL
timeoutnumber30000Request timeout (ms)
retriesnumber3Retry attempts for failed requests
retryDelaynumber1000Initial retry delay (ms)

​
Methods

​
Users

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
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

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

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

​
Widgets

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 ClassStatus CodeWhen Thrown
AuthenticationError401Invalid or missing API key
ForbiddenError403Action not allowed
NotFoundError404Resource not found
ValidationError400Invalid request data
ConflictError409Resource already exists
RateLimitError429Rate 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!
});