@venizia/ignis 0.4.2 → 0.4.4

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

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../../../src/components/health-check/controller.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseRestController, type TRouteContext } from '@/base/controllers';\nimport { api, inject } from '@/base/metadata';\nimport { jsonContent, jsonResponse } from '@venizia/ignis-kernel';\nimport type { IApplicationInfo } from '@venizia/ignis-kernel';\nimport { z } from '@hono/zod-openapi';\nimport { HTTP, type ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport {\n  HealthCheckBindingKeys,\n  HealthCheckHeaders,\n  HealthCheckRestPaths,\n  type IHealthCheckOptions,\n} from './common';\nimport { HealthCheckReporter } from './reporter';\n\nconst RouteConfigs = {\n  ROOT: {\n    method: HTTP.Methods.GET,\n    path: HealthCheckRestPaths.ROOT,\n    responses: jsonResponse({\n      schema: z.object({ status: z.string(), timestamp: z.iso.datetime() }).openapi({\n        description: 'HealthCheck Schema',\n        examples: [{ status: 'ok', timestamp: new Date().toISOString() }],\n      }),\n      description: 'Health check status',\n    }),\n  },\n  STATS: {\n    method: HTTP.Methods.GET,\n    path: HealthCheckRestPaths.STATS,\n    request: {\n      headers: z.object({\n        [HealthCheckHeaders.SECRET_KEY]: z.string().optional().openapi({\n          description: 'The stats key',\n        }),\n      }),\n    },\n    responses: jsonResponse({\n      schema: z\n        .object({\n          status: z.string(),\n          timestamp: z.iso.datetime(),\n          build: z.object({\n            service: z.string(),\n            version: z.string(),\n            commit: z.string(),\n            branch: z.string(),\n            builtAt: z.string(),\n          }),\n          process: z.object({\n            pid: z.number(),\n            uptime: z.number(),\n            uptimeHuman: z.string(),\n            runtime: z.string(),\n            environment: z.string(),\n          }),\n          memory: z.object({ rss: z.string(), heapUsed: z.string(), heapTotal: z.string() }),\n        })\n        .openapi({ description: 'HealthCheck Stats Schema' }),\n      description:\n        'Build stamp, process and memory - closed outside the development environments unless enabled',\n    }),\n  },\n  PING: {\n    method: HTTP.Methods.POST,\n    path: HealthCheckRestPaths.PING,\n    request: {\n      body: jsonContent({\n        description: 'PING | Request body',\n        schema: z.object({\n          type: z.string().optional().default('PING'),\n          message: z.string().min(1).max(255),\n        }),\n      }),\n    },\n    responses: jsonResponse({\n      schema: z\n        .object({\n          type: z.string().optional().default('PONG'),\n          date: z.iso.datetime(),\n          message: z.string(),\n        })\n        .openapi({\n          description: 'HealthCheck PingPong Schema',\n          examples: [{ date: new Date().toISOString(), message: 'ok' }],\n        }),\n      description: 'HealthCheck PingPong Message',\n    }),\n  },\n} as const;\n\nexport class HealthCheckController extends BaseRestController {\n  /**\n   * Both dependencies arrive through the container, so two applications in one process each get\n   * their own gate - a static field would let the last one to boot decide for every other.\n   */\n  constructor(\n    @inject({ key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS, isOptional: true })\n    private readonly healthOptions: IHealthCheckOptions = {},\n    @inject({ key: HealthCheckBindingKeys.APPLICATION_INFO, isOptional: true })\n    private readonly appInfo?: IApplicationInfo,\n  ) {\n    super({ scope: HealthCheckController.name });\n\n    // Note: This is optional declare internal controller route definitions\n    this.definitions = RouteConfigs;\n  }\n\n  override binding(): ValueOrPromise<void> {\n    // Public liveness probe: status and clock only. Nothing here names a runtime or a version.\n    this.bindRoute({ configs: RouteConfigs.ROOT }).to({\n      handler: (context) => {\n        return context.json(HealthCheckReporter.buildSummary(), HTTP.ResultCodes.RS_2.Ok);\n      },\n    });\n\n    if (!HealthCheckReporter.isStatsEnabled({ options: this.healthOptions })) {\n      this.logger\n        .for(this.binding.name)\n        .debug('Stats route disabled | path: %s', HealthCheckRestPaths.STATS);\n      return;\n    }\n\n    this.bindRoute({ configs: RouteConfigs.STATS }).to({\n      handler: (context) => {\n        // `context.notFound()`, not a thrown 404: it runs the application's own notFound handler,\n        // so the refusal is byte-identical to the answer for a route that was never mounted. A\n        // thrown `ApplicationError` serializes a different body and would confirm the route exists.\n        if (\n          !HealthCheckReporter.isStatsAuthorized({\n            options: this.healthOptions,\n            header: context.req.header(HealthCheckHeaders.SECRET_KEY),\n          })\n        ) {\n          return context.notFound();\n        }\n\n        return context.json(\n          HealthCheckReporter.buildStats({ options: this.healthOptions, appInfo: this.appInfo }),\n          HTTP.ResultCodes.RS_2.Ok,\n        );\n      },\n    });\n  }\n\n  // Method 3: Using 'decorators' to create a controller route, with an explicit type assertion for the validated request data\n  @api({ configs: RouteConfigs.PING })\n  pingPong(context: TRouteContext) {\n    const { message } = context.req.valid<{ type?: string; message: string }>('json');\n\n    // Return type is automatically validated against the response schema\n    return context.json(\n      { type: 'PONG', date: new Date().toISOString(), message },\n      HTTP.ResultCodes.RS_2.Ok,\n    );\n  }\n}\n"]}

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

@@ -0,0 +1,5 @@
+export * from './common/index.js';
+export * from './component.js';
+export * from './controller.js';
+export * from './reporter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/health-check/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,5 @@
+export * from './common/index.js';
+export * from './component.js';
+export * from './controller.js';
+export * from './reporter.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/components/health-check/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC","sourcesContent":["export * from './common';\nexport * from './component';\nexport * from './controller';\nexport * from './reporter';\n"]}

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

@@ -0,0 +1,53 @@
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+export declare class MailDefaults {
+    static readonly BATCH_CONCURRENCY = 5;
+    static readonly FALLBACK_FROM = "noreply@example.com";
+    /** Bytes of attachment content one message may carry, all attachments together. */
+    static readonly MAX_ATTACHMENT_BYTES: number;
+}
+/** 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 declare class MailErrorCodes {
+    static readonly INVALID_CONFIGURATION: string;
+    static readonly SEND_FAILED: string;
+    static readonly VERIFICATION_FAILED: string;
+    static readonly INVALID_RECIPIENT: string;
+    static readonly BATCH_SEND_FAILED: string;
+    static readonly TEMPLATE_NOT_FOUND: string;
+    static readonly ATTACHMENT_PATH_REFUSED: string;
+    static readonly ATTACHMENT_TOO_LARGE: string;
+    static readonly BODY_SOURCE_REFUSED: string;
+}
+export declare class MailExecutorErrors {
+    static readonly PROCESSOR_NOT_SET = "Processor not set. Call setProcessor() first.";
+}
+export declare class MailQueueExecutorTypes {
+    static readonly DIRECT = "direct";
+    static readonly INTERNAL_QUEUE = "internal-queue";
+    static readonly BULLMQ = "bullmq";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export declare class BullMQExecutorModes {
+    static readonly QUEUE_ONLY = "queue-only";
+    static readonly WORKER_ONLY = "worker-only";
+    static readonly BOTH = "both";
+    static readonly MODE_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export declare class MailProviders {
+    static readonly NODEMAILER = "nodemailer";
+    static readonly MAILGUN = "mailgun";
+    static readonly CUSTOM = "custom";
+    static readonly AMAZON_SES = "amazon-ses";
+}
+export type TMailProvider = TConstValue<typeof MailProviders>;
+/** How the delay between two attempts to send a queued mail grows: FIXED stays the same, EXPONENTIAL doubles. */
+export declare class MailBackoffTypes {
+    static readonly FIXED = "fixed";
+    static readonly EXPONENTIAL = "exponential";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+/** Valid mail backoff type values. */
+export type TMailBackoffType = TConstValue<typeof MailBackoffTypes>;
+//# sourceMappingURL=constants.d.ts.map

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