@dereekb/nestjs 14.14.0 → 14.15.0

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/twilio",
-  "version": "14.14.0",
+  "version": "14.15.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.14.0",
-    "@dereekb/model": "14.14.0",
-    "@dereekb/nestjs": "14.14.0",
-    "@dereekb/rxjs": "14.14.0",
-    "@dereekb/util": "14.14.0",
+    "@dereekb/date": "14.15.0",
+    "@dereekb/model": "14.15.0",
+    "@dereekb/nestjs": "14.15.0",
+    "@dereekb/rxjs": "14.15.0",
+    "@dereekb/util": "14.15.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",

package/twilio/src/lib/index.d.ts

@@ -2,6 +2,7 @@ export * from './twilio.type';
 export * from './twilio.config';
 export * from './twilio.api';
 export * from './twilio.service';
+export * from './twilio.diagnostic';
 export * from './twilio.module';
 export * from './lookup';
 export * from './verify';

package/twilio/src/lib/lookup/lookup.module.d.ts

@@ -1,7 +1,25 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+export interface ProvideAppTwilioLookupMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the `TwilioApi`, typically the app's module built by `appTwilioModuleMetadata()`.
+     *
+     * Defaults to {@link TwilioModule}.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Twilio Lookup v2 (phone validation, carrier info) module.
+ *
+ * @param config - The module metadata configuration including the dependency module.
+ * @returns NestJS ModuleMetadata for registering the Twilio Lookup module.
+ */
+export declare function appTwilioLookupModuleMetadata(config?: Maybe<ProvideAppTwilioLookupMetadataConfig>): ModuleMetadata;
 /**
  * NestJS module that exposes Twilio Lookup v2 (phone validation, carrier info).
  *
- * Imports {@link TwilioModule} for the underlying Twilio client.
+ * Imports {@link TwilioModule} for the underlying Twilio client. Use {@link appTwilioLookupModuleMetadata}
+ * to use the app's own Twilio module instead.
  */
 export declare class TwilioLookupModule {
 }

package/twilio/src/lib/twilio.api.d.ts

