@bernierllc/email-manager 0.4.0 → 0.4.2

package/dist/capabilities/degradation-logger.d.ts

@@ -0,0 +1,59 @@
+export type LogLevel = 'silent' | 'info' | 'warn' | 'error';
+export interface DegradationLoggerConfig {
+    logger: {
+        warn: Function;
+        info: Function;
+        error: Function;
+    };
+    logLevel: LogLevel;
+    includeDocLinks: boolean;
+    docsBaseUrl?: string;
+}
+export interface DegradationEvent {
+    provider: string;
+    feature: string;
+    strategy: string;
+    description: string;
+    docUrl: string;
+}
+export interface UnsupportedEvent {
+    provider: string;
+    feature: string;
+    message: string;
+}
+/**
+ * DegradationLogger provides structured logging for feature degradation
+ * and unsupported feature events across email providers. It respects
+ * configurable log levels and optionally includes documentation links.
+ */
+export declare class DegradationLogger {
+    private readonly config;
+    constructor(config: DegradationLoggerConfig);
+    /**
+     * Log a degradation event when a provider does not natively support a feature
+     * and a fallback strategy is being used.
+     */
+    logDegradation(event: DegradationEvent): void;
+    /**
+     * Log an unsupported feature event. These are always logged at error level
+     * (unless log level is silent).
+     */
+    logUnsupported(event: UnsupportedEvent): void;
+    /**
+     * Check whether a message at the given severity should be logged
+     * based on the configured log level.
+     *
+     * The configured logLevel sets the minimum severity that gets logged:
+     * - 'silent': nothing is logged
+     * - 'error': only error-level messages
+     * - 'warn': error + warn messages
+     * - 'info': everything (error + warn + info)
+     */
+    private shouldLog;
+    /**
+     * Resolve a doc URL, prepending the docsBaseUrl if the path is relative
+     * and includeDocLinks is enabled.
+     */
+    private resolveDocUrl;
+}
+//# sourceMappingURL=degradation-logger.d.ts.map

package/dist/capabilities/degradation-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation-logger.d.ts","sourceRoot":"","sources":["../../src/capabilities/degradation-logger.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5D,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAaD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,EAAE,uBAAuB;IAI3C;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAwB7C;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAgB7C;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS;IAUjB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAqBtB"}

package/dist/capabilities/degradation-logger.js

@@ -0,0 +1,106 @@
+/*
+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.
+*/
+/**
+ * Severity ranking for log levels, used for filtering.
+ * Higher numbers mean more severe / less filtered.
+ */
+const LOG_LEVEL_SEVERITY = {
+    silent: -1,
+    info: 0,
+    warn: 1,
+    error: 2,
+};
+/**
+ * DegradationLogger provides structured logging for feature degradation
+ * and unsupported feature events across email providers. It respects
+ * configurable log levels and optionally includes documentation links.
+ */
+export class DegradationLogger {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Log a degradation event when a provider does not natively support a feature
+     * and a fallback strategy is being used.
+     */
+    logDegradation(event) {
+        if (!this.shouldLog('warn')) {
+            return;
+        }
+        const fullDocUrl = this.resolveDocUrl(event.docUrl);
+        const message = `${event.provider.toUpperCase()} does not support native ${event.feature}. ` +
+            `Using ${event.strategy}: ${event.description}. ` +
+            `Docs: ${fullDocUrl}. ` +
+            `Override: set featureOverrides.${event.feature}.behavior = 'error' to disable degradation.`;
+        const metadata = {
+            provider: event.provider,
+            feature: event.feature,
+            strategy: event.strategy,
+            description: event.description,
+            docUrl: fullDocUrl,
+        };
+        this.config.logger.warn(message, metadata);
+    }
+    /**
+     * Log an unsupported feature event. These are always logged at error level
+     * (unless log level is silent).
+     */
+    logUnsupported(event) {
+        if (!this.shouldLog('error')) {
+            return;
+        }
+        const message = `${event.provider.toUpperCase()} does not support ${event.feature}: ${event.message}`;
+        const metadata = {
+            provider: event.provider,
+            feature: event.feature,
+        };
+        this.config.logger.error(message, metadata);
+    }
+    /**
+     * Check whether a message at the given severity should be logged
+     * based on the configured log level.
+     *
+     * The configured logLevel sets the minimum severity that gets logged:
+     * - 'silent': nothing is logged
+     * - 'error': only error-level messages
+     * - 'warn': error + warn messages
+     * - 'info': everything (error + warn + info)
+     */
+    shouldLog(messageSeverity) {
+        const configuredLevel = this.config.logLevel;
+        if (configuredLevel === 'silent') {
+            return false;
+        }
+        // The configured level is the minimum severity we show.
+        // A message is shown if its severity >= the configured threshold.
+        return LOG_LEVEL_SEVERITY[messageSeverity] >= LOG_LEVEL_SEVERITY[configuredLevel];
+    }
+    /**
+     * Resolve a doc URL, prepending the docsBaseUrl if the path is relative
+     * and includeDocLinks is enabled.
+     */
+    resolveDocUrl(docUrl) {
+        if (!this.config.includeDocLinks) {
+            return docUrl;
+        }
+        // If it's already an absolute URL, return as-is
+        if (docUrl.startsWith('http://') || docUrl.startsWith('https://')) {
+            return docUrl;
+        }
+        // Prepend docsBaseUrl for relative paths
+        if (this.config.docsBaseUrl) {
+            const base = this.config.docsBaseUrl.endsWith('/')
+                ? this.config.docsBaseUrl.slice(0, -1)
+                : this.config.docsBaseUrl;
+            const path = docUrl.startsWith('/') ? docUrl : `/${docUrl}`;
+            return `${base}${path}`;
+        }
+        return docUrl;
+    }
+}
+//# sourceMappingURL=degradation-logger.js.map

