@moanakyc/node-sdk

Typed Node.js client for the MoanaKYC API. Provides a clean interface for creating applicants, verification sessions, and verifying webhook signatures.

Requirements

• Node.js >= 20 (uses built-in fetch)

Installation

npm install @moanakyc/node-sdk

Quick Start

import { MoanaKYC } from '@moanakyc/node-sdk';

const client = new MoanaKYC({
  apiKey: 'mk_live_...',
  baseUrl: 'https://api.moanakyc.to', // optional, this is the default
  webhookSecret: 'whsec_...', // optional, for webhook verification
});

Applicants

// Create an applicant
const applicant = await client.applicants.create({
  firstName: 'Sione',
  lastName: 'Taufa',
  email: '[email protected]',
});

// Get an applicant
const fetched = await client.applicants.get(applicant.id);

// Update an applicant
const updated = await client.applicants.update(applicant.id, {
  phone: '+676-12345',
});

// List applicants (single page)
const page = await client.applicants.listPage({ page: 1, limit: 20 });
console.log(page.data, page.meta);

// Iterate all applicants (automatic pagination)
for await (const a of client.applicants.list()) {
  console.log(a.id, a.firstName);
}

Sessions

// Create a verification session
const session = await client.sessions.create({
  applicantId: applicant.id,
  profileId: 'your-profile-uuid',
});

// session.sdkToken -> pass to frontend Web SDK
// session.decision -> 'approved' | 'declined' | 'review' | null

// Get session status
const result = await client.sessions.get(session.id);

// Iterate all sessions
for await (const s of client.sessions.list({ status: 'completed' })) {
  console.log(s.id, s.decision);
}

Webhook Verification

// Option 1: Secret provided in constructor
const client = new MoanaKYC({
  apiKey: 'mk_live_...',
  webhookSecret: 'whsec_...',
});

const isValid = client.webhooks.verify(rawBody, signatureHeader);

// Option 2: Secret provided per-call
const isValid = client.webhooks.verify(rawBody, signatureHeader, secret);

In an Express handler:

app.post('/webhooks/moanakyc', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-moanakyc-signature'] as string;
  const rawBody = req.body.toString('utf8');

  if (!client.webhooks.verify(rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  // Handle event...

  res.status(200).send('OK');
});

Error Handling

The SDK throws typed errors for API failures:

import {
  MoanaKYCError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  ValidationError,
  ConflictError,
} from '@moanakyc/node-sdk';

try {
  await client.applicants.get('non-existent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Not found:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.log('Bad API key');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  }
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | API key (mk_live_* or mk_test_*) | | baseUrl | string | https://api.moanakyc.to | API base URL | | timeout | number | 30000 | Request timeout in ms | | maxRetries | number | 3 | Max retries on 5xx/429 errors | | webhookSecret | string | — | Webhook secret for signature verification |

Retry Behavior

• Requests that receive 5xx or 429 responses are automatically retried
• Exponential backoff: 1s, 2s, 4s (capped at 10s)
• 4xx errors (except 429) are not retried
• Timeouts are retried