@@ -2,8 +2,18 @@ import { Twilio } from './twilio.interop';
 import { TwilioServiceConfig } from './twilio.config';
 export declare class TwilioApi {
     readonly config: TwilioServiceConfig;
-    readonly client: Twilio;
+    private _client?;
     constructor(config: TwilioServiceConfig);
+    /**
+     * The Twilio SDK client, created on first access.
+     *
+     * Created lazily because the SDK constructor throws when the Account SID does not start with `AC`, so a
+     * config holding the placeholder values of a committed `.env` can still be provided. Accessing the client
+     * with such a config throws.
+     *
+     * @returns The Twilio SDK client.
+     */
+    get client(): Twilio;
 }
 /**
  * Provides a reference to a TwilioApi instance.

package/twilio/src/lib/twilio.config.d.ts

@@ -6,7 +6,6 @@ export declare const TWILIO_API_KEY_SID_ENV_VAR = "TWILIO_API_KEY_SID";
 export declare const TWILIO_API_KEY_SECRET_ENV_VAR = "TWILIO_API_KEY_SECRET";
 export declare const TWILIO_PHONE_NUMBER_ENV_VAR = "TWILIO_PHONE_NUMBER";
 export declare const TWILIO_MESSAGING_SERVICE_SID_ENV_VAR = "TWILIO_MESSAGING_SERVICE_SID";
-export declare const TWILIO_STATUS_CALLBACK_URL_ENV_VAR = "TWILIO_STATUS_CALLBACK_URL";
 export declare const TWILIO_SANDBOX_ENV_VAR = "TWILIO_SANDBOX";
 /**
  * Twilio client credentials. Either {@link authToken} or the {@link apiKeySid}/{@link apiKeySecret}
@@ -47,6 +46,9 @@ export interface TwilioMessagesConfig {
     /**
      * Default status callback URL applied to outbound messages when the caller does not
      * supply one explicitly.
+     *
+     * Not read from the environment. Build it from the app's public webhook URL with
+     * `twilioWebhookUrls()`.
      */
     readonly defaultStatusCallback?: Maybe<TwilioStatusCallbackUrl>;
     /**
@@ -69,3 +71,55 @@ export declare abstract class TwilioServiceConfig {
     readonly messages: TwilioMessagesConfig;
     static assertValidConfig(config: TwilioServiceConfig): void;
 }
+/**
+ * Values treated as unset by {@link usableTwilioServiceConfig}.
+ *
+ * These are the stand-in values a committed `.env` ships with, which are truthy and so pass
+ * {@link TwilioServiceConfig.assertValidConfig}, but crash the `twilio` SDK constructor.
+ */
+export declare const TWILIO_PLACEHOLDER_CONFIG_VALUES: readonly string[];
+/**
+ * Returns true if the input is unset or one of the {@link TWILIO_PLACEHOLDER_CONFIG_VALUES}.
+ *
+ * @param value - Configured value to check.
+ * @returns True if the value should be treated as unset.
+ */
+export declare function isPlaceholderTwilioConfigValue(value: Maybe<string>): boolean;
+/**
+ * Returns a copy of the input config with its placeholder and malformed values removed, or
+ * undefined if what remains cannot send SMS.
+ *
+ * A usable config has:
+ * - an Account SID starting with `AC`
+ * - an Auth Token, or an API Key SID starting with `SK` together with its secret
+ * - a sender phone number starting with `+`, or a Messaging Service SID starting with `MG`
+ *
+ * Values that are unset, one of the {@link TWILIO_PLACEHOLDER_CONFIG_VALUES}, or missing their
+ * expected prefix are dropped from the returned config, so a placeholder Messaging Service SID or
+ * API key never shadows a real sender or auth token. A status callback URL that is not an
+ * `http(s)` URL is dropped as well, since it does not affect whether the config can send.
+ *
+ * `twilioServiceConfigFactory()` uses this to remove placeholder values from a usable environment config.
+ *
+ * @param config - Config to check, typically read from the environment.
+ * @returns The usable config, or undefined if the config cannot send SMS.
+ *
+ * @example
+ * ```ts
+ * const config = usableTwilioServiceConfig(twilioServiceConfigFromConfigService(configService));
+ * ```
+ */
+export declare function usableTwilioServiceConfig(config: Maybe<TwilioServiceConfig>): Maybe<TwilioServiceConfig>;
+/**
+ * Returns true if {@link usableTwilioServiceConfig} can build a usable config from the input.
+ *
+ * Use it to decide whether a provided `TwilioService` can send, e.g.
+ * `isUsableTwilioServiceConfig(twilioService.twilioApi.config)`.
+ *
+ * Note that a usable config may still carry placeholder values; pass the input through
+ * {@link usableTwilioServiceConfig} to get a copy with them removed before using it.
+ *
+ * @param config - Config to check, typically read from the environment.
+ * @returns True if the config can send SMS.
+ */
+export declare function isUsableTwilioServiceConfig(config: Maybe<TwilioServiceConfig>): config is TwilioServiceConfig;

package/twilio/src/lib/twilio.diagnostic.d.ts

