@venizia/ignis 0.4.3 → 0.4.5

package/dist/esm/components/health-check/reporter.d.ts

@@ -0,0 +1,98 @@
+import { type TBuildInfoRecord } from '@venizia/ignis-helpers/core';
+import type { IApplicationInfo } from '@venizia/ignis-kernel';
+import type { IHealthCheckOptions } from './common/index.js';
+/**
+ * Assembles what `GET /health` and `GET /health/stats` answer.
+ *
+ * Never reads the filesystem and never spawns `git`: the build stamp is PUSHED in at the
+ * entrypoint through {@link BuildInfoRegistry} (or the component's own options), so a
+ * `bun build --compile` binary and a Distroless image - neither of which has `node_modules`,
+ * `.git` or a readable `package.json` - report exactly what a dev machine does.
+ */
+export declare class HealthCheckReporter {
+    private static readonly BYTES_PER_MB;
+    /** Public liveness answer: liveness and the server clock, nothing a probe cannot already see. */
+    static buildSummary(): {
+        status: string;
+        timestamp: string;
+    };
+    /**
+     * Fail-closed, copying `AppErrorMiddleware.isProduction`: the default is MEMBERSHIP in
+     * `DEVELOPMENT_ENVS`, never inequality against `production`. `staging`, `uat`, `alpha` and a
+     * typo all keep this route shut, because the runtime and release it names are what picks an
+     * exploit. `ambient`, not `current`: an unset `NODE_ENV` is a host that cannot prove it is a dev
+     * machine, and `current` would mask it as `development`.
+     *
+     * `enable` is compared to `true`/`false` rather than read through `??`: this binding is
+     * env/config driven, and a JSON-derived `"false"` is truthy - an operator who wrote false would
+     * otherwise get the route mounted.
+     */
+    static isStatsEnabled(opts: {
+        options: IHealthCheckOptions;
+        /** Reads the ambient environment; injected by tests so nothing has to write `process.env`. */
+        environment?: () => string | undefined;
+    }): boolean;
+    /**
+     * No `secretKey` configured leaves the route open to whatever can reach the port - stated, not
+     * implied. Anything that is not a non-blank string fails CLOSED: a blank or config-derived
+     * non-string key is a pipeline that lost the variable, and reading it as "no key" would publish
+     * the route the operator meant to lock.
+     *
+     * The comparison is a plain `===`: a remote timing attack on a header compare is not practical
+     * through an HTTP stack, and a constant-time digest compare would buy nothing here.
+     */
+    /**
+     * Whether the stats route is mounted, unauthenticated, and on a host that cannot be shown to be a
+     * development one. That combination stays LEGAL - on a cluster-internal port it is often the right
+     * call - so this reports rather than refuses, and the component turns it into one warning at boot.
+     *
+     * It exists because `enable: true` bypasses the environment gate entirely: an operator who sets it
+     * for a local run and ships the same code publishes the runtime version, the release and the
+     * memory profile to whatever can reach the port. A blank `secretKey` is NOT unguarded - that fails
+     * closed in {@link isStatsAuthorized}.
+     */
+    static isStatsUnguarded(opts: {
+        options: IHealthCheckOptions;
+        environment?: () => string | undefined;
+    }): boolean;
+    static isStatsAuthorized(opts: {
+        options: IHealthCheckOptions;
+        header?: string;
+    }): boolean;
+    /** The slot is a process-wide `globalThis` entry any dependency can write, and `IBuildInfo` types it without checking - so a non-string never reaches the response schema, which declares `z.string()`. */
+    private static extractText;
+    /**
+     * Explicit options win over the registry, and the application's own `getAppInfo()` fills what
+     * neither carries - so a host that ran no generator still reports its real name and version.
+     */
+    static resolveBuildInfo(opts: {
+        options: IHealthCheckOptions;
+        appInfo?: IApplicationInfo;
+    }): TBuildInfoRecord;
+    /** `3661` -> `1h 1m 1s`: an operator reads a restart out of this faster than out of a float. */
+    static toHumanUptime(opts: {
+        seconds: number;
+    }): string;
+    private static toMegabytes;
+    static buildStats(opts: {
+        options: IHealthCheckOptions;
+        appInfo?: IApplicationInfo;
+    }): {
+        build: Required<import("@venizia/ignis-helpers").IBuildInfo>;
+        process: {
+            pid: number;
+            uptime: number;
+            uptimeHuman: string;
+            runtime: string;
+            environment: string;
+        };
+        memory: {
+            rss: string;
+            heapUsed: string;
+            heapTotal: string;
+        };
+        status: string;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=reporter.d.ts.map

package/dist/esm/components/health-check/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../../../src/components/health-check/reporter.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAe;IAEnD,iGAAiG;IACjG,MAAM,CAAC,YAAY,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAI5D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;QAC1B,OAAO,EAAE,mBAAmB,CAAC;QAC7B,8FAA8F;QAC9F,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;KACxC,GAAG,OAAO;IAcX;;;;;;;;OAQG;IACH;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE;QAC5B,OAAO,EAAE,mBAAmB,CAAC;QAC7B,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;KACxC,GAAG,OAAO;IAiBX,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,mBAAmB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAa1F,2MAA2M;IAC3M,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE;QAC5B,OAAO,EAAE,mBAAmB,CAAC;QAC7B,OAAO,CAAC,EAAE,gBAAgB,CAAC;KAC5B,GAAG,gBAAgB;IAepB,gGAAgG;IAChG,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IASvD,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,mBAAmB,CAAC;QAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAAE;;;;;;;;;;;;;;gBA9HnD,MAAM;mBAAa,MAAM;;CAoJ3D"}

package/dist/esm/components/health-check/reporter.js

@@ -0,0 +1,133 @@
+import { Environment } from '@venizia/ignis-helpers';
+import { BuildInfoRegistry } from '@venizia/ignis-helpers/core';
+/**
+ * Assembles what `GET /health` and `GET /health/stats` answer.
+ *
+ * Never reads the filesystem and never spawns `git`: the build stamp is PUSHED in at the
+ * entrypoint through {@link BuildInfoRegistry} (or the component's own options), so a
+ * `bun build --compile` binary and a Distroless image - neither of which has `node_modules`,
+ * `.git` or a readable `package.json` - report exactly what a dev machine does.
+ */
+export class HealthCheckReporter {
+    static { this.BYTES_PER_MB = 1024 * 1024; }
+    /** Public liveness answer: liveness and the server clock, nothing a probe cannot already see. */
+    static buildSummary() {
+        return { status: 'ok', timestamp: new Date().toISOString() };
+    }
+    /**
+     * Fail-closed, copying `AppErrorMiddleware.isProduction`: the default is MEMBERSHIP in
+     * `DEVELOPMENT_ENVS`, never inequality against `production`. `staging`, `uat`, `alpha` and a
+     * typo all keep this route shut, because the runtime and release it names are what picks an
+     * exploit. `ambient`, not `current`: an unset `NODE_ENV` is a host that cannot prove it is a dev
+     * machine, and `current` would mask it as `development`.
+     *
+     * `enable` is compared to `true`/`false` rather than read through `??`: this binding is
+     * env/config driven, and a JSON-derived `"false"` is truthy - an operator who wrote false would
+     * otherwise get the route mounted.
+     */
+    static isStatsEnabled(opts) {
+        const { enable } = opts.options.stats ?? {};
+        if (typeof enable === 'boolean') {
+            return enable;
+        }
+        const ambient = opts.environment ? opts.environment() : Environment.ambient;
+        if (ambient === undefined) {
+            return false;
+        }
+        return Environment.DEVELOPMENT_ENVS.has(ambient.toLowerCase());
+    }
+    /**
+     * No `secretKey` configured leaves the route open to whatever can reach the port - stated, not
+     * implied. Anything that is not a non-blank string fails CLOSED: a blank or config-derived
+     * non-string key is a pipeline that lost the variable, and reading it as "no key" would publish
+     * the route the operator meant to lock.
+     *
+     * The comparison is a plain `===`: a remote timing attack on a header compare is not practical
+     * through an HTTP stack, and a constant-time digest compare would buy nothing here.
+     */
+    /**
+     * Whether the stats route is mounted, unauthenticated, and on a host that cannot be shown to be a
+     * development one. That combination stays LEGAL - on a cluster-internal port it is often the right
+     * call - so this reports rather than refuses, and the component turns it into one warning at boot.
+     *
+     * It exists because `enable: true` bypasses the environment gate entirely: an operator who sets it
+     * for a local run and ships the same code publishes the runtime version, the release and the
+     * memory profile to whatever can reach the port. A blank `secretKey` is NOT unguarded - that fails
+     * closed in {@link isStatsAuthorized}.
+     */
+    static isStatsUnguarded(opts) {
+        if (!HealthCheckReporter.isStatsEnabled(opts)) {
+            return false;
+        }
+        if (opts.options.stats?.secretKey !== undefined) {
+            return false;
+        }
+        const ambient = opts.environment ? opts.environment() : Environment.ambient;
+        if (ambient === undefined) {
+            return true;
+        }
+        return !Environment.DEVELOPMENT_ENVS.has(ambient.toLowerCase());
+    }
+    static isStatsAuthorized(opts) {
+        const secretKey = opts.options.stats?.secretKey;
+        if (secretKey === undefined) {
+            return true;
+        }
+        if (typeof secretKey !== 'string' || secretKey.trim().length === 0) {
+            return false;
+        }
+        return opts.header === secretKey;
+    }
+    /** The slot is a process-wide `globalThis` entry any dependency can write, and `IBuildInfo` types it without checking - so a non-string never reaches the response schema, which declares `z.string()`. */
+    static extractText(opts) {
+        return typeof opts.value === 'string' && opts.value.length > 0 ? opts.value : undefined;
+    }
+    /**
+     * Explicit options win over the registry, and the application's own `getAppInfo()` fills what
+     * neither carries - so a host that ran no generator still reports its real name and version.
+     */
+    static resolveBuildInfo(opts) {
+        const stamp = opts.options.stats?.buildInfo ?? BuildInfoRegistry.get() ?? {};
+        const extract = HealthCheckReporter.extractText;
+        return {
+            service: extract({ value: stamp.service }) ?? opts.appInfo?.name ?? BuildInfoRegistry.UNSPECIFIED,
+            version: extract({ value: stamp.version }) ?? opts.appInfo?.version ?? BuildInfoRegistry.UNSPECIFIED,
+            commit: extract({ value: stamp.commit }) ?? BuildInfoRegistry.UNSPECIFIED,
+            branch: extract({ value: stamp.branch }) ?? BuildInfoRegistry.UNSPECIFIED,
+            builtAt: extract({ value: stamp.builtAt }) ?? BuildInfoRegistry.UNSPECIFIED,
+        };
+    }
+    /** `3661` -> `1h 1m 1s`: an operator reads a restart out of this faster than out of a float. */
+    static toHumanUptime(opts) {
+        const total = Math.floor(opts.seconds);
+        const hours = Math.floor(total / 3600);
+        const minutes = Math.floor((total % 3600) / 60);
+        const seconds = total % 60;
+        return `${hours}h ${minutes}m ${seconds}s`;
+    }
+    static toMegabytes(opts) {
+        return `${(opts.bytes / HealthCheckReporter.BYTES_PER_MB).toFixed(1)} MB`;
+    }
+    static buildStats(opts) {
+        const memory = process.memoryUsage();
+        const uptime = process.uptime();
+        return {
+            ...HealthCheckReporter.buildSummary(),
+            build: HealthCheckReporter.resolveBuildInfo(opts),
+            process: {
+                pid: process.pid,
+                uptime,
+                uptimeHuman: HealthCheckReporter.toHumanUptime({ seconds: uptime }),
+                runtime: `bun ${Bun.version}`,
+                // `ambient`, not `current`: an unset `NODE_ENV` is reported as such, never dressed up as `development`.
+                environment: Environment.ambient ?? BuildInfoRegistry.UNSPECIFIED,
+            },
+            memory: {
+                rss: HealthCheckReporter.toMegabytes({ bytes: memory.rss }),
+                heapUsed: HealthCheckReporter.toMegabytes({ bytes: memory.heapUsed }),
+                heapTotal: HealthCheckReporter.toMegabytes({ bytes: memory.heapTotal }),
+            },
+        };
+    }
+}
+//# sourceMappingURL=reporter.js.map

package/dist/esm/components/health-check/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../../../../src/components/health-check/reporter.ts"],"names":[],"mappings":"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","sourcesContent":["import { Environment } from '@venizia/ignis-helpers';\nimport { BuildInfoRegistry, type TBuildInfoRecord } from '@venizia/ignis-helpers/core';\nimport type { IApplicationInfo } from '@venizia/ignis-kernel';\nimport type { IHealthCheckOptions } from './common';\n\n/**\n * Assembles what `GET /health` and `GET /health/stats` answer.\n *\n * Never reads the filesystem and never spawns `git`: the build stamp is PUSHED in at the\n * entrypoint through {@link BuildInfoRegistry} (or the component's own options), so a\n * `bun build --compile` binary and a Distroless image - neither of which has `node_modules`,\n * `.git` or a readable `package.json` - report exactly what a dev machine does.\n */\nexport class HealthCheckReporter {\n  private static readonly BYTES_PER_MB = 1024 * 1024;\n\n  /** Public liveness answer: liveness and the server clock, nothing a probe cannot already see. */\n  static buildSummary(): { status: string; timestamp: string } {\n    return { status: 'ok', timestamp: new Date().toISOString() };\n  }\n\n  /**\n   * Fail-closed, copying `AppErrorMiddleware.isProduction`: the default is MEMBERSHIP in\n   * `DEVELOPMENT_ENVS`, never inequality against `production`. `staging`, `uat`, `alpha` and a\n   * typo all keep this route shut, because the runtime and release it names are what picks an\n   * exploit. `ambient`, not `current`: an unset `NODE_ENV` is a host that cannot prove it is a dev\n   * machine, and `current` would mask it as `development`.\n   *\n   * `enable` is compared to `true`/`false` rather than read through `??`: this binding is\n   * env/config driven, and a JSON-derived `\"false\"` is truthy - an operator who wrote false would\n   * otherwise get the route mounted.\n   */\n  static isStatsEnabled(opts: {\n    options: IHealthCheckOptions;\n    /** Reads the ambient environment; injected by tests so nothing has to write `process.env`. */\n    environment?: () => string | undefined;\n  }): boolean {\n    const { enable } = opts.options.stats ?? {};\n    if (typeof enable === 'boolean') {\n      return enable;\n    }\n\n    const ambient = opts.environment ? opts.environment() : Environment.ambient;\n    if (ambient === undefined) {\n      return false;\n    }\n\n    return Environment.DEVELOPMENT_ENVS.has(ambient.toLowerCase());\n  }\n\n  /**\n   * No `secretKey` configured leaves the route open to whatever can reach the port - stated, not\n   * implied. Anything that is not a non-blank string fails CLOSED: a blank or config-derived\n   * non-string key is a pipeline that lost the variable, and reading it as \"no key\" would publish\n   * the route the operator meant to lock.\n   *\n   * The comparison is a plain `===`: a remote timing attack on a header compare is not practical\n   * through an HTTP stack, and a constant-time digest compare would buy nothing here.\n   */\n  /**\n   * Whether the stats route is mounted, unauthenticated, and on a host that cannot be shown to be a\n   * development one. That combination stays LEGAL - on a cluster-internal port it is often the right\n   * call - so this reports rather than refuses, and the component turns it into one warning at boot.\n   *\n   * It exists because `enable: true` bypasses the environment gate entirely: an operator who sets it\n   * for a local run and ships the same code publishes the runtime version, the release and the\n   * memory profile to whatever can reach the port. A blank `secretKey` is NOT unguarded - that fails\n   * closed in {@link isStatsAuthorized}.\n   */\n  static isStatsUnguarded(opts: {\n    options: IHealthCheckOptions;\n    environment?: () => string | undefined;\n  }): boolean {\n    if (!HealthCheckReporter.isStatsEnabled(opts)) {\n      return false;\n    }\n\n    if (opts.options.stats?.secretKey !== undefined) {\n      return false;\n    }\n\n    const ambient = opts.environment ? opts.environment() : Environment.ambient;\n    if (ambient === undefined) {\n      return true;\n    }\n\n    return !Environment.DEVELOPMENT_ENVS.has(ambient.toLowerCase());\n  }\n\n  static isStatsAuthorized(opts: { options: IHealthCheckOptions; header?: string }): boolean {\n    const secretKey = opts.options.stats?.secretKey;\n    if (secretKey === undefined) {\n      return true;\n    }\n\n    if (typeof secretKey !== 'string' || secretKey.trim().length === 0) {\n      return false;\n    }\n\n    return opts.header === secretKey;\n  }\n\n  /** The slot is a process-wide `globalThis` entry any dependency can write, and `IBuildInfo` types it without checking - so a non-string never reaches the response schema, which declares `z.string()`. */\n  private static extractText(opts: { value: unknown }): string | undefined {\n    return typeof opts.value === 'string' && opts.value.length > 0 ? opts.value : undefined;\n  }\n\n  /**\n   * Explicit options win over the registry, and the application's own `getAppInfo()` fills what\n   * neither carries - so a host that ran no generator still reports its real name and version.\n   */\n  static resolveBuildInfo(opts: {\n    options: IHealthCheckOptions;\n    appInfo?: IApplicationInfo;\n  }): TBuildInfoRecord {\n    const stamp = opts.options.stats?.buildInfo ?? BuildInfoRegistry.get() ?? {};\n    const extract = HealthCheckReporter.extractText;\n\n    return {\n      service:\n        extract({ value: stamp.service }) ?? opts.appInfo?.name ?? BuildInfoRegistry.UNSPECIFIED,\n      version:\n        extract({ value: stamp.version }) ?? opts.appInfo?.version ?? BuildInfoRegistry.UNSPECIFIED,\n      commit: extract({ value: stamp.commit }) ?? BuildInfoRegistry.UNSPECIFIED,\n      branch: extract({ value: stamp.branch }) ?? BuildInfoRegistry.UNSPECIFIED,\n      builtAt: extract({ value: stamp.builtAt }) ?? BuildInfoRegistry.UNSPECIFIED,\n    };\n  }\n\n  /** `3661` -> `1h 1m 1s`: an operator reads a restart out of this faster than out of a float. */\n  static toHumanUptime(opts: { seconds: number }): string {\n    const total = Math.floor(opts.seconds);\n    const hours = Math.floor(total / 3600);\n    const minutes = Math.floor((total % 3600) / 60);\n    const seconds = total % 60;\n\n    return `${hours}h ${minutes}m ${seconds}s`;\n  }\n\n  private static toMegabytes(opts: { bytes: number }): string {\n    return `${(opts.bytes / HealthCheckReporter.BYTES_PER_MB).toFixed(1)} MB`;\n  }\n\n  static buildStats(opts: { options: IHealthCheckOptions; appInfo?: IApplicationInfo }) {\n    const memory = process.memoryUsage();\n    const uptime = process.uptime();\n\n    return {\n      ...HealthCheckReporter.buildSummary(),\n      build: HealthCheckReporter.resolveBuildInfo(opts),\n      process: {\n        pid: process.pid,\n        uptime,\n        uptimeHuman: HealthCheckReporter.toHumanUptime({ seconds: uptime }),\n        runtime: `bun ${Bun.version}`,\n        // `ambient`, not `current`: an unset `NODE_ENV` is reported as such, never dressed up as `development`.\n        environment: Environment.ambient ?? BuildInfoRegistry.UNSPECIFIED,\n      },\n      memory: {\n        rss: HealthCheckReporter.toMegabytes({ bytes: memory.rss }),\n        heapUsed: HealthCheckReporter.toMegabytes({ bytes: memory.heapUsed }),\n        heapTotal: HealthCheckReporter.toMegabytes({ bytes: memory.heapTotal }),\n      },\n    };\n  }\n}\n"]}

package/dist/esm/components/index.d.ts

@@ -0,0 +1,6 @@
+export * from './auth/index.js';
+export * from './controller/index.js';
+export * from './health-check/index.js';
+export * from './request-tracker/index.js';
+export * from './api-reference/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/esm/components/index.js

@@ -0,0 +1,7 @@
+export * from './auth/index.js';
+export * from './controller/index.js';
+export * from './health-check/index.js';
+export * from './request-tracker/index.js';
+export * from './api-reference/index.js';
+// Excluded from the barrel - import directly from the subpath: mail, socket-io, static-asset, websocket
+//# sourceMappingURL=index.js.map

package/dist/esm/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAEhC,wGAAwG","sourcesContent":["export * from './auth';\nexport * from './controller';\nexport * from './health-check';\nexport * from './request-tracker';\nexport * from './api-reference';\n\n// Excluded from the barrel - import directly from the subpath: mail, socket-io, static-asset, websocket\n"]}

package/dist/esm/components/mail/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAGjE,qBAAa,YAAY;IACvB,MAAM,CAAC,QAAQ,CAAC,iBAAiB,KAAK;IACtC,MAAM,CAAC,QAAQ,CAAC,aAAa,yBAAyB;IACtD,mFAAmF;IACnF,MAAM,CAAC,QAAQ,CAAC,oBAAoB,SAAoB;CACzD;AAED,yKAAyK;AACzK,qBAAa,cAAc;IACzB,MAAM,CAAC,QAAQ,CAAC,qBAAqB,SAElC;IACH,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAiE;IAC5F,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAEhC;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,SAE9B;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,SAE9B;IACH,MAAM,CAAC,QAAQ,CAAC,kBAAkB,SAE/B;IACH,MAAM,CAAC,QAAQ,CAAC,uBAAuB,SAEpC;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,SAEjC;IACH,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAEhC;CACJ;AAED,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,iBAAiB,mDAAmD;CACrF;AAED,qBAAa,sBAAsB;IACjC,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAClC,MAAM,CAAC,QAAQ,CAAC,cAAc,oBAAoB;IAClD,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAElC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAAoE;IAC9F,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGvC;AAED,qBAAa,mBAAmB;IAC9B,MAAM,CAAC,QAAQ,CAAC,UAAU,gBAAgB;IAC1C,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAC5C,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;IAE9B,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAmE;IAC3F,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGvC;AAED,qBAAa,aAAa;IACxB,MAAM,CAAC,QAAQ,CAAC,UAAU,gBAAgB;IAC1C,MAAM,CAAC,QAAQ,CAAC,OAAO,aAAa;IACpC,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY;IAElC,MAAM,CAAC,QAAQ,CAAC,UAAU,gBAAgB;CAC3C;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAE9D,iHAAiH;AACjH,qBAAa,gBAAgB;IAC3B,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAE5C,MAAM,CAAC,QAAQ,CAAC,UAAU,cAAmD;IAE7E,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGvC;AAED,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/esm/components/mail/common/constants.js

@@ -0,0 +1,73 @@
+import { MessageCode } from '@venizia/ignis-helpers/core';
+export class MailDefaults {
+    static { this.BATCH_CONCURRENCY = 5; }
+    static { this.FALLBACK_FROM = 'noreply@example.com'; }
+    /** Bytes of attachment content one message may carry, all attachments together. */
+    static { this.MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024; }
+}
+/** Built via {@link MessageCode.build}: `ApplicationError` lower-cases codes, so a SCREAMING_CASE literal would reach the client in a spelling no const here matches. */
+export class MailErrorCodes {
+    static { this.INVALID_CONFIGURATION = MessageCode.build({
+        parts: ['core', 'mail', 'invalid_configuration'],
+    }); }
+    static { this.SEND_FAILED = MessageCode.build({ parts: ['core', 'mail', 'send_failed'] }); }
+    static { this.VERIFICATION_FAILED = MessageCode.build({
+        parts: ['core', 'mail', 'verification_failed'],
+    }); }
+    static { this.INVALID_RECIPIENT = MessageCode.build({
+        parts: ['core', 'mail', 'invalid_recipient'],
+    }); }
+    static { this.BATCH_SEND_FAILED = MessageCode.build({
+        parts: ['core', 'mail', 'batch_send_failed'],
+    }); }
+    static { this.TEMPLATE_NOT_FOUND = MessageCode.build({
+        parts: ['core', 'mail', 'template_not_found'],
+    }); }
+    static { this.ATTACHMENT_PATH_REFUSED = MessageCode.build({
+        parts: ['core', 'mail', 'attachment_path_refused'],
+    }); }
+    static { this.ATTACHMENT_TOO_LARGE = MessageCode.build({
+        parts: ['core', 'mail', 'attachment_too_large'],
+    }); }
+    static { this.BODY_SOURCE_REFUSED = MessageCode.build({
+        parts: ['core', 'mail', 'body_source_refused'],
+    }); }
+}
+export class MailExecutorErrors {
+    static { this.PROCESSOR_NOT_SET = 'Processor not set. Call setProcessor() first.'; }
+}
+export class MailQueueExecutorTypes {
+    static { this.DIRECT = 'direct'; }
+    static { this.INTERNAL_QUEUE = 'internal-queue'; }
+    static { this.BULLMQ = 'bullmq'; }
+    static { this.SCHEME_SET = new Set([this.DIRECT, this.INTERNAL_QUEUE, this.BULLMQ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+export class BullMQExecutorModes {
+    static { this.QUEUE_ONLY = 'queue-only'; }
+    static { this.WORKER_ONLY = 'worker-only'; }
+    static { this.BOTH = 'both'; }
+    static { this.MODE_SET = new Set([this.QUEUE_ONLY, this.WORKER_ONLY, this.BOTH]); }
+    static isValid(value) {
+        return this.MODE_SET.has(value);
+    }
+}
+export class MailProviders {
+    static { this.NODEMAILER = 'nodemailer'; }
+    static { this.MAILGUN = 'mailgun'; }
+    static { this.CUSTOM = 'custom'; }
+    // Amazon SES supports both SMTP and HTTPS - this provider is the HTTPS API path; SMTP goes through NODEMAILER instead.
+    static { this.AMAZON_SES = 'amazon-ses'; }
+}
+/** How the delay between two attempts to send a queued mail grows: FIXED stays the same, EXPONENTIAL doubles. */
+export class MailBackoffTypes {
+    static { this.FIXED = 'fixed'; }
+    static { this.EXPONENTIAL = 'exponential'; }
+    static { this.SCHEME_SET = new Set([this.FIXED, this.EXPONENTIAL]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+//# sourceMappingURL=constants.js.map

package/dist/esm/components/mail/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/components/mail/common/constants.ts"],"names":[],"mappings":"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","sourcesContent":["import type { TConstValue } from '@venizia/ignis-helpers/common';\nimport { MessageCode } from '@venizia/ignis-helpers/core';\n\nexport class MailDefaults {\n  static readonly BATCH_CONCURRENCY = 5;\n  static readonly FALLBACK_FROM = 'noreply@example.com';\n  /** Bytes of attachment content one message may carry, all attachments together. */\n  static readonly MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;\n}\n\n/** Built via {@link MessageCode.build}: `ApplicationError` lower-cases codes, so a SCREAMING_CASE literal would reach the client in a spelling no const here matches. */\nexport class MailErrorCodes {\n  static readonly INVALID_CONFIGURATION = MessageCode.build({\n    parts: ['core', 'mail', 'invalid_configuration'],\n  });\n  static readonly SEND_FAILED = MessageCode.build({ parts: ['core', 'mail', 'send_failed'] });\n  static readonly VERIFICATION_FAILED = MessageCode.build({\n    parts: ['core', 'mail', 'verification_failed'],\n  });\n  static readonly INVALID_RECIPIENT = MessageCode.build({\n    parts: ['core', 'mail', 'invalid_recipient'],\n  });\n  static readonly BATCH_SEND_FAILED = MessageCode.build({\n    parts: ['core', 'mail', 'batch_send_failed'],\n  });\n  static readonly TEMPLATE_NOT_FOUND = MessageCode.build({\n    parts: ['core', 'mail', 'template_not_found'],\n  });\n  static readonly ATTACHMENT_PATH_REFUSED = MessageCode.build({\n    parts: ['core', 'mail', 'attachment_path_refused'],\n  });\n  static readonly ATTACHMENT_TOO_LARGE = MessageCode.build({\n    parts: ['core', 'mail', 'attachment_too_large'],\n  });\n  static readonly BODY_SOURCE_REFUSED = MessageCode.build({\n    parts: ['core', 'mail', 'body_source_refused'],\n  });\n}\n\nexport class MailExecutorErrors {\n  static readonly PROCESSOR_NOT_SET = 'Processor not set. Call setProcessor() first.';\n}\n\nexport class MailQueueExecutorTypes {\n  static readonly DIRECT = 'direct';\n  static readonly INTERNAL_QUEUE = 'internal-queue';\n  static readonly BULLMQ = 'bullmq';\n\n  static readonly SCHEME_SET = new Set<string>([this.DIRECT, this.INTERNAL_QUEUE, this.BULLMQ]);\n  static isValid(value: string): boolean {\n    return this.SCHEME_SET.has(value);\n  }\n}\n\nexport class BullMQExecutorModes {\n  static readonly QUEUE_ONLY = 'queue-only';\n  static readonly WORKER_ONLY = 'worker-only';\n  static readonly BOTH = 'both';\n\n  static readonly MODE_SET = new Set<string>([this.QUEUE_ONLY, this.WORKER_ONLY, this.BOTH]);\n  static isValid(value: string): boolean {\n    return this.MODE_SET.has(value);\n  }\n}\n\nexport class MailProviders {\n  static readonly NODEMAILER = 'nodemailer';\n  static readonly MAILGUN = 'mailgun';\n  static readonly CUSTOM = 'custom';\n  // Amazon SES supports both SMTP and HTTPS - this provider is the HTTPS API path; SMTP goes through NODEMAILER instead.\n  static readonly AMAZON_SES = 'amazon-ses';\n}\n\nexport type TMailProvider = TConstValue<typeof MailProviders>;\n\n/** How the delay between two attempts to send a queued mail grows: FIXED stays the same, EXPONENTIAL doubles. */\nexport class MailBackoffTypes {\n  static readonly FIXED = 'fixed';\n  static readonly EXPONENTIAL = 'exponential';\n\n  static readonly SCHEME_SET = new Set<string>([this.FIXED, this.EXPONENTIAL]);\n\n  static isValid(value: string): boolean {\n    return this.SCHEME_SET.has(value);\n  }\n}\n\n/** Valid mail backoff type values. */\nexport type TMailBackoffType = TConstValue<typeof MailBackoffTypes>;\n"]}

package/dist/esm/components/mail/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAIrF,oPAAoP;AACpP,qTAAqT;AACrT,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;IAgBrB,gIAAgI;;;;;;;;;;;;;;;;;;;;;;;;;CAsB7E,CAAC;AAEtD,2GAA2G;AAC3G,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,iBAAkB,SAAQ,eAAe,CAAC,OAAO,UAAU,CAAC;KAAG;CAC1E"}

package/dist/esm/components/mail/common/errors.js

@@ -0,0 +1,44 @@
+import { ErrorScopes } from '@venizia/ignis-helpers/core';
+import { HTTP } from '@venizia/ignis-helpers/common';
+/** Codes a client branches on for a mail request it can fix - a missing template, a message that is not sendable. Delivery failures are NOT here: they are 5xx and stay codeless, because a client cannot act on the remote provider being down. */
+/** Codes are LITERAL strings, deliberately not `MailErrorCodes.*`: `MessageCode.build()` returns `string`, which erases the literal type `TRegisterErrors` is built on and silently kills autocomplete. The values are identical to what those constants produce - they are a public contract and must not shift. */
+export const MailErrors = {
+    TEMPLATE_NOT_FOUND: {
+        message: { text: 'Mail template not found', code: 'core.mail.template_not_found' },
+        statusCode: HTTP.ResultCodes.RS_4.NotFound,
+        category: ErrorScopes.BUSINESS,
+    },
+    INVALID_CONFIGURATION: {
+        message: { text: 'Invalid mail configuration', code: 'core.mail.invalid_configuration' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.VALIDATION,
+    },
+    INVALID_RECIPIENT: {
+        message: { text: 'Invalid mail recipient', code: 'core.mail.invalid_recipient' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.VALIDATION,
+    },
+    /** One answer for every refused source - outside the root, missing, not a file - so a caller cannot probe which files exist. */
+    ATTACHMENT_PATH_REFUSED: {
+        message: {
+            text: 'Mail attachment path refused',
+            code: 'core.mail.attachment_path_refused',
+        },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.VALIDATION,
+    },
+    ATTACHMENT_TOO_LARGE: {
+        message: {
+            text: 'Mail attachments are larger than the maximum allowed',
+            code: 'core.mail.attachment_too_large',
+        },
+        statusCode: HTTP.ResultCodes.RS_4.ContentTooLarge,
+        category: ErrorScopes.VALIDATION,
+    },
+    BODY_SOURCE_REFUSED: {
+        message: { text: 'Mail body must be text', code: 'core.mail.body_source_refused' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.VALIDATION,
+    },
+};
+//# sourceMappingURL=errors.js.map

package/dist/esm/components/mail/common/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/components/mail/common/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAErD,oPAAoP;AACpP,qTAAqT;AACrT,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,kBAAkB,EAAE;QAClB,OAAO,EAAE,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,8BAA8B,EAAE;QAClF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ;QAC1C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;IACD,qBAAqB,EAAE;QACrB,OAAO,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,iCAAiC,EAAE;QACxF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,UAAU;KACjC;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,6BAA6B,EAAE;QAChF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,UAAU;KACjC;IACD,gIAAgI;IAChI,uBAAuB,EAAE;QACvB,OAAO,EAAE;YACP,IAAI,EAAE,8BAA8B;YACpC,IAAI,EAAE,mCAAmC;SAC1C;QACD,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,UAAU;KACjC;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE;YACP,IAAI,EAAE,sDAAsD;YAC5D,IAAI,EAAE,gCAAgC;SACvC;QACD,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,eAAe;QACjD,QAAQ,EAAE,WAAW,CAAC,UAAU;KACjC;IACD,mBAAmB,EAAE;QACnB,OAAO,EAAE,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,+BAA+B,EAAE;QAClF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,UAAU;KACjC;CACkD,CAAC","sourcesContent":["import type { TErrorDefinition, TRegisterErrors } from '@venizia/ignis-helpers/core';\nimport { ErrorScopes } from '@venizia/ignis-helpers/core';\nimport { HTTP } from '@venizia/ignis-helpers/common';\n\n/** Codes a client branches on for a mail request it can fix - a missing template, a message that is not sendable. Delivery failures are NOT here: they are 5xx and stay codeless, because a client cannot act on the remote provider being down. */\n/** Codes are LITERAL strings, deliberately not `MailErrorCodes.*`: `MessageCode.build()` returns `string`, which erases the literal type `TRegisterErrors` is built on and silently kills autocomplete. The values are identical to what those constants produce - they are a public contract and must not shift. */\nexport const MailErrors = {\n  TEMPLATE_NOT_FOUND: {\n    message: { text: 'Mail template not found', code: 'core.mail.template_not_found' },\n    statusCode: HTTP.ResultCodes.RS_4.NotFound,\n    category: ErrorScopes.BUSINESS,\n  },\n  INVALID_CONFIGURATION: {\n    message: { text: 'Invalid mail configuration', code: 'core.mail.invalid_configuration' },\n    statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n    category: ErrorScopes.VALIDATION,\n  },\n  INVALID_RECIPIENT: {\n    message: { text: 'Invalid mail recipient', code: 'core.mail.invalid_recipient' },\n    statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n    category: ErrorScopes.VALIDATION,\n  },\n  /** One answer for every refused source - outside the root, missing, not a file - so a caller cannot probe which files exist. */\n  ATTACHMENT_PATH_REFUSED: {\n    message: {\n      text: 'Mail attachment path refused',\n      code: 'core.mail.attachment_path_refused',\n    },\n    statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n    category: ErrorScopes.VALIDATION,\n  },\n  ATTACHMENT_TOO_LARGE: {\n    message: {\n      text: 'Mail attachments are larger than the maximum allowed',\n      code: 'core.mail.attachment_too_large',\n    },\n    statusCode: HTTP.ResultCodes.RS_4.ContentTooLarge,\n    category: ErrorScopes.VALIDATION,\n  },\n  BODY_SOURCE_REFUSED: {\n    message: { text: 'Mail body must be text', code: 'core.mail.body_source_refused' },\n    statusCode: HTTP.ResultCodes.RS_4.BadRequest,\n    category: ErrorScopes.VALIDATION,\n  },\n} as const satisfies Record<string, TErrorDefinition>;\n\n/** Registers these codes with the shared key registry so a consumer gets autocomplete on `messageCode`. */\ndeclare module '@venizia/ignis-helpers' {\n  interface IErrorKeyRegistry extends TRegisterErrors<typeof MailErrors> {}\n}\n"]}

package/dist/esm/components/mail/common/index.d.ts

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './constants.js';
+export * from './keys.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/mail/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/esm/components/mail/common/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './constants.js';
+export * from './keys.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/mail/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/components/mail/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC","sourcesContent":["export * from './errors';\nexport * from './constants';\nexport * from './keys';\nexport * from './types';\n"]}

package/dist/esm/components/mail/common/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/common/keys.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAQ;IAEnB,MAAM,CAAC,QAAQ,CAAC,YAAY,kCAAkC;IAC9D,MAAM,CAAC,QAAQ,CAAC,0BAA0B,gDAAgD;IAG1F,MAAM,CAAC,QAAQ,CAAC,uBAAuB,6CAA6C;IACpF,MAAM,CAAC,QAAQ,CAAC,uBAAuB,6CAA6C;IAGpF,MAAM,CAAC,QAAQ,CAAC,oBAAoB,mDAAmD;IACvF,MAAM,CAAC,QAAQ,CAAC,YAAY,kCAAkC;IAG9D,MAAM,CAAC,QAAQ,CAAC,gCAAgC,sDACK;IACrD,MAAM,CAAC,QAAQ,CAAC,iCAAiC,uDACK;IACtD,MAAM,CAAC,QAAQ,CAAC,gCAAgC,sDACK;IAGrD,MAAM,CAAC,QAAQ,CAAC,4BAA4B,kDAAkD;IAC9F,MAAM,CAAC,QAAQ,CAAC,4BAA4B,kDAAkD;CAC/F"}

package/dist/esm/components/mail/common/keys.js

@@ -0,0 +1,19 @@
+export class MailKeys {
+    // Options & Configs
+    static { this.MAIL_OPTIONS = '@app/components/mail/options'; }
+    static { this.MAIL_QUEUE_EXECUTOR_CONFIG = '@app/components/mail/queue/executor-config'; }
+    // Transporter
+    static { this.MAIL_TRANSPORT_PROVIDER = '@app/components/mail/transport-provider'; }
+    static { this.MAIL_TRANSPORT_INSTANCE = '@app/components/mail/transport-instance'; }
+    // Services
+    static { this.MAIL_TEMPLATE_ENGINE = '@app/components/mail/services/template-engine'; }
+    static { this.MAIL_SERVICE = '@app/components/mail/service'; }
+    // Generators
+    static { this.MAIL_VERIFICATION_CODE_GENERATOR = '@app/components/mail/verification/code-generator'; }
+    static { this.MAIL_VERIFICATION_TOKEN_GENERATOR = '@app/components/mail/verification/token-generator'; }
+    static { this.MAIL_VERIFICATION_DATA_GENERATOR = '@app/components/mail/verification/data-generator'; }
+    // Queue
+    static { this.MAIL_QUEUE_EXECUTOR_PROVIDER = '@app/components/mail/queue-executor-provider'; }
+    static { this.MAIL_QUEUE_EXECUTOR_INSTANCE = '@app/components/mail/queue-executor-instance'; }
+}
+//# sourceMappingURL=keys.js.map

package/dist/esm/components/mail/common/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../../../src/components/mail/common/keys.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAQ;IACnB,oBAAoB;aACJ,iBAAY,GAAG,8BAA8B,CAAC;aAC9C,+BAA0B,GAAG,4CAA4C,CAAC;IAE1F,cAAc;aACE,4BAAuB,GAAG,yCAAyC,CAAC;aACpE,4BAAuB,GAAG,yCAAyC,CAAC;IAEpF,WAAW;aACK,yBAAoB,GAAG,+CAA+C,CAAC;aACvE,iBAAY,GAAG,8BAA8B,CAAC;IAE9D,aAAa;aACG,qCAAgC,GAC9C,kDAAkD,CAAC;aACrC,sCAAiC,GAC/C,mDAAmD,CAAC;aACtC,qCAAgC,GAC9C,kDAAkD,CAAC;IAErD,QAAQ;aACQ,iCAA4B,GAAG,8CAA8C,CAAC;aAC9E,iCAA4B,GAAG,8CAA8C,CAAC","sourcesContent":["export class MailKeys {\n  // Options & Configs\n  static readonly MAIL_OPTIONS = '@app/components/mail/options';\n  static readonly MAIL_QUEUE_EXECUTOR_CONFIG = '@app/components/mail/queue/executor-config';\n\n  // Transporter\n  static readonly MAIL_TRANSPORT_PROVIDER = '@app/components/mail/transport-provider';\n  static readonly MAIL_TRANSPORT_INSTANCE = '@app/components/mail/transport-instance';\n\n  // Services\n  static readonly MAIL_TEMPLATE_ENGINE = '@app/components/mail/services/template-engine';\n  static readonly MAIL_SERVICE = '@app/components/mail/service';\n\n  // Generators\n  static readonly MAIL_VERIFICATION_CODE_GENERATOR =\n    '@app/components/mail/verification/code-generator';\n  static readonly MAIL_VERIFICATION_TOKEN_GENERATOR =\n    '@app/components/mail/verification/token-generator';\n  static readonly MAIL_VERIFICATION_DATA_GENERATOR =\n    '@app/components/mail/verification/data-generator';\n\n  // Queue\n  static readonly MAIL_QUEUE_EXECUTOR_PROVIDER = '@app/components/mail/queue-executor-provider';\n  static readonly MAIL_QUEUE_EXECUTOR_INSTANCE = '@app/components/mail/queue-executor-instance';\n}\n"]}

package/dist/esm/components/mail/common/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './message.js';
+export * from './options.js';
+export * from './queue.js';
+export * from './template.js';
+export * from './verification.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/mail/common/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/esm/components/mail/common/types/index.js

@@ -0,0 +1,6 @@
+export * from './message.js';
+export * from './options.js';
+export * from './queue.js';
+export * from './template.js';
+export * from './verification.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/mail/common/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC","sourcesContent":["export * from './message';\nexport * from './options';\nexport * from './queue';\nexport * from './template';\nexport * from './verification';\n"]}

package/dist/esm/components/mail/common/types/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC/E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACtD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACtD,SAAS,CACP,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACA,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9B,YAAY,CAAC,IAAI,EAAE;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1B,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;KACjC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B"}

package/dist/esm/components/mail/common/types/message.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=message.js.map

package/dist/esm/components/mail/common/types/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/message.ts"],"names":[],"mappings":"","sourcesContent":["import type { Readable } from 'node:stream';\n\nexport interface IMailAttachment {\n  filename?: string;\n  contentType?: string;\n  /** A file under the mail options' `attachmentRoot`; refused when no root is set. */\n  path?: string;\n  content?: string | Buffer | Uint8Array | Readable | ReadableStream<Uint8Array>;\n  encoding?: BufferEncoding;\n  cid?: string;\n  [key: string]: any;\n}\n\nexport interface IMailMessage {\n  from?: string;\n  to: string | string[];\n  cc?: string | string[];\n  bcc?: string | string[];\n  replyTo?: string;\n  subject: string;\n  text?: string;\n  html?: string;\n  attachments?: IMailAttachment[];\n  headers?: Record<string, string>;\n  requireValidate?: boolean;\n  [key: string]: any;\n}\n\nexport interface IMailSendResult {\n  success: boolean;\n  messageId?: string;\n  response?: any;\n  error?: string;\n}\n\nexport interface IMailTransport {\n  send(message: IMailMessage): Promise<IMailSendResult>;\n  verify(): Promise<boolean>;\n  close?(): Promise<void>;\n}\n\nexport interface IMailService {\n  send(message: IMailMessage): Promise<IMailSendResult>;\n  sendBatch(\n    messages: IMailMessage[],\n    options?: {\n      concurrency?: number;\n    },\n  ): Promise<IMailSendResult[]>;\n  sendTemplate(opts: {\n    templateName: string;\n    data: Record<string, any>;\n    recipients: string | string[];\n    options?: Partial<IMailMessage>;\n  }): Promise<IMailSendResult>;\n  verify(): Promise<boolean>;\n}\n"]}

package/dist/esm/components/mail/common/types/options.d.ts

@@ -0,0 +1,72 @@
+import type { AnyType } from '@venizia/ignis-helpers/common';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport';
+import type { IMailTransport } from './message.js';
+export interface IBaseMailOptions {
+    from?: string;
+    fromName?: string;
+    /**
+     * The only directory an `attachment.path` may be read from; `path` is resolved against it and
+     * refused if it lands outside, symlinks included. Unset, every `path` is refused.
+     */
+    attachmentRoot?: string;
+    /** Bytes of attachment content one message may carry, all attachments together. Default 25 MB. */
+    maxAttachmentBytes?: number;
+}
+export interface INodemailerMailOptions extends IBaseMailOptions {
+    provider: 'nodemailer';
+    config: TNodemailerConfig;
+    module?: TNodemailerModule;
+}
+export interface IMailgunMailOptions extends IBaseMailOptions {
+    provider: 'mailgun';
+    config: TMailgunConfig;
+    module?: TMailgunModule;
+}
+export interface IAmazonSesMailOptions extends IBaseMailOptions {
+    provider: 'amazon-ses';
+    config: TAmazonSesConfig;
+    module?: TAmazonSesModule;
+}
+export interface ICustomMailOptions extends IBaseMailOptions {
+    provider: 'custom';
+    config: IMailTransport;
+}
+export interface IGenericMailOptions extends IBaseMailOptions {
+    provider: string;
+    config: Record<string, AnyType>;
+}
+export type TMailOptions = INodemailerMailOptions | IAmazonSesMailOptions | IMailgunMailOptions | ICustomMailOptions | IGenericMailOptions;
+export type TNodemailerConfig = SMTPTransport | SMTPTransport.Options | string;
+export type TMailgunConfig = AnyType & {
+    domain: string;
+};
+/**
+ * The peer module itself, handed over by an application that already holds it. A `bun build
+ * --compile` binary carries no `node_modules`, so the runtime lookup these transports fall back to
+ * has nothing to resolve against - passing the module through the options is what a compiled
+ * application does instead. Typed as the shape each transport actually uses, so a wrong module is
+ * a compile error rather than a boot crash.
+ */
+export type TNodemailerModule = {
+    createTransport: (config: AnyType, defaults?: AnyType) => AnyType;
+};
+export type TMailgunModule = new (formData: AnyType) => AnyType;
+export type TAmazonSesConfig = {
+    region: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    endpoint?: string;
+};
+/** Same story as {@link TNodemailerModule} - a compiled binary hands this over explicitly since there is no `node_modules` to resolve `@aws-sdk/client-sesv2` against. */
+export type TAmazonSesModule<TConfig extends AnyType = AnyType, TClient extends AnyType = AnyType> = {
+    SESv2Client: new (config: TConfig) => TClient;
+    SendEmailCommand: new (input: AnyType) => AnyType;
+    GetAccountCommand: new (input?: AnyType) => AnyType;
+};
+export type TAmazonSesClient = Pick<TAmazonSesModule, 'SendEmailCommand' | 'GetAccountCommand'> & {
+    client: AnyType;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/esm/components/mail/common/types/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../../../../src/components/mail/common/types/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,YAAY,GACpB,sBAAsB,GACtB,qBAAqB,GACrB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC;AAG/E,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,eAAe,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,KAAK,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;AAEhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,0KAA0K;AAC1K,MAAM,MAAM,gBAAgB,CAC1B,OAAO,SAAS,OAAO,GAAG,OAAO,EACjC,OAAO,SAAS,OAAO,GAAG,OAAO,IAC/B;IACF,WAAW,EAAE,KAAK,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C,gBAAgB,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAClD,iBAAiB,EAAE,KAAK,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,GAAG,mBAAmB,CAAC,GAAG;IAChG,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC"}

package/dist/esm/components/mail/common/types/options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=options.js.map