SMSTunnel for Node.js

npm install @narcisbodea/smstunnel-sdk

SMSTUNNEL_API_KEY=sk_live_...

// send.mjs. Run it: node --env-file=.env send.mjs
import { SmsTunnelNodeClient } from '@narcisbodea/smstunnel-sdk/node';

const client = new SmsTunnelNodeClient({ apiKey: process.env.SMSTUNNEL_API_KEY });

const result = await client.sendSms('+14155550123', 'Your order #1042 has shipped.');

console.log(result.messageId); // keep it to look up the status later

// send.cjs
const { SmsTunnelNodeClient } = require('@narcisbodea/smstunnel-sdk/node');

const client = new SmsTunnelNodeClient({ apiKey: process.env.SMSTUNNEL_API_KEY });

client
  .sendSms('+14155550123', 'Your order #1042 has shipped.')
  .then((result) => console.log(result.messageId))
  .catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });

const result = await client.sendSms(
  '+14155550123',                // international format; one number per call
  'See you at 10:30.',           // up to 1600 characters
  '6aea3248fedd7cccac9abf42',    // the phone that sends it (Phones → Copy); undefined lets SMSTunnel pick one of yours
  { defaultCountryCode: '+40' }, // completes numbers written without + or 00, like 0721 123 456
);

result.messageId;      // string
result.queued;         // true when no phone of yours was online: the text waits and goes out when one is back
result.data.branded;   // true when the Free plan added its short line to the text
result.data.remaining; // left today, e.g. { clean: 1985, total: 1985 } (-1 and 'unlimited' when there is no limit)

await client.send2FaSms('+14155550123', 'Your sign-in code is 482913');
// a third argument takes { deviceId, defaultCountryCode }, as for a text

const { data: status } = await client.getMessageStatus(result.messageId); // needs sms:read

status.status;         // 'pending', 'sent', 'delivered' or 'failed'
status.deliveryStatus; // the same, or 'unconfirmed': handed to the SIM, but the phone got no confirmation
status.sentAt;         // when it went out (ISO 8601, UTC)
status.errorMessage;   // why it failed, or null

const { data: phones } = await client.getDevices();
for (const phone of phones.devices) {
  console.log(phone.id, phone.name, phone.isOnline ? 'online' : 'offline'); // and phone.lastSeenAt
}

const { data: usage } = await client.getUsage();
usage.plan;                 // 'free', 'twofa' (Starter), 'standard', 'pro' (Professional) or 'enterprise'
usage.usage.smsClean;       // texts sent today
usage.remaining.smsClean;   // texts left today, or 'unlimited'
usage.remaining.twoFaClean; // sign-in codes left today, or 'unlimited'

const { data: page } = await client.getReceivedSms({
  since: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // the last 24 hours
  phone: '+14155550123', // only from this number
  limit: 20,             // 1 to 100
  page: 1,
});

for (const text of page.messages) { // newest first
  console.log(text.receivedAt, text.sender, text.message);
}

page.hasMore; // ask for the next page

await client.encryptAndSendSms('+14155550123', 'Your order has shipped.', '6aea3248fedd7cccac9abf42');

// server.mjs. Run it: node --env-file=.env server.mjs
import express from 'express';
import { SmsTunnelNodeClient } from '@narcisbodea/smstunnel-sdk/node';

const sms = new SmsTunnelNodeClient({ apiKey: process.env.SMSTUNNEL_API_KEY });
const OWNER_PHONE = process.env.OWNER_PHONE; // your own number, e.g. +14155550123

const app = express();
app.use(express.json());

app.post('/orders', async (req, res) => {
  const order = await saveOrder(req.body); // your own code
  res.status(201).json({ id: order.id });

  // After the answer, so the customer never waits for the text.
  try {
    await sms.sendSms(OWNER_PHONE, `New order #${order.id} from ${order.name}: ${order.total}`);
  } catch (error) {
    console.warn(`The text about order #${order.id} did not go out: ${error.message}`);
  }
});

app.listen(3000);

// sms.module.ts
import { Module } from '@nestjs/common';
import {
  SMSTUNNEL_OPTIONS,
  SmsTunnelService,
  type SmsTunnelModuleOptions,
} from '@narcisbodea/smstunnel-sdk/server';

const smsTunnel: SmsTunnelModuleOptions = {
  // The key stays in the environment: there is nothing for the service to save.
  storage: {
    getConfig: async () => ({
      serverUrl: 'https://smstunnel.io',
      apiKey: process.env.SMSTUNNEL_API_KEY ?? '',
    }),
    updateConfig: async () => {},
    clearConfig: async () => {},
  },
  callbackBaseUrl: '', // used only to link a phone by QR code
};

@Module({
  providers: [{ provide: SMSTUNNEL_OPTIONS, useValue: smsTunnel }, SmsTunnelService],
  exports: [SmsTunnelService],
})
export class SmsModule {}

// orders.service.ts, in a module with imports: [SmsModule]
import { Injectable, Logger } from '@nestjs/common';
import { SmsTunnelService } from '@narcisbodea/smstunnel-sdk/server';

@Injectable()
export class OrdersService {
  private readonly log = new Logger(OrdersService.name);

  constructor(private readonly sms: SmsTunnelService) {}

  async markShipped(order: Order): Promise<void> {
    // ...save the order first
    const result = await this.sms.sendSms(order.phone, `Your order #${order.id} has shipped.`);
    if (!result.success) {
      const why = `${result.status ?? 'no answer'} ${result.error}`;
      this.log.warn(`The shipping text for order #${order.id} did not go out: ${why}`);
    }
  }
}

// sms.module.ts
import { Module } from '@nestjs/common';
import { SmsTunnelNodeClient } from '@narcisbodea/smstunnel-sdk/node';

@Module({
  providers: [
    {
      provide: SmsTunnelNodeClient,
      useFactory: () => new SmsTunnelNodeClient({ apiKey: process.env.SMSTUNNEL_API_KEY ?? '' }),
    },
  ],
  exports: [SmsTunnelNodeClient],
})
export class SmsModule {}

import { SmsTunnelApiError } from '@narcisbodea/smstunnel-sdk/node';

try {
  await client.sendSms(number, text);
} catch (error) {
  if (error instanceof SmsTunnelApiError) {
    // SMSTunnel answered: error.status, error.code (e.g. 'PERMISSION_REQUIRED'), error.permission, error.body,
    // error.retryAfter (seconds, on a 429 for too many requests)
    console.warn(`SMSTunnel ${error.status} ${error.code ?? '-'}: ${error.message}`);
  } else if (error.name === 'AbortError') {
    // no answer within the timeout: the text may still go out, so check before you send it again
  } else {
    // SMSTunnel could not be reached: error.cause says why (ENOTFOUND, ECONNREFUSED, a TLS error)
  }
}

const client = new SmsTunnelNodeClient({
  apiKey: process.env.SMSTUNNEL_API_KEY,
  timeout: 15_000,                    // per call, in milliseconds; the default is 30 seconds
  serverUrl: 'http://127.0.0.1:3141', // a test server of your own; the default is https://smstunnel.io
});