@@ -0,0 +1,306 @@
+/**
+ * @module twilio.diagnostic
+ *
+ * Read-only helpers over the Twilio Messages, Accounts, and Lookup APIs.
+ *
+ * These exist to answer "why did this number not get the text?" without sending anything. They are all
+ * failure-tolerant: an unreachable API surfaces as an `unknown` result rather than a thrown error, so a
+ * diagnostic routine can report what it could learn instead of aborting, and never mistakes an outage
+ * for a problem with the number.
+ */
+import { type Maybe } from '@dereekb/util';
+import { type TwilioApi } from './twilio.api';
+import { type TwilioMessageSid, type TwilioMessageStatus, type TwilioPhoneNumber } from './twilio.type';
+/**
+ * The default number of messages to read back when inspecting a number's recent texts.
+ */
+export declare const DEFAULT_TWILIO_RECENT_MESSAGES_LIMIT = 20;
+/**
+ * The default window of history to inspect when reading a number's recent texts.
+ */
+export declare const DEFAULT_TWILIO_RECENT_MESSAGES_WINDOW_DAYS = 30;
+/**
+ * Twilio error codes relevant to delivery diagnosis.
+ *
+ * Twilio reports these on a failed or undelivered message, and on the error a rejected send throws. Twilio
+ * notes that the code for a given cause may change as it improves its errors, so treat them as hints and
+ * keep the error message alongside. Unknown codes are passed through untouched.
+ */
+export declare enum TwilioMessageErrorCode {
+    /**
+     * The `To` number is not a valid phone number.
+     */
+    INVALID_TO_NUMBER = 21211,
+    /**
+     * The recipient replied STOP, so the sender may not text them until they reply START.
+     */
+    UNSUBSCRIBED_RECIPIENT = 21610,
+    /**
+     * The `To` number is not a mobile number, so it cannot receive texts.
+     */
+    NOT_A_MOBILE_NUMBER = 21614,
+    /**
+     * The account's message queue overflowed. Temporary.
+     */
+    QUEUE_OVERFLOW = 30001,
+    /**
+     * The Twilio account is suspended.
+     */
+    ACCOUNT_SUSPENDED = 30002,
+    /**
+     * The phone is switched off or out of coverage. Usually temporary.
+     */
+    UNREACHABLE_DESTINATION_HANDSET = 30003,
+    /**
+     * The carrier or the phone blocked the message.
+     */
+    MESSAGE_BLOCKED = 30004,
+    /**
+     * The number does not exist or is no longer in service.
+     */
+    UNKNOWN_DESTINATION_HANDSET = 30005,
+    /**
+     * The number is a landline, or its carrier cannot receive texts.
+     */
+    LANDLINE_OR_UNREACHABLE_CARRIER = 30006,
+    /**
+     * The carrier filtered the message, usually as suspected spam.
+     */
+    MESSAGE_FILTERED = 30007,
+    /**
+     * Twilio could not determine why the message failed. Often temporary.
+     */
+    UNKNOWN_ERROR = 30008,
+    /**
+     * The sending number is not registered for A2P 10DLC messaging, so US carriers block it.
+     */
+    UNREGISTERED_NUMBER = 30034
+}
+/**
+ * A message as read back for diagnosis.
+ */
+export interface TwilioDiagnosticMessage {
+    readonly sid: TwilioMessageSid;
+    readonly status: TwilioMessageStatus;
+    readonly to: string;
+    /**
+     * Set when the message failed or was not delivered. See {@link TwilioMessageErrorCode}.
+     */
+    readonly errorCode?: Maybe<number>;
+    /**
+     * Twilio's description of `errorCode`.
+     */
+    readonly errorMessage?: Maybe<string>;
+    /**
+     * When the message was sent. Unset while it is still queued.
+     */
+    readonly dateSent?: Maybe<Date>;
+    readonly dateCreated?: Maybe<Date>;
+    /**
+     * When the message's status last changed.
+     */
+    readonly dateUpdated?: Maybe<Date>;
+}
+/**
+ * The fields of a Twilio message instance that {@link twilioDiagnosticMessage} reads.
+ */
+export interface TwilioDiagnosticMessageInput {
+    readonly sid: string;
+    readonly status: string;
+    readonly to: string;
+    readonly errorCode?: Maybe<number>;
+    readonly errorMessage?: Maybe<string>;
+    readonly dateSent?: Maybe<Date>;
+    readonly dateCreated?: Maybe<Date>;
+    readonly dateUpdated?: Maybe<Date>;
+}
+/**
+ * Converts a Twilio message instance to a {@link TwilioDiagnosticMessage}.
+ *
+ * @param message - The message instance.
+ * @returns The diagnostic message.
+ */
+export declare function twilioDiagnosticMessage(message: TwilioDiagnosticMessageInput): TwilioDiagnosticMessage;
+/**
+ * Returns the time a message last changed state: its update time, falling back to its send and creation times.
+ *
+ * @param message - The message.
+ * @returns The time, if Twilio recorded any.
+ */
+export declare function twilioDiagnosticMessageDate(message: TwilioDiagnosticMessage): Maybe<Date>;
+/**
+ * Returns the Twilio error code of a thrown Twilio error, such as the error a rejected send throws.
+ *
+ * @param error - The thrown value.
+ * @returns The error code, if the error carries one.
+ */
+export declare function twilioErrorCode(error: unknown): Maybe<number>;
+/**
+ * Returns the HTTP status of a thrown Twilio error.
+ *
+ * @param error - The thrown value.
+ * @returns The HTTP status, if the error carries one.
+ */
+export declare function twilioErrorStatus(error: unknown): Maybe<number>;
+/**
+ * Why a diagnostic read could not be made.
+ */
+export interface TwilioDiagnosticError {
+    /**
+     * The error message.
+     */
+    readonly message: string;
+    /**
+     * The HTTP status Twilio responded with, if it responded. 401 and 403 mean the credentials were refused, or are not
+     * allowed to read the resource, such as a Standard API key reading the account.
+     */
+    readonly status?: Maybe<number>;
+    /**
+     * Twilio's error code, if it gave one.
+     */
+    readonly code?: Maybe<number>;
+}
+/**
+ * Converts a thrown value to a {@link TwilioDiagnosticError}.
+ *
+ * @param error - The thrown value.
+ * @returns The diagnostic error.
+ */
+export declare function twilioDiagnosticError(error: unknown): TwilioDiagnosticError;
+/**
+ * Whether a diagnostic read was refused because of the credentials, rather than failing to reach Twilio.
+ *
+ * @param error - The read's error, if it failed.
+ * @returns True if Twilio answered with 401 or 403.
+ */
+export declare function isTwilioDiagnosticPermissionError(error: Maybe<TwilioDiagnosticError>): boolean;
+/**
+ * Options for {@link twilioRecentMessagesForRecipient}.
+ */
+export interface TwilioRecentMessagesForRecipientOptions {
+    /**
+     * The maximum number of messages to read back. Defaults to {@link DEFAULT_TWILIO_RECENT_MESSAGES_LIMIT}.
+     */
+    readonly limit?: Maybe<number>;
+    /**
+     * Only read back messages sent after this time.
+     */
+    readonly dateSentAfter?: Maybe<Date>;
+}
+/**
+ * Result of {@link twilioRecentMessagesForRecipient}.
+ */
+export interface TwilioRecentMessagesForRecipientResult {
+    /**
+     * The messages sent to the number, newest first. Empty when none were found or they could not be read.
+     */
+    readonly messages: TwilioDiagnosticMessage[];
+    /**
+     * True if the messages could not be read.
+     */
+    readonly unknown?: Maybe<boolean>;
+    /**
+     * Why the messages could not be read.
+     */
+    readonly error?: Maybe<TwilioDiagnosticError>;
+}
+/**
+ * Reads the messages recently sent to a number, newest first.
+ *
+ * @param api - The Twilio API.
+ * @param to - The number the messages were sent to.
+ * @param options - How many messages to read, and how far back.
+ * @returns The messages, with `unknown` set if they could not be read.
+ */
+export declare function twilioRecentMessagesForRecipient(api: TwilioApi, to: TwilioPhoneNumber, options?: Maybe<TwilioRecentMessagesForRecipientOptions>): Promise<TwilioRecentMessagesForRecipientResult>;
+/**
+ * Result of {@link twilioMessageForSid}.
+ */
+export interface TwilioMessageForSidResult {
+    /**
+     * The message, if it exists.
+     */
+    readonly message?: Maybe<TwilioDiagnosticMessage>;
+    /**
+     * True if the message could not be read. A message that does not exist is not unknown.
+     */
+    readonly unknown?: Maybe<boolean>;
+    /**
+     * Why the message could not be read.
+     */
+    readonly error?: Maybe<TwilioDiagnosticError>;
+}
+/**
+ * Reads a single message, such as a test message whose outcome is being followed.
+ *
+ * @param api - The Twilio API.
+ * @param sid - The message SID.
+ * @returns The message, with `unknown` set if it could not be read.
+ */
+export declare function twilioMessageForSid(api: TwilioApi, sid: TwilioMessageSid): Promise<TwilioMessageForSidResult>;
+/**
+ * The state of the Twilio account.
+ */
+export interface TwilioAccountState {
+    /**
+     * Twilio's status for the account. `active` is healthy; `suspended` and `closed` send nothing.
+     */
+    readonly status?: Maybe<string>;
+    /**
+     * True if the state could not be read.
+     */
+    readonly unknown?: Maybe<boolean>;
+    /**
+     * Why the state could not be read.
+     */
+    readonly error?: Maybe<TwilioDiagnosticError>;
+}
+/**
+ * Reads the account's state.
+ *
+ * Twilio does not let a Standard API key read the account, so with one this is always `unknown`, with a permission
+ * error. See {@link isTwilioDiagnosticPermissionError}.
+ *
+ * An account that is not `active` sends nothing regardless of the recipient, so this distinguishes a system-wide
+ * outage from a per-recipient problem.
+ *
+ * @param api - The Twilio API.
+ * @returns The account's state, with `unknown` set if it could not be read.
+ */
+export declare function twilioAccountState(api: TwilioApi): Promise<TwilioAccountState>;
+/**
+ * Result of {@link twilioLookupPhoneNumberForDiagnosis}.
+ */
+export interface TwilioPhoneNumberDiagnosis {
+    /**
+     * Whether Twilio could resolve the number to a valid phone number. Unset when the lookup could not be made.
+     */
+    readonly valid?: Maybe<boolean>;
+    /**
+     * The line type, such as `mobile`, `landline` or `nonFixedVoip`, when it was requested and Twilio knows it.
+     */
+    readonly lineType?: Maybe<string>;
+    /**
+     * The carrier name, when the line type was requested and Twilio knows it.
+     */
+    readonly carrierName?: Maybe<string>;
+    /**
+     * True if the lookup could not be made.
+     */
+    readonly unknown?: Maybe<boolean>;
+    /**
+     * Why the lookup could not be made.
+     */
+    readonly error?: Maybe<TwilioDiagnosticError>;
+}
+/**
+ * Looks up a number with Twilio Lookup v2.
+ *
+ * Unlike {@link TwilioLookupService.lookup}, a failed lookup is reported as `unknown` rather than as an invalid number.
+ *
+ * @param api - The Twilio API.
+ * @param phoneNumber - The number to look up.
+ * @param includeLineType - Whether to request the line type. Twilio charges per lookup for it.
+ * @returns The diagnosis, with `unknown` set if the lookup could not be made.
+ */
+export declare function twilioLookupPhoneNumberForDiagnosis(api: TwilioApi, phoneNumber: TwilioPhoneNumber, includeLineType?: Maybe<boolean>): Promise<TwilioPhoneNumberDiagnosis>;