package/dist/capabilities/degradation-logger.js.map

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

package/dist/capabilities/feature-router.d.ts

@@ -0,0 +1,55 @@
+import type { CapabilityResolver } from './resolver.js';
+export interface ProviderInfo {
+    id: string;
+    name: string;
+    type: 'sendgrid' | 'mailgun' | 'postmark' | 'ses' | 'smtp';
+    isActive: boolean;
+    priority: number;
+}
+export interface RoutingResult {
+    provider: ProviderInfo;
+    source: 'provider' | 'platform' | 'enhanced' | 'unsupported';
+    degraded: boolean;
+    degradation: {
+        strategy: string;
+        description: string;
+        docUrl: string;
+    } | null;
+    attemptedProviders: string[];
+}
+export interface FeatureOverride {
+    behavior: 'native-first' | 'platform-always' | 'error';
+}
+export interface FeatureRouterConfig {
+    resolver: CapabilityResolver;
+    fallbackResolver?: CapabilityResolver;
+    featureOverrides?: Record<string, FeatureOverride>;
+}
+/**
+ * Smart routing engine that decides which provider handles a feature request.
+ *
+ * The router inspects the capability matrix (via a {@link CapabilityResolver})
+ * to find the best active provider for a given feature, respecting priority
+ * ordering and feature overrides.
+ */
+export declare class FeatureRouter {
+    private readonly resolver;
+    private readonly fallbackResolver;
+    private readonly featureOverrides;
+    constructor(config: FeatureRouterConfig);
+    /**
+     * Find the best provider for a given feature.
+     *
+     * @throws {FeatureUnsupportedError} when no provider can handle the feature
+     */
+    findProviderForFeature(feature: string, providers: ProviderInfo[]): Promise<RoutingResult>;
+    private handlePlatformAlways;
+    private handleErrorOverride;
+    private handleNativeFirst;
+    /**
+     * Resolve a capability entry, falling back to the fallback resolver on error.
+     * Returns `undefined` when the capability cannot be resolved at all.
+     */
+    private resolveCapability;
+}
+//# sourceMappingURL=feature-router.d.ts.map

package/dist/capabilities/feature-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-router.d.ts","sourceRoot":"","sources":["../../src/capabilities/feature-router.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAMxD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;IAC7D,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,cAAc,GAAG,iBAAiB,GAAG,OAAO,CAAC;CACxD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACpD;AAMD;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;IAClE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;gBAEvD,MAAM,EAAE,mBAAmB;IAMvC;;;;OAIG;IACG,sBAAsB,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,YAAY,EAAE,GACxB,OAAO,CAAC,aAAa,CAAC;YAiCX,oBAAoB;YAgBpB,mBAAmB;YA4BnB,iBAAiB;IAuD/B;;;OAGG;YACW,iBAAiB;CAmBhC"}

package/dist/capabilities/feature-router.js

