@dataflows/sms 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataFlows Australia Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# DataFlows SMS for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Node.js client for the [DataFlows SMS API](https://dataflows.com.au/developers). It has no dependencies and needs Node 18 or newer.
+
+## Install
+
+```bash
+npm install @dataflows/sms
+```
+
+## Send your first SMS
+
+Find your API token in your DataFlows account under Developers, and keep it in an environment variable:
+
+```bash
+export DATAFLOWS_API_TOKEN="your-token"
+```
+
+```js
+import { DataFlows } from '@dataflows/sms';
+
+const client = new DataFlows();
+
+const result = await client.sms.send({
+  recipient: '61404235133',
+  senderId: 'YOUR_SENDER_ID',
+  message: 'Hello from DataFlows',
+});
+
+console.log(result.campaign_id);
+```
+
+This really sends a text and uses your credit, so change the number first. `require` works too:
+
+```js
+const { DataFlows } = require('@dataflows/sms');
+```
+
+## What you can do
+
+| Call | What it does |
+|---|---|
+| `client.account.profile()` | Your account details |
+| `client.account.balance()` | Your remaining balance |
+| `client.senderIds.list()` | Your active sender IDs |
+| `client.sms.send({ recipient, senderId, message, scheduleTime })` | Send or schedule an SMS |
+| `client.sms.list({ page, limit })` | A page of your sent messages |
+| `client.sms.get(uid)` | One message |
+| `client.groups.list({ page })` | A page of your contact groups |
+| `client.groups.create({ name })` | Add a group |
+| `client.groups.get(groupUid)` | One group |
+| `client.groups.update(groupUid, { name })` | Rename a group |
+| `client.groups.delete(groupUid)` | Delete a group |
+| `client.contacts.list(groupUid, { page })` | A page of a group's contacts |
+| `client.contacts.create(groupUid, { phone, firstName, lastName, fields })` | Add a contact |
+| `client.contacts.get(groupUid, contactUid)` | One contact |
+| `client.contacts.update(groupUid, contactUid, { phone, firstName, lastName, fields })` | Change a contact |
+| `client.contacts.delete(groupUid, contactUid)` | Delete a contact |
+
+## Sending
+
+**Numbers** go in international format, such as `61404235133`. A number containing letters is refused before anything is sent.
+
+**Several numbers:** pass a list as `recipient`. They're sent during the request, so a long list takes longer, and you get one result per number.
+
+**Scheduling:** set `scheduleTime` to `YYYY-MM-DD HH:mm` in your account's timezone.
+
+**Delivery status:** a message's `customer_status` of `Delivered` means the carrier accepted it. It doesn't confirm the message reached the phone.
+
+**Trial accounts** can only send to numbers they have verified.
+
+## Contacts
+
+Adding a contact sends the group's welcome text if you've set one up on that group. `fields` holds your group's custom fields, by tag. Leave `phone` out of an update to keep the current number.
+
+## Errors
+
+Every failure throws a `DataFlowsError`. This includes errors the API answers with HTTP 200, which many of them do.
+
+```js
+import { DataFlows, DataFlowsError } from '@dataflows/sms';
+
+try {
+  await client.sms.send({ recipient: '61404235133', senderId: 'YOUR_SENDER_ID', message: 'Hello' });
+} catch (error) {
+  if (error instanceof DataFlowsError) {
+    console.error(error.code, error.httpStatus, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+| `error.code` | Meaning |
+|---|---|
+| `api_error` | DataFlows refused the request. `error.message` says why |
+| `invalid_input` | Something is missing or wrong. Nothing was sent to DataFlows |
+| `rate_limited` | Over 600 requests per minute for this token |
+| `timeout` | No answer in time. A send may still have gone out |
+| `network_error` | DataFlows couldn't be reached |
+| `invalid_response` | DataFlows sent back something unexpected |
+
+**Nothing is retried automatically**, so a message can't go out twice because of this client. After a `timeout`, check `client.sms.list()` before you send again.
+
+## Options
+
+```js
+const client = new DataFlows({
+  apiToken: 'your-token', // defaults to DATAFLOWS_API_TOKEN
+  timeout: 60000,         // milliseconds per request, this is the default
+});
+```
+
+## More
+
+- [Developer hub](https://dataflows.com.au/developers)
+- [API reference](https://docs.dataflows.com.au/)
+- [OpenAPI spec](https://sms.dataflows.com.au/openapi.json)
+- Help: support@dataflows.com.au
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@dataflows/sms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official Node.js client for the DataFlows SMS API",
+  "keywords": ["sms", "dataflows", "text message", "australia", "api"],
+  "homepage": "https://dataflows.com.au/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dataflows-au/dataflows-sms-node.git"
+  },
+  "bugs": {
+    "email": "support@dataflows.com.au"
+  },
+  "license": "MIT",
+  "author": "DataFlows Australia Pty Ltd",
+  "main": "./src/index.cjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.cjs"
+    }
+  },
+  "files": ["src"],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/client.test.cjs"
+  }
+}

package/src/index.cjs

@@ -0,0 +1,178 @@
+'use strict';
+
+const VERSION = '0.1.0';
+const DEFAULT_BASE_URL = 'https://sms.dataflows.com.au/api/http';
+const DEFAULT_TIMEOUT_MS = 60000;
+
+// Digits and the usual separators only. The API's number parser reads letters
+// as a phone keypad, so "61412345xxx" would otherwise reach a real number.
+const VALID_NUMBER = /^(?=.*[0-9])[0-9+()\-\s]+$/;
+
+class DataFlowsError extends Error {
+  /**
+   * @param {string} message
+   * @param {{code?: string, httpStatus?: number, response?: unknown, cause?: unknown}} [details]
+   */
+  constructor(message, { code = 'api_error', httpStatus, response, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'DataFlowsError';
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.response = response;
+  }
+}
+
+function requireValue(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new DataFlowsError(`${name} is required.`, { code: 'invalid_input' });
+  }
+}
+
+function recipientValue(recipient) {
+  requireValue(recipient, 'recipient');
+  const numbers = (Array.isArray(recipient) ? recipient : String(recipient).split(','))
+    .map((number) => String(number).trim());
+
+  if (numbers.length === 0) {
+    throw new DataFlowsError('recipient is required.', { code: 'invalid_input' });
+  }
+
+  const invalid = numbers.find((number) => !VALID_NUMBER.test(number));
+  if (invalid !== undefined) {
+    throw new DataFlowsError(`"${invalid}" is not a valid phone number. Use digits only.`, { code: 'invalid_input' });
+  }
+  return numbers.join(',');
+}
+
+function contactBody({ phone, firstName, lastName, fields } = {}) {
+  const body = { ...fields };
+  if (phone !== undefined) body.PHONE = phone;
+  if (firstName !== undefined) body.FIRST_NAME = firstName;
+  if (lastName !== undefined) body.LAST_NAME = lastName;
+  return body;
+}
+
+function segment(value, name) {
+  requireValue(value, name);
+  return encodeURIComponent(String(value));
+}
+
+class DataFlows {
+  /**
+   * @param {{apiToken?: string, baseUrl?: string, timeout?: number, fetch?: typeof fetch}} [options]
+   */
+  constructor({ apiToken = process.env.DATAFLOWS_API_TOKEN, baseUrl = DEFAULT_BASE_URL, timeout = DEFAULT_TIMEOUT_MS, fetch: fetchImpl = globalThis.fetch } = {}) {
+    if (!apiToken) {
+      throw new DataFlowsError('An API token is required. Pass apiToken or set DATAFLOWS_API_TOKEN.', { code: 'invalid_input' });
+    }
+    if (!/^https:\/\//.test(baseUrl) && !/^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(baseUrl)) {
+      throw new DataFlowsError('baseUrl must use https, so your API token is never sent unencrypted.', { code: 'invalid_input' });
+    }
+    if (typeof fetchImpl !== 'function') {
+      throw new DataFlowsError('No fetch is available. Use Node 18 or newer, or pass your own fetch.', { code: 'invalid_input' });
+    }
+
+    const root = baseUrl.replace(/\/+$/, '');
+
+    // Held in this closure, not on the instance, so logging the client can't show the token.
+    const call = async (method, path, { query, body } = {}) => {
+      const search = new URLSearchParams();
+      for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined && value !== null) search.set(key, String(value));
+      }
+      const queryString = search.toString();
+      const url = root + path + (queryString ? `?${queryString}` : '');
+
+      const headers = {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': `dataflows-sms-node/${VERSION}`,
+      };
+      if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+      let response;
+      try {
+        response = await fetchImpl(url, {
+          method,
+          headers,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(timeout),
+        });
+      } catch (cause) {
+        if (cause?.name === 'TimeoutError' || cause?.name === 'AbortError') {
+          throw new DataFlowsError(`The request timed out after ${timeout}ms. If this was a send, the message may still have gone out, so check before trying again.`, { code: 'timeout', cause });
+        }
+        throw new DataFlowsError(`Could not reach DataFlows: ${cause?.message ?? cause}`, { code: 'network_error', cause });
+      }
+
+      let payload;
+      try {
+        payload = await response.json();
+      } catch (cause) {
+        throw new DataFlowsError(`DataFlows sent a response that isn't JSON (HTTP ${response.status}).`, { code: 'invalid_response', httpStatus: response.status, cause });
+      }
+
+      // Many errors answer HTTP 200 with status "error", so the HTTP code alone isn't enough.
+      if (!response.ok || payload?.status === 'error') {
+        throw new DataFlowsError(payload?.message || `DataFlows answered HTTP ${response.status}.`, {
+          code: response.status === 429 ? 'rate_limited' : 'api_error',
+          httpStatus: response.status,
+          response: payload,
+        });
+      }
+      return payload;
+    };
+
+    const data = async (...args) => (await call(...args)).data;
+    const done = async (...args) => { await call(...args); };
+
+    this.account = {
+      profile: () => data('GET', '/me'),
+      balance: () => data('GET', '/balance'),
+    };
+
+    this.senderIds = {
+      list: async () => (await call('GET', '/sender-ids')).value,
+    };
+
+    this.sms = {
+      send: async ({ recipient, senderId, message, scheduleTime } = {}) => {
+        const to = recipientValue(recipient);
+        requireValue(senderId, 'senderId');
+        requireValue(message, 'message');
+        const body = { recipient: to, sender_id: senderId, message };
+        if (scheduleTime !== undefined) body.schedule_time = scheduleTime;
+        return data('POST', '/sms/send', { body });
+      },
+      list: ({ page, limit } = {}) => data('GET', '/sms', { query: { page, limit } }),
+      get: async (uid) => data('GET', `/sms/${segment(uid, 'uid')}`),
+    };
+
+    this.groups = {
+      list: ({ page } = {}) => data('GET', '/contacts', { query: { page } }),
+      create: async ({ name } = {}) => {
+        requireValue(name, 'name');
+        return data('POST', '/contacts', { body: { name } });
+      },
+      get: async (groupUid) => data('POST', `/contacts/${segment(groupUid, 'groupUid')}/show`),
+      update: async (groupUid, { name } = {}) => {
+        requireValue(name, 'name');
+        return data('PATCH', `/contacts/${segment(groupUid, 'groupUid')}`, { body: { name } });
+      },
+      delete: async (groupUid) => done('DELETE', `/contacts/${segment(groupUid, 'groupUid')}`),
+    };
+
+    this.contacts = {
+      list: async (groupUid, { page } = {}) => data('POST', `/contacts/${segment(groupUid, 'groupUid')}/all`, { query: { page } }),
+      create: async (groupUid, input = {}) => {
+        requireValue(input.phone, 'phone');
+        return data('POST', `/contacts/${segment(groupUid, 'groupUid')}/store`, { body: contactBody(input) });
+      },
+      get: async (groupUid, contactUid) => data('POST', `/contacts/${segment(groupUid, 'groupUid')}/search/${segment(contactUid, 'contactUid')}`),
+      update: async (groupUid, contactUid, input = {}) => data('PATCH', `/contacts/${segment(groupUid, 'groupUid')}/update/${segment(contactUid, 'contactUid')}`, { body: contactBody(input) }),
+      delete: async (groupUid, contactUid) => done('DELETE', `/contacts/${segment(groupUid, 'groupUid')}/delete/${segment(contactUid, 'contactUid')}`),
+    };
+  }
+}
+
+module.exports = { DataFlows, DataFlowsError, VERSION };

