@maacgo/sms

@maacgo/sms · Node.js SDK

Taiwan-first SMS API. Send SMS in 3 lines.

npm install @maacgo/sms

Quickstart

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

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

await sms.send({
  to: '[phone]',
  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: '[phone]', 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: ['[phone]', '[phone]'],
});
// 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();
});

License

MIT