package/twilio/src/lib/twilio.module.d.ts

@@ -1,17 +1,53 @@
+import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
+import { type Maybe } from '@dereekb/util';
 import { TwilioServiceConfig } from './twilio.config';
+import { TwilioWebhookUrlsConfig } from './webhook/webhook.twilio.url';
+/**
+ * Reads a {@link TwilioServiceConfig} from environment variables without validating it.
+ *
+ * {@link twilioServiceConfigFactory} builds the validated config from it.
+ *
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns The unvalidated {@link TwilioServiceConfig}.
+ */
+export declare function twilioServiceConfigFromConfigService(configService: ConfigService): TwilioServiceConfig;
 /**
  * Factory that creates a {@link TwilioServiceConfig} from environment variables.
  *
+ * When the environment holds a usable config, its placeholder values are removed (see
+ * {@link usableTwilioServiceConfig}), so a placeholder Messaging Service SID or API key never shadows a real
+ * sender or auth token. Otherwise the placeholder values are kept, which lets the app start; {@link TwilioApi}
+ * only creates the SDK client when it is first used.
+ *
  * @param configService - NestJS config service for reading environment variables.
+ * @param webhookUrlsConfig - The app's public webhook URLs. When set, outbound texts request status callbacks at its status callback URL.
  * @returns A validated {@link TwilioServiceConfig}.
  */
