@ariary/notification 3.0.5 → 3.0.8

package/README.md

@@ -8,6 +8,12 @@ SMS and notification task SDK for the Ariary API.
 yarn add @ariary/notification
 ```
 
+## Get your credentials
+
+1. Sign in at [ariari.mg](https://ariari.mg)
+2. Create a project
+3. You'll receive a `projectId` and a `secret`
+
 ## Setup
 
 ```ts
@@ -23,6 +29,13 @@ Ariari.config({
 
 `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 |
+
 ```ts
 // single recipient
 const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })
@@ -37,10 +50,96 @@ const task = await Ariari.send(
 )
 ```
 
+#### 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 |
+
+```ts
+// 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) |
+
+```ts
+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.
 
+### `task.status()` — TaskStatus
+
+| Field | Type | Description |
+|---|---|---|
+| `total` | number | Total SMS count |
+| `sent` | number | Successfully sent |
+| `failed` | number | Failed to send |
+| `delivered` | number | Confirmed delivered |
+
+### `task.status(count, page?)` — TaskWithDetails
+
+| Field | Type | Description |
+|---|---|---|
+| `task` | TaskResponse | Task metadata (see below) |
+| `sms` | SmsDetail[] | List of SMS details |
+| `total` | number | Total SMS count |
+
+### TaskResponse
+
+| Field | Type | Description |
+|---|---|---|
+| `_id` | string | Task ID |
+| `status` | TaskStatus | Delivery counters per SMS |
+| `statusPage` | TaskStatus | Delivery counters per SMS page |
+| `createdAt` | string | Creation date |
+| `scheduledAt` | string? | Scheduled date |
+
+### 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 |
+
 ```ts
 const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })
 
@@ -76,7 +175,7 @@ const task = await Ariari.send({ phone: '0340000000', message: 'Hello!' })
 const taskId = task.id // save this
 
 // later