@@ -0,0 +1,143 @@
+/*
+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 { FeatureUnsupportedError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// FeatureRouter
+// ---------------------------------------------------------------------------
+/**
+ * Smart routing engine that decides which provider handles a feature request.
+ *
+ * The router inspects the capability matrix (via a {@link CapabilityResolver})
+ * to find the best active provider for a given feature, respecting priority
+ * ordering and feature overrides.
+ */
+export class FeatureRouter {
+    constructor(config) {
+        this.resolver = config.resolver;
+        this.fallbackResolver = config.fallbackResolver;
+        this.featureOverrides = config.featureOverrides ?? {};
+    }
+    /**
+     * Find the best provider for a given feature.
+     *
+     * @throws {FeatureUnsupportedError} when no provider can handle the feature
+     */
+    async findProviderForFeature(feature, providers) {
+        // 1. Filter to active providers only
+        const activeProviders = providers.filter((p) => p.isActive);
+        if (activeProviders.length === 0) {
+            throw new FeatureUnsupportedError(feature, providers.map((p) => p.id));
+        }
+        // 2. Sort by priority (lowest number = highest priority)
+        const sorted = [...activeProviders].sort((a, b) => a.priority - b.priority);
+        // 3. Check for feature override
+        const override = this.featureOverrides[feature];
+        if (override?.behavior === 'platform-always') {
+            return this.handlePlatformAlways(feature, sorted);
+        }
+        if (override?.behavior === 'error') {
+            return this.handleErrorOverride(feature, sorted, providers);
+        }
+        // 4. Default: native-first -- iterate providers in priority order
+        return this.handleNativeFirst(feature, sorted, providers);
+    }
+    // -------------------------------------------------------------------------
+    // Override handlers
+    // -------------------------------------------------------------------------
+    async handlePlatformAlways(feature, sorted) {
+        const first = sorted[0];
+        const capability = await this.resolveCapability(first.type, feature);
+        return {
+            provider: first,
+            source: 'platform',
+            degraded: true,
+            degradation: capability?.degradation ?? null,
+            attemptedProviders: [first.id],
+        };
+    }
+    async handleErrorOverride(feature, sorted, allProviders) {
+        const attemptedProviders = [];
+        for (const provider of sorted) {
+            attemptedProviders.push(provider.id);
+            const capability = await this.resolveCapability(provider.type, feature);
+            if (capability && (capability.source === 'provider' || capability.source === 'enhanced')) {
+                return {
+                    provider,
+                    source: capability.source,
+                    degraded: false,
+                    degradation: null,
+                    attemptedProviders,
+                };
+            }
+        }
+        throw new FeatureUnsupportedError(feature, allProviders.map((p) => p.id));
+    }
+    async handleNativeFirst(feature, sorted, allProviders) {
+        const attemptedProviders = [];
+        let platformFallback;
+        for (const provider of sorted) {
+            attemptedProviders.push(provider.id);
+            const capability = await this.resolveCapability(provider.type, feature);
+            if (!capability) {
+                continue;
+            }
+            // Native or enhanced -- return immediately
+            if (capability.source === 'provider' || capability.source === 'enhanced') {
+                return {
+                    provider,
+                    source: capability.source,
+                    degraded: false,
+                    degradation: null,
+                    attemptedProviders,
+                };
+            }
+            // Track first platform fallback
+            if (capability.source === 'platform' && !platformFallback) {
+                platformFallback = { provider, capability };
+            }
+        }
+        // 5. No native/enhanced found -- try platform degradation
+        if (platformFallback) {
+            return {
+                provider: platformFallback.provider,
+                source: 'platform',
+                degraded: true,
+                degradation: platformFallback.capability.degradation ?? null,
+                attemptedProviders,
+            };
+        }
+        // 6. Completely unsupported
+        throw new FeatureUnsupportedError(feature, allProviders.map((p) => p.id));
+    }
+    // -------------------------------------------------------------------------
+    // Resolver helper
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve a capability entry, falling back to the fallback resolver on error.
+     * Returns `undefined` when the capability cannot be resolved at all.
+     */
+    async resolveCapability(providerType, feature) {
+        try {
+            return await this.resolver.getCapability(providerType, feature);
+        }
+        catch (primaryError) {
+            if (this.fallbackResolver) {
+                try {
+                    return await this.fallbackResolver.getCapability(providerType, feature);
+                }
+                catch {
+                    // Both resolvers failed -- treat as unresolvable
+                    return undefined;
+                }
+            }
+            // No fallback -- propagate error
+            throw primaryError;
+        }
+    }
+}
+//# sourceMappingURL=feature-router.js.map

package/dist/capabilities/feature-router.js.map

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

package/dist/capabilities/in-memory-resolver.d.ts

