@ariary/notification

SMS and notification task SDK for the Ariary API.

Install

yarn add @ariary/notification

Get your credentials

1. Sign in at ariari.mg
2. Create a project
3. You'll receive a projectId and a secret

Setup

import Ariari from '@ariary/notification'

Ariari.config({
  projectId: 'your-project-id',
  secret: 'your-secret',
})

Send SMS

Ariari.send() accepts one or more messages. Phone numbers are automatically normalized (+261340000000, 261340000000, 0340000000 all work).

Each message has the following shape:

| Field | Type | Required | Description | |---|---|---|---| | phone | string | string[] | Yes | Recipient phone number(s) | | message | string | Yes | SMS content |

// single recipient
const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })

// multiple recipients, same message
const task = await Ariari.send({ phone: ['0340000000', '0330000000'], message: 'Hello!' })

// multiple messages at once
const task = await Ariari.send(
  { phone: '0340000000', message: 'Hello!' },
  { phone: '+261330000000', message: 'Hi there!' }
)

Deferred sending

Pass a schedule string as the first argument to delay sending. Supports shorthand durations or ISO dates.

| Format | Example | Description | |---|---|---| | Minutes | 30m | Send in 30 minutes | | Hours | 2h | Send in 2 hours | | Combined | 1h30m | Send in 1 hour 30 minutes | | ISO date | 2026-03-01T08:00:00.000Z | Send at exact date/time |

// in 1 hour
const task = await Ariari.send('1h', { phone: '0340000000', message: 'See you soon!' })

// in 1h30m
const task = await Ariari.send('1h30m', { phone: '0340000000', message: 'Reminder' })

// at exact date
const task = await Ariari.send(
  '2026-03-01T08:00:00.000Z',
  { phone: '0340000000', message: 'Happy March!' }
)

Estimate

Estimate credit consumption before sending.

| Field | Type | Required | Description | |---|---|---|---| | text | string | Yes | SMS content | | repeat | number | No | Number of recipients (defaults to 1) |

Returns:

| Field | Type | Description | |---|---|---| | sms | number | Total SMS records (messages exceeding 9 pages are split into multiple SMS) | | credit | number | Total page count (actual credit consumption) |

const estimate = await Ariari.estimate(
  { text: 'Bonjour, votre commande est prête', repeat: 9 },
  { text: 'Votre code: 123456', repeat: 3 }
)
// { sms: 12, credit: 12 }

Track a Task

send() returns a Task object. Call .status() to check delivery progress.

All methods return the same response shape:

| Field | Type | Description | |---|---|---| | task | TaskData | Task metadata (see below) | | sms | SmsDetail[] | List of SMS details ([] when no details requested) | | total | number | Total SMS count for pagination (0 when no details requested) |

| Method | Description | |---|---| | task.status() | Task only, sms: [] | | task.status(count) | Task + first count SMS | | task.status(count, page) | Task + paginated SMS | | task.fullStatus() | Task + all SMS |

TaskData

| Field | Type | Description | |---|---|---| | _id | string | Task ID | | status | TaskCounters | Delivery counters per SMS | | statusPage | TaskCounters | Delivery counters per SMS page | | projectId | string | Project ID | | createdAt | string | Creation date | | scheduledAt | string? | Scheduled date (only if scheduled) |

TaskCounters

| Field | Type | Description | |---|---|---| | total | number | Total SMS count | | sent | number | Successfully sent | | failed | number | Failed to send | | delivered | number | Confirmed delivered |

SmsDetail

| Field | Type | Description | |---|---|---| | smsId | string | SMS ID | | phone | string | Recipient phone number | | message | string | SMS content | | status | SmsStatus | SCHEDULED | PENDING | SENT | DELIVERED | FAILED | | retryCount | number | Number of retry attempts |

const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })

// task only (sms: [], total: 0)
const res = await task.status()
// res.task.status => { total: 1, sent: 1, failed: 0, delivered: 0 }

// task + first 10 SMS
const details = await task.status(10)
// details.sms => [{ smsId, phone, message, status, retryCount }]

// paginated: 20 per page, page 2
const page2 = await task.status(20, 2)

// all SMS at once
const full = await task.fullStatus()
// full.sms => [...all SMS], full.total => 50

SMS statuses: SmsStatus.SCHEDULED | SmsStatus.PENDING | SmsStatus.SENT | SmsStatus.DELIVERED | SmsStatus.FAILED

A SmsStatus enum is also exported:

import { SmsStatus } from '@ariary/notification'

if (sms.status === SmsStatus.DELIVERED) { ... }

Retrieve an existing Task

Store task.id to retrieve it later with .getTask().

// after sending
const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })
const taskId = task.id // save this

// later
const task = Ariari.getTask(taskId)
const status = await task.status()

Multiple instances

Use name to manage separate Ariari instances with different credentials. Ariari.config() returns the instance directly.

const marketing = Ariari.config({
  name: 'marketing',
  projectId: 'project-a',
  secret: 'secret-a',
})

const alerts = Ariari.config({
  name: 'alerts',
  projectId: 'project-b',
  secret: 'secret-b',
})

await marketing.send({ phone: '0340000000', message: 'Promo!' })
await alerts.send({ phone: '0330000000', message: 'Server down' })

You can also retrieve a named instance later with Ariari.get().

const marketing = Ariari.get('marketing')

Without name, the instance defaults to "main" and is used by static methods (Ariari.send, Ariari.getTask).