@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/notifications/sms/services/sms.backend.service.d.ts

@@ -3,9 +3,9 @@
  *
  * Main service for sending SMS messages. Orchestrates:
  * - Provider resolution via ExternalProvidersRegistryBackendService
- * - Request transformation via SMSFeature
+ * - The provider's own `SMS_PROVIDER` runtime contract, read from the registry, which supplies the
+ *   endpoint and the request/response projection
  * - Raw HTTP execution (Basic Auth for Twilio)
- * - Response parsing via SMSFeature
  *
  * Mirrors the pattern of EmailBackendService for consistency.
  */

package/dist/esm/notifications/sms/services/sms.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sms.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAEnH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAY1J,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD,qBACa,iBAAiB;IAIS,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IACd,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IANzG,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EAC3C,aAAa,EAAE,uBAAuB,EACtB,yBAAyB,EAAE,uCAAuC;IAKlJ;;;;;;OAMG;IACU,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6ClF;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0F1B;;;OAGG;YACW,sBAAsB;CAqDrC"}
+{"version":3,"file":"sms.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAEnH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAa1J,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD,qBACa,iBAAiB;IAIS,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IACd,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IANzG,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EAC3C,aAAa,EAAE,uBAAuB,EACtB,yBAAyB,EAAE,uCAAuC;IAKlJ;;;;;;OAMG;IACU,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6ClF;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA0F1B;;;OAGG;YACW,sBAAsB;CAqDrC"}

package/dist/esm/notifications/sms/services/sms.backend.service.js

@@ -3,9 +3,9 @@
  *
  * Main service for sending SMS messages. Orchestrates:
  * - Provider resolution via ExternalProvidersRegistryBackendService
- * - Request transformation via SMSFeature
+ * - The provider's own `SMS_PROVIDER` runtime contract, read from the registry, which supplies the
+ *   endpoint and the request/response projection
  * - Raw HTTP execution (Basic Auth for Twilio)
- * - Response parsing via SMSFeature
  *
  * Mirrors the pattern of EmailBackendService for consistency.
  */