-export declare function twilioServiceConfigFactory(configService: ConfigService): TwilioServiceConfig;
+export declare function twilioServiceConfigFactory(configService: ConfigService, webhookUrlsConfig?: Maybe<TwilioWebhookUrlsConfig>): TwilioServiceConfig;
+export interface ProvideAppTwilioMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional module that exports a {@link TwilioWebhookUrlsConfig}. When provided, outbound texts request status
+     * callbacks at the app's `/webhook/twilio/status` route.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Twilio module, which provides
+ * {@link TwilioApi} and {@link TwilioService} for sending SMS.
+ *
+ * Reads the Twilio credentials and default sender from environment variables.
+ *
+ * @param config - The module metadata configuration including the optional dependency module.
+ * @returns NestJS ModuleMetadata for registering the Twilio module.
+ */
+export declare function appTwilioModuleMetadata(config?: Maybe<ProvideAppTwilioMetadataConfig>): ModuleMetadata;
 /**
  * NestJS module that provides the {@link TwilioApi} and {@link TwilioService} for sending SMS
  * via Twilio.
  *
- * Reads Twilio credentials and default sender configuration from environment variables.
+ * Reads Twilio credentials and default sender configuration from environment variables. Use
+ * {@link appTwilioModuleMetadata} to supply the app's webhook URLs.
  */
 export declare class TwilioModule {
 }

