@dereekb/nestjs 14.14.0 → 14.15.0

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

@@ -1,22 +1,54 @@
+import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
+import { type Maybe } from '@dereekb/util';
 import { TwilioWebhookServiceConfig } from './webhook.twilio.config';
+import { TwilioWebhookUrlsConfig } from './webhook.twilio.url';
 /**
  * Factory that creates a {@link TwilioWebhookServiceConfig} from environment variables.
  *
+ * The auth token is read from `TWILIO_WEBHOOK_AUTH_TOKEN`, falling back to `TWILIO_AUTH_TOKEN`. A real
+ * value is preferred over a placeholder one (see {@link isPlaceholderTwilioConfigValue}), so a placeholder
+ * webhook token does not shadow a real auth token. When both are placeholders the placeholder is kept,
+ * which lets the app start and rejects every request as unverified.
+ *
+ * Requests are verified against the app's public webhook URL when `webhookUrlsConfig` is set, and otherwise
+ * against the URL rebuilt from the request headers.
+ *
  * @param configService - NestJS config service for reading environment variables.
+ * @param webhookUrlsConfig - The app's public webhook URLs.
  * @returns A populated {@link TwilioWebhookServiceConfig}.
  */
-export declare function twilioWebhookServiceConfigFactory(configService: ConfigService): TwilioWebhookServiceConfig;
+export declare function twilioWebhookServiceConfigFactory(configService: ConfigService, webhookUrlsConfig?: Maybe<TwilioWebhookUrlsConfig>): TwilioWebhookServiceConfig;
+export interface ProvideAppTwilioWebhookMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional module that exports a {@link TwilioWebhookUrlsConfig}. When provided, requests are verified against
+     * the app's public webhook URL.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+}
 /**
- * NestJS module that handles incoming Twilio webhook requests at:
+ * Convenience function used to generate ModuleMetadata for an app's Twilio webhook module, which handles
+ * incoming Twilio webhook requests at:
  *   - `POST /webhook/twilio/status` (Message status callbacks)
  *   - `POST /webhook/twilio/incoming` (Incoming SMS / MMS messages)
  *
- * Webhook bodies are verified against the X-Twilio-Signature header before dispatch.
+ * Webhook bodies are verified against the X-Twilio-Signature header before dispatch. Only the auth
+ * token is needed for that, so this module does not depend on the Twilio module and can be imported in
+ * environments without a usable Twilio sending config.
  *
  * Requires the consuming application to register the raw-body middleware from
  * `@dereekb/nestjs` for the `/webhook/twilio` path so that signature verification can read
  * the unparsed form body.
+ *
+ * Register handlers by injecting the exported {@link TwilioWebhookService} into a provider passed in `providers`.
+ *
+ * @param config - The module metadata configuration including the optional dependency module.
+ * @returns NestJS ModuleMetadata for registering the Twilio webhook module.
+ */
+export declare function appTwilioWebhookModuleMetadata(config?: Maybe<ProvideAppTwilioWebhookMetadataConfig>): ModuleMetadata;
+/**
+ * NestJS module that handles incoming Twilio webhook requests at `/webhook/twilio`. See
+ * {@link appTwilioWebhookModuleMetadata}, which also lets the app supply its public webhook URLs.
  */
 export declare class TwilioWebhookModule {
 }

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

@@ -0,0 +1,63 @@
+import { type Maybe } from '@dereekb/util';
+import { type TwilioIncomingMessagePayload } from './webhook.twilio';
+/**
+ * The opt-out keyword type Twilio reports on an incoming message (`OptOutType`).
+ *
+ * https://help.twilio.com/articles/31560110671259
+ */
+export declare enum TwilioOptOutType {
+    /**
+     * The sender opted out. Twilio blocks every message to them until they opt back in.
+     */
+    STOP = "STOP",
+    /**
+     * The sender opted back in.
+     */
+    START = "START",
+    /**
+     * The sender asked for help.
+     */
+    HELP = "HELP"
+}
+/**
+ * Twilio's default opt-out keywords.
+ */
+export declare const DEFAULT_TWILIO_OPT_OUT_KEYWORDS: readonly string[];
+/**
+ * Twilio's default opt-in keywords.
+ */
+export declare const DEFAULT_TWILIO_OPT_IN_KEYWORDS: readonly string[];
+/**
+ * Twilio's default help keywords.
+ */
+export declare const DEFAULT_TWILIO_HELP_KEYWORDS: readonly string[];
+/**
+ * Reads a {@link TwilioOptOutType} from a string, case-insensitively.
+ *
+ * @param value - The value to read, such as Twilio's `OptOutType` parameter.
+ * @returns The opt-out type, or undefined when the value is not one.
+ */
+export declare function twilioOptOutTypeFromString(value: Maybe<string>): Maybe<TwilioOptOutType>;
+/**
+ * Config for {@link twilioIncomingMessageOptOutType}.
+ */
+export interface TwilioIncomingMessageOptOutTypeConfig {
+    /**
+     * Only trust Twilio's `OptOutType` parameter, and never match the body against the default keywords.
+     *
+     * Use with Advanced Opt-Out and custom keywords, where the default keywords may not be keywords at all.
+     */
+    readonly optOutTypeOnly?: Maybe<boolean>;
+}
+/**
+ * Returns the opt-out keyword type of an incoming message, if it is one.
+ *
+ * Twilio's `OptOutType` parameter wins when present. It is only sent for messages to a Messaging Service, or to a number with
+ * Advanced Opt-Out. Otherwise the body is matched, trimmed and case-insensitively, against Twilio's default keywords. Only a whole-body
+ * match counts, so "Stop please" is not a keyword, matching how Twilio itself handles keywords.
+ *
+ * @param payload - The incoming message.
+ * @param config - Whether to skip the default keyword fallback.
+ * @returns The opt-out type, or undefined when the message is not a keyword.
+ */
+export declare function twilioIncomingMessageOptOutType(payload: Pick<TwilioIncomingMessagePayload, 'OptOutType' | 'Body'>, config?: Maybe<TwilioIncomingMessageOptOutTypeConfig>): Maybe<TwilioOptOutType>;

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