@@ -25,7 +25,7 @@ import { injectable, inject } from 'inversify';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { describeCaughtError, projectCaughtErrorLogFields } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
 import { EngineCapability, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';
-import { ExternalProvider_ExchangeProtocol_Kind, } from '@wildo-ai/external-connectors-models';
+import { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
 function parseSMSCredentials(secretValue) {
     try {
         const parsed = JSON.parse(secretValue);
@@ -142,7 +142,7 @@ let SMSBackendService = class SMSBackendService {
             });
         }
         const smsContract = this.externalProvidersRegistry.getProviderRuntimeContract(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER);
-        if (smsContract?.kind !== 'sms') {
+        if (smsContract?.kind !== ProviderProtocolRuntimeKind.SMS) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
                 context: {
                     message: `No SMS_PROVIDER runtime contract found for provider: ${providerId}`,
@@ -151,7 +151,7 @@ let SMSBackendService = class SMSBackendService {
                 },
             });
         }
-        // The framework currently ships a single `kind: 'sms'` runtime
+        // The framework currently ships a single `kind: ProviderProtocolRuntimeKind.SMS` runtime
         // contract (Twilio). The execute-request path below assumes the
         // Twilio REST API shape (`/Accounts/{AccountSid}/Messages.json`,
         // Basic Auth, form-encoded body). When a second SMS adapter

package/dist/esm/notifications/sms/services/sms.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"sms.backend.service.js","sourceRoot":"","sources":["../../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * SMS Backend Service\n *\n * Main service for sending SMS messages. Orchestrates:\n * - Provider resolution via ExternalProvidersRegistryBackendService\n * - Request transformation via SMSFeature\n * - Raw HTTP execution (Basic Auth for Twilio)\n * - Response parsing via SMSFeature\n *\n * Mirrors the pattern of EmailBackendService for consistency.\n */\n\nimport { injectable, inject } from 'inversify';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { describeCaughtError, projectCaughtErrorLogFields } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';\nimport { EngineCapability, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';\nimport {\n  ExternalProvider_ExchangeProtocol_Kind,\n  type StandardSMS_SendRequest,\n  type StandardSMS_SendResponse,\n} from '@wildo-ai/external-connectors-models';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TYPES\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SMSSendResult {\n  success: boolean;\n  messageId?: string;\n  providerId?: string;\n  error?: string;\n}\n\ninterface SMSProviderConfig {\n  providerId: string;\n  accountSid: string;\n  authToken: string;\n  endpoint: string;\n  fromNumber?: string;\n}\n\nfunction parseSMSCredentials(secretValue: string): { accountSid: string; authToken: string } | null {\n  try {\n    const parsed = JSON.parse(secretValue) as {\n      accountSid?: unknown;\n      authToken?: unknown;\n    };\n    if (\n      typeof parsed.accountSid === 'string'\n      && parsed.accountSid.length > 0\n      && typeof parsed.authToken === 'string'\n      && parsed.authToken.length > 0\n    ) {\n      return {\n        accountSid: parsed.accountSid,\n        authToken: parsed.authToken,\n      };\n    }\n  } catch {\n    // Fallback below handles non-JSON encodings.\n  }\n\n  const [accountSid, authToken] = secretValue.includes('|')\n    ? secretValue.split('|', 2)\n    : secretValue.split(':', 2);\n  if (accountSid && authToken) {\n    return { accountSid, authToken };\n  }\n\n  return null;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SERVICE\n// ─────────────────────────────────────────────────────────────────────────────\n\n@injectable()\nexport class SMSBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly configService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('SMSBackendService');\n  }\n\n  /**\n   * Send an SMS message.\n   *\n   * @param to - Recipient phone number in E.164 format\n   * @param body - Message body\n   * @param from - Optional sender phone number (uses provider default if not set)\n   */\n  public async send(to: string, body: string, from?: string): Promise<SMSSendResult> {\n    const startTime = Date.now();\n\n    try {\n      // 1. Resolve SMS provider\n      const providerConfig = this.resolveSMSProvider();\n\n      // 2. Build standard request\n      const request: StandardSMS_SendRequest = {\n        to,\n        body,\n        from: from ?? providerConfig.fromNumber,\n      };\n\n      // 3. Execute via provider\n      const response = await this.executeProviderRequest(providerConfig, request);\n\n      const durationMs = Date.now() - startTime;\n      this.logDebug('SMS sent successfully', {\n        to,\n        providerId: providerConfig.providerId,\n        messageId: response.messageId,\n        durationMs,\n      });\n\n      return {\n        success: true,\n        messageId: response.messageId,\n        providerId: providerConfig.providerId,\n      };\n    } catch (error) {\n      const durationMs = Date.now() - startTime;\n      this.logger.error('Failed to send SMS', {\n        to,\n        ...projectCaughtErrorLogFields(error),\n        durationMs,\n      });\n\n      return {\n        success: false,\n        error: describeCaughtError(error),\n      };\n    }\n  }\n\n  /**\n   * Resolve the SMS provider for the SMS capability.\n   * Mirrors EmailBackendService.resolveEmailProvider() pattern.\n   */\n  private resolveSMSProvider(): SMSProviderConfig {\n    const providerId = this.externalProvidersRegistry.getPrimaryProviderForEngineCapability(EngineCapability.SMS);\n\n    if (!providerId) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        { context: { message: 'No SMS provider configured for capability: SMS', capability: EngineCapability.SMS } }\n      );\n    }\n\n    if (!this.externalProvidersRegistry.isProviderEnabled(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER)) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        { context: { message: `SMS provider is disabled by external provider configuration: ${providerId}`, providerId } },\n      );\n    }\n\n    const secretRef = this.externalProvidersRegistry.getConfiguredProviderSecretRef(\n      providerId,\n      ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n    );\n    const encodedCredentials = secretRef\n      ? this.externalProvidersRegistry.getProviderSecret(\n          providerId,\n          ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n          secretRef,\n        )\n      : undefined;\n    const parsedCredentials = encodedCredentials\n      ? parseSMSCredentials(encodedCredentials)\n      : null;\n\n    if (!parsedCredentials) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        {\n          context: {\n            message: `No env-provided credentials configured for SMS provider: ${providerId}`,\n            providerId,\n            capability: EngineCapability.SMS,\n            secretRef,\n          },\n        }\n      );\n    }\n\n    const smsContract = this.externalProvidersRegistry.getProviderRuntimeContract(\n      providerId,\n      ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n    );\n    if (smsContract?.kind !== 'sms') {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        {\n          context: {\n            message: `No SMS_PROVIDER runtime contract found for provider: ${providerId}`,\n            providerId,\n            capability: EngineCapability.SMS,\n          },\n        }\n      );\n    }\n    // The framework currently ships a single `kind: 'sms'` runtime\n    // contract (Twilio). The execute-request path below assumes the\n    // Twilio REST API shape (`/Accounts/{AccountSid}/Messages.json`,\n    // Basic Auth, form-encoded body). When a second SMS adapter\n    // arrives, factor the provider-specific request shape into the\n    // contract via `sdkFactory` / `buildSendPayload` (mirror of the\n    // email surface) — do NOT reintroduce a `provider === '<ref>'`\n    // literal at this consumer site.\n    const appConfig = this.configService.config as Record<string, unknown>;\n    // Get optional from number from provider config\n    const providersConfig = appConfig?.providerConfigurations as Record<string, Record<string, {\n      fromNumber?: string;\n    }> | undefined> | undefined;\n    const providerConf = providersConfig?.[providerId]?.[ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER];\n\n    return {\n      providerId,\n      accountSid: parsedCredentials.accountSid,\n      authToken: parsedCredentials.authToken,\n      endpoint: smsContract.baseUrl,\n      fromNumber: providerConf?.fromNumber,\n    };\n  }\n\n  /**\n   * Execute the SMS send request via provider.\n   * Uses raw fetch() with Basic Auth for Twilio's REST API (form-encoded).\n   */\n  private async executeProviderRequest(\n    providerConfig: SMSProviderConfig,\n    request: StandardSMS_SendRequest\n  ): Promise<StandardSMS_SendResponse> {\n    // Build the URL (Twilio uses /Accounts/{AccountSid}/Messages.json)\n    const url = `${providerConfig.endpoint}/Accounts/${providerConfig.accountSid}/Messages.json`;\n\n    // Build Basic Auth header\n    const basicAuth = Buffer.from(`${providerConfig.accountSid}:${providerConfig.authToken}`).toString('base64');\n\n    // Build form-encoded body from transformer output\n    const formBody = new URLSearchParams({\n      To: request.to,\n      Body: request.body,\n      ...(request.from ? { From: request.from } : {}),\n    }).toString();\n\n    const response = await fetch(url, {\n      method: 'POST',\n      headers: {\n        [WildoHeaderKeys.CONTENT_TYPE]: 'application/x-www-form-urlencoded',\n        [WildoHeaderKeys.AUTHORIZATION]: `Basic ${basicAuth}`,\n      },\n      body: formBody,\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      throw this.errorBuilder.buildError(\n        ErrorType.EXTERNAL_SERVICE,\n        undefined,\n        {\n          context: {\n            message: `SMS provider returned error: ${response.status}`,\n            providerId: providerConfig.providerId,\n            statusCode: response.status,\n            errorBody,\n          }\n        }\n      );\n    }\n\n    const responseData = await response.json() as Record<string, unknown>;\n    const hasProviderError = responseData.error_code !== undefined && responseData.error_code !== null;\n\n    return {\n      success: !hasProviderError,\n      messageId: String(responseData.sid ?? responseData.messageId ?? `${providerConfig.providerId}-${Date.now()}`),\n      status: hasProviderError\n        ? 'failed'\n        : typeof responseData.status === 'string' ? responseData.status as StandardSMS_SendResponse['status'] : undefined,\n    };\n  }\n}\n"]}
+{"version":3,"file":"sms.backend.service.js","sourceRoot":"","sources":["../../../../../../src/notifications/sms/services/sms.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * SMS Backend Service\n *\n * Main service for sending SMS messages. Orchestrates:\n * - Provider resolution via ExternalProvidersRegistryBackendService\n * - The provider's own `SMS_PROVIDER` runtime contract, read from the registry, which supplies the\n *   endpoint and the request/response projection\n * - Raw HTTP execution (Basic Auth for Twilio)\n *\n * Mirrors the pattern of EmailBackendService for consistency.\n */\n\nimport { injectable, inject } from 'inversify';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { describeCaughtError, projectCaughtErrorLogFields } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';\nimport { EngineCapability, ErrorType, WildoHeaderKeys } from '@wildo-ai/saas-models';\nimport {\n  ExternalProvider_ExchangeProtocol_Kind,\n  type StandardSMS_SendRequest,\n  type StandardSMS_SendResponse,\n  ProviderProtocolRuntimeKind,\n} from '@wildo-ai/external-connectors-models';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// TYPES\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SMSSendResult {\n  success: boolean;\n  messageId?: string;\n  providerId?: string;\n  error?: string;\n}\n\ninterface SMSProviderConfig {\n  providerId: string;\n  accountSid: string;\n  authToken: string;\n  endpoint: string;\n  fromNumber?: string;\n}\n\nfunction parseSMSCredentials(secretValue: string): { accountSid: string; authToken: string } | null {\n  try {\n    const parsed = JSON.parse(secretValue) as {\n      accountSid?: unknown;\n      authToken?: unknown;\n    };\n    if (\n      typeof parsed.accountSid === 'string'\n      && parsed.accountSid.length > 0\n      && typeof parsed.authToken === 'string'\n      && parsed.authToken.length > 0\n    ) {\n      return {\n        accountSid: parsed.accountSid,\n        authToken: parsed.authToken,\n      };\n    }\n  } catch {\n    // Fallback below handles non-JSON encodings.\n  }\n\n  const [accountSid, authToken] = secretValue.includes('|')\n    ? secretValue.split('|', 2)\n    : secretValue.split(':', 2);\n  if (accountSid && authToken) {\n    return { accountSid, authToken };\n  }\n\n  return null;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SERVICE\n// ─────────────────────────────────────────────────────────────────────────────\n\n@injectable()\nexport class SMSBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly configService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('SMSBackendService');\n  }\n\n  /**\n   * Send an SMS message.\n   *\n   * @param to - Recipient phone number in E.164 format\n   * @param body - Message body\n   * @param from - Optional sender phone number (uses provider default if not set)\n   */\n  public async send(to: string, body: string, from?: string): Promise<SMSSendResult> {\n    const startTime = Date.now();\n\n    try {\n      // 1. Resolve SMS provider\n      const providerConfig = this.resolveSMSProvider();\n\n      // 2. Build standard request\n      const request: StandardSMS_SendRequest = {\n        to,\n        body,\n        from: from ?? providerConfig.fromNumber,\n      };\n\n      // 3. Execute via provider\n      const response = await this.executeProviderRequest(providerConfig, request);\n\n      const durationMs = Date.now() - startTime;\n      this.logDebug('SMS sent successfully', {\n        to,\n        providerId: providerConfig.providerId,\n        messageId: response.messageId,\n        durationMs,\n      });\n\n      return {\n        success: true,\n        messageId: response.messageId,\n        providerId: providerConfig.providerId,\n      };\n    } catch (error) {\n      const durationMs = Date.now() - startTime;\n      this.logger.error('Failed to send SMS', {\n        to,\n        ...projectCaughtErrorLogFields(error),\n        durationMs,\n      });\n\n      return {\n        success: false,\n        error: describeCaughtError(error),\n      };\n    }\n  }\n\n  /**\n   * Resolve the SMS provider for the SMS capability.\n   * Mirrors EmailBackendService.resolveEmailProvider() pattern.\n   */\n  private resolveSMSProvider(): SMSProviderConfig {\n    const providerId = this.externalProvidersRegistry.getPrimaryProviderForEngineCapability(EngineCapability.SMS);\n\n    if (!providerId) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        { context: { message: 'No SMS provider configured for capability: SMS', capability: EngineCapability.SMS } }\n      );\n    }\n\n    if (!this.externalProvidersRegistry.isProviderEnabled(providerId, ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER)) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        { context: { message: `SMS provider is disabled by external provider configuration: ${providerId}`, providerId } },\n      );\n    }\n\n    const secretRef = this.externalProvidersRegistry.getConfiguredProviderSecretRef(\n      providerId,\n      ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n    );\n    const encodedCredentials = secretRef\n      ? this.externalProvidersRegistry.getProviderSecret(\n          providerId,\n          ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n          secretRef,\n        )\n      : undefined;\n    const parsedCredentials = encodedCredentials\n      ? parseSMSCredentials(encodedCredentials)\n      : null;\n\n    if (!parsedCredentials) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        {\n          context: {\n            message: `No env-provided credentials configured for SMS provider: ${providerId}`,\n            providerId,\n            capability: EngineCapability.SMS,\n            secretRef,\n          },\n        }\n      );\n    }\n\n    const smsContract = this.externalProvidersRegistry.getProviderRuntimeContract(\n      providerId,\n      ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER,\n    );\n    if (smsContract?.kind !== ProviderProtocolRuntimeKind.SMS) {\n      throw this.errorBuilder.buildError(\n        ErrorType.CONFIGURATION,\n        undefined,\n        {\n          context: {\n            message: `No SMS_PROVIDER runtime contract found for provider: ${providerId}`,\n            providerId,\n            capability: EngineCapability.SMS,\n          },\n        }\n      );\n    }\n    // The framework currently ships a single `kind: ProviderProtocolRuntimeKind.SMS` runtime\n    // contract (Twilio). The execute-request path below assumes the\n    // Twilio REST API shape (`/Accounts/{AccountSid}/Messages.json`,\n    // Basic Auth, form-encoded body). When a second SMS adapter\n    // arrives, factor the provider-specific request shape into the\n    // contract via `sdkFactory` / `buildSendPayload` (mirror of the\n    // email surface) — do NOT reintroduce a `provider === '<ref>'`\n    // literal at this consumer site.\n    const appConfig = this.configService.config as Record<string, unknown>;\n    // Get optional from number from provider config\n    const providersConfig = appConfig?.providerConfigurations as Record<string, Record<string, {\n      fromNumber?: string;\n    }> | undefined> | undefined;\n    const providerConf = providersConfig?.[providerId]?.[ExternalProvider_ExchangeProtocol_Kind.SMS_PROVIDER];\n\n    return {\n      providerId,\n      accountSid: parsedCredentials.accountSid,\n      authToken: parsedCredentials.authToken,\n      endpoint: smsContract.baseUrl,\n      fromNumber: providerConf?.fromNumber,\n    };\n  }\n\n  /**\n   * Execute the SMS send request via provider.\n   * Uses raw fetch() with Basic Auth for Twilio's REST API (form-encoded).\n   */\n  private async executeProviderRequest(\n    providerConfig: SMSProviderConfig,\n    request: StandardSMS_SendRequest\n  ): Promise<StandardSMS_SendResponse> {\n    // Build the URL (Twilio uses /Accounts/{AccountSid}/Messages.json)\n    const url = `${providerConfig.endpoint}/Accounts/${providerConfig.accountSid}/Messages.json`;\n\n    // Build Basic Auth header\n    const basicAuth = Buffer.from(`${providerConfig.accountSid}:${providerConfig.authToken}`).toString('base64');\n\n    // Build form-encoded body from transformer output\n    const formBody = new URLSearchParams({\n      To: request.to,\n      Body: request.body,\n      ...(request.from ? { From: request.from } : {}),\n    }).toString();\n\n    const response = await fetch(url, {\n      method: 'POST',\n      headers: {\n        [WildoHeaderKeys.CONTENT_TYPE]: 'application/x-www-form-urlencoded',\n        [WildoHeaderKeys.AUTHORIZATION]: `Basic ${basicAuth}`,\n      },\n      body: formBody,\n    });\n\n    if (!response.ok) {\n      const errorBody = await response.text();\n      throw this.errorBuilder.buildError(\n        ErrorType.EXTERNAL_SERVICE,\n        undefined,\n        {\n          context: {\n            message: `SMS provider returned error: ${response.status}`,\n            providerId: providerConfig.providerId,\n            statusCode: response.status,\n            errorBody,\n          }\n        }\n      );\n    }\n\n    const responseData = await response.json() as Record<string, unknown>;\n    const hasProviderError = responseData.error_code !== undefined && responseData.error_code !== null;\n\n    return {\n      success: !hasProviderError,\n      messageId: String(responseData.sid ?? responseData.messageId ?? `${providerConfig.providerId}-${Date.now()}`),\n      status: hasProviderError\n        ? 'failed'\n        : typeof responseData.status === 'string' ? responseData.status as StandardSMS_SendResponse['status'] : undefined,\n    };\n  }\n}\n"]}

