@objectstack/service-sms 14.5.0

package/src/sms-plugin.test.ts

@@ -0,0 +1,155 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import { SmsServicePlugin } from './sms-plugin.js';
+import { SmsService, LogSmsTransport } from './sms-service.js';
+import { AliyunSmsTransport, TwilioSmsTransport } from './transports/index.js';
+
+/**
+ * Lightweight fake PluginContext (service registry + kernel:ready hooks +
+ * a fake settings service) — mirrors the messaging plugin's test harness.
+ */
+function fakeCtx(opts: { settingsValues?: Record<string, unknown> } = {}) {
+  const services = new Map<string, unknown>();
+  const readyHooks: Array<() => Promise<void> | void> = [];
+  const actions = new Map<string, (input: any) => Promise<any>>();
+  const subscriptions: Array<{ ns: string; fn: () => void }> = [];
+  let values = opts.settingsValues;
+
+  if (values !== undefined) {
+    services.set('settings', {
+      async getNamespace(ns: string) {
+        if (ns !== 'sms') throw new Error('unknown namespace');
+        const wrapped: Record<string, { value: unknown }> = {};
+        for (const [k, v] of Object.entries(values ?? {})) wrapped[k] = { value: v };
+        return { values: wrapped };
+      },
+      subscribe(ns: string, fn: () => void) { subscriptions.push({ ns, fn }); return () => {}; },
+      registerAction(ns: string, id: string, fn: (input: any) => Promise<any>) {
+        actions.set(`${ns}/${id}`, fn);
+      },
+    });
+  }
+
+  const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+  const ctx = {
+    logger,
+    registerService(name: string, svc: unknown) { services.set(name, svc); },
+    getService(name: string) {
+      if (!services.has(name)) throw new Error(`service not found: ${name}`);
+      return services.get(name);
+    },
+    hook(event: string, fn: () => Promise<void> | void) {
+      if (event === 'kernel:ready') readyHooks.push(fn);
+    },
+  } as any;
+
+  return {
+    ctx,
+    services,
+    logger,
+    actions,
+    setValues: (v: Record<string, unknown>) => { values = v; },
+    notifyChange: async () => { for (const s of subscriptions) s.fn(); await new Promise((r) => setTimeout(r, 0)); },
+    fireReady: async () => { for (const fn of readyHooks) await fn(); },
+  };
+}
+
+describe('SmsServicePlugin', () => {
+  it('registers the sms service with the log fallback (unconfigured)', async () => {
+    const { ctx, services } = fakeCtx();
+    await new SmsServicePlugin().init(ctx);
+    const svc = services.get('sms') as SmsService;
+    expect(svc).toBeInstanceOf(SmsService);
+    expect(svc.isConfigured()).toBe(false);
+    expect(svc.options.transport).toBeInstanceOf(LogSmsTransport);
+  });
+
+  it('builds a provider transport from constructor options', async () => {
+    const { ctx, services } = fakeCtx();
+    await new SmsServicePlugin({
+      provider: 'twilio',
+      providerOptions: { accountSid: 'AC1', authToken: 't', from: '+15005550006' },
+    }).init(ctx);
+    const svc = services.get('sms') as SmsService;
+    expect(svc.isConfigured()).toBe(true);
+    expect(svc.options.transport).toBeInstanceOf(TwilioSmsTransport);
+  });
+
+  it('falls back to log (not a boot failure) on incomplete constructor credentials', async () => {
+    const { ctx, services, logger } = fakeCtx();
+    await new SmsServicePlugin({ provider: 'aliyun', providerOptions: {} }).init(ctx);
+    const svc = services.get('sms') as SmsService;
+    expect(svc.isConfigured()).toBe(false);
+    expect(logger.warn).toHaveBeenCalled();
+  });
+
+  it('rebuilds the transport from the sms settings namespace at kernel:ready', async () => {
+    const harness = fakeCtx({
+      settingsValues: {
+        provider: 'aliyun',
+        aliyun_access_key_id: 'ak',
+        aliyun_access_key_secret: 'sec',
+        aliyun_sign_name: '签名',
+        aliyun_template_code: 'SMS_1',
+      },
+    });
+    const plugin = new SmsServicePlugin();
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    await harness.fireReady();
+
+    const svc = harness.services.get('sms') as SmsService;
+    expect(svc.isConfigured()).toBe(true);
+    expect(svc.options.transport).toBeInstanceOf(AliyunSmsTransport);
+  });
+
+  it('keeps the previous transport when settings are incomplete', async () => {
+    const harness = fakeCtx({ settingsValues: { provider: 'twilio', twilio_account_sid: 'AC1' } });
+    const plugin = new SmsServicePlugin();
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    await harness.fireReady();
+
+    const svc = harness.services.get('sms') as SmsService;
+    expect(svc.isConfigured()).toBe(false);
+    expect(svc.options.transport).toBeInstanceOf(LogSmsTransport);
+  });
+
+  it('live-applies settings changes via subscribe', async () => {
+    const harness = fakeCtx({ settingsValues: { provider: 'log' } });
+    const plugin = new SmsServicePlugin();
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    await harness.fireReady();
+
+    const svc = harness.services.get('sms') as SmsService;
+    expect(svc.isConfigured()).toBe(false);
+
+    harness.setValues({
+      provider: 'twilio',
+      twilio_account_sid: 'AC1',
+      twilio_auth_token: 'tok',
+      twilio_from_number: '+15005550006',
+    });
+    await harness.notifyChange();
+    expect(svc.isConfigured()).toBe(true);
+    expect(svc.options.transport).toBeInstanceOf(TwilioSmsTransport);
+  });
+
+  it('registers an sms/test action that validates the recipient', async () => {
+    const harness = fakeCtx({ settingsValues: { provider: 'log' } });
+    const plugin = new SmsServicePlugin();
+    await plugin.init(harness.ctx);
+    await plugin.start(harness.ctx);
+    await harness.fireReady();
+
+    const test = harness.actions.get('sms/test');
+    expect(test).toBeDefined();
+    const bad = await test!({ values: { provider: 'log' }, payload: { to: 'not-a-phone' }, ctx: {} });
+    expect(bad.ok).toBe(false);
+    const good = await test!({ values: { provider: 'log' }, payload: { to: '+15005550006' }, ctx: {} });
+    expect(good.ok).toBe(true);
+    expect(good.message).not.toContain('5550006'); // masked
+  });
+});

