@plyaz/types 1.13.3 → 1.13.5

package/dist/notifications/types.d.ts

@@ -0,0 +1,1937 @@
+/**
+ * Notification Type Definitions
+ *
+ * Core type definitions for the @plyaz/notifications package
+ * All notification-related types, interfaces, and type utilities
+ *
+ * @module notifications/types
+ */
+import type { UnknownRecord, Promisable } from 'type-fest';
+import type { MessageCatalog } from '../errors';
+import type { WEBHOOK_ENCRYPTION_METHOD, WEBHOOK_EVENT_TYPE, SIGNATURE_METHOD } from './enums';
+import type z from 'zod';
+/**
+ * Notification channels supported by the system
+ */
+export type NotificationChannel = 'email' | 'sms' | 'push';
+/**
+ * Notification priority levels for queue processing
+ */
+export type QueuePriority = 'high' | 'normal' | 'low';
+/**
+ * Notification category for compliance and user preferences (FR-4.3)
+ *
+ * Categories determine how notifications can be opted out:
+ * - transactional: Cannot be opted out (password resets, order confirmations)
+ * - marketing: User can opt-out (newsletters, promotions)
+ * - social: User can opt-out (likes, comments, follows)
+ * - system: System alerts and notifications (security alerts, system status)
+ * - promotional: Promotional offers and campaigns
+ */
+export type NotificationCategory = 'transactional' | 'marketing' | 'social' | 'system' | 'promotional';
+/**
+ * Notification status
+ */
+export type NotificationStatus = 'queued' | 'processing' | 'sent' | 'delivered' | 'failed' | 'bounced';
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Provider names - type-safe constants for provider identification
+ */
+export type ProviderName = string;
+/**
+ * Result pattern for type-safe error handling
+ * Eliminates need for try-catch in happy path
+ *
+ * Note: This is the same as Result from @plyaz/types/common
+ * We re-export here for convenience, but use the common one to avoid duplication
+ */
+export type NotificationResult<T, E = Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/**
+ * Email validation result
+ * Returned by validateEmails() method on email adapters
+ */
+export interface EmailValidationResult {
+    /** Email address that was validated */
+    email: string;
+    /** Whether the email is valid and deliverable */
+    valid: boolean;
+    /** Reason why email is invalid (optional) */
+    reason?: string;
+}
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit (default: 5) */
+    threshold: number;
+    /** Milliseconds before attempting half-open (default: 60000) */
+    timeout: number;
+    /** Successful attempts needed in half-open to close (default: 3) */
+    halfOpenAttempts: number;
+}
+/**
+ * Single webhook handler configuration
+ */
+export interface WebhookHandlerConfig {
+    /** Webhook adapter class or instance */
+    adapter: unknown;
+    /** Webhook secret for signature verification */
+    secret: string;
+    /** Public key for ECDSA verification (SendGrid) */
+    publicKey?: string;
+    /** Verification method */
+    verificationMethod?: 'ecdsa' | 'hmac';
+    /** Priority (lower = higher priority, executed first) */
+    priority?: number;
+    /** Maximum webhook age in seconds */
+    maxWebhookAge?: number;
+    /** Whether this webhook handler is enabled */
+    enabled?: boolean;
+}
+/**
+ * Webhook configuration for a provider
+ * Supports single handler or array of handlers (for SoC)
+ */
+export interface WebhookConfig {
+    /** Whether webhooks are enabled globally */
+    enabled: boolean;
+    /** Webhook endpoint URL (optional, for documentation) */
+    url?: string;
+    /**
+     * Webhook handlers - can be:
+     * - Single handler config
+     * - Array of handler configs (for Separation of Concerns)
+     */
+    handlers: WebhookHandlerConfig | WebhookHandlerConfig[];
+}
+/**
+ * Notification Provider configuration
+ * Defines how a notification provider is initialized and configured
+ */
+export interface NotificationProviderConfig {
+    /** Provider name */
+    name: ProviderName;
+    /** Whether provider is enabled */
+    enabled: boolean;
+    /** Priority (1 = highest, 999 = lowest/fallback) */
+    priority: number;
+    /** Provider-specific credentials and settings */
+    credentials: UnknownRecord;
+    /** Optional circuit breaker configuration */
+    circuitBreaker?: CircuitBreakerConfig;
+    /** Optional webhook configuration (Post-MVP) */
+    webhook?: WebhookConfig;
+}
+/**
+ * API client configuration for providers that use @plyaz/api
+ *
+ * This allows passing any ApiConfig to override global defaults.
+ * Engineers can customize error handling, retries, interceptors, etc. per adapter.
+ *
+ * Common overrides:
+ * - baseURL, headers, timeout (required/recommended)
+ * - retryStrategy, retryCount, retryDelay (retry behavior)
+ * - onError, errorHandlers (custom error handling)
+ * - onRequest, onResponse, onRetry (custom interceptors)
+ */
+export type ApiClientConfig = {
+    /** Base URL for the API (required) */
+    baseURL: string;
+} & Partial<Record<string, unknown>>;
+/**
+ * Base adapter configuration
+ */
+export interface BaseAdapterConfig {
+    /** Provider name */
+    providerName: string;
+    /** Channel this adapter handles */
+    channel: NotificationChannel;
+    /** Priority for fallback ordering */
+    priority: number;
+    /** Optional fallback adapter */
+    fallbackAdapter?: unknown;
+    /** Optional logger */
+    logger?: unknown;
+    /** Attachment resolver options */
+    attachmentResolverOptions?: AttachmentResolverOptions;
+    /** API client configuration (for providers using @plyaz/api) */
+    apiClientConfig?: ApiClientConfig;
+    /**
+     * Retry configuration for this adapter
+     * Defaults to RETRY_CONFIG values if not provided
+     * Set to false to disable retries for this adapter
+     */
+    retryConfig?: NotificationRetryConfig | false;
+    /**
+     * Webhook configuration for this adapter
+     * Supports single handler or array of handlers for Separation of Concerns
+     */
+    webhookConfig?: WebhookConfig;
+    /**
+     * Token generation configuration for unsubscribe/preference links
+     * Enables automatic token generation for compliance features
+     */
+    tokenConfig?: TokenConfig;
+    /**
+     * Token URL configuration
+     * Defines base URLs for different token types (unsubscribe, preferences, etc.)
+     */
+    tokenUrls?: TokenUrlConfig;
+    /**
+     * SMS validation configuration (SMS adapters only)
+     * Configure character limits, encoding detection, and truncation behavior
+     * Overrides service-level SMS validation config
+     */
+    smsValidation?: SMSValidationConfig;
+    /**
+     * URL shortener configuration
+     * Configure URL shortening for SMS and Push notifications
+     * Helps save characters in SMS messages
+     */
+    urlShortener?: UrlShortenerConfig;
+}
+/**
+ * Infobip Email adapter configuration
+ */
+export interface InfobipEmailConfig extends UnknownRecord {
+    /** Infobip API Key from your account */
+    apiKey: string;
+    /**
+     * Infobip API Base URL
+     * Default: https://api.infobip.com
+     * Regional URLs available (EU, US, etc.)
+     */
+    baseUrl?: string;
+    /** Default sender email address (must be verified in your Infobip account) */
+    fromEmail: string;
+    /** Default sender name (optional) */
+    fromName?: string;
+    /** Priority for adapter selection (lower = higher priority) */
+    priority: number;
+    /** Fallback adapter if Infobip fails */
+    fallbackAdapter?: unknown;
+    /** Webhook configuration for delivery tracking */
+    webhookConfig?: WebhookConfig;
+    /** Token configuration for unsubscribe/preference management */
+    tokenConfig?: TokenConfig;
+    /** Token URL configuration */
+    tokenUrls?: TokenUrlConfig;
+    /**
+     * Request timeout in milliseconds
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * SendGrid adapter configuration
+ */
+export interface SendGridConfig extends UnknownRecord {
+    /** SendGrid API Key */
+    apiKey: string;
+    /** Default sender email address */
+    fromEmail: string;
+    /** Default sender name (optional) */
+    fromName?: string;
+    /** Priority for adapter selection (lower = higher priority) */
+    priority: number;
+    /** Fallback adapter if SendGrid fails */
+    fallbackAdapter?: unknown;
+    /**
+     * Webhook configuration for SendGrid Event Webhook
+     * Supports single handler or array of handlers for Separation of Concerns
+     */
+    webhookConfig?: WebhookConfig;
+    /**
+     * Token generation configuration for unsubscribe/preference links
+     * Enables CAN-SPAM compliance features
+     */
+    tokenConfig?: TokenConfig;
+    /**
+     * Token URL configuration
+     * Defines base URLs for different token types (unsubscribe, preferences, etc.)
+     */
+    tokenUrls?: TokenUrlConfig;
+}
+/**
+ * Mock provider configuration (for testing)
+ */
+export interface MockProviderConfig extends UnknownRecord {
+    providerName: string;
+    priority: number;
+    shouldFail?: boolean;
+    delayMs?: number;
+    fallbackAdapter?: unknown;
+}
+/**
+ * Attachment definition
+ */
+export interface Attachment {
+    /** File name */
+    filename: string;
+    /** File content (base64 encoded or Buffer) */
+    content?: string | globalThis.Buffer;
+    /** URL to fetch the file from */
+    url?: string;
+    /** MIME type */
+    type?: string;
+    /** Content disposition (attachment or inline) */
+    disposition?: 'attachment' | 'inline';
+    /** Content ID for inline attachments */
+    contentId?: string;
+}
+/**
+ * Notification input sent to adapters
+ */
+export interface NotificationInput {
+    /** Recipient address (email, phone, or device token) */
+    to: string;
+    /** Subject (email and push only) */
+    subject?: string;
+    /** Plain text content */
+    text: string;
+    /** HTML content (email only) */
+    html?: string;
+    /** Template data for variable substitution */
+    templateData?: UnknownRecord;
+    /** File attachments (email only) */
+    attachments?: NotificationAttachment[];
+    /** Custom headers (email only, e.g., List-Unsubscribe) */
+    headers?: Record<string, string>;
+}
+/**
+ * Notification send result from adapters
+ */
+export interface NotificationSendResult {
+    /** Provider's message ID for tracking */
+    messageId: string;
+    /** Provider name that sent the notification */
+    provider: string;
+    /** Timestamp when sent */
+    timestamp: Date;
+    /** Number of retry attempts made (1 = success on first try, 2+ = retries) */
+    retryAttempts?: number;
+    /** Failure reason if send failed (for tracking) */
+    failureReason?: string;
+}
+/**
+ * Notification response returned to application
+ */
+export interface NotificationResponse {
+    /** Unique notification ID (correlation ID) */
+    notificationId: string;
+    /** Current status */
+    status: NotificationStatus;
+    /** Provider that sent it (if sent) */
+    provider?: string;
+    /** Provider's message ID (if sent) */
+    providerMessageId?: string;
+    /** Number of retry attempts made before success/failure */
+    retryAttempts?: number;
+    /** Failure reason if notification failed */
+    failureReason?: string;
+}
+/**
+ * Send email parameters
+ */
+export interface SendEmailParams {
+    /** Recipient ID (user ID) */
+    recipientId: string;
+    /** Email address */
+    to: string;
+    /** Template ID to use */
+    templateId: string;
+    /** Data for template variables */
+    templateData?: UnknownRecord;
+    /** Locale for template (default: 'en') */
+    locale?: string;
+    /** Priority (default: 'normal') */
+    priority?: QueuePriority;
+    /** Correlation ID for tracking (auto-generated if not provided) */
+    correlationId?: string;
+    /** File attachments for the email */
+    attachments?: Attachment[];
+    /**
+     * Notification category (default: 'transactional')
+     * Determines opt-out behavior
+     */
+    category?: NotificationCategory;
+}
+/**
+ * Send SMS parameters
+ */
+export interface SendSMSParams {
+    /** Recipient ID (user ID) */
+    recipientId: string;
+    /** Phone number (E.164 format) */
+    to: string;
+    /** Template ID to use */
+    templateId: string;
+    /** Data for template variables */
+    templateData?: UnknownRecord;
+    /** Locale for template (default: 'en') */
+    locale?: string;
+    /** Priority (default: 'normal') */
+    priority?: QueuePriority;
+    /** Correlation ID for tracking (auto-generated if not provided) */
+    correlationId?: string;
+    /**
+     * Notification category (default: 'transactional')
+     * Determines opt-out behavior
+     */
+    category?: NotificationCategory;
+}
+/**
+ * Send push notification parameters
+ */
+export interface SendPushParams {
+    /** Recipient ID (user ID) */
+    recipientId: string;
+    /** Device token */
+    to: string;
+    /** Template ID to use */
+    templateId: string;
+    /** Data for template variables */
+    templateData?: UnknownRecord;
+    /** Locale for template (default: 'en') */
+    locale?: string;
+    /**
+     * Notification category (default: 'transactional')
+     * Determines opt-out behavior
+     */
+    category?: NotificationCategory;
+    /** Priority (default: 'normal') */
+    priority?: QueuePriority;
+    /** Correlation ID for tracking (auto-generated if not provided) */
+    correlationId?: string;
+}
+/**
+ * Queued notification for internal queue
+ */
+export interface QueuedNotification {
+    /** Correlation ID */
+    id: string;
+    /** Recipient ID */
+    recipientId: string;
+    /** Channel type */
+    channel: NotificationChannel;
+    /** Template ID */
+    templateId: string;
+    /** Priority for queue sorting */
+    priority: QueuePriority;
+    /** Notification input */
+    input: NotificationInput;
+    /** Timestamp queued */
+    queuedAt: Date;
+    /** Retry count */
+    retryCount: number;
+}
+/**
+ * Available layout variants
+ * - branded: Full branding with logo, colors, and styling
+ * - minimal: Simple, clean layout with basic styling
+ * - transactional: Ultra-minimal for transactional emails
+ * - none: No layout (disable header/footer)
+ */
+export type LayoutVariant = 'branded' | 'minimal' | 'transactional' | 'none';
+/**
+ * Layout configuration for templates
+ * Can be:
+ * - string: Use same variant for header and footer
+ * - object: Configure header and footer separately
+ * - false/null: Disable all layouts
+ */
+export type LayoutConfig = LayoutVariant | {
+    /** Header layout variant (or false to disable) */
+    header?: LayoutVariant | false;
+    /** Footer layout variant (or false to disable) */
+    footer?: LayoutVariant | false;
+} | false | null;
+/**
+ * Resolved layout configuration (after applying defaults)
+ */
+export interface ResolvedLayoutConfig {
+    /** Header variant to use (null if disabled) */
+    header: LayoutVariant | null;
+    /** Footer variant to use (null if disabled) */
+    footer: LayoutVariant | null;
+}
+/**
+ * Token generation strategies
+ * - aes-256-gcm: Encrypted token (most secure, larger size)
+ * - jwt: Standard JWT (readable payload, signed)
+ * - hmac-sha256: HMAC-signed token (compact, fast)
+ */
+export type TokenStrategy = 'aes-256-gcm' | 'jwt' | 'hmac-sha256';
+/**
+ * Action destinations
+ * - url: Opens a web page (FE calls API with token)
+ * - webhook: Calls API directly (immediate processing)
+ */
+export type ActionDestination = 'url' | 'webhook';
+/**
+ * Token types (action_destination format)
+ * - unsubscribe_url: User clicks → Opens unsubscribe page
+ * - unsubscribe_webhook: User clicks → Calls API directly
+ * - preference_url: User clicks → Opens preference center
+ * - preference_webhook: User clicks → Updates preferences via webhook
+ * - tracking_pixel: Invisible pixel for open tracking (always webhook)
+ */
+export type TokenType = 'unsubscribe_url' | 'unsubscribe_webhook' | 'preference_url' | 'preference_webhook' | 'tracking_pixel';
+/**
+ * Token configuration for generation
+ */
+export interface TokenConfig {
+    /** Token generation strategy */
+    strategy: TokenStrategy;
+    /** Secret key for encryption/signing */
+    secret: string;
+    /** Token expiry in seconds (default: 2592000 = 30 days) */
+    expirySeconds?: number;
+}
+/**
+ * Token URL configuration
+ */
+export interface TokenUrlConfig {
+    /** Base URLs for each token type */
+    baseUrls: {
+        unsubscribe_url?: string;
+        unsubscribe_webhook?: string;
+        preference_url?: string;
+        preference_webhook?: string;
+        tracking_pixel?: string;
+    };
+    /** Query parameters to include in generated URLs */
+    includeQueryParams?: {
+        /** Include template name */
+        template?: boolean;
+        /** Include email address (hashed) */
+        email?: boolean;
+        /** Include notification category */
+        category?: boolean;
+        /** Include timestamp */
+        timestamp?: boolean;
+    };
+    /** Per-category URL overrides */
+    categoryOverrides?: {
+        [category: string]: {
+            unsubscribe_url?: string;
+            unsubscribe_webhook?: string;
+            preference_url?: string;
+            preference_webhook?: string;
+        };
+    };
+}
+/**
+ * Token payload (encrypted/signed data)
+ */
+export interface TokenPayload {
+    /** User/recipient ID */
+    recipientId: string;
+    /** Token type */
+    type: TokenType;
+    /** Notification category */
+    category: string;
+    /** Expiration timestamp (Unix seconds) */
+    expiresAt: number;
+    /** Optional correlation ID */
+    correlationId?: string;
+}
+/**
+ * Template unsubscribe configuration
+ * Can be:
+ * - false: Disable unsubscribe completely
+ * - true: Enable with default settings
+ * - object: Custom configuration
+ */
+export type TemplateUnsubscribeConfig = boolean | {
+    /** Enable unsubscribe for this template */
+    enabled?: boolean;
+    /** Action destination type */
+    type?: ActionDestination;
+    /** Custom URL override (bypasses adapter config) */
+    customUrl?: string;
+    /**
+     * Include List-Unsubscribe email header (RFC 8058)
+     * Allows one-click unsubscribe in email clients.
+     */
+    includeListUnsubscribeHeader?: boolean;
+};
+/**
+ * Template frontmatter metadata
+ */
+export interface TemplateFrontmatter {
+    /** Email subject template */
+    subject?: string;
+    /** From email address */
+    from?: string;
+    /** From name */
+    fromName?: string;
+    /** Channel this template is for */
+    channel: NotificationChannel;
+    /** Notification category */
+    category?: NotificationCategory;
+    /** Preheader text (email only) */
+    preheader?: string;
+    /** Unsubscribe configuration */
+    unsubscribe?: TemplateUnsubscribeConfig;
+    /** Layout configuration */
+    layout?: LayoutConfig;
+    /** Any additional metadata */
+    [key: string]: unknown;
+}
+/**
+ * Rendered template output
+ */
+export interface RenderedTemplate {
+    /** Template metadata from frontmatter */
+    metadata: TemplateFrontmatter;
+    /** Rendered subject (with variables substituted) */
+    subject?: string;
+    /** HTML content (email only) */
+    html?: string;
+    /** Plain text content */
+    text: string;
+    /** Locale used */
+    locale: string;
+    /** Optional headers (e.g., List-Unsubscribe) */
+    headers?: Record<string, string>;
+}
+/**
+ * SMS Encoding Type
+ * Determines character limits and segment sizes
+ */
+export type SMSEncoding = 'GSM-7' | 'UCS-2';
+/**
+ * SMS Validation Behavior
+ * Determines what happens when SMS exceeds character limits
+ */
+export type SMSValidationBehavior = 'warn' | 'error' | 'truncate' | 'allow';
+/**
+ * SMS Validation Configuration
+ * Configurable limits and behavior for SMS character validation
+ */
+export interface SMSValidationConfig {
+    /**
+     * Enable SMS character validation
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of SMS segments to allow
+     * @default 10
+     */
+    maxSegments?: number;
+    /**
+     * Warning threshold as percentage of limit (0-100)
+     * @default 90
+     */
+    warningThreshold?: number;
+    /**
+     * Behavior when message exceeds character limit
+     * @default 'warn'
+     */
+    onExceedLimit?: SMSValidationBehavior;
+    /**
+     * Behavior when message exceeds max segments
+     * @default 'error'
+     */
+    onExceedSegments?: SMSValidationBehavior;
+    /**
+     * Custom single message limit (GSM-7 encoding)
+     * @default 160
+     */
+    gsm7SingleLimit?: number;
+    /**
+     * Custom multi-part segment limit (GSM-7 encoding)
+     * @default 153
+     */
+    gsm7MultiPartLimit?: number;
+    /**
+     * Custom single message limit (UCS-2 encoding)
+     * @default 70
+     */
+    ucs2SingleLimit?: number;
+    /**
+     * Custom multi-part segment limit (UCS-2 encoding)
+     * @default 67
+     */
+    ucs2MultiPartLimit?: number;
+}
+/**
+ * SMS Character Analysis Result
+ * Information about SMS message encoding and segmentation
+ */
+export interface SMSCharacterAnalysis {
+    /** Total character count */
+    characterCount: number;
+    /** Detected encoding type (GSM-7 or UCS-2) */
+    encoding: SMSEncoding;
+    /** Number of SMS segments required */
+    segmentCount: number;
+    /** Characters per segment for this message */
+    charactersPerSegment: number;
+    /** Characters remaining in current segment */
+    remainingInSegment: number;
+    /** Whether message exceeds single segment */
+    isMultiPart: boolean;
+    /** Whether message contains unicode/emoji */
+    containsUnicode: boolean;
+    /** Whether message exceeds configured limits */
+    exceedsLimit: boolean;
+    /** Whether message exceeds max segments */
+    exceedsMaxSegments: boolean;
+    /** Warning message if applicable */
+    warning?: string;
+    /** List of non-GSM-7 characters that triggered UCS-2 encoding */
+    unicodeCharacters?: string[];
+}
+/**
+ * URL Shortening Options
+ */
+export interface UrlShortenOptions {
+    /** Custom short code (if supported by adapter) */
+    customCode?: string;
+    /** Expiration time in seconds */
+    expiresIn?: number;
+    /** Metadata to store with the shortened URL */
+    metadata?: UnknownRecord;
+    /** Notification context (for tracking) */
+    notificationContext?: {
+        recipientId: string;
+        templateId: string;
+        channel: NotificationChannel;
+        category?: string;
+    };
+}
+/**
+ * URL Analytics Data
+ */
+export interface UrlAnalytics {
+    /** Shortened URL */
+    shortUrl: string;
+    /** Original long URL */
+    originalUrl: string;
+    /** Number of clicks */
+    clicks: number;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last clicked timestamp */
+    lastClickedAt?: number;
+    /** Expiration timestamp */
+    expiresAt?: number;
+    /** Additional metadata */
+    metadata?: UnknownRecord;
+}
+/**
+ * URL Shortener Adapter Interface
+ * Implement this interface to create custom URL shortening providers
+ */
+export interface UrlShortenerAdapter {
+    /**
+     * Shorten a long URL
+     */
+    shorten(url: string, options?: UrlShortenOptions): Promise<string>;
+    /**
+     * Expand a shortened URL back to original (optional)
+     */
+    expand?(shortUrl: string): Promise<string | null>;
+    /**
+     * Get analytics for a shortened URL (optional)
+     */
+    getAnalytics?(shortUrl: string): Promise<UrlAnalytics | null>;
+}
+/**
+ * URL Shortener Storage Interface
+ * Implement this to provide persistent storage for self-hosted URL shortening
+ */
+export interface UrlShortenerStorage {
+    /**
+     * Store a URL mapping
+     */
+    store(shortCode: string, originalUrl: string, options?: {
+        expiresAt?: number;
+        metadata?: UnknownRecord;
+    }): Promise<void>;
+    /**
+     * Retrieve original URL by short code
+     */
+    retrieve(shortCode: string): Promise<string | null>;
+    /**
+     * Check if a short code exists
+     */
+    exists(shortCode: string): Promise<boolean>;
+    /**
+     * Increment click count for a short code
+     */
+    incrementClicks?(shortCode: string): Promise<void>;
+    /**
+     * Get analytics for a short code
+     */
+    getAnalytics?(shortCode: string): Promise<UrlAnalytics | null>;
+    /**
+     * Clean up expired URLs (optional maintenance method)
+     */
+    cleanup?(): Promisable<void>;
+}
+/**
+ * URL Shortener Configuration
+ */
+export interface UrlShortenerConfig {
+    /**
+     * Enable URL shortening per channel
+     * @default { sms: true, push: false, email: false }
+     */
+    enabled?: boolean | {
+        sms?: boolean;
+        push?: boolean;
+        email?: boolean;
+    };
+    /**
+     * URL shortener adapter
+     */
+    adapter: UrlShortenerAdapter;
+    /**
+     * Minimum URL length to trigger shortening
+     * @default 50
+     */
+    minUrlLength?: number;
+    /**
+     * Only shorten URLs matching these domain patterns
+     * @default []
+     */
+    allowedDomains?: string[];
+    /**
+     * Skip shortening URLs matching these domain patterns
+     * @default ['bit.ly', 'tinyurl.com', 't.co', 'goo.gl']
+     */
+    skipDomains?: string[];
+    /**
+     * Base URL for shortened links (for self-hosted)
+     */
+    baseUrl?: string;
+}
+/**
+ * Provider configuration item - supports two patterns:
+ * 1. Direct adapter instance (simple): new SendGridAdapter({...}, logger)
+ * 2. Config object (dynamic/runtime): { name: 'SendGrid', enabled: true, credentials: {...} }
+ */
+export type ProviderConfigOrAdapter = NotificationProviderConfig | unknown;
+/**
+ * Notification providers configuration
+ * Organized by channel for easy access
+ *
+ * Supports two patterns:
+ * 1. Simple (direct adapters): email: [new SendGridAdapter({...}, logger)]
+ * 2. Dynamic (config-driven): email: [{ name: 'SendGrid', enabled: true, credentials: {...} }]
+ */
+export interface NotificationProvidersConfig {
+    /** Email provider configurations or adapter instances */
+    email: ProviderConfigOrAdapter[];
+    /** SMS provider configurations or adapter instances */
+    sms: ProviderConfigOrAdapter[];
+    /** Push notification provider configurations or adapter instances */
+    push: ProviderConfigOrAdapter[];
+}
+/**
+ * Notification health status
+ */
+export interface NotificationHealthStatus {
+    /** Overall health */
+    healthy: boolean;
+    /** Timestamp */
+    timestamp: Date;
+    /** Provider statuses */
+    providers: ProviderStatus[];
+}
+/**
+ * Provider status
+ */
+export interface ProviderStatus {
+    /** Provider name */
+    provider: string;
+    /** Channel */
+    channel: NotificationChannel;
+    /** Healthy? */
+    healthy: boolean;
+    /** Latency in ms */
+    latency?: number;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Circuit breaker stats */
+    circuitBreaker?: CircuitBreakerStats;
+}
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    nextAttemptTime?: number;
+}
+/**
+ * Retry configuration for notifications
+ * Renamed to avoid collision with api/retry types
+ */
+export interface NotificationRetryConfig {
+    /** Maximum retry attempts */
+    maxAttempts?: number;
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+    /** Backoff multiplier */
+    backoffMultiplier?: number;
+    /** Add random jitter to prevent thundering herd */
+    jitter?: boolean;
+}
+/**
+ * Retry result for notifications
+ * Renamed to avoid collision with api/retry types
+ */
+export interface NotificationRetryResult<T> {
+    success: boolean;
+    data?: T;
+    error?: Error;
+    attempts: number;
+}
+/**
+ * Token verification result
+ */
+export interface TokenVerificationResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+}
+/**
+ * Notification queue statistics (simple version)
+ */
+export interface NotificationQueueStats {
+    size: number;
+    processing: number;
+    processed: number;
+    failed: number;
+}
+/**
+ * Notification queue configuration (simple version)
+ */
+export interface NotificationQueueConfig {
+    maxSize?: number;
+    processImmediately?: boolean;
+}
+/**
+ * InMemory queue statistics (detailed version)
+ * Used by InMemoryQueue implementation
+ */
+export interface InMemoryQueueStats {
+    size: number;
+    processing: boolean;
+    highPriority: number;
+    normalPriority: number;
+    lowPriority: number;
+    processedCount: number;
+    failedCount: number;
+}
+/**
+ * InMemory queue configuration
+ * Used by InMemoryQueue implementation
+ */
+export interface InMemoryQueueConfig {
+    /** Maximum queue size (default: 10000) */
+    maxSize?: number;
+    /** Enable auto-processing (default: false for manual control) */
+    autoProcess?: boolean;
+}
+/**
+ * HMAC signature verification options
+ */
+export interface HMACSignatureOptions {
+    secret: string;
+    payload: string | globalThis.Buffer;
+    signature: string;
+    timestamp?: string;
+    encoding?: 'hex' | 'base64';
+}
+/**
+ * Webhook signature computation options
+ */
+export interface WebhookSignatureOptions {
+    secret: string;
+    payload: string | globalThis.Buffer;
+    timestamp: string;
+    method?: 'hmac' | 'ecdsa';
+    encoding?: 'hex' | 'base64';
+}
+/**
+ * Template render options
+ * Renamed to avoid collision with testing RenderOptions
+ */
+export interface NotificationRenderOptions {
+    /** Locale for template */
+    locale?: string;
+    /** Fallback locale if preferred not found */
+    fallbackLocale?: string;
+    /** Layout data for header/footer */
+    layoutData?: {
+        unsubscribeUrl?: string;
+        preferencesUrl?: string;
+        companyName?: string;
+        companyAddress?: string;
+        [key: string]: unknown;
+    };
+    /** SMS validation config override */
+    smsValidation?: SMSValidationConfig;
+    /** URL shortener config override */
+    urlShortener?: UrlShortenerConfig;
+    /** Notification context for event emission */
+    notificationContext?: {
+        recipientId: string;
+        templateId: string;
+        channel: NotificationChannel;
+        category?: string;
+        correlationId?: string;
+    };
+    /** URL shortening event callback */
+    onUrlShortened?: (payload: {
+        originalUrl: string;
+        shortUrl: string;
+        channel: NotificationChannel;
+        recipientId: string;
+        templateId: string;
+        category?: string;
+        correlationId?: string;
+        charactersSaved: number;
+        timestamp: Date;
+        metadata?: UnknownRecord;
+    }) => Promisable<void>;
+}
+/**
+ * Attachment disposition
+ * - attachment: Download as file
+ * - inline: Embed in content (e.g., images in email)
+ */
+export type AttachmentDisposition = 'attachment' | 'inline';
+/**
+ * Attachment source type
+ */
+export type AttachmentSourceType = 'buffer' | 'url' | 'path' | 'cloud';
+/**
+ * Cloud storage provider types
+ */
+export type CloudStorageProvider = 's3' | 'r2' | 'gcs' | 'azure-blob' | 'custom';
+/**
+ * Basic authentication credentials
+ */
+export interface BasicAuthCredentials {
+    username: string;
+    password: string;
+}
+/**
+ * Bearer token authentication
+ */
+export interface BearerAuthCredentials {
+    token: string;
+}
+/**
+ * API key authentication
+ */
+export interface ApiKeyAuthCredentials {
+    key: string;
+    /** Header name (default: 'X-API-Key') */
+    headerName?: string;
+}
+/**
+ * OAuth2 credentials
+ */
+export interface OAuth2Credentials {
+    accessToken: string;
+    tokenType?: string;
+}
+/**
+ * AWS Signature V4 credentials (for S3, R2, etc.)
+ */
+export interface AWSSignatureCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region?: string;
+    sessionToken?: string;
+}
+/**
+ * Custom authentication (provide your own headers)
+ */
+export interface CustomAuthCredentials {
+    headers: Record<string, string>;
+}
+/**
+ * Authentication for URL/cloud attachments
+ */
+export interface AttachmentAuth {
+    /** Authentication type */
+    type: 'basic' | 'bearer' | 'api-key' | 'oauth2' | 'aws-signature' | 'custom';
+    /** Credentials */
+    credentials: BasicAuthCredentials | BearerAuthCredentials | ApiKeyAuthCredentials | OAuth2Credentials | AWSSignatureCredentials | CustomAuthCredentials;
+}
+/**
+ * Cloud storage configuration
+ */
+export interface CloudStorageConfig {
+    /** Provider type */
+    provider: CloudStorageProvider;
+    /** Bucket/container name */
+    bucket: string;
+    /** Object key/path */
+    key: string;
+    /** Region (for AWS S3, R2) */
+    region?: string;
+    /** Custom endpoint (for R2, MinIO, etc.) */
+    endpoint?: string;
+    /** Authentication credentials */
+    auth: AttachmentAuth;
+}
+/**
+ * Attachment source configuration
+ */
+export type AttachmentSource = {
+    /** Direct buffer/string content */
+    type: 'buffer';
+    content: globalThis.Buffer | string;
+} | {
+    /** HTTP/HTTPS URL */
+    type: 'url';
+    url: string;
+    /** Optional authentication for protected URLs */
+    auth?: AttachmentAuth;
+    /** Custom headers */
+    headers?: Record<string, string>;
+} | {
+    /** Local file system path */
+    type: 'path';
+    path: string;
+} | {
+    /** Cloud storage (S3, R2, GCS, Azure) */
+    type: 'cloud';
+    config: CloudStorageConfig;
+};
+/**
+ * Notification attachment interface (channel-agnostic)
+ * Prefixed to avoid collision if imported with other Attachment types
+ */
+export interface NotificationAttachment {
+    /** Filename with extension (e.g., "invoice.pdf") */
+    filename: string;
+    /** Attachment source (buffer, URL, path, or cloud storage) */
+    source: AttachmentSource;
+    /** MIME type (e.g., "application/pdf", "image/png") */
+    contentType: string;
+    /** Size in bytes (auto-calculated if not provided) */
+    size?: number;
+    /** How to display: 'attachment' (download) or 'inline' (embed) */
+    disposition?: AttachmentDisposition;
+    /** Content ID for inline images (e.g., "logo" for cid:logo) */
+    contentId?: string;
+}
+/**
+ * Provider-specific attachment capabilities
+ *
+ * Each adapter declares what attachments it supports
+ */
+export interface AttachmentCapabilities {
+    /** Maximum number of attachments allowed */
+    maxAttachments: number;
+    /** Maximum size per attachment in bytes */
+    maxSizePerAttachment: number;
+    /** Maximum total size of all attachments in bytes */
+    maxTotalSize: number;
+    /** Supported MIME types (e.g., ['application/pdf', 'image/*']) */
+    supportedMimeTypes: string[];
+    /** Supported file extensions (e.g., ['.pdf', '.jpg', '.png']) */
+    supportedExtensions: string[];
+    /** Supports inline attachments (embedded images) */
+    supportsInline: boolean;
+    /** Accepts base64-encoded content */
+    supportsBase64: boolean;
+}
+/**
+ * Attachment validation result
+ */
+export interface AttachmentValidationResult {
+    valid: boolean;
+    errors: AttachmentValidationError[];
+}
+/**
+ * Attachment validation error
+ */
+export interface AttachmentValidationError {
+    type: AttachmentErrorType;
+    message: string;
+    attachment?: Attachment;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Attachment error types
+ */
+export type AttachmentErrorType = 'EXCEEDS_MAX_ATTACHMENTS' | 'EXCEEDS_SIZE_LIMIT' | 'EXCEEDS_TOTAL_SIZE' | 'UNSUPPORTED_MIME_TYPE' | 'UNSUPPORTED_EXTENSION' | 'INVALID_FILENAME' | 'INVALID_CONTENT' | 'INLINE_NOT_SUPPORTED';
+/**
+ * Transformed attachment for provider use
+ * This is the common format used by most email providers (SendGrid, Mailgun, etc.)
+ * Providers can use this directly or create their own format
+ */
+export interface TransformedAttachment {
+    /** Attachment filename */
+    filename: string;
+    /** Base64-encoded content */
+    content: string;
+    /** MIME type */
+    type: string;
+    /** Disposition: 'attachment' or 'inline' */
+    disposition: 'attachment' | 'inline';
+    /** Content ID for inline attachments (optional) */
+    content_id?: string;
+}
+/**
+ * Resolved attachment with buffer content
+ * Result of resolving an attachment from its source
+ */
+export interface ResolvedAttachment {
+    filename: string;
+    content: globalThis.Buffer;
+    contentType: string;
+    size: number;
+    disposition?: 'attachment' | 'inline';
+    contentId?: string;
+}
+/**
+ * Attachment resolver options
+ * Configuration for resolving attachments from various sources
+ */
+export interface AttachmentResolverOptions {
+    /** Timeout for HTTP requests in milliseconds */
+    httpTimeout?: number;
+    /** Maximum file size to fetch */
+    maxFileSize?: number;
+    /** Allow local file paths (default: true) */
+    allowLocalPaths?: boolean;
+    /** Logger */
+    logger?: unknown;
+}
+/**
+ * Base event payload with generic metadata support
+ */
+export interface NotificationEventPayload<TMetadata = UnknownRecord> {
+    notificationId: string;
+    recipientId: string;
+    channel: NotificationChannel;
+    templateId: string;
+    timestamp: Date;
+    category: NotificationCategory;
+    metadata?: TMetadata;
+}
+/**
+ * Sent event payload
+ */
+export interface NotificationSentPayload extends NotificationEventPayload {
+    provider: string;
+    providerMessageId: string;
+    attemptedProviders: string[];
+    fallbackUsed: boolean;
+    metadata?: {
+        provider?: string;
+        messageId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Failed event payload
+ */
+export interface NotificationFailedPayload extends NotificationEventPayload {
+    error?: {
+        message: string;
+        code?: string;
+        [key: string]: unknown;
+    };
+    attemptedProviders: string[];
+    retryCount: number;
+    nextRetryAt?: Date;
+}
+/**
+ * Delivered event payload (from webhooks)
+ */
+export interface NotificationDeliveredPayload extends NotificationEventPayload {
+    provider: string;
+    providerMessageId: string;
+    deliveredAt: Date;
+}
+/**
+ * Engagement event payload (clicks, opens)
+ */
+export interface NotificationEngagementPayload extends NotificationEventPayload {
+    provider: string;
+    providerMessageId: string;
+    eventType: 'opened' | 'clicked';
+    timestamp: Date;
+    metadata?: {
+        url?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * URL Shortening Event Payload
+ * Emitted when a URL is shortened during template rendering
+ */
+export interface UrlShortenedPayload {
+    /** Original long URL */
+    originalUrl: string;
+    /** Shortened URL */
+    shortUrl: string;
+    /** Notification channel (sms, push, email) */
+    channel: NotificationChannel;
+    /** Recipient ID */
+    recipientId: string;
+    /** Template ID */
+    templateId: string;
+    /** Notification category */
+    category?: string;
+    /** Correlation ID for tracking */
+    correlationId?: string;
+    /** Characters saved by shortening */
+    charactersSaved: number;
+    /** Timestamp when URL was shortened */
+    timestamp: Date;
+    /** Optional metadata */
+    metadata?: UnknownRecord;
+}
+/**
+ * Debug event payload
+ */
+export interface DebugEventPayload<TMetadata = UnknownRecord> {
+    correlationId: string;
+    userId?: string;
+    event: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+    data: UnknownRecord;
+    metadata?: TMetadata;
+}
+/**
+ * Generic event callback function type
+ * Used by EventManager for type-safe event handling
+ */
+export type EventCallback<T = unknown> = (payload: T) => void | Promise<void>;
+/**
+ * Event callback types
+ */
+export interface NotificationEventCallbacks {
+    onQueued?: (payload: NotificationEventPayload) => Promisable<void>;
+    onProcessing?: (payload: NotificationEventPayload) => Promisable<void>;
+    onSent?: (payload: NotificationSentPayload) => Promisable<void>;
+    onFailed?: (payload: NotificationFailedPayload) => Promisable<void>;
+    onDelivered?: (payload: NotificationDeliveredPayload) => Promisable<void>;
+    onBounced?: (payload: NotificationEventPayload) => Promisable<void>;
+    onComplained?: (payload: NotificationEventPayload) => Promisable<void>;
+    onOpened?: (payload: NotificationEngagementPayload) => Promisable<void>;
+    onClicked?: (payload: NotificationEngagementPayload) => Promisable<void>;
+    onUrlShortened?: (payload: UrlShortenedPayload) => Promisable<void>;
+}
+/**
+ * Debug event callbacks
+ */
+export interface NotificationDebugEventCallbacks {
+    onQueued?: (payload: DebugEventPayload) => Promisable<void>;
+    onProviderSelected?: (payload: DebugEventPayload) => Promisable<void>;
+    onRateLimitChecked?: (payload: DebugEventPayload) => Promisable<void>;
+    onTemplateRendered?: (payload: DebugEventPayload) => Promisable<void>;
+    onSendingToProvider?: (payload: DebugEventPayload) => Promisable<void>;
+    onProviderSuccess?: (payload: DebugEventPayload) => Promisable<void>;
+    onProviderFailure?: (payload: DebugEventPayload) => Promisable<void>;
+    onWebhookReceived?: (payload: DebugEventPayload) => Promisable<void>;
+    onDelivered?: (payload: DebugEventPayload) => Promisable<void>;
+    onCircuitBreakerOpened?: (payload: DebugEventPayload) => Promisable<void>;
+    onFallbackTriggered?: (payload: DebugEventPayload) => Promisable<void>;
+}
+/**
+ * Logger interface
+ */
+export interface Logger {
+    debug(message: string, meta?: UnknownRecord): void;
+    info(message: string, meta?: UnknownRecord): void;
+    warn(message: string, meta?: UnknownRecord): void;
+    error(message: string, meta?: UnknownRecord): void;
+}
+/**
+ * Log level type
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * NotificationAdapter - Base interface all providers must implement
+ *
+ * This is the contract for all notification providers (SendGrid, Twilio, FCM, etc.)
+ * The adapter pattern ensures providers are swappable without code changes.
+ */
+export interface NotificationAdapter {
+    /** Provider name (type-safe from @plyaz/types) */
+    readonly providerName: string;
+    /** Priority for fallback ordering (1 = highest, 999 = lowest) */
+    readonly priority: number;
+    /** Channel this adapter handles */
+    readonly channel: NotificationChannel;
+    /** Optional fallback adapter to use if this adapter fails */
+    readonly fallbackAdapter?: NotificationAdapter;
+    /** Optional webhook adapters for this provider */
+    readonly webhooks?: unknown[];
+    /** Check if provider is available (credentials set, etc.) */
+    isAvailable(): boolean;
+    /** Health check for monitoring */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        latency?: number;
+        error?: string;
+    }>;
+    /** Send notification via this provider */
+    send(input: NotificationInput): Promise<NotificationResult<NotificationSendResult>>;
+    /** Send bulk notifications via this provider */
+    sendBulk?(inputs: NotificationInput[]): Promise<NotificationResult<NotificationSendResult>[]>;
+    /** Get attachment capabilities for this provider */
+    getAttachmentCapabilities(): AttachmentCapabilities;
+    /** Check if attachment is supported by this provider */
+    isSupportedAttachment(attachment: NotificationAttachment): boolean;
+    /** Get list of supported file extensions */
+    getSupportedAttachmentExtensions(): string[];
+    /** Get SMS validation configuration for this adapter (SMS adapters only) */
+    getSMSValidationConfig?(): SMSValidationConfig | undefined;
+    /** Get URL shortener configuration for this adapter */
+    getUrlShortenerConfig?(): UrlShortenerConfig | undefined;
+    /** Validate email addresses (Email adapters only) */
+    validateEmails?(emails: string[]): Promise<NotificationResult<EmailValidationResult[]>>;
+}
+/**
+ * ProviderPlugin - Factory pattern for creating provider adapters
+ *
+ * Plugins decouple provider registration from implementation.
+ */
+export interface ProviderPlugin<TConfig = UnknownRecord> {
+    /** Unique provider name */
+    name: ProviderName;
+    /** Channel this provider supports (email, sms, push) */
+    channel: NotificationChannel;
+    /** Factory method to create adapter instance */
+    create(config: TConfig, logger: Logger): NotificationAdapter;
+}
+/**
+ * TranslationService - Interface for template loading
+ *
+ * Abstracts template storage (file system, database, CDN, etc.)
+ */
+export interface TranslationService {
+    /** Get template content by path */
+    getTemplate(path: string): Promise<string>;
+}
+/**
+ * PreferenceChecker - Interface for user preference checking
+ *
+ * Allows external applications to enforce user preferences without vendor lock-in.
+ */
+export interface PreferenceChecker {
+    /**
+     * Check if a notification should be sent to a recipient
+     */
+    shouldSend(recipientId: string, category: NotificationCategory, channel: NotificationChannel): Promisable<boolean>;
+    /**
+     * Bulk preference check for batch operations
+     */
+    shouldSendBulk?(recipients: Array<{
+        recipientId: string;
+        category: NotificationCategory;
+        channel: NotificationChannel;
+    }>): Promisable<boolean[]>;
+}
+/**
+ * Error handler callbacks
+ */
+export interface NotificationErrorHandlers {
+    onProviderError?: (error: Error) => Promisable<void>;
+    onQueueError?: (error: Error) => Promisable<void>;
+    onWebhookError?: (error: Error) => Promisable<void>;
+    onAnyError?: (error: Error) => Promisable<void>;
+}
+/**
+ * NotificationServiceConfig - Main service configuration
+ *
+ * This is the primary configuration interface for creating NotificationService
+ */
+export interface NotificationServiceConfig {
+    /** Required: Provider configuration */
+    providers: NotificationProvidersConfig;
+    /** Optional: Locale configuration */
+    locale?: {
+        default: string;
+        fallback: string;
+    };
+    /** Optional: Additional error message catalogs */
+    additionalErrorMessages?: Record<string, MessageCatalog>;
+    /** Optional: Event handlers for lifecycle hooks */
+    events?: NotificationEventCallbacks;
+    /** Optional: Error handlers */
+    errorHandlers?: NotificationErrorHandlers;
+    /** Optional: Debug event handlers (for observability/analytics) */
+    debugEvents?: NotificationDebugEventCallbacks;
+    /** Optional: External dependencies */
+    logger?: Logger;
+    translationService?: TranslationService;
+    /** Optional: User preference checker */
+    preferenceChecker?: PreferenceChecker;
+    /** Optional: SMS validation configuration */
+    smsValidation?: SMSValidationConfig;
+}
+/**
+ * NotificationService - Main public API interface
+ *
+ * This is the public interface that applications interact with
+ */
+export interface NotificationServiceInstance {
+    sendEmail(params: SendEmailParams): Promise<NotificationResult<NotificationResponse>>;
+    sendSMS(params: SendSMSParams): Promise<NotificationResult<NotificationResponse>>;
+    sendPush(params: SendPushParams): Promise<NotificationResult<NotificationResponse>>;
+    sendBulkEmail(requests: SendEmailParams[]): Promise<NotificationResult<NotificationResponse>[]>;
+    sendBulkSMS(requests: SendSMSParams[]): Promise<NotificationResult<NotificationResponse>[]>;
+    sendBulkPush(requests: SendPushParams[]): Promise<NotificationResult<NotificationResponse>[]>;
+    validateEmails(emails: string[], providerName?: string): Promise<NotificationResult<EmailValidationResult[]>>;
+    healthCheck(): Promise<NotificationHealthStatus>;
+    getProviderStatus(): Promise<ProviderStatus[]>;
+}
+/**
+ * Processing function type
+ * Takes a queued notification and processes it
+ */
+export type ProcessFunction = (notification: QueuedNotification) => Promise<void>;
+/**
+ * Queue processor configuration
+ */
+export interface QueueProcessorConfig {
+    /** Number of concurrent workers */
+    concurrency?: number;
+    /** Processing interval in ms */
+    interval?: number;
+    /** Maximum retries per notification */
+    maxRetries?: number;
+    /** Enable auto-start */
+    autoStart?: boolean;
+    /** Optional event manager */
+    eventManager?: unknown;
+    /** Optional logger */
+    logger?: Logger;
+}
+/**
+ * Raw webhook payload from HTTP request
+ * Renamed to avoid collision with payments WebhookPayload
+ */
+export interface NotificationWebhookPayload<TBody = unknown> {
+    /** HTTP headers from webhook request */
+    headers: Record<string, string | string[] | undefined>;
+    /** Parsed body from webhook request */
+    body: TBody;
+    /** Query parameters if any */
+    query?: Record<string, string | string[]>;
+    /** Request method (usually POST) */
+    method?: string;
+    /** Full URL path */
+    url?: string;
+}
+/**
+ * Processed webhook event ready for internal handling
+ */
+export interface ProcessedWebhookEvent {
+    /** Internal notification ID (from our system) */
+    notificationId: string;
+    /** Provider's message ID */
+    providerMessageId: string;
+    /** Recipient identifier */
+    recipientId?: string;
+    /** Event type */
+    eventType: WEBHOOK_EVENT_TYPE;
+    /** Provider name */
+    provider: string;
+    /** Channel (email, sms, push) */
+    channel: NotificationChannel;
+    /** Notification category */
+    category?: NotificationCategory;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Additional provider-specific data */
+    metadata?: UnknownRecord;
+    /** Error details if event is failure-related */
+    error?: {
+        code?: string;
+        message?: string;
+        reason?: string;
+    };
+    /** Engagement data for opens/clicks */
+    engagement?: {
+        url?: string;
+        userAgent?: string;
+        ipAddress?: string;
+        location?: string;
+    };
+}
+/**
+ * Verification result from signature check
+ */
+export interface VerificationResult {
+    /** Whether signature is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Additional verification details */
+    details?: UnknownRecord;
+}
+/**
+ * Webhook processing result
+ */
+export interface WebhookProcessingResult {
+    /** Whether processing succeeded */
+    success: boolean;
+    /** Processed events (can be multiple events in one webhook) */
+    events: ProcessedWebhookEvent[];
+    /** Error if processing failed */
+    error?: Error;
+    /** Whether this was a duplicate (idempotency check) */
+    duplicate?: boolean;
+    /** Processing metadata */
+    metadata?: {
+        processingTime?: number;
+        eventCount?: number;
+    };
+}
+/**
+ * Main Webhook Adapter Interface
+ *
+ * All provider webhook adapters must implement this interface
+ *
+ * @template TPayload - Provider-specific payload type
+ * @template TSchema - Zod schema type for validation
+ */
+export interface WebhookAdapter<TPayload = unknown, TSchema extends z.ZodType<TPayload> = z.ZodType<TPayload>> {
+    /** Provider name (sendgrid, infobip, twilio, etc.) */
+    readonly providerName: string;
+    /** Channel this webhook handles */
+    readonly channel: NotificationChannel;
+    /** Zod schema for payload validation */
+    readonly schema: TSchema;
+    /** Priority for webhook processing (lower = higher priority) */
+    readonly priority?: number;
+    /**
+     * Verify webhook signature/authenticity
+     * CRITICAL: Always verify before processing to prevent spoofing
+     */
+    verify(payload: NotificationWebhookPayload<unknown>): Promisable<VerificationResult>;
+    /**
+     * Parse and process webhook payload
+     * Maps provider events to internal event format
+     */
+    process(payload: NotificationWebhookPayload<TPayload>): Promisable<ProcessedWebhookEvent[]>;
+    /**
+     * Extract idempotency key from payload
+     * Used to prevent duplicate processing
+     */
+    getIdempotencyKey?(payload: NotificationWebhookPayload<TPayload>): string;
+    /**
+     * Optional: Check if this adapter should handle this webhook
+     * Useful when multiple adapters are registered for same provider
+     */
+    shouldProcess?(payload: NotificationWebhookPayload<unknown>): boolean;
+    /**
+     * Optional: Custom error handler for this adapter
+     */
+    handleError?(error: Error, payload: NotificationWebhookPayload<unknown>): Promisable<void>;
+}
+/**
+ * Webhook middleware for pre/post processing
+ */
+export interface WebhookMiddleware {
+    /** Middleware name for logging */
+    name: string;
+    /** Priority (lower = runs earlier) */
+    priority?: number;
+    /**
+     * Execute before webhook processing
+     */
+    before?(payload: NotificationWebhookPayload<unknown>): Promisable<NotificationWebhookPayload<unknown> | void>;
+    /**
+     * Execute after webhook processing
+     */
+    after?(result: WebhookProcessingResult, payload: NotificationWebhookPayload<unknown>): Promisable<WebhookProcessingResult | void>;
+    /**
+     * Execute on error
+     */
+    onError?(error: Error, payload: NotificationWebhookPayload<unknown>): Promisable<void>;
+}
+/**
+ * Configuration for webhook adapter
+ */
+export interface WebhookAdapterConfig {
+    /** Secret key for signature verification */
+    secret: string;
+    /** Enable/disable this webhook adapter */
+    enabled?: boolean;
+    /** Custom timeout for webhook processing (ms) */
+    timeout?: number;
+    /** Custom idempotency TTL (ms) */
+    idempotencyTTL?: number;
+    /** Additional provider-specific configuration */
+    [key: string]: unknown;
+}
+/**
+ * Webhook encryption methods
+ */
+export type WebhookEncryptionMethod = 'hmac' | 'ecdsa' | 'rsa' | 'custom';
+/**
+ * Webhook encryption configuration
+ */
+export interface WebhookEncryption {
+    /** Encryption/signing method */
+    method: WebhookEncryptionMethod;
+    /** Secret key for HMAC */
+    secret?: string;
+    /** Public key for ECDSA/RSA verification */
+    publicKey?: string;
+    /** Private key for ECDSA/RSA signing (if generating webhooks) */
+    privateKey?: string;
+    /** Algorithm (e.g., 'sha256', 'sha512') */
+    algorithm?: string;
+    /** Encoding (e.g., 'hex', 'base64') */
+    encoding?: 'hex' | 'base64';
+    /** Custom verification function */
+    verify?: (payload: string, signature: string) => Promisable<boolean>;
+    /** Custom signing function */
+    sign?: (payload: string) => Promisable<string>;
+}
+/**
+ * Webhook Encryption Configuration
+ * Used to automatically hash PII before sending to providers
+ */
+export interface WebhookEncryptionConfig {
+    /** Enable/disable automatic PII hashing */
+    enabled: boolean;
+    /** Encryption method */
+    method: WEBHOOK_ENCRYPTION_METHOD;
+    /** Secret key for hashing (MUST be stored securely) */
+    secret: string;
+    /** Hash length (characters), default: 16 */
+    hashLength?: number;
+    /** Fields to automatically hash, default: ['recipientId', 'userId'] */
+    fieldsToHash?: string[];
+    /** Whether to store ID mappings automatically */
+    storeMapping?: boolean;
+    /** Optional: External store for ID mappings */
+    idMappingStore?: IdMappingStore;
+}
+/**
+ * ID Mapping Store Interface
+ * Implement this to store hashed ID mappings in your database
+ */
+export interface IdMappingStore {
+    /** Store a mapping between original and hashed ID */
+    store(originalId: string, hashedId: string): Promise<void>;
+    /** Retrieve original ID from hashed ID */
+    getOriginalId(hashedId: string): Promise<string | undefined>;
+    /** Retrieve hashed ID from original ID */
+    getHashedId(originalId: string): Promise<string | undefined>;
+    /** Delete a mapping */
+    delete(originalId: string): Promise<void>;
+    /** Bulk store mappings (for performance) */
+    storeBulk?(mappings: Array<{
+        originalId: string;
+        hashedId: string;
+    }>): Promise<void>;
+}
+/**
+ * Hashed ID result
+ */
+export interface HashedIdResult {
+    /** Original ID (PII) */
+    originalId: string;
+    /** Hashed ID (PII-safe) */
+    hashedId: string;
+    /** Encryption method used */
+    method: WEBHOOK_ENCRYPTION_METHOD;
+    /** When it was hashed */
+    hashedAt: Date;
+}
+/**
+ * External idempotency store interface
+ * Implement this to use Redis, Database, etc.
+ */
+export interface ExternalIdempotencyStore {
+    /** Check if key exists and is not expired */
+    has(key: string): Promise<boolean>;
+    /** Store key with TTL */
+    set(key: string, ttl: number, metadata?: UnknownRecord): Promise<void>;
+    /** Remove key */
+    delete(key: string): Promise<void>;
+    /** Clear all keys (for testing) */
+    clear?(): Promise<void>;
+}
+/**
+ * Idempotency Store Configuration
+ */
+export interface IdempotencyStoreConfig {
+    /** Default TTL for idempotency keys (ms) */
+    defaultTTL?: number;
+    /** Cleanup interval for expired keys (ms) */
+    cleanupInterval?: number;
+    /** Maximum keys to store in memory */
+    maxKeys?: number;
+    /** External store (Redis, DB) - optional */
+    externalStore?: ExternalIdempotencyStore;
+}
+/**
+ * Webhook Manager Configuration
+ */
+export interface WebhookManagerConfig {
+    /** Idempotency store configuration */
+    idempotency?: IdempotencyStoreConfig;
+    /** Global timeout for webhook processing (ms) */
+    timeout?: number;
+    /** Enable/disable webhook processing globally */
+    enabled?: boolean;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Base webhook adapter configuration
+ */
+export interface BaseWebhookAdapterConfig extends WebhookAdapterConfig {
+    /** Secret key for signature verification */
+    secret: string;
+    /** Signature verification method */
+    signatureMethod?: SIGNATURE_METHOD;
+    /** Header name containing the signature */
+    signatureHeader?: string;
+    /** Logger instance */
+    logger?: unknown;
+}
+/**
+ * Idempotency record (internal use)
+ * Used by IdempotencyStore to track processed webhook events
+ */
+export interface IdempotencyRecord {
+    /** Unique idempotency key */
+    key: string;
+    /** When this key was first processed */
+    processedAt: Date;
+    /** When this key expires and can be removed */
+    expiresAt: Date;
+    /** Optional metadata associated with this key */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Template cache entry (internal use)
+ * Used by TemplateEngine for caching parsed templates
+ */
+export interface TemplateCacheEntry {
+    /** Template source code */
+    source: string;
+    /** Parsed template metadata/frontmatter */
+    metadata: TemplateFrontmatter;
+}
+/**
+ * Infobip Email Delivery Webhook configuration
+ */
+export interface InfobipDeliveryWebhookConfig {
+    /**
+     * Secret key for signature verification (optional)
+     * Infobip doesn't provide signature verification by default
+     * You can implement IP allowlisting or custom verification
+     */
+    secret?: string;
+    /** Enable/disable this webhook handler */
+    enabled?: boolean;
+    /**
+     * Enable/disable strict validation
+     * If true, will validate all fields according to schema
+     * Default: true
+     */
+    strictValidation?: boolean;
+    /**
+     * Priority for webhook processing (lower = higher priority)
+     * Default: 100
+     */
+    priority?: number;
+    /** Logger instance */
+    logger?: unknown;
+}
+/**
+ * Infobip Email Tracking Webhook configuration
+ */
+export interface InfobipTrackingWebhookConfig {
+    /**
+     * Secret key for signature verification (optional)
+     * Infobip doesn't provide signature verification by default
+     * You can implement IP allowlisting or custom verification
+     */
+    secret?: string;
+    /** Enable/disable this webhook handler */
+    enabled?: boolean;
+    /**
+     * Enable/disable strict validation
+     * If true, will validate all fields according to schema
+     * Default: true
+     */
+    strictValidation?: boolean;
+    /**
+     * Priority for webhook processing (lower = higher priority)
+     * Default: 101 (slightly lower priority than delivery webhooks)
+     */
+    priority?: number;
+    /** Logger instance */
+    logger?: unknown;
+}
+/**
+ * SendGrid Webhook configuration
+ */
+export interface SendGridWebhookConfig {
+    /**
+     * Verification method
+     * - 'ecdsa': Use ECDSA with public key (RECOMMENDED, more secure)
+     * - 'hmac': Use HMAC with secret (legacy/fallback method)
+     *
+     * Default: 'ecdsa' if publicKey is provided, otherwise 'hmac'
+     */
+    verificationMethod?: 'ecdsa' | 'hmac';
+    /**
+     * Public key for ECDSA verification (base64 PEM format)
+     * Get from: GET https://api.sendgrid.com/v3/user/webhooks/event/settings/signed
+     * Required if verificationMethod is 'ecdsa'
+     */
+    publicKey?: string;
+    /**
+     * Secret key for HMAC verification
+     * Required if verificationMethod is 'hmac' or as fallback
+     */
+    secret: string;
+    /**
+     * Maximum webhook age in seconds (default: 600 = 10 minutes)
+     * Rejects webhooks older than this to prevent replay attacks
+     */
+    maxWebhookAge?: number;
+    /** Enable/disable this webhook handler */
+    enabled?: boolean;
+    /**
+     * Priority for webhook processing (lower = higher priority)
+     * Default: 100
+     */
+    priority?: number;
+    /** Logger instance */
+    logger?: unknown;
+}