package/dist/esm/notifications/webhooks/controllers/webhook-auto-controller.backend.service.d.ts

@@ -6,9 +6,11 @@
  * then iterates each provider's endpoints, and registers:
  *   POST /webhooks/{providerRef}/{endpointKey}
  *
- * e.g., POST /webhooks/stripe/billing
- *       POST /webhooks/google/calendar
- *       POST /webhooks/google/drive
+ * One provider declares the protocol today, and it declares one endpoint:
+ *   POST /webhooks/stripe/billing
+ *
+ * A second provider registers here the moment it declares `WEBHOOK_ORIGINATOR` with its own
+ * `endpoints`; no edit to this controller is needed.
  *
  * This replaces manual per-provider webhook controllers (like BillingWebhookControllerBackendService).
  *
@@ -22,6 +24,36 @@ import type { BackendProviderRegistryBackendService } from '../../../external-pr
 import type { ExternalProvidersRegistryBackendService } from '../../../external-providers/services/external-providers-registry.backend.service';
 import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service';
 import type { WebhookHandlerBackendService } from '../../../notifications/webhooks/services/webhook-handler.backend.service';
+/**
+ * Why a declared webhook endpoint did NOT get an Express route.
+ *
+ * A closed vocabulary rather than a free string: each member names a DIFFERENT
+ * missing registration, with a different remedy, and an operator reading the
+ * startup log has to be able to tell them apart. The two are independent — an
+ * endpoint can be missing either, or both.
+ */
+export declare enum WebhookRouteWithholdingReason {
+    /**
+     * No {@link WebhookCapabilityHandler} is registered for the endpoint's
+     * `capability`. The route would reach `handleWebhookRequest`, complete
+     * signature verification and idempotency claiming, then fail at dispatch.
+     */
+    NO_CAPABILITY_HANDLER = "NO_CAPABILITY_HANDLER",
+    /**
+     * No `WebhookCapabilityAdapter` is registered for `providerRef:endpointKey`
+     * on {@link WebhookHandlerBackendService}. The route would fail at the very
+     * top of `processWebhook`, before signature verification.
+     */
+    NO_ENDPOINT_ADAPTER = "NO_ENDPOINT_ADAPTER"
+}
+/** One declared endpoint whose route was deliberately not mounted, and why. */
+export interface WebhookRouteWithholding {
+    providerRef: string;
+    endpointKey: string;
+    capability: string;
+    routePath: string;
+    reasons: WebhookRouteWithholdingReason[];
+}
 export declare class WebhookAutoControllerBackendService extends AbstractControllerBackendService {
     private readonly backendProviderRegistry;
     private readonly externalProvidersRegistry;
@@ -34,7 +66,21 @@ export declare class WebhookAutoControllerBackendService extends AbstractControl
      * setupRoutes() reads from this cache (sync) to register routes.
      */
     private loadedEndpoints;
-    /** Routes recorded only after Express accepted their registration. */
+    /** Route paths recorded only after Express accepted their registration. */
+    private registeredRoutePaths;
+    /**
+     * Declared endpoints whose route was WITHHELD because the capability could
+     * not be dispatched. Kept so the decision is inspectable after startup rather
+     * than only visible in a log line that has already scrolled past.
+     */
+    private withheldRoutes;
+    /**
+     * Set once {@link registerWebhookRoutes} has run. The mount decision is taken
+     * ONCE, from the registration state at that instant, so anything registered
+     * afterwards cannot change which routes exist — see
+     * {@link registerCapabilityHandler}, which refuses to let that be silent.
+     */
+    private routesRegistered;
     constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, backendProviderRegistry: BackendProviderRegistryBackendService, externalProvidersRegistry: ExternalProvidersRegistryBackendService);
     /**
      * Initialize with required dependencies, pre-load endpoint configs, AND
@@ -69,6 +115,16 @@ export declare class WebhookAutoControllerBackendService extends AbstractControl
     /**
      * Register a capability handler for dispatching processed events.
      * Called at startup by capability modules (e.g., billing module).
+     *
+     * MUST be called before {@link initialize}. `start-application` satisfies this
+     * ordering today — step 4.5 initializes capability modules (which register
+     * here) and step 4.6 initializes this controller — and the guard below exists
+     * so a future step inserted the other way round is LOUD instead of silent.
+     *
+     * The failure it catches is genuinely confusing without it: a late-registered
+     * handler works perfectly at request time (the map is read per request), but
+     * the route it would serve was already withheld at mount time, so the endpoint
+     * answers 404 while a handler for it demonstrably exists.
      */
     registerCapabilityHandler(handler: WebhookCapabilityHandler): void;
     /**
@@ -76,6 +132,13 @@ export declare class WebhookAutoControllerBackendService extends AbstractControl
      * registered. Provider configuration, signature material, endpoint payloads,
      * and handler metadata are intentionally absent.
      */