package/src/sms-plugin.ts

@@ -0,0 +1,252 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { ISmsTransport } from '@objectstack/spec/contracts';
+import { SmsService, LogSmsTransport, maskPhoneNumber, normalizeSmsRecipient } from './sms-service.js';
+import { makeSmsTransport, type SmsProviderTag } from './transports/index.js';
+
+/**
+ * Plugin configuration. Mirrors EmailServicePluginOptions: a directly
+ * injected transport wins, then `provider` + credentials, then the
+ * development `LogSmsTransport` fallback (no real send).
+ */
+export interface SmsServicePluginOptions {
+  /** Pluggable delivery transport. Overrides `provider`/credentials. */
+  transport?: ISmsTransport;
+  /** Provider tag — `'log' | 'aliyun' | 'twilio'`. Default `'log'`. */
+  provider?: SmsProviderTag;
+  /** Provider-specific credentials/options (see transport option types). */
+  providerOptions?: Record<string, unknown>;
+  /** Retry attempts on transport throw. Default 0. */
+  retries?: number;
+}
+
+/** Translate an `sms` settings-namespace snapshot into transport inputs. */
+function providerFromSettings(values: Record<string, unknown>): {
+  provider: SmsProviderTag;
+  options: Record<string, unknown>;
+  missing?: string;
+} {
+  const provider = String(values.provider ?? 'log') as SmsProviderTag;
+  const str = (k: string): string | undefined => {
+    const v = values[k];
+    return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+  };
+  if (provider === 'aliyun') {
+    const accessKeyId = str('aliyun_access_key_id');
+    const accessKeySecret = str('aliyun_access_key_secret');
+    const signName = str('aliyun_sign_name');
+    if (!accessKeyId || !accessKeySecret || !signName) {
+      return { provider, options: {}, missing: 'aliyun_access_key_id / aliyun_access_key_secret / aliyun_sign_name' };
+    }
+    return {
+      provider,
+      options: {
+        accessKeyId,
+        accessKeySecret,
+        signName,
+        ...(str('aliyun_template_code') ? { defaultTemplateCode: str('aliyun_template_code') } : {}),
+      },
+    };
+  }
+  if (provider === 'twilio') {
+    const accountSid = str('twilio_account_sid');
+    const authToken = str('twilio_auth_token');
+    const from = str('twilio_from_number');
+    const messagingServiceSid = str('twilio_messaging_service_sid');
+    if (!accountSid || !authToken || (!from && !messagingServiceSid)) {
+      return { provider, options: {}, missing: 'twilio_account_sid / twilio_auth_token / twilio_from_number (or messaging service SID)' };
+    }
+    return {
+      provider,
+      options: {
+        accountSid,
+        authToken,
+        ...(from ? { from } : {}),
+        ...(messagingServiceSid ? { messagingServiceSid } : {}),
+      },
+    };
+  }
+  return { provider: 'log', options: {} };
+}
+
+/**
+ * SmsServicePlugin — registers the `sms` service (#2780).
+ *
+ * Lifecycle:
+ *   - `init`: build transport (injected → provider+credentials →
+ *     LogSmsTransport fallback); register the SmsService so dependents
+ *     (auth OTP, the messaging `sms` channel) can resolve it.
+ *   - `start` (kernel:ready): bind the `sms` settings namespace so the
+ *     admin UI can live-swap the provider without a restart, and register
+ *     the `sms/test` action. Env-locked keys (OS_SMS_*) still win at the
+ *     settings-resolver level.
+ *
+ * Deliberately NO persistence objects: SMS bodies carry OTP codes — see the
+ * ISmsService contract header.
+ */
+export class SmsServicePlugin implements Plugin {
+  name = 'com.objectstack.service.sms';
+  version = '1.0.0';
+  type = 'standard' as const;
+
+  private readonly options: SmsServicePluginOptions;
+  private service?: SmsService;
+
+  constructor(options: SmsServicePluginOptions = {}) {
+    this.options = options;
+  }
+
+  private resolveInitialTransport(ctx: PluginContext): { transport: ISmsTransport; configured: boolean } {
+    if (this.options.transport) return { transport: this.options.transport, configured: true };
+    const provider = this.options.provider ?? 'log';
+    if (provider === 'log') return { transport: new LogSmsTransport(ctx.logger), configured: false };
+    try {
+      return {
+        transport: makeSmsTransport({ provider, options: this.options.providerOptions, logger: ctx.logger }),
+        configured: true,
+      };
+    } catch (err: any) {
+      // Incomplete constructor credentials must not take the kernel down —
+      // fall back to the dev transport; the settings bind (kernel:ready)
+      // can still swap in a working provider.
+      ctx.logger.warn(
+        `SmsServicePlugin: provider='${provider}' selected but transport build failed (${err?.message ?? err}) — falling back to LogSmsTransport.`,
+      );
+      return { transport: new LogSmsTransport(ctx.logger), configured: false };
+    }
+  }
+
+  async init(ctx: PluginContext): Promise<void> {
+    const { transport, configured } = this.resolveInitialTransport(ctx);
+    if (!configured) {
+      ctx.logger.info('SmsServicePlugin: no provider configured — using LogSmsTransport (SMS will NOT be sent)');
+    } else {
+      ctx.logger.info(`SmsServicePlugin: using '${this.options.provider ?? 'custom'}' provider`);
+    }
+    this.service = new SmsService({
+      transport,
+      configured,
+      retries: this.options.retries,
+      logger: ctx.logger,
+    });
+    ctx.registerService('sms', this.service);
+    ctx.logger.info('SmsServicePlugin: sms service registered');
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    ctx.hook('kernel:ready', async () => {
+      if (!this.service) return;
+      // A host-injected transport is authoritative — settings only manage
+      // the provider-tag path.
+      if (this.options.transport) return;
+      try {
+        const settings = ctx.getService<any>('settings');
+        if (!settings || typeof settings.getNamespace !== 'function') return;
+
+        const applySettings = async () => {
+          try {
+            const payload = await settings.getNamespace('sms');
+            const values: Record<string, unknown> = {};
+            for (const [k, v] of Object.entries(payload.values as Record<string, any>)) {
+              values[k] = v?.value;
+            }
+            this.applySmsSettings(values, ctx);
+          } catch (err: any) {
+            ctx.logger.warn('SmsServicePlugin: failed to apply sms settings: ' + (err?.message ?? err));
+          }
+        };
+        await applySettings();
+        if (typeof settings.subscribe === 'function') {
+          settings.subscribe('sms', () => { void applySettings(); });
+          ctx.logger.info('SmsServicePlugin: bound to settings:changed for namespace=sms');
+        }
+
+        // `sms/test` action — validate the (possibly unsaved) form values by
+        // sending a real test message through a one-shot transport, mirroring
+        // the `mail/test` handler in EmailServicePlugin.
+        if (typeof settings.registerAction === 'function') {
+          const svc = this.service;
+          settings.registerAction('sms', 'test', async ({ values, payload, ctx: actionCtx }: any) => {
+            const overrides = (payload && typeof payload === 'object' && payload.values && typeof payload.values === 'object')
+              ? payload.values
+              : (payload ?? {});
+            const merged: Record<string, unknown> = { ...(values ?? {}), ...overrides };
+            const rawTo = (actionCtx?.body?.to as string | undefined) ?? (payload?.to as string | undefined);
+            const to = rawTo ? normalizeSmsRecipient(rawTo) : undefined;
+            if (!to) {
+              return { ok: false, severity: 'error', message: 'Provide a valid "to" phone number (E.164 recommended).' };
+            }
+
+            const resolved = providerFromSettings(merged);
+            if (resolved.missing) {
+              return { ok: false, severity: 'error', message: `${resolved.provider}: missing ${resolved.missing}.` };
+            }
+
+            let target: SmsService = svc;
+            if (resolved.provider !== 'log') {
+              try {
+                const transport = makeSmsTransport({ provider: resolved.provider, options: resolved.options, logger: ctx.logger });
+                target = new SmsService({ transport, configured: true, logger: ctx.logger });
+              } catch (err: any) {
+                return { ok: false, severity: 'error', message: `Failed to build ${resolved.provider} transport: ${err?.message ?? String(err)}` };
+              }
+            }
+
+            try {
+              const result = await target.send({
+                to,
+                body: 'ObjectStack SMS test message.',
+                templateParams: { content: 'ObjectStack SMS test message.' },
+              });
+              if (result.status === 'failed') {
+                return { ok: false, severity: 'error', message: result.error ?? 'Send failed.' };
+              }
+              return {
+                ok: true,
+                severity: 'info',
+                message: `Sent test SMS to ${maskPhoneNumber(to)} via ${resolved.provider} (id=${result.messageId ?? result.id}).`,
+              };
+            } catch (err: any) {
+              return { ok: false, severity: 'error', message: err?.message ?? String(err) };
+            }
+          });
+        }
+      } catch {
+        // settings service not registered — constructor opts remain authoritative.
+      }
+    });
+  }
+
+  /**
+   * Translate the `sms` settings snapshot into a transport and hot-swap it
+   * on the running SmsService. Incomplete credentials keep the previous
+   * transport (with a warning) so a half-saved form can't break delivery.
+   */
+  private applySmsSettings(values: Record<string, unknown>, ctx: PluginContext): void {
+    if (!this.service) return;
+    const resolved = providerFromSettings(values);
+    if (resolved.missing) {
+      ctx.logger.warn(
+        `SmsServicePlugin: provider='${resolved.provider}' selected but ${resolved.missing} is empty — transport NOT rebuilt.`,
+      );
+      return;
+    }
+    if (resolved.provider === 'log') {
+      // Downgrade to the dev transport only when the operator explicitly
+      // selected `log`; an unset namespace keeps the constructor opts.
+      if (values.provider === 'log') {
+        this.service.setTransport(new LogSmsTransport(ctx.logger), false);
+        ctx.logger.info('SmsServicePlugin: sms settings applied (provider=log; SMS will NOT be sent).');
+      }
+      return;
+    }
+    try {
+      const transport = makeSmsTransport({ provider: resolved.provider, options: resolved.options, logger: ctx.logger });
+      this.service.setTransport(transport, true);
+      ctx.logger.info(`SmsServicePlugin: transport rebuilt from settings (provider=${resolved.provider}).`);
+    } catch (err: any) {
+      ctx.logger.warn('SmsServicePlugin: failed to rebuild transport: ' + (err?.message ?? err));
+    }
+  }
+}

