@objectstack/service-sms 14.5.0

package/src/transports/aliyun.ts

@@ -0,0 +1,115 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import type { ISmsTransport, NormalizedSmsMessage, SmsTransportSendResult } from '@objectstack/spec/contracts';
+
+export interface AliyunSmsTransportOptions {
+  accessKeyId: string;
+  accessKeySecret: string;
+  /** 短信签名 SignName — the registered sender signature, e.g. `阿里云短信测试`. */
+  signName: string;
+  /**
+   * Default 模板 TemplateCode used when the input carries no `templateId`
+   * (Aliyun only delivers pre-registered templates — free-form bodies are
+   * refused by the API). A catch-all template with a single `${content}`
+   * variable makes generic notification sends possible.
+   */
+  defaultTemplateCode?: string;
+  /** API endpoint host. Default `dysmsapi.aliyuncs.com`. */
+  endpoint?: string;
+  /** Injectable fetch for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+const API_VERSION = '2017-05-25';
+const ALGORITHM = 'ACS3-HMAC-SHA256';
+
+const sha256Hex = (s: string): string => createHash('sha256').update(s, 'utf8').digest('hex');
+const hmac256Hex = (key: string, s: string): string => createHmac('sha256', key).update(s, 'utf8').digest('hex');
+
+/** RFC 3986 percent-encoding (Aliyun requires `%20`, `%2A`, `%7E` handling). */
+const encode = (s: string): string =>
+  encodeURIComponent(s)
+    .replace(/\+/g, '%20')
+    .replace(/\*/g, '%2A')
+    .replace(/%7E/g, '~');
+
+/**
+ * Aliyun SMS (dysmsapi `SendSms`) transport, signed with the current
+ * ACS3-HMAC-SHA256 scheme — plain `fetch` + `node:crypto`, no vendor SDK.
+ *
+ * Aliyun is template-only: the transport sends `templateId` (falling back to
+ * the configured default TemplateCode) with `templateParams` (falling back to
+ * `{ content: body }` for the catch-all-template pattern). The rendered
+ * `body` itself is never transmitted outside `TemplateParam`.
+ */
+export class AliyunSmsTransport implements ISmsTransport {
+  private readonly endpoint: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly options: AliyunSmsTransportOptions) {
+    if (!options.accessKeyId || !options.accessKeySecret) {
+      throw new Error('AliyunSmsTransport: accessKeyId and accessKeySecret are required');
+    }
+    if (!options.signName) {
+      throw new Error('AliyunSmsTransport: signName is required');
+    }
+    this.endpoint = options.endpoint ?? 'dysmsapi.aliyuncs.com';
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  async send(message: NormalizedSmsMessage): Promise<SmsTransportSendResult> {
+    const templateCode = message.templateId ?? this.options.defaultTemplateCode;
+    if (!templateCode) {
+      throw new Error(
+        'AliyunSmsTransport: Aliyun requires a template — pass templateId or configure a default template code',
+      );
+    }
+    const templateParam = JSON.stringify(message.templateParams ?? { content: message.body });
+
+    const query: Record<string, string> = {
+      PhoneNumbers: message.to,
+      SignName: this.options.signName,
+      TemplateCode: templateCode,
+      TemplateParam: templateParam,
+    };
+    const canonicalQuery = Object.keys(query)
+      .sort()
+      .map((k) => `${encode(k)}=${encode(query[k])}`)
+      .join('&');
+
+    const bodyHash = sha256Hex(''); // POST with all parameters in the query string
+    const headers: Record<string, string> = {
+      host: this.endpoint,
+      'x-acs-action': 'SendSms',
+      'x-acs-content-sha256': bodyHash,
+      'x-acs-date': new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+      'x-acs-signature-nonce': randomUUID(),
+      'x-acs-version': API_VERSION,
+    };
+    const signedHeaderNames = Object.keys(headers).sort();
+    const canonicalHeaders = signedHeaderNames.map((k) => `${k}:${headers[k].trim()}\n`).join('');
+    const signedHeaders = signedHeaderNames.join(';');
+
+    const canonicalRequest = ['POST', '/', canonicalQuery, canonicalHeaders, signedHeaders, bodyHash].join('\n');
+    const stringToSign = `${ALGORITHM}\n${sha256Hex(canonicalRequest)}`;
+    const signature = hmac256Hex(this.options.accessKeySecret, stringToSign);
+
+    const response = await this.fetchImpl(`https://${this.endpoint}/?${canonicalQuery}`, {
+      method: 'POST',
+      headers: {
+        ...headers,
+        Authorization: `${ALGORITHM} Credential=${this.options.accessKeyId},SignedHeaders=${signedHeaders},Signature=${signature}`,
+      },
+    });
+
+    let payload: any = {};
+    try { payload = await response.json(); } catch { /* non-JSON error body */ }
+    if (!response.ok || payload?.Code !== 'OK') {
+      const code = payload?.Code ?? `HTTP_${response.status}`;
+      const detail = payload?.Message ?? response.statusText ?? 'request failed';
+      throw new Error(`Aliyun SendSms failed (${code}): ${detail}`);
+    }
+    return { messageId: String(payload.BizId ?? payload.RequestId ?? ''), response: payload.RequestId };
+  }
+}

package/src/transports/index.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ISmsTransport } from '@objectstack/spec/contracts';
+import { LogSmsTransport } from '../sms-service.js';
+import { AliyunSmsTransport } from './aliyun.js';
+import { TwilioSmsTransport } from './twilio.js';
+
+export { AliyunSmsTransport, type AliyunSmsTransportOptions } from './aliyun.js';
+export { TwilioSmsTransport, type TwilioSmsTransportOptions } from './twilio.js';
+
+export type SmsProviderTag = 'log' | 'aliyun' | 'twilio';
+
+export interface MakeSmsTransportOptions {
+  provider: SmsProviderTag;
+  /** Provider-specific credentials/options (see the transport option types). */
+  options?: Record<string, unknown>;
+  logger?: { info: (msg: string, meta?: any) => void };
+}
+
+/**
+ * Build an ISmsTransport from a provider tag + opts. Used by
+ * SmsServicePlugin to materialise the transport selected by config /
+ * the `sms` settings namespace.
+ *
+ * Throws when a non-`log` provider is missing required credentials.
+ */
+export function makeSmsTransport(opts: MakeSmsTransportOptions): ISmsTransport {
+  const { provider, options = {}, logger } = opts;
+  switch (provider) {
+    case 'log':
+      return new LogSmsTransport(logger);
+    case 'aliyun':
+      return new AliyunSmsTransport(options as any);
+    case 'twilio':
+      return new TwilioSmsTransport(options as any);
+    default:
+      throw new Error(`makeSmsTransport: unknown provider '${provider}'`);
+  }
+}