+    getRegisteredWebhookRoutePaths(): ReadonlyArray<string>;
+    /**
+     * Return the declared endpoints whose route was deliberately NOT mounted,
+     * with the reason. Carries no provider configuration or signature material —
+     * only the route identity and which registration was missing.
+     */
+    getWithheldWebhookRoutes(): ReadonlyArray<WebhookRouteWithholding>;
     /**
      * Required by `AbstractControllerBackendService`, which invokes this hook
      * synchronously from its constructor (`super(...)`). This controller
@@ -87,13 +150,62 @@ export declare class WebhookAutoControllerBackendService extends AbstractControl
      */
     protected setupRoutes(): void;
     /**
-     * Register one Express route per pre-loaded provider webhook endpoint.
+     * Register one Express route per pre-loaded provider webhook endpoint —
+     * EXCEPT those whose capability cannot actually be dispatched.
+     *
      * Invoked from `initialize()` after `webhookHandler` and `loadedEndpoints`
      * have been populated. Idempotent-safe against an empty cache; guards on the
      * handler so a mis-sequenced call fails visibly rather than registering dead
      * routes.
+     *
+     * ── Why an undispatchable endpoint is WITHHELD rather than mounted ────────
+     *
+     * A declared endpoint needs two registrations that this controller does not
+     * own and cannot create: a `WebhookCapabilityAdapter` (verify + parse, on
+     * `WebhookHandlerBackendService`) and a `WebhookCapabilityHandler` (dispatch,
+     * here). Both are supplied by the capability module — for `billing`, inside
+     * `start-application.initializeBillingServices`, which is deliberately
+     * NON-FATAL: if it throws part-way, or if `billing.enabled` is false while the
+     * provider is still enabled for `WEBHOOK_ORIGINATOR`, the application boots
+     * with the provider's endpoint declared and neither registration present.
+     *
+     * Mounting a route in that state produces a 500 on every inbound delivery
+     * (`No webhook adapter registered for ...`, or `No capability handler for ...`
+     * below), and a 500 is precisely the answer that tells a vendor to RETRY — an
+     * instruction that can never be satisfied, because no retry supplies a missing
+     * startup registration. The endpoint therefore absorbs the vendor's full retry
+     * schedule and eventually gets disabled on the vendor's side, while the only
+     * local signal is a repeating error log.
+     *
+     * Not mounting says the true thing instead: this endpoint does not exist. The
+     * vendor gets a 404 rather than a retry instruction, and the operator gets one
+     * loud, remedy-naming error at startup — the moment the misconfiguration was
+     * actually introduced.
+     *
+     * REJECTED — refusing at BOOT (throwing from here). It is the shape the rest of
+     * the registry uses, and it is wrong at this site for three reasons. (1) It
+     * would not even be loud: `start-application.initializeWebhookAutoController`
+     * wraps `initialize()` in a non-fatal catch that downgrades a throw to a warn,
+     * so the net effect would be a quieter log AND the loss of every OTHER
+     * provider's working route. (2) It inverts a decision the engine already took
+     * explicitly — billing initialization failure is documented as survivable
+     * ("the app can still run without billing"); a failed optional subsystem must
+     * not become a refusal to start. (3) `billing.enabled: false` beside a
+     * registered Stripe provider is a COHERENT configuration, and refusing to boot
+     * over it would be a false alarm. The check is per-endpoint, so a capability
+     * that is wired keeps its route regardless of a sibling that is not.
      */
     private registerWebhookRoutes;