package/src/sms-service.test.ts

@@ -0,0 +1,129 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import { SmsService, LogSmsTransport, maskPhoneNumber, normalizeSmsRecipient } from './sms-service.js';
+
+const collectingLogger = () => {
+  const lines: string[] = [];
+  return {
+    lines,
+    info: (msg: string) => { lines.push(String(msg)); },
+    warn: (msg: string) => { lines.push(String(msg)); },
+  };
+};
+
+describe('normalizeSmsRecipient', () => {
+  it('accepts E.164 and strips human separators', () => {
+    expect(normalizeSmsRecipient('+8613800000000')).toBe('+8613800000000');
+    expect(normalizeSmsRecipient('+1 (500) 555-0006')).toBe('+15005550006');
+    expect(normalizeSmsRecipient('138 0000 0000')).toBe('13800000000');
+  });
+  it('rejects garbage', () => {
+    expect(normalizeSmsRecipient('bob@example.com')).toBeUndefined();
+    expect(normalizeSmsRecipient('123')).toBeUndefined();
+    expect(normalizeSmsRecipient('')).toBeUndefined();
+  });
+});
+
+describe('maskPhoneNumber', () => {
+  it('keeps prefix + last two digits only', () => {
+    const masked = maskPhoneNumber('+8613812345678');
+    expect(masked.startsWith('+8613')).toBe(true);
+    expect(masked.endsWith('78')).toBe(true);
+    expect(masked).not.toContain('12345');
+  });
+});
+
+describe('SmsService', () => {
+  it('sends through the transport and reports the provider id', async () => {
+    const send = vi.fn(async () => ({ messageId: 'prov_1' }));
+    const svc = new SmsService({ transport: { send }, configured: true });
+    const r = await svc.send({ to: '+15005550006', body: 'hello' });
+    expect(r.status).toBe('sent');
+    expect(r.messageId).toBe('prov_1');
+    expect(send).toHaveBeenCalledWith({ to: '+15005550006', body: 'hello' });
+  });
+
+  it('throws on an invalid recipient BEFORE the transport is called', async () => {
+    const send = vi.fn();
+    const svc = new SmsService({ transport: { send }, configured: true });
+    await expect(svc.send({ to: 'not-a-phone', body: 'x' })).rejects.toThrow(/VALIDATION_FAILED/);
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('resolves status:failed (not a throw) on transport errors', async () => {
+    const svc = new SmsService({
+      transport: { async send() { throw new Error('provider down'); } },
+      configured: true,
+    });
+    const r = await svc.send({ to: '+15005550006', body: 'x' });
+    expect(r.status).toBe('failed');
+    expect(r.error).toContain('provider down');
+  });
+
+  it('retries on transport throw when retries > 0', async () => {
+    let calls = 0;
+    const svc = new SmsService({
+      transport: { async send() { if (++calls < 2) throw new Error('flaky'); return { messageId: 'ok' }; } },
+      configured: true,
+      retries: 1,
+    });
+    const r = await svc.send({ to: '+15005550006', body: 'x' });
+    expect(r.status).toBe('sent');
+    expect(calls).toBe(2);
+  });
+
+  it('never logs the message body (OTP red line, #2780)', async () => {
+    const logger = collectingLogger();
+    const svc = new SmsService({
+      transport: { async send() { return { messageId: 'prov_1' }; } },
+      configured: true,
+      logger,
+    });
+    await svc.send({ to: '+8613812345678', body: '123456 is your code' });
+    // also exercise the failure path
+    svc.setTransport({ async send() { throw new Error('down'); } }, true);
+    await svc.send({ to: '+8613812345678', body: '654321 is your code' });
+    for (const line of logger.lines) {
+      expect(line).not.toContain('123456');
+      expect(line).not.toContain('654321');
+      expect(line).not.toContain('13812345678'); // full number masked too
+    }
+  });
+
+  it('surfaces isConfigured / setTransport upgrades', async () => {
+    const svc = new SmsService({ transport: new LogSmsTransport(), configured: false });
+    expect(svc.isConfigured()).toBe(false);
+    svc.setTransport({ async send() { return { messageId: 'x' }; } }, true);
+    expect(svc.isConfigured()).toBe(true);
+  });
+});
+
+describe('LogSmsTransport', () => {
+  it('suppresses the body in production', async () => {
+    const logger = collectingLogger();
+    const transport = new LogSmsTransport(logger);
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      await transport.send({ to: '+8613812345678', body: 'SECRET-999999' });
+    } finally {
+      process.env.NODE_ENV = prev;
+    }
+    expect(logger.lines.join('\n')).not.toContain('SECRET-999999');
+    expect(logger.lines.join('\n')).toContain('body suppressed');
+  });
+
+  it('prints the body outside production (local OTP testing)', async () => {
+    const logger = collectingLogger();
+    const transport = new LogSmsTransport(logger);
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'test';
+    try {
+      await transport.send({ to: '+8613812345678', body: 'code 424242' });
+    } finally {
+      process.env.NODE_ENV = prev;
+    }
+    expect(logger.lines.join('\n')).toContain('code 424242');
+  });
+});

package/src/sms-service.ts

@@ -0,0 +1,144 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  ISmsService,
+  ISmsTransport,
+  NormalizedSmsMessage,
+  SendSmsInput,
+  SendSmsResult,
+  SmsTransportSendResult,
+} from '@objectstack/spec/contracts';
+
+/**
+ * Normalize + validate a recipient phone number. Accepts E.164 and common
+ * human formats (spaces / dashes / dots / parens are stripped). Returns
+ * `undefined` when the result doesn't look like a phone number.
+ *
+ * Same shape rule as plugin-auth's `normalizePhoneNumber` — 6-15 digits
+ * with an optional leading `+` (kept local: the two packages must not
+ * depend on each other).
+ */
+export function normalizeSmsRecipient(raw: string): string | undefined {
+  const stripped = String(raw ?? '').replace(/[\s\-().]/g, '');
+  return /^\+?[0-9]{6,15}$/.test(stripped) ? stripped : undefined;
+}
+
+/**
+ * Mask a phone number for log lines: keep the prefix (country-code-ish) and
+ * the last two digits, hide the middle. `+8613812345678` → `+8613******78`.
+ * SMS logging policy: masked recipient + status ONLY — never the body
+ * (OTP codes travel in it; see the ISmsService contract header).
+ */
+export function maskPhoneNumber(phone: string): string {
+  const p = String(phone ?? '');
+  if (p.length <= 6) return `${p.slice(0, 2)}****`;
+  return `${p.slice(0, 5)}${'*'.repeat(Math.max(2, p.length - 7))}${p.slice(-2)}`;
+}
+
+/**
+ * Development transport — never actually sends. Logs the masked recipient
+ * (and, OUTSIDE production only, the message body so local OTP flows are
+ * testable) and returns a synthetic message id.
+ *
+ * The production-body suppression is a hard rule from #2780: OTP codes must
+ * never land in logs. In dev the body IS the delivery — same pattern as the
+ * auth magic-link / invitation URLs, which are printed in dev only.
+ */
+export class LogSmsTransport implements ISmsTransport {
+  private counter = 0;
+  constructor(private readonly logger?: { info: (msg: string, meta?: any) => void }) {}
+  async send(message: NormalizedSmsMessage): Promise<SmsTransportSendResult> {
+    const messageId = `dev-sms-${Date.now()}-${++this.counter}`;
+    const dev = (globalThis as any)?.process?.env?.NODE_ENV !== 'production';
+    this.logger?.info(
+      `[LogSmsTransport] would send SMS to ${maskPhoneNumber(message.to)}` +
+      (dev ? ` — body: ${message.body}` : ' (body suppressed outside dev)'),
+      { messageId },
+    );
+    return { messageId, response: 'logged' };
+  }
+}
+
+export interface SmsServiceOptions {
+  transport: ISmsTransport;
+  /**
+   * Whether `transport` is a real provider (Aliyun / Twilio / injected).
+   * `false` = development log fallback; surfaced via `isConfigured()` so
+   * consumers can gate SMS-dependent features in production.
+   */
+  configured: boolean;
+  /** Retry attempts on transport throw. Default 0 (no retry). */
+  retries?: number;
+  /** Logger for diagnostic output. NEVER receives message bodies. */
+  logger?: {
+    info: (msg: string, meta?: any) => void;
+    warn: (msg: string, meta?: any) => void;
+  };
+}
+
+/**
+ * Concrete ISmsService implementation.
+ *
+ * Flow: validate + normalize input → transport.send() (with optional
+ * retry) → SendSmsResult. Deliberately NO persistence and NO body logging —
+ * see the contract header in `@objectstack/spec/contracts/sms-service.ts`.
+ */
+export class SmsService implements ISmsService {
+  constructor(public options: SmsServiceOptions) {
+    if (!options.transport) throw new Error('SmsService: transport is required');
+  }
+
+  /**
+   * Hot-swap the underlying transport (settings namespace changed). The
+   * `configured` flag travels with the transport.
+   */
+  setTransport(transport: ISmsTransport, configured: boolean): void {
+    this.options.transport = transport;
+    this.options.configured = configured;
+  }
+
+  isConfigured(): boolean {
+    return this.options.configured;
+  }
+
+  async send(input: SendSmsInput): Promise<SendSmsResult> {
+    const to = normalizeSmsRecipient(input?.to ?? '');
+    if (!to) {
+      throw new Error(`VALIDATION_FAILED: '${maskPhoneNumber(String(input?.to ?? ''))}' is not a valid phone number`);
+    }
+    const body = String(input?.body ?? '').trim();
+    if (!body && !input?.templateId && !input?.templateParams) {
+      throw new Error('VALIDATION_FAILED: body (or templateId/templateParams) is required');
+    }
+
+    const normalized: NormalizedSmsMessage = {
+      to,
+      body,
+      ...(input.templateId ? { templateId: input.templateId } : {}),
+      ...(input.templateParams ? { templateParams: input.templateParams } : {}),
+    };
+
+    const id = `sms-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    const maxAttempts = (this.options.retries ?? 0) + 1;
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const result = await this.options.transport.send(normalized);
+        this.options.logger?.info(
+          `[SmsService] sent to ${maskPhoneNumber(to)} (messageId=${result.messageId})`,
+        );
+        return { id, status: 'sent', messageId: result.messageId };
+      } catch (err) {
+        lastError = err;
+        if (attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, Math.min(2000, 100 * 2 ** (attempt - 1))));
+        }
+      }
+    }
+    const errMessage = String((lastError as Error)?.message ?? lastError ?? 'send failed').slice(0, 500);
+    this.options.logger?.warn(
+      `[SmsService] send to ${maskPhoneNumber(to)} failed: ${errMessage}`,
+    );
+    return { id, status: 'failed', error: errMessage };
+  }
+}