@@ -0,0 +1,27 @@
+import type { CapabilityEntry } from '@bernierllc/email-sender';
+import type { CapabilityResolverAdmin } from './resolver.js';
+/**
+ * In-memory implementation of {@link CapabilityResolverAdmin}.
+ *
+ * Initialised with a deep clone of the canonical {@link CAPABILITY_MATRIX} so
+ * that mutations made through the admin interface never affect the original
+ * static data.
+ */
+export declare class InMemoryCapabilityResolver implements CapabilityResolverAdmin {
+    private readonly data;
+    constructor();
+    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>;
+    /**
+     * Resolves the capability map for a known provider or throws.
+     */
+    private resolveProvider;
+    /**
+     * Validates a capability entry against the Zod schema, throwing a
+     * {@link CapabilityResolverError} with code `INVALID_ENTRY` on failure.
+     */
+    private validateEntry;
+}
+//# sourceMappingURL=in-memory-resolver.d.ts.map

package/dist/capabilities/in-memory-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-resolver.d.ts","sourceRoot":"","sources":["../../src/capabilities/in-memory-resolver.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;GAMG;AACH,qBAAa,0BAA2B,YAAW,uBAAuB;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;;IAUtC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAY1E,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAQnF,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvF,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC;IAahB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAUtB"}

package/dist/capabilities/in-memory-resolver.js

