SDK Node.js

npm install @labyrinthe/connect

import { Labyrinthe } from '@labyrinthe/connect';

// From the environment: LABYRINTHE_API_KEY, LABYRINTHE_BASE_URL
const client = new Labyrinthe();

// Or explicitly
const configured = new Labyrinthe({
  apiKey: 'lsk_test_xxxxxxxxxxxxxxxx',
  timeoutMs: 30_000,   // per attempt
  maxRetries: 2,       // 0 to 10
  defaultSender: 'MABOUTIQUE',
});

configured.isTestMode; // true with a lsk_test_ key

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

const message = await client.sms.send({
  to: '243812345678',
  body: 'Votre commande 1042 est prête.',
  reference: 'CMD-1042',
  idempotencyKey: 'order-1042-ready', // replaying within 24 h sends nothing again
});

console.log(message.id, message.status); // 'queued'

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

const batch = await client.sms.sendMany({
  recipients: ['243812345678', '0899999999'],
  body: 'Rappel : reunion demain 9h.',
  sender: 'MABOUTIQUE', // an approved Sender ID of the account
  reference: 'RAPPEL-2026-11-06',
  idempotencyKey: 'reminder-2026-11-06',
});

for (const message of batch.messages) {
  console.log(message.recipient, message.status);
}

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

const estimate = await client.sms.estimate({
  body: 'Votre code est 482913',
  recipients: ['243812345678', '0812345678', '0899999999'],
});

console.log(estimate.encoding, estimate.recipientsCount, estimate.totalCredits); // gsm7 2 2
if (!estimate.isAffordable) {
  // top up before sending
}

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

const { balance, held } = await client.balance.get();

console.log(balance + ' credits available, ' + held + ' held');

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

// One page
const page = await client.sms.list({ status: 'delivered', from: '2026-11-01', perPage: 50 });
console.log(page.total, page.hasMore);

// Every page, lazily
for await (const message of client.sms.list({ status: 'delivered', from: '2026-11-01' })) {
  console.log(message.id, message.recipient);
}

import { Labyrinthe, OtpResendTooSoonError } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

try {
  const otp = await client.otp.send({ phone: '243812345678', locale: 'fr' });
  session.otpId = otp.otpId; // keep it server-side
  console.log(otp.codeLength, otp.resendAfterSeconds); // 6 60
  console.log(otp.testCode); // '482913' with a lsk_test_ key, null in live
} catch (error) {
  if (error instanceof OtpResendTooSoonError) {
    console.log('Wait ' + (error.retryAfterMs ?? 0) / 1000 + ' s');
  } else {
    throw error;
  }
}

import { Labyrinthe } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

const result = await client.otp.verify({ otpId: session.otpId, code: req.body.code });

if (result.verified) {
  delete session.otpId; // phone verified: log the user in
} else if (result.reason === 'invalid_code') {
  console.log('Wrong code, ' + result.attemptsRemaining + ' attempt(s) left');
} else {
  console.log('Ask for a new code:', result.reason); // expired, max_attempts_reached, already_used
}

import express from 'express';
import { labyrintheWebhook } from '@labyrinthe/connect/express';

const app = express();

// Before express.json(): the middleware needs the raw body
app.post('/webhooks/labyrinthe', labyrintheWebhook({
  secret: process.env.LABYRINTHE_WEBHOOK_SECRET,
  onEvent: async (event) => {
    switch (event.event) {
      case 'message.status_changed':
        console.log(event.data.messageId, event.data.status);
        break;
      case 'otp.failed':
        console.log(event.data.otpId, event.data.reason);
        break;
      default:
        break; // unknown events are acknowledged
    }
  },
}));

app.use(express.json());

// Next.js App Router (app/api/webhooks/labyrinthe/route.ts):
// import { labyrintheWebhookHandler } from '@labyrinthe/connect/next';
// export const POST = labyrintheWebhookHandler({ onEvent: async (event) => { … } });

import { Labyrinthe, ApiError, FeatureDisabledError, InsufficientCreditsError, RateLimitError, RecipientNotSendableError } from '@labyrinthe/connect';

const client = new Labyrinthe({ apiKey: 'lsk_test_xxxxxxxxxxxxxxxx' }); // or new Labyrinthe() (LABYRINTHE_API_KEY)

try {
  await client.sms.send({ to: '243812345678', body: 'Bonjour' });
} catch (error) {
  if (error instanceof FeatureDisabledError) {
    // 503 maintenance: nothing was sent, no credit used
    console.log(error.feature, error.blockedBy, error.adminMessage, error.until);
    if (error.retryAfter !== null) scheduleRetry(error.retryAfter); // seconds
    else queueForLater();
  } else if (error instanceof InsufficientCreditsError) {
    notifyTopUp(error.available, error.required);
  } else if (error instanceof RecipientNotSendableError) {
    console.log(error.rejected); // [{ recipient, reason }]
  } else if (error instanceof RateLimitError) {
    scheduleRetry((error.retryAfterMs ?? 60_000) / 1000);
  } else if (error instanceof ApiError) {
    console.error(error.code, error.status, error.requestId);
  } else {
    throw error; // network error, timeout…
  }
}

// app/api/webhooks/labyrinthe/route.ts — Node.js or Edge runtime
import { labyrintheWebhookHandler } from '@labyrinthe/connect/next';

export const POST = labyrintheWebhookHandler({
  // secret defaults to LABYRINTHE_WEBHOOK_SECRET
  onEvent: async (event) => {
    if (event.event === 'message.status_changed') {
      console.log(event.data.messageId, event.data.status);
    }
    // Answer within 10 s: queue slow work. Throwing answers 500 and the delivery is retried.
  },
});