feat(routing): add rule-based SIP routing for inbound and outbound calls with dashboard route management

ts/config.ts

@@ -39,10 +39,85 @@ export interface IDeviceConfig {
   extension: string;
 }
 
+// ---------------------------------------------------------------------------
+// Match/Action routing model
+// ---------------------------------------------------------------------------
+
+/**
+ * Criteria for matching a call to a route.
+ * All specified fields must match (AND logic).
+ * Omitted fields are wildcards (match anything).
+ */
+export interface ISipRouteMatch {
+  /** Whether this route applies to inbound or outbound calls. */
+  direction: 'inbound' | 'outbound';
+
+  /**
+   * Match the dialed/called number (To/Request-URI for inbound DID, dialed digits for outbound).
+   * Supports: exact string, prefix with trailing '*' (e.g. "+4930*"), or regex ("/^\\+49/").
+   */
+  numberPattern?: string;
+
+  /** Match caller ID / From number (same pattern syntax). */
+  callerPattern?: string;
+
+  /** For inbound: match by source provider ID. */
+  sourceProvider?: string;
+
+  /** For outbound: match by source device ID (or 'browser' for browser devices). */
+  sourceDevice?: string;
+}
+
+/** What to do when a route matches. */
+export interface ISipRouteAction {
+  // --- Inbound actions (ring targets) ---
+
+  /** Device IDs to ring. Empty/omitted = ring all devices. */
+  targets?: string[];
+
+  /** Also ring connected browser clients. Default false. */
+  ringBrowsers?: boolean;
+
+  // --- Outbound actions (provider selection) ---
+
+  /** Provider ID to use for outbound. */
+  provider?: string;
+
+  /** Failover provider IDs, tried in order if primary is unregistered. */
+  failoverProviders?: string[];
+
+  // --- Number transformation (outbound) ---
+
+  /** Strip this prefix from the dialed number before sending to provider. */
+  stripPrefix?: string;
+
+  /** Prepend this prefix to the dialed number before sending to provider. */
+  prependPrefix?: string;
+}
+
+/** A single routing rule — the core unit of the match/action model. */
+export interface ISipRoute {
+  /** Unique identifier for this route. */
+  id: string;
+
+  /** Human-readable name shown in the UI. */
+  name: string;
+
+  /** Higher priority routes are evaluated first. Default 0. */
+  priority: number;
+
+  /** Disabled routes are skipped during evaluation. Default true. */
+  enabled: boolean;
+
+  /** Criteria that a call must match for this route to apply. */
+  match: ISipRouteMatch;
+
+  /** What to do when the route matches. */
+  action: ISipRouteAction;
+}
+
 export interface IRoutingConfig {
-  outbound: { default: string };
-  inbound: Record<string, string[]>;
-  ringBrowsers?: Record<string, boolean>;
+  routes: ISipRoute[];
 }
 
 export interface IProxyConfig {
@@ -118,8 +193,9 @@ export function loadConfig(): IAppConfig {
     d.extension ??= '100';
   }
 
-  cfg.routing ??= { outbound: { default: cfg.providers[0].id }, inbound: {} };
-  cfg.routing.outbound ??= { default: cfg.providers[0].id };
+  cfg.routing ??= { routes: [] };
+  cfg.routing.routes ??= [];
+
   cfg.contacts ??= [];
   for (const c of cfg.contacts) {
     c.starred ??= false;
@@ -128,6 +204,141 @@ export function loadConfig(): IAppConfig {
   return cfg;
 }
 
+// ---------------------------------------------------------------------------
+// Pattern matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Test a value against a pattern string.
+ * - undefined/empty pattern: matches everything (wildcard)
+ * - Prefix: "pattern*" matches values starting with "pattern"
+ * - Regex: "/pattern/" or "/pattern/i" compiles as RegExp
+ * - Otherwise: exact match
+ */
+export function matchesPattern(pattern: string | undefined, value: string): boolean {
+  if (!pattern) return true;
+
+  // Prefix match: "+49*"
+  if (pattern.endsWith('*')) {
+    return value.startsWith(pattern.slice(0, -1));
+  }
+
+  // Regex match: "/^\\+49/" or "/pattern/i"
+  if (pattern.startsWith('/')) {
+    const lastSlash = pattern.lastIndexOf('/');
+    if (lastSlash > 0) {
+      const re = new RegExp(pattern.slice(1, lastSlash), pattern.slice(lastSlash + 1));
+      return re.test(value);
+    }
+  }
+
+  // Exact match.
+  return value === pattern;
+}
+
+// ---------------------------------------------------------------------------
+// Route resolution
+// ---------------------------------------------------------------------------
+
+/** Result of resolving an outbound route. */
+export interface IOutboundRouteResult {
+  provider: IProviderConfig;
+  transformedNumber: string;
+}
+
+/** Result of resolving an inbound route. */
+export interface IInboundRouteResult {
+  /** Device IDs to ring (empty = all devices). */
+  deviceIds: string[];
+  ringBrowsers: boolean;
+}
+
+/**
+ * Resolve which provider to use for an outbound call, and transform the number.
+ *
+ * @param cfg - app config
+ * @param dialedNumber - the number being dialed
+ * @param sourceDeviceId - optional device originating the call
+ * @param isProviderRegistered - callback to check if a provider is currently registered
+ */
+export function resolveOutboundRoute(
+  cfg: IAppConfig,
+  dialedNumber: string,
+  sourceDeviceId?: string,
+  isProviderRegistered?: (providerId: string) => boolean,
+): IOutboundRouteResult | null {
+  const routes = cfg.routing.routes
+    .filter((r) => r.enabled && r.match.direction === 'outbound')
+    .sort((a, b) => b.priority - a.priority);
+
+  for (const route of routes) {
+    const m = route.match;
+
+    if (!matchesPattern(m.numberPattern, dialedNumber)) continue;
+    if (m.sourceDevice && m.sourceDevice !== sourceDeviceId) continue;
+
+    // Find a registered provider (primary + failovers).
+    const candidates = [route.action.provider, ...(route.action.failoverProviders || [])].filter(Boolean) as string[];
+    for (const pid of candidates) {
+      const provider = getProvider(cfg, pid);
+      if (!provider) continue;
+      if (isProviderRegistered && !isProviderRegistered(pid)) continue;
+
+      // Apply number transformation.
+      let num = dialedNumber;
+      if (route.action.stripPrefix && num.startsWith(route.action.stripPrefix)) {
+        num = num.slice(route.action.stripPrefix.length);
+      }
+      if (route.action.prependPrefix) {
+        num = route.action.prependPrefix + num;
+      }
+
+      return { provider, transformedNumber: num };
+    }
+
+    // Route matched but no provider is available — continue to next route.
+  }
+
+  // Fallback: first available provider.
+  const fallback = cfg.providers[0];
+  return fallback ? { provider: fallback, transformedNumber: dialedNumber } : null;
+}
+
+/**
+ * Resolve which devices/browsers to ring for an inbound call.
+ *
+ * @param cfg - app config
+ * @param providerId - the provider the call is coming from
+ * @param calledNumber - the DID / called number (from Request-URI)
+ * @param callerNumber - the caller ID (from From header)
+ */
+export function resolveInboundRoute(
+  cfg: IAppConfig,
+  providerId: string,
+  calledNumber: string,
+  callerNumber: string,
+): IInboundRouteResult {
+  const routes = cfg.routing.routes
+    .filter((r) => r.enabled && r.match.direction === 'inbound')
+    .sort((a, b) => b.priority - a.priority);
+
+  for (const route of routes) {
+    const m = route.match;
+
+    if (m.sourceProvider && m.sourceProvider !== providerId) continue;
+    if (!matchesPattern(m.numberPattern, calledNumber)) continue;
+    if (!matchesPattern(m.callerPattern, callerNumber)) continue;
+
+    return {
+      deviceIds: route.action.targets || [],
+      ringBrowsers: route.action.ringBrowsers ?? false,
+    };
+  }
+
+  // Fallback: ring all devices + browsers.
+  return { deviceIds: [], ringBrowsers: true };
+}
+
 // ---------------------------------------------------------------------------
 // Lookup helpers
 // ---------------------------------------------------------------------------
@@ -140,14 +351,19 @@ export function getDevice(cfg: IAppConfig, id: string): IDeviceConfig | null {
   return cfg.devices.find((d) => d.id === id) ?? null;
 }
 
+/**
+ * @deprecated Use resolveOutboundRoute() instead. Kept for backward compat.
+ */
 export function getProviderForOutbound(cfg: IAppConfig): IProviderConfig | null {
-  const id = cfg.routing?.outbound?.default;
-  if (!id) return cfg.providers[0] || null;
-  return getProvider(cfg, id) || cfg.providers[0] || null;
+  const result = resolveOutboundRoute(cfg, '');
+  return result?.provider ?? null;
 }
 
+/**
+ * @deprecated Use resolveInboundRoute() instead. Kept for backward compat.
+ */
 export function getDevicesForInbound(cfg: IAppConfig, providerId: string): IDeviceConfig[] {
-  const ids = cfg.routing.inbound[providerId];
-  if (!ids?.length) return cfg.devices; // fallback: ring all devices
-  return ids.map((id) => getDevice(cfg, id)).filter(Boolean) as IDeviceConfig[];
+  const result = resolveInboundRoute(cfg, providerId, '', '');
+  if (!result.deviceIds.length) return cfg.devices;
+  return result.deviceIds.map((id) => getDevice(cfg, id)).filter(Boolean) as IDeviceConfig[];
 }