@bernierllc/email-manager 0.4.0 → 0.4.2

package/dist/capabilities/matrix.js

@@ -0,0 +1,247 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+// ---------------------------------------------------------------------------
+// Feature Definitions -- SINGLE SOURCE OF TRUTH
+// ---------------------------------------------------------------------------
+// Every feature the platform recognises is declared here. Types, arrays, and
+// the capability matrix itself are all derived from this object so that adding
+// a feature in one place is enough.
+// ---------------------------------------------------------------------------
+export const FEATURE_DEFINITIONS = {
+    sendEmail: 'Send a single email through a provider',
+    batchSend: 'Send multiple emails in a single operation',
+    providerTemplates: 'Use templates stored on the provider (server-side)',
+    localTemplates: 'Render templates locally before sending',
+    calendarInvites: 'Attach iCalendar (.ics) invites to outgoing emails',
+    calendarEventMgmt: 'Create, update, and cancel calendar events programmatically',
+    webhooksReceive: 'Receive webhook callbacks from the provider for email events',
+    webhookNormalization: 'Normalize provider-specific webhook payloads into a common format',
+    deliveryTracking: 'Track delivery status of sent emails (delivered, bounced, etc.)',
+    inboundEmailParsing: 'Parse inbound emails forwarded by the provider',
+    /**
+     * subscriptionMgmt -- Manage subscriber lists, preference centres, and
+     * opt-in / opt-out lifecycle. This is distinct from suppressionLists which
+     * deals with bounce/complaint suppression at the provider level.
+     */
+    subscriptionMgmt: 'Manage subscriber lists, preferences, and opt-in/opt-out lifecycle',
+    /**
+     * suppressionLists -- Provider-level bounce and complaint suppression.
+     * Automatically maintained by the provider to prevent sending to addresses
+     * that have bounced or filed complaints. Distinct from subscriptionMgmt
+     * which handles user-facing subscription preferences.
+     */
+    suppressionLists: 'Provider-level bounce and complaint suppression lists',
+    unsubscribeUrlGeneration: 'Generate one-click unsubscribe URLs for email headers',
+    scheduledSend: 'Schedule emails for future delivery',
+    openClickTracking: 'Track email opens and link clicks',
+    emailContentParsing: 'Parse and transform email content (HTML/text)',
+    emailHeaderMgmt: 'Set and manage custom email headers',
+    attachments: 'Attach files to outgoing emails',
+    advancedAttachmentProcessing: 'Process, validate, and transform attachments (resize, compress, etc.)',
+    dkimSpf: 'Programmatic DKIM/SPF authentication configuration',
+    linkBranding: 'Custom branded tracking domains for links',
+    retryResilience: 'Automatic retry with backoff on transient failures',
+    multiProviderFailover: 'Automatic failover to alternate providers on failure',
+};
+/**
+ * Ordered array of every feature name (derived from FEATURE_DEFINITIONS keys).
+ */
+export const FEATURE_NAMES = Object.keys(FEATURE_DEFINITIONS);
+export const PROVIDER_NAMES = [
+    'sendgrid',
+    'mailgun',
+    'postmark',
+    'ses',
+    'smtp',
+];
+// ---------------------------------------------------------------------------
+// Helper builders -- keep individual entries concise
+// ---------------------------------------------------------------------------
+function provider(description, opts) {
+    return {
+        source: 'provider',
+        description,
+        ...(opts?.limitations ? { limitations: opts.limitations } : {}),
+        degradation: null,
+        overridable: opts?.overridable ?? false,
+    };
+}
+function platform(description, degradation, opts) {
+    return {
+        source: 'platform',
+        description,
+        degradation: degradation ?? null,
+        overridable: opts?.overridable ?? true,
+    };
+}
+function enhanced(description, opts) {
+    return {
+        source: 'enhanced',
+        description,
+        degradation: null,
+        overridable: opts?.overridable ?? true,
+    };
+}
+function unsupported(description) {
+    return {
+        source: 'unsupported',
+        description,
+        degradation: null,
+        overridable: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// CAPABILITY MATRIX
+// ---------------------------------------------------------------------------
+const sendgridCapabilities = {
+    sendEmail: provider('Send email via SendGrid v3 API'),
+    batchSend: provider('Batch send via SendGrid personalizations', { overridable: true }),
+    providerTemplates: provider('SendGrid dynamic templates (Handlebars)', { overridable: true }),
+    localTemplates: platform('Render templates locally before sending via SendGrid'),
+    calendarInvites: platform('Attach iCalendar invites to SendGrid emails'),
+    calendarEventMgmt: platform('Manage calendar events locally, send via SendGrid'),
+    webhooksReceive: provider('SendGrid Event Webhook for delivery events', { overridable: true }),
+    webhookNormalization: enhanced('Normalize SendGrid webhook payloads to common format'),
+    deliveryTracking: provider('Track delivery via SendGrid Event Webhook', { overridable: true }),
+    inboundEmailParsing: enhanced('Parse inbound emails from SendGrid Inbound Parse'),
+    subscriptionMgmt: enhanced('Manage subscriber lists and preferences with SendGrid contacts'),
+    suppressionLists: provider('SendGrid global and group suppression management', { overridable: true }),
+    unsubscribeUrlGeneration: platform('Generate unsubscribe URLs for SendGrid emails'),
+    scheduledSend: provider('SendGrid scheduled send via send_at parameter', { limitations: '72hr max scheduling window', overridable: true }),
+    openClickTracking: provider('SendGrid open and click tracking via tracking settings', { overridable: true }),
+    emailContentParsing: platform('Parse and transform email content for SendGrid'),
+    emailHeaderMgmt: platform('Set custom headers on SendGrid emails'),
+    attachments: provider('File attachments via SendGrid API'),
+    advancedAttachmentProcessing: platform('Process and validate attachments before SendGrid send'),
+    dkimSpf: provider('SendGrid domain authentication (DKIM/SPF)', { overridable: true }),
+    linkBranding: provider('SendGrid branded link tracking domains', { overridable: true }),
+    retryResilience: platform('Automatic retry with backoff for SendGrid API calls'),
+    multiProviderFailover: platform('Failover from SendGrid to alternate providers'),
+};
+const mailgunCapabilities = {
+    sendEmail: provider('Send email via Mailgun API'),
+    batchSend: provider('Batch send via Mailgun recipient variables', { overridable: true }),
+    providerTemplates: provider('Mailgun stored templates', { overridable: true }),
+    localTemplates: platform('Render templates locally before sending via Mailgun'),
+    calendarInvites: platform('Attach iCalendar invites to Mailgun emails'),
+    calendarEventMgmt: platform('Manage calendar events locally, send via Mailgun'),
+    webhooksReceive: provider('Mailgun webhooks for delivery events', { overridable: true }),
+    webhookNormalization: enhanced('Normalize Mailgun webhook payloads to common format'),
+    deliveryTracking: provider('Track delivery via Mailgun webhooks', { overridable: true }),
+    inboundEmailParsing: enhanced('Parse inbound emails from Mailgun Routes'),
+    subscriptionMgmt: enhanced('Manage subscriber lists and preferences with Mailgun mailing lists'),
+    suppressionLists: provider('Mailgun bounce, complaint, and unsubscribe suppression', { overridable: true }),
+    unsubscribeUrlGeneration: platform('Generate unsubscribe URLs for Mailgun emails'),
+    scheduledSend: provider('Mailgun scheduled delivery via o:deliverytime', { limitations: '3-day max scheduling window', overridable: true }),
+    openClickTracking: provider('Mailgun open and click tracking', { overridable: true }),
+    emailContentParsing: platform('Parse and transform email content for Mailgun'),
+    emailHeaderMgmt: platform('Set custom headers on Mailgun emails'),
+    attachments: provider('File attachments via Mailgun API'),
+    advancedAttachmentProcessing: platform('Process and validate attachments before Mailgun send'),
+    dkimSpf: provider('Mailgun domain verification (DKIM/SPF)', { overridable: true }),
+    linkBranding: provider('Mailgun custom tracking domains', { overridable: true }),
+    retryResilience: platform('Automatic retry with backoff for Mailgun API calls'),
+    multiProviderFailover: platform('Failover from Mailgun to alternate providers'),
+};
+const postmarkCapabilities = {
+    sendEmail: provider('Send email via Postmark API'),
+    batchSend: provider('Batch send via Postmark batch API endpoint', { overridable: true }),
+    providerTemplates: provider('Postmark server-side templates', { overridable: true }),
+    localTemplates: platform('Render templates locally before sending via Postmark'),
+    calendarInvites: platform('Attach iCalendar invites to Postmark emails'),
+    calendarEventMgmt: platform('Manage calendar events locally, send via Postmark'),
+    webhooksReceive: provider('Postmark webhooks for delivery, bounce, and spam events', { overridable: true }),
+    webhookNormalization: enhanced('Normalize Postmark webhook payloads to common format'),
+    deliveryTracking: provider('Track delivery via Postmark webhooks and message streams', { overridable: true }),
+    inboundEmailParsing: enhanced('Parse inbound emails from Postmark Inbound'),
+    subscriptionMgmt: platform('Platform-managed subscription preferences (Postmark lacks native list management)', { strategy: 'platform-managed', description: 'Subscription management handled entirely by platform since Postmark has no native list management', docUrl: '/degradation/subscription-mgmt' }),
+    suppressionLists: provider('Postmark suppression stream management', { overridable: true }),
+    unsubscribeUrlGeneration: platform('Generate unsubscribe URLs for Postmark emails'),
+    scheduledSend: platform('Platform-managed scheduled send (Postmark has no native scheduling)', { strategy: 'platform-scheduled', description: 'Emails are queued locally and sent at the scheduled time', docUrl: '/degradation/scheduled-send' }),
+    openClickTracking: provider('Postmark open tracking (click tracking not supported)', { limitations: 'Open tracking only; no click tracking', overridable: true }),
+    emailContentParsing: platform('Parse and transform email content for Postmark'),
+    emailHeaderMgmt: platform('Set custom headers on Postmark emails'),
+    attachments: provider('File attachments via Postmark API'),
+    advancedAttachmentProcessing: platform('Process and validate attachments before Postmark send'),
+    dkimSpf: provider('Postmark domain authentication (DKIM/SPF)', { overridable: true }),
+    linkBranding: unsupported('Postmark does not support custom branded tracking domains'),
+    retryResilience: platform('Automatic retry with backoff for Postmark API calls'),
+    multiProviderFailover: platform('Failover from Postmark to alternate providers'),
+};
+const sesCapabilities = {
+    sendEmail: provider('Send email via AWS SES v2 API'),
+    batchSend: provider('Batch send via SES SendBulkEmail', { overridable: true }),
+    providerTemplates: provider('SES email templates', { overridable: true }),
+    localTemplates: platform('Render templates locally before sending via SES'),
+    calendarInvites: platform('Attach iCalendar invites to SES emails'),
+    calendarEventMgmt: platform('Manage calendar events locally, send via SES'),
+    webhooksReceive: provider('SES event notifications via SNS', { limitations: 'Requires SNS topic configuration', overridable: true }),
+    webhookNormalization: enhanced('Normalize SES/SNS notification payloads to common format'),
+    deliveryTracking: provider('Track delivery via SES SNS notifications', { limitations: 'Requires SNS topic configuration', overridable: true }),
+    inboundEmailParsing: enhanced('Parse inbound emails from SES receiving rules'),
+    subscriptionMgmt: platform('Platform-managed subscription preferences (SES has no native list management)', { strategy: 'platform-managed', description: 'Subscription management handled entirely by platform since SES has no native list management', docUrl: '/degradation/subscription-mgmt' }),
+    suppressionLists: provider('SES account-level suppression list', { overridable: true }),
+    unsubscribeUrlGeneration: platform('Generate unsubscribe URLs for SES emails'),
+    scheduledSend: platform('Platform-managed scheduled send (SES has no native scheduling)', { strategy: 'platform-scheduled', description: 'Emails are queued locally and sent at the scheduled time', docUrl: '/degradation/scheduled-send' }),
+    openClickTracking: unsupported('SES does not provide native open/click tracking'),
+    emailContentParsing: platform('Parse and transform email content for SES'),
+    emailHeaderMgmt: platform('Set custom headers on SES emails'),
+    attachments: provider('File attachments via SES raw email'),
+    advancedAttachmentProcessing: platform('Process and validate attachments before SES send'),
+    dkimSpf: provider('SES DKIM signing and domain verification', { overridable: true }),
+    linkBranding: unsupported('SES does not support custom branded tracking domains'),
+    retryResilience: platform('Automatic retry with backoff for SES API calls'),
+    multiProviderFailover: platform('Failover from SES to alternate providers'),
+};
+const smtpCapabilities = {
+    sendEmail: provider('Send email via SMTP transport'),
+    batchSend: platform('Sequential batch sending over SMTP (no native batch support)', { strategy: 'sequential-batch', description: 'Emails are sent sequentially over the SMTP connection', docUrl: '/degradation/batch-send' }),
+    providerTemplates: unsupported('SMTP does not support server-side templates'),
+    localTemplates: platform('Render templates locally before sending via SMTP'),
+    calendarInvites: platform('Attach iCalendar invites to SMTP emails'),
+    calendarEventMgmt: platform('Manage calendar events locally, send via SMTP'),
+    webhooksReceive: unsupported('SMTP does not provide webhook callbacks'),
+    webhookNormalization: unsupported('SMTP does not provide webhooks to normalize'),
+    deliveryTracking: unsupported('SMTP does not provide delivery tracking callbacks'),
+    inboundEmailParsing: unsupported('SMTP does not provide inbound email parsing'),
+    subscriptionMgmt: platform('Platform-managed subscription preferences (SMTP has no native list management)', { strategy: 'platform-managed', description: 'Subscription management handled entirely by platform since SMTP has no native capabilities', docUrl: '/degradation/subscription-mgmt' }),
+    suppressionLists: platform('Platform-managed suppression lists (SMTP has no native suppression)', { strategy: 'platform-managed', description: 'Suppression list maintained locally since SMTP has no provider-level suppression', docUrl: '/degradation/suppression-lists' }),
+    unsubscribeUrlGeneration: platform('Generate unsubscribe URLs for SMTP emails'),
+    scheduledSend: platform('Platform-managed scheduled send (SMTP has no native scheduling)', { strategy: 'platform-scheduled', description: 'Emails are queued locally and sent at the scheduled time', docUrl: '/degradation/scheduled-send' }),
+    openClickTracking: unsupported('SMTP does not support open/click tracking'),
+    emailContentParsing: platform('Parse and transform email content for SMTP'),
+    emailHeaderMgmt: platform('Set custom headers on SMTP emails'),
+    attachments: provider('File attachments via SMTP MIME'),
+    advancedAttachmentProcessing: platform('Process and validate attachments before SMTP send'),
+    dkimSpf: unsupported('SMTP DKIM/SPF requires manual server configuration, not programmatic'),
+    linkBranding: unsupported('SMTP does not support custom branded tracking domains'),
+    retryResilience: platform('Automatic retry with backoff for SMTP connections'),
+    multiProviderFailover: platform('Failover from SMTP to alternate providers'),
+};
+// ---------------------------------------------------------------------------
+// Exported Matrix
+// ---------------------------------------------------------------------------
+export const CAPABILITY_MATRIX = {
+    version: '1.0.0',
+    lastUpdated: '2026-02-22',
+    providers: {
+        sendgrid: sendgridCapabilities,
+        mailgun: mailgunCapabilities,
+        postmark: postmarkCapabilities,
+        ses: sesCapabilities,
+        smtp: smtpCapabilities,
+    },
+};
+/**
+ * Returns a deep clone of the capability matrix to prevent mutation of the
+ * canonical data.
+ */
+export function getCapabilityMatrix() {
+    return structuredClone(CAPABILITY_MATRIX);
+}
+//# sourceMappingURL=matrix.js.map

package/dist/capabilities/matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.js","sourceRoot":"","sources":["../../src/capabilities/matrix.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/redis-resolver.d.ts

@@ -0,0 +1,95 @@
+import type { CapabilityEntry } from '@bernierllc/email-sender';
+import type { CapabilityResolverAdmin } from './resolver.js';
+/**
+ * Minimal Redis client interface. Compatible with ioredis instances.
+ * Users provide their own Redis client so we don't bundle ioredis.
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    pipeline(): RedisPipelineLike;
+}
+export interface RedisPipelineLike {
+    get(key: string): RedisPipelineLike;
+    set(key: string, value: string, ...args: unknown[]): RedisPipelineLike;
+    exec(): Promise<Array<[Error | null, unknown]>>;
+}
+export interface RedisCapabilityResolverOptions {
+    /** User-provided Redis client (ioredis instance or compatible). */
+    redis: RedisLike;
+    /** Key prefix. Default: 'ecap'. */
+    keyPrefix?: string;
+    /** Agnostic scoping namespace (e.g., org_id). */
+    namespace?: string;
+    /** Cache TTL in seconds. 0 = no expiry. Default: 0. */
+    ttl?: number;
+    /** Optional logger for diagnostics. */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Redis-backed {@link CapabilityResolverAdmin}.
+ *
+ * Stores per-provider, per-feature capability overrides in Redis. When a key
+ * is not present in Redis the resolver falls back to the static
+ * {@link CAPABILITY_MATRIX}.
+ *
+ * Entries read from Redis are validated against `capabilityEntrySchema`; if
+ * validation fails the static matrix entry is returned instead.
+ */
+export declare class RedisCapabilityResolver implements CapabilityResolverAdmin {
+    private readonly redis;
+    private readonly prefix;
+    private readonly namespace;
+    private readonly ttl;
+    private readonly logger;
+    constructor(options: RedisCapabilityResolverOptions);
+    /**
+     * Builds the Redis key for a specific provider + feature pair.
+     *
+     * Without namespace: `ecap:sendgrid:batchSend`
+     * With namespace `org_123`: `ecap:org_123:sendgrid:batchSend`
+     */
+    buildKey(provider: string, feature: string): string;
+    /**
+     * Builds the key pattern for listing all features of a provider.
+     */
+    private buildProviderPattern;
+    /**
+     * Extracts the feature name from a full Redis key.
+     */
+    private extractFeature;
+    getCapability(provider: string, feature: string): Promise<CapabilityEntry>;
+    getProviderCapabilities(provider: string): Promise<Record<string, CapabilityEntry>>;
+    setCapability(provider: string, feature: string, entry: CapabilityEntry): Promise<void>;
+    setProviderCapabilities(provider: string, capabilities: Record<string, CapabilityEntry>): Promise<void>;
+    /**
+     * Parses a JSON string from Redis and validates it against the schema.
+     * Falls back to the static matrix entry on any error.
+     */
+    private parseAndValidate;
+    /**
+     * Parses and validates silently, returning null on failure (used in batch operations).
+     */
+    private parseAndValidateQuiet;
+    /**
+     * Gets a capability entry from the static CAPABILITY_MATRIX.
+     * Throws CapabilityResolverError if provider or feature is unknown.
+     */
+    private getMatrixEntry;
+    /**
+     * Gets all capabilities for a provider from the static matrix.
+     * Returns an empty object for unknown providers (Redis may have entries for providers
+     * not in the static matrix).
+     */
+    private getMatrixProviderCaps;
+    /**
+     * Validates a capability entry against the Zod schema, throwing a
+     * {@link CapabilityResolverError} with code `INVALID_ENTRY` on failure.
+     */
+    private validateEntry;
+}
+//# sourceMappingURL=redis-resolver.d.ts.map

package/dist/capabilities/redis-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-resolver.d.ts","sourceRoot":"","sources":["../../src/capabilities/redis-resolver.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAIhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAM7D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5E,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,QAAQ,IAAI,iBAAiB,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAC;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAAC;IACvE,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,8BAA8B;IAC7C,mEAAmE;IACnE,KAAK,EAAE,SAAS,CAAC;IACjB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CACjD;AAMD;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,uBAAuB;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;gBAEhE,OAAO,EAAE,8BAA8B;IAYnD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAOnD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAShB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmB1E,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAkDnF,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAavF,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAoBtB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;OAGG;IACH,OAAO,CAAC,aAAa;CAUtB"}

package/dist/capabilities/redis-resolver.js

@@ -0,0 +1,227 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+import { capabilityEntrySchema } from '@bernierllc/email-sender';
+import { CAPABILITY_MATRIX } from './matrix.js';
+import { CapabilityResolverError } from './resolver.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Redis-backed {@link CapabilityResolverAdmin}.
+ *
+ * Stores per-provider, per-feature capability overrides in Redis. When a key
+ * is not present in Redis the resolver falls back to the static
+ * {@link CAPABILITY_MATRIX}.
+ *
+ * Entries read from Redis are validated against `capabilityEntrySchema`; if
+ * validation fails the static matrix entry is returned instead.
+ */
+export class RedisCapabilityResolver {
+    constructor(options) {
+        this.redis = options.redis;
+        this.prefix = options.keyPrefix ?? 'ecap';
+        this.namespace = options.namespace;
+        this.ttl = options.ttl ?? 0;
+        this.logger = options.logger;
+    }
+    // -----------------------------------------------------------------------
+    // Key helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Builds the Redis key for a specific provider + feature pair.
+     *
+     * Without namespace: `ecap:sendgrid:batchSend`
+     * With namespace `org_123`: `ecap:org_123:sendgrid:batchSend`
+     */
+    buildKey(provider, feature) {
+        if (this.namespace) {
+            return `${this.prefix}:${this.namespace}:${provider}:${feature}`;
+        }
+        return `${this.prefix}:${provider}:${feature}`;
+    }
+    /**
+     * Builds the key pattern for listing all features of a provider.
+     */
+    buildProviderPattern(provider) {
+        if (this.namespace) {
+            return `${this.prefix}:${this.namespace}:${provider}:*`;
+        }
+        return `${this.prefix}:${provider}:*`;
+    }
+    /**
+     * Extracts the feature name from a full Redis key.
+     */
+    extractFeature(key) {
+        const parts = key.split(':');
+        return parts[parts.length - 1];
+    }
+    // -----------------------------------------------------------------------
+    // Read operations
+    // -----------------------------------------------------------------------
+    async getCapability(provider, feature) {
+        const key = this.buildKey(provider, feature);
+        let raw;
+        try {
+            raw = await this.redis.get(key);
+        }
+        catch {
+            // Redis unavailable -- fall back to static matrix
+            return this.getMatrixEntry(provider, feature);
+        }
+        if (raw === null) {
+            // No override in Redis -- use static matrix
+            return this.getMatrixEntry(provider, feature);
+        }
+        return this.parseAndValidate(raw, provider, feature);
+    }
+    async getProviderCapabilities(provider) {
+        // Start with static matrix entries as base
+        const matrixCaps = this.getMatrixProviderCaps(provider);
+        // Overlay Redis overrides
+        let keys;
+        try {
+            keys = await this.redis.keys(this.buildProviderPattern(provider));
+        }
+        catch {
+            // Redis unavailable -- return matrix entries only
+            return { ...matrixCaps };
+        }
+        if (keys.length === 0) {
+            return { ...matrixCaps };
+        }
+        // Use pipeline for efficient batch fetch
+        const pipeline = this.redis.pipeline();
+        for (const key of keys) {
+            pipeline.get(key);
+        }
+        let results;
+        try {
+            results = await pipeline.exec();
+        }
+        catch {
+            return { ...matrixCaps };
+        }
+        const result = { ...matrixCaps };
+        for (let i = 0; i < keys.length; i++) {
+            const [err, raw] = results[i];
+            if (err || typeof raw !== 'string')
+                continue;
+            const feature = this.extractFeature(keys[i]);
+            const parsed = this.parseAndValidateQuiet(raw);
+            if (parsed) {
+                result[feature] = parsed;
+            }
+        }
+        return result;
+    }
+    // -----------------------------------------------------------------------
+    // Write operations
+    // -----------------------------------------------------------------------
+    async setCapability(provider, feature, entry) {
+        this.validateEntry(entry);
+        const key = this.buildKey(provider, feature);
+        const json = JSON.stringify(entry);
+        if (this.ttl > 0) {
+            await this.redis.set(key, json, 'EX', this.ttl);
+        }
+        else {
+            await this.redis.set(key, json);
+        }
+    }
+    async setProviderCapabilities(provider, capabilities) {
+        // Validate all entries before committing any
+        for (const [feature, entry] of Object.entries(capabilities)) {
+            this.validateEntry(entry, feature);
+        }
+        const pipeline = this.redis.pipeline();
+        for (const [feature, entry] of Object.entries(capabilities)) {
+            const key = this.buildKey(provider, feature);
+            const json = JSON.stringify(entry);
+            if (this.ttl > 0) {
+                pipeline.set(key, json, 'EX', this.ttl);
+            }
+            else {
+                pipeline.set(key, json);
+            }
+        }
+        await pipeline.exec();
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Parses a JSON string from Redis and validates it against the schema.
+     * Falls back to the static matrix entry on any error.
+     */
+    parseAndValidate(raw, provider, feature) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.logger?.warn(`RedisCapabilityResolver: invalid JSON for key ${this.buildKey(provider, feature)}, falling back to matrix`);
+            return this.getMatrixEntry(provider, feature);
+        }
+        const result = capabilityEntrySchema.safeParse(parsed);
+        if (!result.success) {
+            this.logger?.warn(`RedisCapabilityResolver: schema validation failed for key ${this.buildKey(provider, feature)}, falling back to matrix`);
+            return this.getMatrixEntry(provider, feature);
+        }
+        return result.data;
+    }
+    /**
+     * Parses and validates silently, returning null on failure (used in batch operations).
+     */
+    parseAndValidateQuiet(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const result = capabilityEntrySchema.safeParse(parsed);
+        return result.success ? result.data : null;
+    }
+    /**
+     * Gets a capability entry from the static CAPABILITY_MATRIX.
+     * Throws CapabilityResolverError if provider or feature is unknown.
+     */
+    getMatrixEntry(provider, feature) {
+        const providerCaps = CAPABILITY_MATRIX.providers[provider];
+        if (!providerCaps) {
+            throw new CapabilityResolverError(`Unknown provider "${provider}"`, 'UNKNOWN_PROVIDER');
+        }
+        const entry = providerCaps[feature];
+        if (!entry) {
+            throw new CapabilityResolverError(`Unknown feature "${feature}" for provider "${provider}"`, 'UNKNOWN_FEATURE');
+        }
+        return entry;
+    }
+    /**
+     * Gets all capabilities for a provider from the static matrix.
+     * Returns an empty object for unknown providers (Redis may have entries for providers
+     * not in the static matrix).
+     */
+    getMatrixProviderCaps(provider) {
+        const providerCaps = CAPABILITY_MATRIX.providers[provider];
+        return providerCaps ? { ...providerCaps } : {};
+    }
+    /**
+     * Validates a capability entry against the Zod schema, throwing a
+     * {@link CapabilityResolverError} with code `INVALID_ENTRY` on failure.
+     */
+    validateEntry(entry, label) {
+        const result = capabilityEntrySchema.safeParse(entry);
+        if (!result.success) {
+            const prefix = label ? `Invalid entry for "${label}": ` : 'Invalid capability entry: ';
+            throw new CapabilityResolverError(prefix + result.error.issues.map((i) => i.message).join('; '), 'INVALID_ENTRY');
+        }
+    }
+}
+//# sourceMappingURL=redis-resolver.js.map

package/dist/capabilities/redis-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-resolver.js","sourceRoot":"","sources":["../../src/capabilities/redis-resolver.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/resolver-factory.d.ts

@@ -0,0 +1,30 @@
+import type { CapabilityResolver } from './resolver.js';
+export interface ResolverFactoryOptions {
+    /** User-provided resolver instance. When set, the factory returns it directly. */
+    capabilityResolver?: CapabilityResolver;
+    /** Redis key namespace (forwarded to RedisCapabilityResolver). */
+    namespace?: string;
+    /** Redis TTL in seconds (forwarded to RedisCapabilityResolver). */
+    ttl?: number;
+}
+export interface ResolverFactoryLogger {
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+}
+/**
+ * Creates the best-available {@link CapabilityResolver} based on the runtime
+ * environment and the supplied options.
+ *
+ * Resolution order:
+ * 1. If `options.capabilityResolver` is provided, return it directly.
+ * 2. If the `EMAIL_MANAGER_REDIS_URL` environment variable is set **and**
+ *    `ioredis` is installed, return a {@link SafeCapabilityResolver} wrapping
+ *    a {@link RedisCapabilityResolver} with an {@link InMemoryCapabilityResolver}
+ *    fallback.
+ * 3. Otherwise return an {@link InMemoryCapabilityResolver}.
+ *
+ * `ioredis` is loaded via dynamic `import()` so it remains an optional peer
+ * dependency -- projects that do not use Redis never need to install it.
+ */
+export declare function createCapabilityResolver(options?: ResolverFactoryOptions, logger?: ResolverFactoryLogger): Promise<CapabilityResolver>;
+//# sourceMappingURL=resolver-factory.d.ts.map

package/dist/capabilities/resolver-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-factory.d.ts","sourceRoot":"","sources":["../../src/capabilities/resolver-factory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAOxD,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,CAAC,EAAE,sBAAsB,EAChC,MAAM,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA+C7B"}