-const task = await Ariari.getTask(taskId)
+const task = Ariari.getTask(taskId)
 const status = await task.status()
 ```
 

package/dist/index.d.mts

@@ -21,9 +21,6 @@ type Message = {
     phone: string[] | string;
     message: string;
 };
-type SendOptions = {
-    scheduledAt?: string;
-};
 declare enum SmsStatus {
     SCHEDULED = "SCHEDULED",
     PENDING = "PENDING",
@@ -57,6 +54,14 @@ type TaskWithDetails = {
     sms: SmsDetail[];
     total: number;
 };
+type EstimateMessage = {
+    text: string;
+    repeat?: number;
+};
+type EstimateResponse = {
+    sms: number;
+    credit: number;
+};
 
 declare class Task {
     id: string;
@@ -76,10 +81,12 @@ declare class Ariari {
         name?: string;
     }) => Ariari;
     static get: (name?: string) => Ariari;
-    send: (...args: [SendOptions, ...Message[]] | Message[]) => Promise<Task>;
+    send: (...args: [string, ...Message[]] | Message[]) => Promise<Task>;
     getTask: (taskId: string) => Task;
-    static send: (...args: [SendOptions, ...Message[]] | Message[]) => Promise<Task>;
-    static getTask: (taskId: string) => Promise<Task>;
+    estimate: (...messages: EstimateMessage[]) => Promise<EstimateResponse>;
+    static send: (...args: [string, ...Message[]] | Message[]) => Promise<Task>;
+    static getTask: (taskId: string) => Task;
+    static estimate: (...messages: EstimateMessage[]) => Promise<EstimateResponse>;
 }
 
 export { SmsStatus, Ariari as default };

package/dist/index.d.ts

@@ -21,9 +21,6 @@ type Message = {
     phone: string[] | string;
     message: string;
 };
-type SendOptions = {
-    scheduledAt?: string;
-};
 declare enum SmsStatus {
     SCHEDULED = "SCHEDULED",
     PENDING = "PENDING",
@@ -57,6 +54,14 @@ type TaskWithDetails = {
     sms: SmsDetail[];
     total: number;
 };
+type EstimateMessage = {
+    text: string;
+    repeat?: number;
+};
+type EstimateResponse = {
+    sms: number;
+    credit: number;
+};
 
 declare class Task {
     id: string;
@@ -76,10 +81,12 @@ declare class Ariari {
         name?: string;
     }) => Ariari;
     static get: (name?: string) => Ariari;
-    send: (...args: [SendOptions, ...Message[]] | Message[]) => Promise<Task>;
+    send: (...args: [string, ...Message[]] | Message[]) => Promise<Task>;
     getTask: (taskId: string) => Task;
-    static send: (...args: [SendOptions, ...Message[]] | Message[]) => Promise<Task>;
-    static getTask: (taskId: string) => Promise<Task>;
+    estimate: (...messages: EstimateMessage[]) => Promise<EstimateResponse>;
+    static send: (...args: [string, ...Message[]] | Message[]) => Promise<Task>;
+    static getTask: (taskId: string) => Task;
+    static estimate: (...messages: EstimateMessage[]) => Promise<EstimateResponse>;
 }
 
 export { SmsStatus, Ariari as default };

package/dist/index.js

@@ -79,6 +79,17 @@ var SmsStatus = /* @__PURE__ */ ((SmsStatus2) => {
 })(SmsStatus || {});
 
 // src/index.ts
+var parseSchedule = (input) => {
+  const match = input.match(/^(?:(\d+)h)?(?:(\d+)m)?$/);
+  if (match && (match[1] || match[2])) {
+    const ms = (parseInt(match[1] || "0") * 60 + parseInt(match[2] || "0")) * 6e4;
+    return new Date(Date.now() + ms).toISOString();
+  }
+  if (isNaN(Date.parse(input))) {
+    throw new Error(`Invalid schedule format: "${input}". Use a duration (e.g. "1h", "30m", "1h30m") or an ISO date.`);
+  }
+  return input;
+};
 var instances = {};
 var Task = class {
   constructor(id, requester) {
@@ -97,20 +108,23 @@ var Task = class {
 var _Ariari = class _Ariari {
   constructor({ name = "main", ...config }) {
     this.send = async (...args) => {
-      const hasOptions = args[0] && "scheduledAt" in args[0];
-      const options = hasOptions ? args[0] : {};
-      const data = hasOptions ? args.slice(1) : args;
+      const hasSchedule = typeof args[0] === "string";
+      const scheduledAt = hasSchedule ? parseSchedule(args[0]) : void 0;
+      const data = hasSchedule ? args.slice(1) : args;
       const body = {
         messages: data.map((item) => ({
           phones: (Array.isArray(item.phone) ? item.phone : [item.phone]).map(normalizePhoneNumber),
           message: item.message
         })),
-        ...options.scheduledAt && { scheduledAt: options.scheduledAt }
+        ...scheduledAt && { scheduledAt }
       };
       const response = await this._requester.post("/api/sms/bulk", { body });
       return new Task(response._id, this._requester);
     };
     this.getTask = (taskId) => new Task(taskId, this._requester);
+    this.estimate = async (...messages) => {
+      return this._requester.post("/api/sms/estimate", { body: { messages } });
+    };
     this._config = config;
     this._requester = createRequester(config);
     instances[name] = this;
@@ -123,7 +137,8 @@ _Ariari.get = (name = "main") => {
   return instances[name];
 };
 _Ariari.send = async (...args) => await _Ariari.get("main")?.send(...args);
-_Ariari.getTask = async (taskId) => _Ariari.get("main")?.getTask(taskId);
+_Ariari.getTask = (taskId) => _Ariari.get("main")?.getTask(taskId);
+_Ariari.estimate = async (...messages) => await _Ariari.get("main")?.estimate(...messages);
 var Ariari = _Ariari;
 var src_default = Ariari;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -52,6 +52,17 @@ var SmsStatus = /* @__PURE__ */ ((SmsStatus2) => {
 })(SmsStatus || {});
 
 // src/index.ts
+var parseSchedule = (input) => {
+  const match = input.match(/^(?:(\d+)h)?(?:(\d+)m)?$/);
+  if (match && (match[1] || match[2])) {
+    const ms = (parseInt(match[1] || "0") * 60 + parseInt(match[2] || "0")) * 6e4;
+    return new Date(Date.now() + ms).toISOString();
+  }
+  if (isNaN(Date.parse(input))) {
+    throw new Error(`Invalid schedule format: "${input}". Use a duration (e.g. "1h", "30m", "1h30m") or an ISO date.`);
+  }
+  return input;
+};
 var instances = {};
 var Task = class {
   constructor(id, requester) {
@@ -70,20 +81,23 @@ var Task = class {
 var _Ariari = class _Ariari {
   constructor({ name = "main", ...config }) {
     this.send = async (...args) => {
-      const hasOptions = args[0] && "scheduledAt" in args[0];
-      const options = hasOptions ? args[0] : {};
-      const data = hasOptions ? args.slice(1) : args;
+      const hasSchedule = typeof args[0] === "string";
+      const scheduledAt = hasSchedule ? parseSchedule(args[0]) : void 0;
+      const data = hasSchedule ? args.slice(1) : args;
       const body = {
         messages: data.map((item) => ({
           phones: (Array.isArray(item.phone) ? item.phone : [item.phone]).map(normalizePhoneNumber),
           message: item.message
         })),
-        ...options.scheduledAt && { scheduledAt: options.scheduledAt }
+        ...scheduledAt && { scheduledAt }
       };
       const response = await this._requester.post("/api/sms/bulk", { body });
       return new Task(response._id, this._requester);
     };
     this.getTask = (taskId) => new Task(taskId, this._requester);
+    this.estimate = async (...messages) => {
+      return this._requester.post("/api/sms/estimate", { body: { messages } });
+    };
     this._config = config;
     this._requester = createRequester(config);
     instances[name] = this;
@@ -96,7 +110,8 @@ _Ariari.get = (name = "main") => {
   return instances[name];
 };
 _Ariari.send = async (...args) => await _Ariari.get("main")?.send(...args);
-_Ariari.getTask = async (taskId) => _Ariari.get("main")?.getTask(taskId);
+_Ariari.getTask = (taskId) => _Ariari.get("main")?.getTask(taskId);
+_Ariari.estimate = async (...messages) => await _Ariari.get("main")?.estimate(...messages);
 var Ariari = _Ariari;
 var src_default = Ariari;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariary/notification",
-  "version": "3.0.5",
+  "version": "3.0.8",
   "description": "SMS et Notification Task SDK pour l'API Ariary",
   "main": "dist/index.js",
   "module": "dist/index.mjs",