@@ -1,6 +1,5 @@
 import { type Handler } from '@dereekb/util';
 import { type Request } from 'express';
-import { TwilioApi } from '../twilio.api';
 import { type TwilioWebhookEvent, type TwilioWebhookEventType } from './webhook.twilio';
 import { TwilioWebhookServiceConfig } from './webhook.twilio.config';
 export declare class TwilioWebhookService {
@@ -8,7 +7,7 @@ export declare class TwilioWebhookService {
     private readonly _verifier;
     readonly handler: Handler<TwilioWebhookEvent, TwilioWebhookEventType>;
     readonly configure: import("@dereekb/util").HandlerConfigurer<import("./webhook.twilio").TwilioWebhookEventHandlerConfigurer, TwilioWebhookEvent, TwilioWebhookEventType, boolean>;
-    constructor(twilioApi: TwilioApi, webhookConfig: TwilioWebhookServiceConfig);
+    constructor(webhookConfig: TwilioWebhookServiceConfig);
     handleStatusCallback(req: Request, rawBody: Buffer): Promise<void>;
     handleIncomingMessage(req: Request, rawBody: Buffer): Promise<void>;
     private dispatchEvent;

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

@@ -0,0 +1,57 @@
+import { type Maybe, type WebsitePath, type WebsiteUrl } from '@dereekb/util';
+import { type TwilioStatusCallbackUrl } from '../twilio.type';
+/**
+ * Path of the {@link TwilioWebhookController} under the app's webhook path (`/webhook`).
+ */
+export declare const TWILIO_WEBHOOK_PATH: WebsitePath;
+/**
+ * Path of the message status callback route under {@link TWILIO_WEBHOOK_PATH}.
+ */
+export declare const TWILIO_WEBHOOK_STATUS_PATH: WebsitePath;
+/**
+ * Path of the incoming message route under {@link TWILIO_WEBHOOK_PATH}.
+ */
+export declare const TWILIO_WEBHOOK_INCOMING_PATH: WebsitePath;
+/**
+ * Public URLs of the {@link TwilioWebhookController} routes.
+ */
+export interface TwilioWebhookUrls {
+    /**
+     * Origin Twilio calls the webhooks on. Use as `TwilioWebhookConfig.baseUrl`.
+     */
+    readonly baseUrl: WebsiteUrl;
+    /**
+     * URL Twilio posts message status updates to. Use as `TwilioMessagesConfig.defaultStatusCallback`.
+     */
+    readonly statusCallbackUrl: TwilioStatusCallbackUrl;
+    /**
+     * URL Twilio posts incoming messages to. Set it as the phone number's "A message comes in" webhook in the Twilio Console.
+     */
+    readonly incomingMessageUrl: WebsiteUrl;
+}
+/**
+ * Builds the public URLs of the {@link TwilioWebhookController} routes from the app's public webhook URL.
+ *
+ * The `baseUrl` is the origin of the webhook URL, since the verifier appends the request's full path to it.
+ * This assumes requests reach the app with their public path intact, as they do through a Firebase Hosting
+ * rewrite.
+ *
+ * @param webhookUrl - Public URL the app's `/webhook` routes are served at, e.g. `https://app.example.com/api/webhook`.
+ * @returns The Twilio webhook URLs.
+ */
+export declare function twilioWebhookUrls(webhookUrl: WebsiteUrl): TwilioWebhookUrls;
+/**
+ * The app's public Twilio webhook URLs, provided to the Twilio modules through their `dependencyModule`.
+ *
+ * When a module built by `appTwilioModuleMetadata()` can resolve it, outbound texts request status callbacks at
+ * {@link TwilioWebhookUrls.statusCallbackUrl}. When one built by `appTwilioWebhookModuleMetadata()` can, webhook
+ * requests are verified against {@link TwilioWebhookUrls.baseUrl}.
+ *
+ * `twilioWebhookUrlsConfigProvider()` from `@dereekb/firebase-server/twilio` provides it from the server environment.
+ */
+export declare abstract class TwilioWebhookUrlsConfig {
+    /**
+     * The URLs, or undefined when Twilio cannot reach the app's webhooks.
+     */
+    readonly twilioWebhookUrls?: Maybe<TwilioWebhookUrls>;
+}

package/typeform/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/typeform",
-  "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",
     "@typeform/api-client": "^2.10.2",

package/vapiai/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/nestjs/vapiai",
-  "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",
     "@vapi-ai/server-sdk": "^1.2.0",