package/src/index.d.ts

@@ -0,0 +1,152 @@
+export declare const VERSION: string;
+
+export type DataFlowsErrorCode =
+  | 'api_error'
+  | 'invalid_input'
+  | 'invalid_response'
+  | 'network_error'
+  | 'rate_limited'
+  | 'timeout';
+
+export declare class DataFlowsError extends Error {
+  readonly code: DataFlowsErrorCode;
+  /** The HTTP status, when DataFlows answered. Many API errors answer 200. */
+  readonly httpStatus?: number;
+  /** The parsed error response, when there was one. */
+  readonly response?: unknown;
+}
+
+export interface DataFlowsOptions {
+  /** Your API token. Defaults to the DATAFLOWS_API_TOKEN environment variable. */
+  apiToken?: string;
+  baseUrl?: string;
+  /** Milliseconds to wait for each request. Defaults to 60000. */
+  timeout?: number;
+  fetch?: typeof fetch;
+}
+
+export interface Profile {
+  uid: string;
+  api_token?: string;
+  first_name?: string | null;
+  last_name?: string | null;
+  email: string;
+  locale?: string;
+  timezone?: string;
+  last_access_at?: string | null;
+}
+
+export interface Balance {
+  remaining_balance: string;
+  expired_on: string;
+}
+
+export interface SendResult {
+  campaign_id: string;
+  recipient?: string;
+  message?: string;
+  cost?: number;
+  sms_count?: number;
+  status?: string;
+}
+
+export interface Message {
+  uid: string;
+  to: string;
+  from?: string | null;
+  message?: string;
+  /** "Delivered" means the carrier accepted the message, not that it reached the phone. */
+  customer_status?: string | null;
+  cost?: string | null;
+}
+
+export interface Group {
+  uid: string;
+  name: string;
+}
+
+export interface Contact {
+  uid: string;
+  phone: number;
+  status: string;
+  custom_fields?: Record<string, unknown>;
+}
+
+export interface Page<T> {
+  current_page: number;
+  data: T[];
+  first_page_url?: string;
+  from?: number | null;
+  last_page: number;
+  last_page_url?: string;
+  links?: Array<{ url: string | null; label: string; active: boolean }>;
+  next_page_url?: string | null;
+  path?: string;
+  per_page: number;
+  prev_page_url?: string | null;
+  to?: number | null;
+  total: number;
+}
+
+export interface SendSmsInput {
+  /** One number in international format. Sending to several is a separate overload. */
+  recipient: string;
+  /** One of your active sender IDs or numbers. See senderIds.list(). */
+  senderId: string;
+  message: string;
+  /** Send later, as "YYYY-MM-DD HH:mm" in your account's timezone. */
+  scheduleTime?: string;
+}
+
+export interface SendBulkSmsInput extends Omit<SendSmsInput, 'recipient'> {
+  /** Several numbers. They're sent during the request, so a long list takes longer. */
+  recipient: string[];
+}
+
+export interface ContactInput {
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+  /** Your group's custom fields, by tag. */
+  fields?: Record<string, string>;
+}
+
+export declare class DataFlows {
+  constructor(options?: DataFlowsOptions);
+
+  readonly account: {
+    profile(): Promise<Profile>;
+    balance(): Promise<Balance>;
+  };
+
+  readonly senderIds: {
+    list(): Promise<string[]>;
+  };
+
+  readonly sms: {
+    send(input: SendSmsInput): Promise<SendResult>;
+    send(input: SendBulkSmsInput): Promise<Message[]>;
+    list(options?: { page?: number; limit?: number }): Promise<Page<Message>>;
+    get(uid: string): Promise<Message>;
+  };
+
+  readonly groups: {
+    list(options?: { page?: number }): Promise<Page<Group>>;
+    create(input: { name: string }): Promise<Group>;
+    get(groupUid: string): Promise<Group>;
+    update(groupUid: string, input: { name: string }): Promise<Group>;
+    delete(groupUid: string): Promise<void>;
+  };
+
+  readonly contacts: {
+    list(groupUid: string, options?: { page?: number }): Promise<Page<Contact>>;
+    /** Sends the group's welcome text if you've set one up on that group. */
+    create(groupUid: string, input: ContactInput & { phone: string }): Promise<Contact>;
+    get(groupUid: string, contactUid: string): Promise<Contact>;
+    /** Leave phone out to keep the current number. */
+    update(groupUid: string, contactUid: string, input: ContactInput): Promise<Contact>;
+    delete(groupUid: string, contactUid: string): Promise<void>;
+  };
+}
+
+export default DataFlows;

package/src/index.mjs

@@ -0,0 +1,4 @@
+import sdk from './index.cjs';
+
+export const { DataFlows, DataFlowsError, VERSION } = sdk;
+export default DataFlows;