import { Maacgo } from '@maacgo/sms';

const sms = new Maacgo(process.env.MAACGO_API_KEY);

await sms.send({
  to: '+886912345678',
  body: '【你的品牌】驗證碼 123456，5 分鐘內有效。',
});

Create that key from:

Sign in at https://sms.cresclab.com with GitHub
Open API · 金鑰
Create a test or production key

API

`new Maacgo(apiKey, opts?)`

apiKey: your sk_live_ or sk_test_ key from API · 金鑰 after signing in at https://sms.cresclab.com
opts.baseUrl: override default API URL (for self-hosted / staging)
opts.timeout: request timeout ms (default 15000)

`sms.send({ to, body, from?, type? })`

Send one message.

const r = await sms.send({ to: '+886912345678', body: '【你的品牌】訂單 #1234 已出貨' });
// r = { message_id: 'sms_abc', status: 'delivered', segments: 1, cost_cents: 75, balance_cents: 4925 }

`sms.broadcast({ body, recipients, name?, scheduled_at? })`

Send to many.

const r = await sms.broadcast({
  name: '週年慶',
  body: '【你的品牌】週年慶 5 折起！',
  recipients: ['+886912345678', '+886987654321'],
});
// r = { broadcast_id: 'bcast_...', status: 'sent', recipient_count: 2, delivered: 2 }

`sms.list({ limit, status })`

const { messages, summary_7d } = await sms.list({ limit: 50, status: 'delivered' });

`sms.balance()`

const { balance_cents } = await sms.balance();

Errors

try {
  await sms.send({ to: '09XXX', body: '【...】Hi' });
} catch (err) {
  if (err.data?.error === 'ncc_blocked') {
    console.log('NCC compliance failed:', err.data.issues);
  } else if (err.data?.error === 'insufficient_balance') {
    console.log('Please top up');
  }
}

Webhooks

Verify X-Cresclab-Signature:

import { createHmac } from 'node:crypto';

app.post('/webhooks/cresclab', (req, res) => {
  const sig = req.headers['x-cresclab-signature'];
  const expected = createHmac('sha256', process.env.CRESCLAB_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');
  if (sig !== expected) return res.status(401).end();
  // handle req.body.event
  res.status(200).end();
});