+    /**
+     * Decide whether a declared endpoint can actually be served, and if not, say
+     * which registration is missing.
+     *
+     * Returns `null` when the route is dispatchable. Both prerequisites are
+     * evaluated (rather than short-circuiting on the first) so an operator gets
+     * the WHOLE remedy in one log line instead of fixing one registration and
+     * meeting the next on the following restart.
+     */
+    private assessRouteDispatchability;
     private handleWebhookRequest;
 }
 //# sourceMappingURL=webhook-auto-controller.backend.service.d.ts.map

package/dist/esm/notifications/webhooks/controllers/webhook-auto-controller.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-auto-controller.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/notifications/webhooks/controllers/webhook-auto-controller.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sCAAsC,CAAC;AAI9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAC5G,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,0FAA0F,CAAC;AACtJ,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAC1J,OAAO,EAAE,gCAAgC,EAAE,MAAM,0FAA0F,CAAC;AAC5I,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oFAAoF,CAAC;AAEvI,qBACa,mCAAoC,SAAQ,gCAAgC;IAoB1B,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACtC,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAnBzG,uEAAuE;IACvE,OAAO,CAAC,kBAAkB,CAA+C;IAEzE,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAsC;IAE7D,sEAAsE;gBAGjC,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACxC,YAAY,EAAE,mBAAmB,EACL,uBAAuB,EAAE,qCAAqC,EAC5D,yBAAyB,EAAE,uCAAuC;IASlJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACU,UAAU,CACrB,cAAc,EAAE,4BAA4B,GAC3C,OAAO,CAAC,IAAI,CAAC;IAuDhB;;;OAGG;IACH,yBAAyB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;IAKlE;;;;OAIG;IAMH;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAI7B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;YA0Cf,oBAAoB;CA8EnC"}
+{"version":3,"file":"webhook-auto-controller.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/notifications/webhooks/controllers/webhook-auto-controller.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sCAAsC,CAAC;AAI9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAC5G,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,0FAA0F,CAAC;AACtJ,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAC1J,OAAO,EAAE,gCAAgC,EAAE,MAAM,0FAA0F,CAAC;AAC5I,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oFAAoF,CAAC;AAEvI;;;;;;;GAOG;AACH,oBAAY,6BAA6B;IACvC;;;;OAIG;IACH,qBAAqB,0BAA0B;IAC/C;;;;OAIG;IACH,mBAAmB,wBAAwB;CAC5C;AAED,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED,qBACa,mCAAoC,SAAQ,gCAAgC;IAoC1B,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACtC,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAnCzG,uEAAuE;IACvE,OAAO,CAAC,kBAAkB,CAA+C;IAEzE,OAAO,CAAC,cAAc,CAA6C;IAEnE;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAsC;IAE7D,2EAA2E;IAC3E,OAAO,CAAC,oBAAoB,CAAgB;IAE5C;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAiC;IAEvD;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB,CAAS;gBAGI,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACxC,YAAY,EAAE,mBAAmB,EACL,uBAAuB,EAAE,qCAAqC,EAC5D,yBAAyB,EAAE,uCAAuC;IASlJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACU,UAAU,CACrB,cAAc,EAAE,4BAA4B,GAC3C,OAAO,CAAC,IAAI,CAAC;IAuDhB;;;;;;;;;;;;;OAaG;IACH,yBAAyB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;IAoBlE;;;;OAIG;IACI,8BAA8B,IAAI,aAAa,CAAC,MAAM,CAAC;IAI9D;;;;OAIG;IACI,wBAAwB,IAAI,aAAa,CAAC,uBAAuB,CAAC;IAQzE;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAI7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,OAAO,CAAC,qBAAqB;IA8D7B;;;;;;;;OAQG;IACH,OAAO,CAAC,0BAA0B;YAwBpB,oBAAoB;CAqFnC"}