@@ -0,0 +1,79 @@
+/*
+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';
+/**
+ * In-memory implementation of {@link CapabilityResolverAdmin}.
+ *
+ * Initialised with a deep clone of the canonical {@link CAPABILITY_MATRIX} so
+ * that mutations made through the admin interface never affect the original
+ * static data.
+ */
+export class InMemoryCapabilityResolver {
+    constructor() {
+        this.data = structuredClone(CAPABILITY_MATRIX);
+    }
+    // -----------------------------------------------------------------------
+    // Read operations
+    // -----------------------------------------------------------------------
+    async getCapability(provider, feature) {
+        const providerCaps = this.resolveProvider(provider);
+        const entry = providerCaps[feature];
+        if (!entry) {
+            throw new CapabilityResolverError(`Unknown feature "${feature}" for provider "${provider}"`, 'UNKNOWN_FEATURE');
+        }
+        return entry;
+    }
+    async getProviderCapabilities(provider) {
+        return { ...this.resolveProvider(provider) };
+    }
+    // -----------------------------------------------------------------------
+    // Write operations
+    // -----------------------------------------------------------------------
+    async setCapability(provider, feature, entry) {
+        this.validateEntry(entry);
+        // Ensure provider bucket exists (create on demand for admin use-cases)
+        if (!this.data.providers[provider]) {
+            this.data.providers[provider] = {};
+        }
+        this.data.providers[provider][feature] = entry;
+    }
+    async setProviderCapabilities(provider, capabilities) {
+        // Validate every entry before committing any of them
+        for (const [feature, entry] of Object.entries(capabilities)) {
+            this.validateEntry(entry, feature);
+        }
+        this.data.providers[provider] = { ...capabilities };
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Resolves the capability map for a known provider or throws.
+     */
+    resolveProvider(provider) {
+        const caps = this.data.providers[provider];
+        if (!caps) {
+            throw new CapabilityResolverError(`Unknown provider "${provider}"`, 'UNKNOWN_PROVIDER');
+        }
+        return caps;
+    }
+    /**
+     * 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=in-memory-resolver.js.map

package/dist/capabilities/in-memory-resolver.js.map

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

package/dist/capabilities/index.d.ts

@@ -0,0 +1,13 @@
+export { FEATURE_DEFINITIONS, FEATURE_NAMES, PROVIDER_NAMES, CAPABILITY_MATRIX, getCapabilityMatrix, } from './matrix.js';
+export type { FeatureName, ProviderName, ProviderCapabilityMap, CapabilityMatrixData, } from './matrix.js';
+export { CapabilityResolverError } from './resolver.js';
+export type { CapabilityResolver, CapabilityResolverAdmin } from './resolver.js';
+export { InMemoryCapabilityResolver } from './in-memory-resolver.js';
+export { RedisCapabilityResolver } from './redis-resolver.js';
+export type { RedisLike, RedisPipelineLike, RedisCapabilityResolverOptions, } from './redis-resolver.js';
+export { SafeCapabilityResolver } from './safe-resolver.js';
+export { createCapabilityResolver } from './resolver-factory.js';
+export type { ResolverFactoryOptions, ResolverFactoryLogger } from './resolver-factory.js';
+export { FeatureRouter } from './feature-router.js';
+export type { ProviderInfo, RoutingResult, FeatureOverride, FeatureRouterConfig, } from './feature-router.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/capabilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAGjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAGrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG3F,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/capabilities/index.js

@@ -0,0 +1,21 @@
+/*
+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.
+*/
+export { FEATURE_DEFINITIONS, FEATURE_NAMES, PROVIDER_NAMES, CAPABILITY_MATRIX, getCapabilityMatrix, } from './matrix.js';
+// Capability resolver interfaces and error class
+export { CapabilityResolverError } from './resolver.js';
+// In-memory resolver implementation
+export { InMemoryCapabilityResolver } from './in-memory-resolver.js';
+// Redis-backed resolver implementation
+export { RedisCapabilityResolver } from './redis-resolver.js';
+// Safe fallback wrapper
+export { SafeCapabilityResolver } from './safe-resolver.js';
+// Factory function for auto-detecting resolver
+export { createCapabilityResolver } from './resolver-factory.js';
+// Feature router
+export { FeatureRouter } from './feature-router.js';
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AASrB,iDAAiD;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAGxD,oCAAoC;AACpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,uCAAuC;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAO9D,wBAAwB;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,+CAA+C;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/capabilities/matrix.d.ts

@@ -0,0 +1,66 @@
+import type { CapabilityEntry } from '@bernierllc/email-sender';
+export declare const FEATURE_DEFINITIONS: {
+    readonly sendEmail: "Send a single email through a provider";
+    readonly batchSend: "Send multiple emails in a single operation";
+    readonly providerTemplates: "Use templates stored on the provider (server-side)";
+    readonly localTemplates: "Render templates locally before sending";
+    readonly calendarInvites: "Attach iCalendar (.ics) invites to outgoing emails";
+    readonly calendarEventMgmt: "Create, update, and cancel calendar events programmatically";
+    readonly webhooksReceive: "Receive webhook callbacks from the provider for email events";
+    readonly webhookNormalization: "Normalize provider-specific webhook payloads into a common format";
+    readonly deliveryTracking: "Track delivery status of sent emails (delivered, bounced, etc.)";
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly suppressionLists: "Provider-level bounce and complaint suppression lists";
+    readonly unsubscribeUrlGeneration: "Generate one-click unsubscribe URLs for email headers";
+    readonly scheduledSend: "Schedule emails for future delivery";
+    readonly openClickTracking: "Track email opens and link clicks";
+    readonly emailContentParsing: "Parse and transform email content (HTML/text)";
+    readonly emailHeaderMgmt: "Set and manage custom email headers";
+    readonly attachments: "Attach files to outgoing emails";
+    readonly advancedAttachmentProcessing: "Process, validate, and transform attachments (resize, compress, etc.)";
+    readonly dkimSpf: "Programmatic DKIM/SPF authentication configuration";
+    readonly linkBranding: "Custom branded tracking domains for links";
+    readonly retryResilience: "Automatic retry with backoff on transient failures";
+    readonly multiProviderFailover: "Automatic failover to alternate providers on failure";
+};
+/**
+ * Union of every recognised feature name, derived from FEATURE_DEFINITIONS.
+ */
+export type FeatureName = keyof typeof FEATURE_DEFINITIONS;
+/**
+ * Ordered array of every feature name (derived from FEATURE_DEFINITIONS keys).
+ */
+export declare const FEATURE_NAMES: readonly FeatureName[];
+export type ProviderName = 'sendgrid' | 'mailgun' | 'postmark' | 'ses' | 'smtp';
+export declare const PROVIDER_NAMES: readonly ProviderName[];
+/**
+ * A complete capability map for a single provider -- one entry per feature.
+ */
+export type ProviderCapabilityMap = Record<FeatureName, CapabilityEntry>;
+/**
+ * Top-level structure for the capability matrix.
+ */
+export interface CapabilityMatrixData {
+    version: string;
+    lastUpdated: string;
+    providers: Record<ProviderName, ProviderCapabilityMap>;
+}
+export declare const CAPABILITY_MATRIX: CapabilityMatrixData;
+/**
+ * Returns a deep clone of the capability matrix to prevent mutation of the
+ * canonical data.
+ */
+export declare function getCapabilityMatrix(): CapabilityMatrixData;
+//# sourceMappingURL=matrix.d.ts.map

package/dist/capabilities/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/capabilities/matrix.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAUhE,eAAO,MAAM,mBAAmB;;;;;;;;;;;IAW9B;;;;OAIG;;IAEH;;;;;OAKG;;;;;;;;;;;;;CAaK,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAE9B,CAAC;AAMnB,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;AAEhF,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAMxC,CAAC;AAMX;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;CACxD;AAuND,eAAO,MAAM,iBAAiB,EAAE,oBAU/B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,CAE1D"}