package/src/transports/transports.test.ts

@@ -0,0 +1,114 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import { AliyunSmsTransport } from './aliyun.js';
+import { TwilioSmsTransport } from './twilio.js';
+import { makeSmsTransport } from './index.js';
+import { LogSmsTransport } from '../sms-service.js';
+
+const jsonResponse = (body: any, status = 200) =>
+  ({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: 'x',
+    json: async () => body,
+  }) as any;
+
+describe('AliyunSmsTransport', () => {
+  const base = {
+    accessKeyId: 'ak',
+    accessKeySecret: 'secret',
+    signName: '测试签名',
+    defaultTemplateCode: 'SMS_123',
+  };
+
+  it('requires credentials + sign name', () => {
+    expect(() => new AliyunSmsTransport({ ...base, accessKeyId: '' } as any)).toThrow(/accessKeyId/);
+    expect(() => new AliyunSmsTransport({ ...base, signName: '' } as any)).toThrow(/signName/);
+  });
+
+  it('sends a signed SendSms request with template params', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ Code: 'OK', BizId: 'biz_1', RequestId: 'req_1' }));
+    const t = new AliyunSmsTransport({ ...base, fetchImpl: fetchImpl as any });
+    const r = await t.send({ to: '+8613800000000', body: 'ignored', templateParams: { code: '123456' } });
+    expect(r.messageId).toBe('biz_1');
+
+    const [url, init] = fetchImpl.mock.calls[0] as any[];
+    expect(String(url)).toContain('https://dysmsapi.aliyuncs.com/?');
+    expect(String(url)).toContain('PhoneNumbers=%2B8613800000000');
+    expect(String(url)).toContain('TemplateCode=SMS_123');
+    expect(decodeURIComponent(String(url))).toContain('{"code":"123456"}');
+    expect(init.method).toBe('POST');
+    expect(init.headers.Authorization).toMatch(/^ACS3-HMAC-SHA256 Credential=ak,SignedHeaders=host;x-acs-action;/);
+    expect(init.headers['x-acs-action']).toBe('SendSms');
+    expect(init.headers['x-acs-version']).toBe('2017-05-25');
+  });
+
+  it('falls back to { content: body } for the default catch-all template', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ Code: 'OK', BizId: 'b' }));
+    const t = new AliyunSmsTransport({ ...base, fetchImpl: fetchImpl as any });
+    await t.send({ to: '13800000000', body: 'hello world' });
+    expect(decodeURIComponent(String(fetchImpl.mock.calls[0][0]))).toContain('{"content":"hello world"}');
+  });
+
+  it('throws when no template code is available (Aliyun is template-only)', async () => {
+    const t = new AliyunSmsTransport({ ...base, defaultTemplateCode: undefined, fetchImpl: vi.fn() as any });
+    await expect(t.send({ to: '13800000000', body: 'x' })).rejects.toThrow(/template/);
+  });
+
+  it('maps a non-OK Code to a thrown error', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ Code: 'isv.BUSINESS_LIMIT_CONTROL', Message: 'limit' }));
+    const t = new AliyunSmsTransport({ ...base, fetchImpl: fetchImpl as any });
+    await expect(t.send({ to: '13800000000', body: 'x' })).rejects.toThrow(/BUSINESS_LIMIT_CONTROL/);
+  });
+});
+
+describe('TwilioSmsTransport', () => {
+  const base = { accountSid: 'AC123', authToken: 'tok', from: '+15005550006' };
+
+  it('requires credentials and a sender', () => {
+    expect(() => new TwilioSmsTransport({ ...base, authToken: '' } as any)).toThrow(/accountSid and authToken/);
+    expect(() => new TwilioSmsTransport({ accountSid: 'AC123', authToken: 'tok' } as any)).toThrow(/from/);
+  });
+
+  it('POSTs the Messages resource with Basic auth + form body', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ sid: 'SM1', status: 'queued' }, 201));
+    const t = new TwilioSmsTransport({ ...base, fetchImpl: fetchImpl as any });
+    const r = await t.send({ to: '+15005550009', body: 'hi there' });
+    expect(r.messageId).toBe('SM1');
+
+    const [url, init] = fetchImpl.mock.calls[0] as any[];
+    expect(String(url)).toBe('https://api.twilio.com/2010-04-01/Accounts/AC123/Messages.json');
+    expect(init.headers.Authorization).toBe(`Basic ${Buffer.from('AC123:tok').toString('base64')}`);
+    const form = new URLSearchParams(init.body);
+    expect(form.get('To')).toBe('+15005550009');
+    expect(form.get('Body')).toBe('hi there');
+    expect(form.get('From')).toBe('+15005550006');
+  });
+
+  it('prefers MessagingServiceSid over From when configured', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ sid: 'SM2' }, 201));
+    const t = new TwilioSmsTransport({ accountSid: 'AC123', authToken: 'tok', messagingServiceSid: 'MG9', fetchImpl: fetchImpl as any });
+    await t.send({ to: '+15005550009', body: 'x' });
+    const form = new URLSearchParams((fetchImpl.mock.calls[0] as any[])[1].body);
+    expect(form.get('MessagingServiceSid')).toBe('MG9');
+    expect(form.get('From')).toBeNull();
+  });
+
+  it('maps an error response to a thrown error', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({ code: 21211, message: 'invalid To' }, 400));
+    const t = new TwilioSmsTransport({ ...base, fetchImpl: fetchImpl as any });
+    await expect(t.send({ to: '+1', body: 'x' })).rejects.toThrow(/21211.*invalid To/);
+  });
+});
+
+describe('makeSmsTransport', () => {
+  it('builds by provider tag', () => {
+    expect(makeSmsTransport({ provider: 'log' })).toBeInstanceOf(LogSmsTransport);
+    expect(makeSmsTransport({ provider: 'aliyun', options: { accessKeyId: 'a', accessKeySecret: 'b', signName: 'c' } }))
+      .toBeInstanceOf(AliyunSmsTransport);
+    expect(makeSmsTransport({ provider: 'twilio', options: { accountSid: 'a', authToken: 'b', from: '+1' } }))
+      .toBeInstanceOf(TwilioSmsTransport);
+    expect(() => makeSmsTransport({ provider: 'nope' as any })).toThrow(/unknown provider/);
+  });
+});