package/dist/esm/notifications/webhooks/controllers/webhook-auto-controller.backend.service.js

@@ -6,9 +6,11 @@
  * then iterates each provider's endpoints, and registers:
  *   POST /webhooks/{providerRef}/{endpointKey}
  *
- * e.g., POST /webhooks/stripe/billing
- *       POST /webhooks/google/calendar
- *       POST /webhooks/google/drive
+ * One provider declares the protocol today, and it declares one endpoint:
+ *   POST /webhooks/stripe/billing
+ *
+ * A second provider registers here the moment it declares `WEBHOOK_ORIGINATOR` with its own
+ * `endpoints`; no edit to this controller is needed.
  *
  * This replaces manual per-provider webhook controllers (like BillingWebhookControllerBackendService).
  *
@@ -31,6 +33,29 @@ import express from 'express';
 import { ExternalProvider_ExchangeProtocol_Kind, } from '@wildo-ai/external-connectors-models';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service.js';
+/**
+ * Why a declared webhook endpoint did NOT get an Express route.
+ *
+ * A closed vocabulary rather than a free string: each member names a DIFFERENT
+ * missing registration, with a different remedy, and an operator reading the
+ * startup log has to be able to tell them apart. The two are independent — an
+ * endpoint can be missing either, or both.
+ */
+export var WebhookRouteWithholdingReason;
+(function (WebhookRouteWithholdingReason) {
+    /**
+     * No {@link WebhookCapabilityHandler} is registered for the endpoint's
+     * `capability`. The route would reach `handleWebhookRequest`, complete
+     * signature verification and idempotency claiming, then fail at dispatch.
+     */
+    WebhookRouteWithholdingReason["NO_CAPABILITY_HANDLER"] = "NO_CAPABILITY_HANDLER";
+    /**
+     * No `WebhookCapabilityAdapter` is registered for `providerRef:endpointKey`
+     * on {@link WebhookHandlerBackendService}. The route would fail at the very
+     * top of `processWebhook`, before signature verification.
+     */
+    WebhookRouteWithholdingReason["NO_ENDPOINT_ADAPTER"] = "NO_ENDPOINT_ADAPTER";
+})(WebhookRouteWithholdingReason || (WebhookRouteWithholdingReason = {}));
 let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendService extends AbstractControllerBackendService {
     backendProviderRegistry;
     externalProvidersRegistry;
@@ -43,7 +68,21 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
      * setupRoutes() reads from this cache (sync) to register routes.
      */
     loadedEndpoints = new Map();
-    /** Routes recorded only after Express accepted their registration. */
+    /** Route paths recorded only after Express accepted their registration. */
+    registeredRoutePaths = [];
+    /**
+     * Declared endpoints whose route was WITHHELD because the capability could
+     * not be dispatched. Kept so the decision is inspectable after startup rather
+     * than only visible in a log line that has already scrolled past.
+     */
+    withheldRoutes = [];
+    /**
+     * Set once {@link registerWebhookRoutes} has run. The mount decision is taken
+     * ONCE, from the registration state at that instant, so anything registered
+     * afterwards cannot change which routes exist — see
+     * {@link registerCapabilityHandler}, which refuses to let that be silent.
+     */
+    routesRegistered = false;
     constructor(logger, errorBuilder, errorHandler, backendProviderRegistry, externalProvidersRegistry) {
         super(logger, errorBuilder, errorHandler, 'WebhookAutoController');
         this.backendProviderRegistry = backendProviderRegistry;
@@ -126,9 +165,29 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
     /**
      * Register a capability handler for dispatching processed events.
      * Called at startup by capability modules (e.g., billing module).
+     *
+     * MUST be called before {@link initialize}. `start-application` satisfies this
+     * ordering today — step 4.5 initializes capability modules (which register
+     * here) and step 4.6 initializes this controller — and the guard below exists
+     * so a future step inserted the other way round is LOUD instead of silent.
+     *
+     * The failure it catches is genuinely confusing without it: a late-registered
+     * handler works perfectly at request time (the map is read per request), but
+     * the route it would serve was already withheld at mount time, so the endpoint
+     * answers 404 while a handler for it demonstrably exists.
      */
     registerCapabilityHandler(handler) {
         this.capabilityHandlers.set(handler.capability, handler);
+        if (this.routesRegistered) {
+            this.logger.error(`WebhookAutoController: capability handler for '${handler.capability}' was registered AFTER webhook routes were mounted. `
+                + 'Route mounting is decided once, from the registrations present at that moment, so this handler cannot bring back any route '
+                + 'that was withheld for a missing handler — those endpoints will keep answering 404. '
+                + 'Register capability handlers before WebhookAutoControllerBackendService.initialize() runs.', {
+                capability: handler.capability,
+                withheldRoutes: this.withheldRoutes.map((withholding) => withholding.routePath),
+            });
+            return;
+        }
         this.logDebug(`Registered webhook capability handler for ${handler.capability}`);
     }
     /**
@@ -136,6 +195,17 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
      * registered. Provider configuration, signature material, endpoint payloads,
      * and handler metadata are intentionally absent.
      */
+    getRegisteredWebhookRoutePaths() {
+        return [...this.registeredRoutePaths];
+    }
+    /**
+     * Return the declared endpoints whose route was deliberately NOT mounted,
+     * with the reason. Carries no provider configuration or signature material —
+     * only the route identity and which registration was missing.
+     */
+    getWithheldWebhookRoutes() {
+        return this.withheldRoutes.map((withholding) => ({ ...withholding, reasons: [...withholding.reasons] }));
+    }
     // ════════════════════════════════════════════════════════════
     // Routes
     // ════════════════════════════════════════════════════════════
@@ -152,13 +222,53 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
         // No-op by design — see JSDoc above and `registerWebhookRoutes()`.
     }
     /**
-     * Register one Express route per pre-loaded provider webhook endpoint.
+     * Register one Express route per pre-loaded provider webhook endpoint —
+     * EXCEPT those whose capability cannot actually be dispatched.
+     *
      * Invoked from `initialize()` after `webhookHandler` and `loadedEndpoints`
      * have been populated. Idempotent-safe against an empty cache; guards on the
      * handler so a mis-sequenced call fails visibly rather than registering dead
      * routes.
+     *
+     * ── Why an undispatchable endpoint is WITHHELD rather than mounted ────────
+     *
+     * A declared endpoint needs two registrations that this controller does not
+     * own and cannot create: a `WebhookCapabilityAdapter` (verify + parse, on
+     * `WebhookHandlerBackendService`) and a `WebhookCapabilityHandler` (dispatch,
+     * here). Both are supplied by the capability module — for `billing`, inside
+     * `start-application.initializeBillingServices`, which is deliberately
+     * NON-FATAL: if it throws part-way, or if `billing.enabled` is false while the
+     * provider is still enabled for `WEBHOOK_ORIGINATOR`, the application boots
+     * with the provider's endpoint declared and neither registration present.
+     *
+     * Mounting a route in that state produces a 500 on every inbound delivery
+     * (`No webhook adapter registered for ...`, or `No capability handler for ...`
+     * below), and a 500 is precisely the answer that tells a vendor to RETRY — an
+     * instruction that can never be satisfied, because no retry supplies a missing
+     * startup registration. The endpoint therefore absorbs the vendor's full retry
+     * schedule and eventually gets disabled on the vendor's side, while the only
+     * local signal is a repeating error log.
+     *
+     * Not mounting says the true thing instead: this endpoint does not exist. The
+     * vendor gets a 404 rather than a retry instruction, and the operator gets one
+     * loud, remedy-naming error at startup — the moment the misconfiguration was
+     * actually introduced.
+     *
+     * REJECTED — refusing at BOOT (throwing from here). It is the shape the rest of
+     * the registry uses, and it is wrong at this site for three reasons. (1) It
+     * would not even be loud: `start-application.initializeWebhookAutoController`
+     * wraps `initialize()` in a non-fatal catch that downgrades a throw to a warn,
+     * so the net effect would be a quieter log AND the loss of every OTHER
+     * provider's working route. (2) It inverts a decision the engine already took
+     * explicitly — billing initialization failure is documented as survivable
+     * ("the app can still run without billing"); a failed optional subsystem must
+     * not become a refusal to start. (3) `billing.enabled: false` beside a
+     * registered Stripe provider is a COHERENT configuration, and refusing to boot
+     * over it would be a false alarm. The check is per-endpoint, so a capability
+     * that is wired keeps its route regardless of a sibling that is not.
      */
     registerWebhookRoutes() {
+        this.routesRegistered = true;
         if (!this.webhookHandler) {
             this.logger.warn('WebhookAutoController: initialize() ran without a webhook handler — no routes registered');
             return;
@@ -170,6 +280,24 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
         for (const [providerRef, endpoints] of this.loadedEndpoints) {
             for (const endpoint of endpoints) {
                 const routePath = `/webhooks/${providerRef}/${endpoint.key}`;
+                const withholding = this.assessRouteDispatchability(providerRef, endpoint, routePath);
+                if (withholding) {
+                    this.withheldRoutes.push(withholding);
+                    this.logger.error(`WebhookAutoController: NOT registering POST ${routePath} — the endpoint is declared but cannot be dispatched `
+                        + `(${withholding.reasons.join(', ')}). A route mounted in this state can only ever answer 500, which instructs the `
+                        + 'vendor to retry an inbound event that no retry can make processable. Withholding the route so the vendor gets a '
+                        + '404 instead. Remedy: register the capability module that owns '
+                        + `'${endpoint.capability}' before WebhookAutoControllerBackendService.initialize() runs (for billing, check whether `
+                        + 'billing initialization was skipped or failed non-fatally earlier in startup), or disable the WEBHOOK_ORIGINATOR '
+                        + `protocol for provider '${providerRef}'.`, {
+                        providerRef,
+                        endpointKey: endpoint.key,
+                        capability: endpoint.capability,
+                        routePath,
+                        reasons: withholding.reasons,
+                    });
+                    continue;
+                }
                 this.router.post(routePath, 
                 // Defense-in-depth for a future streaming mount. If this controller is
                 // ever assigned the RAW_REQUEST_STREAM mount phase, this express.raw()
@@ -183,10 +311,33 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
                 express.raw({ type: 'application/json' }), this.asyncHandler(async (req, res, _next) => {
                     await this.handleWebhookRequest(providerRef, endpoint, req, res);
                 }));
+                this.registeredRoutePaths.push(routePath);
                 this.logger.info(`Webhook endpoint registered: POST ${routePath}`);
             }
         }
     }
+    /**
+     * Decide whether a declared endpoint can actually be served, and if not, say
+     * which registration is missing.
+     *
+     * Returns `null` when the route is dispatchable. Both prerequisites are
+     * evaluated (rather than short-circuiting on the first) so an operator gets
+     * the WHOLE remedy in one log line instead of fixing one registration and
+     * meeting the next on the following restart.
+     */
+    assessRouteDispatchability(providerRef, endpoint, routePath) {
+        const reasons = [];
+        if (!this.capabilityHandlers.has(endpoint.capability)) {
+            reasons.push(WebhookRouteWithholdingReason.NO_CAPABILITY_HANDLER);
+        }
+        if (!this.webhookHandler?.hasAdapter(providerRef, endpoint.key)) {
+            reasons.push(WebhookRouteWithholdingReason.NO_ENDPOINT_ADAPTER);
+        }
+        if (reasons.length === 0) {
+            return null;
+        }
+        return { providerRef, endpointKey: endpoint.key, capability: endpoint.capability, routePath, reasons };
+    }
     // ════════════════════════════════════════════════════════════
     // Handler
     // ════════════════════════════════════════════════════════════
@@ -228,7 +379,14 @@ let WebhookAutoControllerBackendService = class WebhookAutoControllerBackendServ
                 res.status(200).json({ received: true });
                 return;
             }
-            // Dispatch to capability handler
+            // Dispatch to capability handler.
+            //
+            // Defence in depth only: `registerWebhookRoutes` refuses to MOUNT a route
+            // whose capability has no handler, so this branch is unreachable while that
+            // gate holds — reaching it means the handler map was mutated after mounting
+            // (which `registerCapabilityHandler` refuses to do silently). The throw is
+            // kept rather than removed because the alternative — dispatching to
+            // `undefined` — would 500 anyway, with no explanation.
             const handler = this.capabilityHandlers.get(endpoint.capability);
             if (handler) {
                 await handler.handleEvent(result.executionContext, result.parsedEvent);