package/twilio/src/lib/twilio.service.d.ts

@@ -60,6 +60,10 @@ export interface TwilioSendSmsResult {
      * Error message captured if the send failed.
      */
     readonly error?: Maybe<string>;
+    /**
+     * Twilio error code captured if the send failed, such as 21610 for a recipient who replied STOP. See {@link TwilioMessageErrorCode}.
+     */
+    readonly errorCode?: Maybe<number>;
 }
 export declare class TwilioService {
     private readonly logger;

package/twilio/src/lib/verify/verify.module.d.ts

@@ -1,4 +1,6 @@
+import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
+import { type Maybe } from '@dereekb/util';
 import { TwilioVerifyServiceConfig } from './verify.config';
 /**
  * Factory that creates a {@link TwilioVerifyServiceConfig} from environment variables.
@@ -7,11 +9,27 @@ import { TwilioVerifyServiceConfig } from './verify.config';
  * @returns A validated {@link TwilioVerifyServiceConfig}.
  */
 export declare function twilioVerifyServiceConfigFactory(configService: ConfigService): TwilioVerifyServiceConfig;
+export interface ProvideAppTwilioVerifyMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the `TwilioApi`, typically the app's module built by `appTwilioModuleMetadata()`.
+     *
+     * Defaults to {@link TwilioModule}.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Twilio Verify (OTP / 2FA) module.
+ *
+ * @param config - The module metadata configuration including the dependency module.
+ * @returns NestJS ModuleMetadata for registering the Twilio Verify module.
+ */
+export declare function appTwilioVerifyModuleMetadata(config?: Maybe<ProvideAppTwilioVerifyMetadataConfig>): ModuleMetadata;
 /**
  * NestJS module that exposes Twilio Verify (OTP / 2FA) for starting verifications and
  * checking submitted codes.
  *
- * Imports {@link TwilioModule} for the underlying Twilio client.
+ * Imports {@link TwilioModule} for the underlying Twilio client. Use {@link appTwilioVerifyModuleMetadata}
+ * to use the app's own Twilio module instead.
  */
 export declare class TwilioVerifyModule {
 }

package/twilio/src/lib/webhook/index.d.ts

@@ -1,5 +1,7 @@
 export * from './webhook.twilio';
+export * from './webhook.twilio.optout';
 export * from './webhook.twilio.config';
+export * from './webhook.twilio.url';
 export * from './webhook.twilio.verify';
 export * from './webhook.twilio.service';
 export * from './webhook.twilio.controller';

package/twilio/src/lib/webhook/webhook.twilio.config.d.ts

@@ -1,17 +1,22 @@
 import { type Maybe } from '@dereekb/util';
 export declare const TWILIO_WEBHOOK_AUTH_TOKEN_ENV_VAR = "TWILIO_WEBHOOK_AUTH_TOKEN";
-export declare const TWILIO_WEBHOOK_BASE_URL_ENV_VAR = "TWILIO_WEBHOOK_BASE_URL";
 export declare const TWILIO_WEBHOOK_SKIP_VERIFY_ENV_VAR = "TWILIO_WEBHOOK_SKIP_VERIFY";
 export interface TwilioWebhookConfig {
     /**
-     * Twilio Auth Token used to verify the X-Twilio-Signature header. When unset, the value
-     * configured on {@link TwilioServiceConfig} is used.
+     * Twilio Auth Token used to verify the X-Twilio-Signature header. Required.
+     *
+     * `twilioWebhookServiceConfigFactory()` reads it from `TWILIO_WEBHOOK_AUTH_TOKEN`, falling back to
+     * `TWILIO_AUTH_TOKEN`.
      */
     readonly authToken?: Maybe<string>;
     /**
-     * Base URL of the deployed webhook (e.g. `https://api.example.com`). Twilio computes the
-     * request signature over the full URL it called, so behind a proxy the public URL must be
-     * supplied here for verification to succeed.
+     * Public origin Twilio calls the webhook on (e.g. `https://api.example.com`). Twilio computes the
+     * request signature over the full URL it called, so behind a proxy the public origin must be
+     * supplied here for verification to succeed. When unset, the URL is rebuilt from the request's
+     * `X-Forwarded-Proto` / `X-Forwarded-Host` / `Host` headers.
+     *
+     * Not read from the environment. Build it from the app's public webhook URL with
+     * `twilioWebhookUrls()`.
      */
     readonly baseUrl?: Maybe<string>;
     /**

package/twilio/src/lib/webhook/webhook.twilio.d.ts

@@ -1,5 +1,6 @@
 import { type Maybe, type Handler, type HandlerBindAccessor, type HandlerMappedSetFunction } from '@dereekb/util';
-import { type TwilioAccountSid, type TwilioMessageSid, type TwilioMessageStatus, type TwilioPhoneNumber } from '../twilio.type';
+import { type TwilioAccountSid, type TwilioMessageSid, type TwilioMessageStatus, type TwilioMessagingServiceSid, type TwilioPhoneNumber } from '../twilio.type';
+import { type TwilioOptOutType } from './webhook.twilio.optout';
 /**
  * Twilio webhook event type.
  */
@@ -40,6 +41,15 @@ export interface TwilioIncomingMessagePayload {
     readonly FromState?: Maybe<string>;
     readonly FromZip?: Maybe<string>;
     readonly FromCountry?: Maybe<string>;
+    /**
+     * The Messaging Service the message was sent to, if it was sent to one.
+     */
+    readonly MessagingServiceSid?: Maybe<TwilioMessagingServiceSid>;
+    /**
+     * The opt-out keyword type Twilio matched the message to, if any. Only sent for messages to a Messaging Service, or to a number with
+     * Advanced Opt-Out. See {@link twilioIncomingMessageOptOutType}, which also matches the default keywords when it is absent.
+     */
+    readonly OptOutType?: Maybe<TwilioOptOutType>;
     /**
      * Resolved MediaUrl0..MediaUrlN entries, ordered by index. Empty array when no media.
      */