package/src/transports/twilio.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ISmsTransport, NormalizedSmsMessage, SmsTransportSendResult } from '@objectstack/spec/contracts';
+
+export interface TwilioSmsTransportOptions {
+  accountSid: string;
+  authToken: string;
+  /** Sender number (E.164). One of `from` / `messagingServiceSid` is required. */
+  from?: string;
+  /** Twilio Messaging Service SID (alternative to a fixed `from` number). */
+  messagingServiceSid?: string;
+  /** API base URL override (tests). Default `https://api.twilio.com`. */
+  baseUrl?: string;
+  /** Injectable fetch for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Twilio Programmable Messaging transport — a single `POST
+ * /2010-04-01/Accounts/{sid}/Messages.json` with HTTP Basic auth. Plain
+ * `fetch`, no vendor SDK. Free-form: delivers `body` verbatim.
+ */
+export class TwilioSmsTransport implements ISmsTransport {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly options: TwilioSmsTransportOptions) {
+    if (!options.accountSid || !options.authToken) {
+      throw new Error('TwilioSmsTransport: accountSid and authToken are required');
+    }
+    if (!options.from && !options.messagingServiceSid) {
+      throw new Error('TwilioSmsTransport: one of from / messagingServiceSid is required');
+    }
+    this.baseUrl = (options.baseUrl ?? 'https://api.twilio.com').replace(/\/$/, '');
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  async send(message: NormalizedSmsMessage): Promise<SmsTransportSendResult> {
+    const form = new URLSearchParams({
+      To: message.to,
+      Body: message.body,
+      ...(this.options.messagingServiceSid
+        ? { MessagingServiceSid: this.options.messagingServiceSid }
+        : { From: this.options.from as string }),
+    });
+    const auth = Buffer.from(`${this.options.accountSid}:${this.options.authToken}`).toString('base64');
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/2010-04-01/Accounts/${encodeURIComponent(this.options.accountSid)}/Messages.json`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Basic ${auth}`,
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: form.toString(),
+      },
+    );
+
+    let payload: any = {};
+    try { payload = await response.json(); } catch { /* non-JSON error body */ }
+    if (!response.ok) {
+      const code = payload?.code ?? `HTTP_${response.status}`;
+      const detail = payload?.message ?? response.statusText ?? 'request failed';
+      throw new Error(`Twilio send failed (${code}): ${detail}`);
+    }
+    return { messageId: String(payload.sid ?? ''), response: payload.status };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}