@discover-cloud/shared 1.0.11 → 1.2.1

package/dist/middleware/error-handler.middleware.d.ts

@@ -1,15 +1,29 @@
 import { Request, Response, NextFunction } from "express";
 /**
- * GLOBAL ERROR HANDLER
- * ─────────────────────
- * Centralized error handler for all Express services.
+ * GLOBAL ERROR HANDLER  (@discover-cloud/shared)
+ * ────────────────────────────────────────────────
+ * Centralised Express error handler. Register as the last middleware in
+ * every service's app.ts:
+ *
+ *   app.use(GlobalErrorHandler.handle);
  *
  * Handles in order:
- *   1. ZodError  → 400 with flattened validation details
- *   2. AppError  → mapped statusCode + code
- *   3. Unknown   → 500 Internal Server Error (internals never leaked)
+ *   1. ZodError  → 400 VALIDATION_ERROR with flattened field errors
+ *   2. AppError  → mapped statusCode + code (details forwarded to client)
+ *   3. Unknown   → 500 INTERNAL_SERVER_ERROR (internals never leaked)
+ *
+ * Logging strategy:
+ *   Development — full error object printed for stack traces during development.
+ *   Production  — message only for AppError/Error (no stack, no details in logs).
+ *                 Unknown errors log the raw value at warn level.
+ *                 In production, a structured logger (Pino) replaces console.*
+ *                 in each service — these console calls are captured by stdout.
  *
- * Every response includes requestId for traceability.
+ * Security:
+ *   Unknown (unexpected) errors never expose internals to the client.
+ *   AppError.details IS forwarded — callers that set details on an AppError
+ *   are intentionally choosing to surface that context (e.g. validation hints).
+ *   Never put secrets, stack traces, or raw DB errors in AppError.details.
  */
 export declare class GlobalErrorHandler {
     static handle(err: unknown, req: Request, res: Response, _next: NextFunction): void;

package/dist/middleware/error-handler.middleware.js

@@ -5,37 +5,65 @@ const zod_1 = require("zod");
 const errors_1 = require("../errors");
 const utils_1 = require("../utils");
 /**
- * GLOBAL ERROR HANDLER
- * ─────────────────────
- * Centralized error handler for all Express services.
+ * GLOBAL ERROR HANDLER  (@discover-cloud/shared)
+ * ────────────────────────────────────────────────
+ * Centralised Express error handler. Register as the last middleware in
+ * every service's app.ts:
+ *
+ *   app.use(GlobalErrorHandler.handle);
  *
  * Handles in order:
- *   1. ZodError  → 400 with flattened validation details
- *   2. AppError  → mapped statusCode + code
- *   3. Unknown   → 500 Internal Server Error (internals never leaked)
+ *   1. ZodError  → 400 VALIDATION_ERROR with flattened field errors
+ *   2. AppError  → mapped statusCode + code (details forwarded to client)
+ *   3. Unknown   → 500 INTERNAL_SERVER_ERROR (internals never leaked)
+ *
+ * Logging strategy:
+ *   Development — full error object printed for stack traces during development.
+ *   Production  — message only for AppError/Error (no stack, no details in logs).
+ *                 Unknown errors log the raw value at warn level.
+ *                 In production, a structured logger (Pino) replaces console.*
+ *                 in each service — these console calls are captured by stdout.
  *
- * Every response includes requestId for traceability.
+ * Security:
+ *   Unknown (unexpected) errors never expose internals to the client.
+ *   AppError.details IS forwarded — callers that set details on an AppError
+ *   are intentionally choosing to surface that context (e.g. validation hints).
+ *   Never put secrets, stack traces, or raw DB errors in AppError.details.
  */
 class GlobalErrorHandler {
     static handle(err, req, res, _next) {
-        if (process.env.NODE_ENV !== "production") {
+        // ── Logging ──────────────────────────────────────────────────────────
+        if (process.env["NODE_ENV"] !== "production") {
+            // Full object in development — stack traces + details are useful locally.
             console.error(`[req ${req.id}]`, err);
         }
+        else if (err instanceof Error) {
+            // Production: message only — no stack, no details, no internal paths.
+            console.error(`[req ${req.id}] ${err.name}: ${err.message}`);
+        }
         else {
-            console.error(`[req ${req.id}]`, err instanceof Error ? err.message : err);
+            // Non-Error throw (string, object, etc.) — log at warn; this should not happen.
+            console.warn(`[req ${req.id}] Non-Error thrown:`, typeof err);
         }
-        // 1. Zod validation errors
+        // ── 1. Zod validation errors ─────────────────────────────────────────
         if (err instanceof zod_1.ZodError) {
-            (0, utils_1.failure)(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten() // default flatten — preserves fieldErrors + formErrors + codes
-            );
+            // flatten() groups errors into fieldErrors (keyed by path) and formErrors
+            // (top-level). This shape is stable across Zod versions and is what
+            // clients should key on for field-level error display.
+            (0, utils_1.failure)(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
             return;
         }
-        // 2. Known AppError subclasses — instanceof, never duck-typing
+        // ── 2. Known AppError subclasses ─────────────────────────────────────
+        // instanceof check — no duck-typing, no accidental matches.
+        // AppError.details is caller-controlled context (e.g. validation hints)
+        // and is intentionally forwarded to the client.
         if (err instanceof errors_1.AppError) {
             (0, utils_1.failure)(res, req, err.message, err.code, err.statusCode, err.details);
             return;
         }
-        // 3. Unexpected errors — never leak internals to the client
+        // ── 3. Unexpected errors — never leak internals ───────────────────────
+        // Generic 500 with no details. The actual error is logged above (production:
+        // message only; development: full object). Nothing internal reaches the client.
         (0, utils_1.failure)(res, req, "Internal Server Error", "INTERNAL_SERVER_ERROR", 500);
     }
 }

package/dist/middleware/request-id.middleware.d.ts

@@ -1,20 +1,22 @@
 import { Request, Response, NextFunction } from "express";
 /**
- * REQUEST ID MIDDLEWARE
- * ──────────────────────
+ * REQUEST ID MIDDLEWARE  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────────
  * Attaches a unique request ID to req.id for distributed tracing.
+ * Register early in the middleware stack — before any logger or handler
+ * that needs to include the request ID in its output.
  *
  * Priority:
  *   1. x-request-id header forwarded by the API Gateway (or load balancer)
- *   2. Generate a new UUID if no upstream header is present
+ *   2. Newly generated UUID v4 if no upstream header is present
  *
- * Fix vs original:
- *   The original always generated a new UUID, breaking distributed tracing.
- *   If the gateway mints a requestId and forwards it via x-request-id,
- *   the downstream service must carry that same ID — otherwise logs across
- *   services cannot be correlated.
+ * Why forward the upstream header?
+ *   The gateway mints a requestId and stamps it on every internal request.
+ *   If downstream services generate their own IDs, the same logical request
+ *   carries different IDs in each service's logs, breaking cross-service
+ *   log correlation. Forwarding the upstream ID keeps the trace consistent.
  *
- * Also sets x-request-id on the response so clients and proxies can
- *   correlate their logs with the service's logs.
+ * The resolved ID is also echoed back on the response via x-request-id
+ * so clients and proxies can correlate their own logs with the service's.
  */
 export declare const requestId: (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/request-id.middleware.js

@@ -3,31 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestId = void 0;
 const crypto_1 = require("crypto");
 /**
- * REQUEST ID MIDDLEWARE
- * ──────────────────────
+ * REQUEST ID MIDDLEWARE  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────────
  * Attaches a unique request ID to req.id for distributed tracing.
+ * Register early in the middleware stack — before any logger or handler
+ * that needs to include the request ID in its output.
  *
  * Priority:
  *   1. x-request-id header forwarded by the API Gateway (or load balancer)
- *   2. Generate a new UUID if no upstream header is present
+ *   2. Newly generated UUID v4 if no upstream header is present
  *
- * Fix vs original:
- *   The original always generated a new UUID, breaking distributed tracing.
- *   If the gateway mints a requestId and forwards it via x-request-id,
- *   the downstream service must carry that same ID — otherwise logs across
- *   services cannot be correlated.
+ * Why forward the upstream header?
+ *   The gateway mints a requestId and stamps it on every internal request.
+ *   If downstream services generate their own IDs, the same logical request
+ *   carries different IDs in each service's logs, breaking cross-service
+ *   log correlation. Forwarding the upstream ID keeps the trace consistent.
  *
- * Also sets x-request-id on the response so clients and proxies can
- *   correlate their logs with the service's logs.
+ * The resolved ID is also echoed back on the response via x-request-id
+ * so clients and proxies can correlate their own logs with the service's.
  */
 const requestId = (req, res, next) => {
     const upstream = req.headers["x-request-id"];
-    // Header can technically be a string array (multi-value) — take the first
-    const id = Array.isArray(upstream)
-        ? upstream[0]
-        : upstream ?? (0, crypto_1.randomUUID)();
+    // Header can be a string array (multi-value header) — take the first value.
+    const id = Array.isArray(upstream) ? upstream[0] : (upstream ?? (0, crypto_1.randomUUID)());
     req.id = id;
-    // Echo back on the response for client-side correlation
+    // Echo back on the response for client-side and proxy-side correlation.
     res.setHeader("x-request-id", id);
     next();
 };

package/dist/middleware/validate.middleware.d.ts

@@ -1,25 +1,34 @@
 import { Request, Response, NextFunction } from "express";
 import { ZodType } from "zod";
 /**
- * VALIDATOR MIDDLEWARE
- * ─────────────────────
- * Validates and parses request input using a Zod schema.
- * On success, attaches the parsed data to req.validated.
- * On failure, passes a ZodError to GlobalErrorHandler → 400 response.
+ * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
+ * ────────────────────────────────────────────────
+ * Validates and parses request input against a Zod schema.
+ * On success, attaches the parsed (coerced + stripped) data to req.validated.
+ * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
  *
- * Changes vs original:
- *   - Added "headers" as a valid source (useful for API key / custom header validation)
- *   - req.validated typed as unknown — consumers must narrow via z.infer at route level
+ * Source options:
+ *   "body"    — req.body    (POST/PUT/PATCH payloads)
+ *   "params"  — req.params  (URL path parameters)
+ *   "query"   — req.query   (URL query string)
+ *   "headers" — req.headers (custom header validation, e.g. API keys)
+ *
+ * Narrowing req.validated in a controller:
+ *   req.validated is typed as unknown in express.d.ts — consumers must
+ *   narrow it to the schema's inferred type at the call site:
+ *
+ *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+ *
+ *   This is intentional: the middleware is schema-agnostic and cannot
+ *   carry the generic type through Express's untyped req object.
  *
  * Usage:
- *   router.post("/orders",
+ *   router.post(
+ *     "/orders",
  *     requireAuth,
  *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create
+ *     controller.create,
  *   );
- *
- *   // In controller:
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
  */
 export declare class Validator {
     static validate<T>(schema: ZodType<T>, source?: "body" | "params" | "query" | "headers"): (req: Request, _res: Response, next: NextFunction) => void;

package/dist/middleware/validate.middleware.js

@@ -2,37 +2,46 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Validator = void 0;
 /**
- * VALIDATOR MIDDLEWARE
- * ─────────────────────
- * Validates and parses request input using a Zod schema.
- * On success, attaches the parsed data to req.validated.
- * On failure, passes a ZodError to GlobalErrorHandler → 400 response.
+ * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
+ * ────────────────────────────────────────────────
+ * Validates and parses request input against a Zod schema.
+ * On success, attaches the parsed (coerced + stripped) data to req.validated.
+ * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
  *
- * Changes vs original:
- *   - Added "headers" as a valid source (useful for API key / custom header validation)
- *   - req.validated typed as unknown — consumers must narrow via z.infer at route level
+ * Source options:
+ *   "body"    — req.body    (POST/PUT/PATCH payloads)
+ *   "params"  — req.params  (URL path parameters)
+ *   "query"   — req.query   (URL query string)
+ *   "headers" — req.headers (custom header validation, e.g. API keys)
+ *
+ * Narrowing req.validated in a controller:
+ *   req.validated is typed as unknown in express.d.ts — consumers must
+ *   narrow it to the schema's inferred type at the call site:
+ *
+ *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+ *
+ *   This is intentional: the middleware is schema-agnostic and cannot
+ *   carry the generic type through Express's untyped req object.
  *
  * Usage:
- *   router.post("/orders",
+ *   router.post(
+ *     "/orders",
  *     requireAuth,
  *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create
+ *     controller.create,
  *   );
- *
- *   // In controller:
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
  */
 class Validator {
     static validate(schema, source = "body") {
         return (req, _res, next) => {
             const result = schema.safeParse(req[source]);
             if (!result.success) {
-                // ZodError propagates to GlobalErrorHandler → 400 with flatten()
+                // Pass the ZodError to GlobalErrorHandler — it flattens and returns 400.
                 next(result.error);
                 return;
             }
-            // req.validated typed as unknown in express.d.ts
-            // Narrow to your schema type at the route/controller level
+            // Attach the parsed data (coerced + unknown keys stripped by Zod).
+            // req.validated is typed as unknown — narrow to your schema type in the controller.
             req.validated = result.data;
             next();
         };

package/dist/middleware/validated-merge.middleware.js

@@ -19,8 +19,7 @@ exports.mergeValidated = exports.captureValidated = void 0;
  * enough. Casting to unknown first tells TypeScript we know what we're doing.
  */
 const captureValidated = (key, tempKey) => (req, _res, next) => {
-    req[tempKey] =
-        req.validated[key];
+    req[tempKey] = req.validated[key];
     next();
 };
 exports.captureValidated = captureValidated;

package/dist/types/express.types.d.ts

@@ -1,42 +1,47 @@
 /**
- * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
- * ───────────────────────────────────────────────
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES  (@discover-cloud/shared)
+ * ──────────────────────────────────────────────────────────────────────────
  * Single source of truth for everything attached to Express's Request object
  * and all internal JWT payload shapes.
  *
- * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ * Import in each service's entrypoint to activate the augmentation:
  *   import "@discover-cloud/shared/types/express";
  *
- * ─── Permission flow ────────────────────────────────────────────────
- *   JWT carries:        accountId + accountRole   (lean, no perms)
- *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
- *   AccessContext has:  perms                      (populated by auth middleware)
+ * ─── Permission flow ────────────────────────────────────────────────────
+ *   JWT carries:       accountId + accountRole    (lean payload, no perms)
+ *   Redis derives:     GlobalPermission[]          (role map on cache miss)
+ *   AccessContext has: perms                       (resolved by auth middleware)
  *
- *   perms never touch the JWT — they live in the permission cache and are
- *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ *   perms never touch the JWT — they live in the Redis permission cache and
+ *   are resolved into req.accessContext by RequireAuthMiddleware per request.
+ * ────────────────────────────────────────────────────────────────────────
  */
 import { JWTPayload } from "jose";
-import { AccountRole } from "../enums";
-import { GlobalPermission } from "../enums";
+import { AccountRole, GlobalPermission } from "../enums";
 interface BaseInternalJwtPayload extends JWTPayload {
     /**
-     * JWT ID — REQUIRED.
+     * JWT ID — required.
      * Used for the Redis kill-switch (session revocation / account suspension).
-     * Overrides JWTPayload's optional jti with required.
+     * Overrides JWTPayload's optional jti with a required string.
      */
     jti: string;
-    /** typ discriminator — guards against token type confusion attacks */
+    /**
+     * Token type discriminator — guards against token confusion attacks.
+     * InternalJwtVerifier rejects any token where typ !== "internal",
+     * even if it passes signature verification.
+     */
     typ: "internal";
     /**
      * The entity that last minted or forwarded this token.
-     *   "api-gateway"   → direct user-initiated request
-     *   "order-service" → service-to-service call on behalf of a user
+     *   "api-gateway"        → direct user-initiated request
+     *   "notification-service" → service-to-service call on behalf of a user
      * Used for audit logging and conditional authorization.
      */
     caller: string;
     /**
      * Propagated request ID for distributed tracing.
      * Ties together logs across the entire service call chain.
+     * Set by the gateway from the incoming x-request-id header.
      */
     requestId?: string;
     iss: string;
@@ -46,11 +51,10 @@ interface BaseInternalJwtPayload extends JWTPayload {
     nbf: number;
 }
 /**
- * Human JWT payload — issued on behalf of an authenticated user.
- * Minted by the gateway after verifying an external JWT.
- *
- * accountRole is carried so the permission cache can derive perms
- * from globalRolePermissions on a cold cache miss — without a DB call.
+ * HumanInternalJwtPayload
+ * Issued on behalf of an authenticated user after external JWT verification.
+ * accountRole is carried so the permission cache can derive perms from
+ * globalRolePermissions on a cold cache miss — without a DB call.
  */
 export interface HumanInternalJwtPayload extends BaseInternalJwtPayload {
     isMachine: false;
@@ -59,14 +63,15 @@ export interface HumanInternalJwtPayload extends BaseInternalJwtPayload {
     externalJti?: string;
 }
 /**
- * Machine JWT payload — service-to-service calls with no user context.
- * Intentionally carries NO user fields — absence is enforced by the type.
+ * MachineInternalJwtPayload
+ * Issued for service-to-service calls with no user context.
+ * Intentionally carries no user fields — their absence is enforced by the type.
  */
 export interface MachineInternalJwtPayload extends BaseInternalJwtPayload {
     isMachine: true;
     serviceId: string;
 }
-/** The full internal JWT payload union — use this in verifiers and auth middleware */
+/** Full internal JWT payload union — use in verifiers and auth middleware */
 export type InternalJwtPayload = HumanInternalJwtPayload | MachineInternalJwtPayload;
 export interface HumanAccessContext {
     kind: "human";
@@ -74,7 +79,7 @@ export interface HumanAccessContext {
     accountRole: AccountRole;
     /**
      * Resolved from Redis permission cache — NOT from the JWT.
-     * Always present by the time req.accessContext is set.
+     * Always present by the time req.accessContext is populated.
      * Invalidated on role change, suspension, and account deletion.
      */
     perms: GlobalPermission[];
@@ -113,13 +118,13 @@ declare module "express-serve-static-core" {
     interface Request {
         /**
          * Unique request ID — set by requestId middleware.
-         * Respects upstream x-request-id from the gateway / load balancer.
+         * Respects upstream x-request-id forwarded by the gateway / load balancer.
          * Always present after requestId middleware runs.
          */
         id: string;
         /**
-         * Validated + parsed request body/query/params/headers.
-         * Typed as unknown — narrow at the route level:
+         * Validated + parsed request input (body / params / query / headers).
+         * Typed as unknown — narrow at the route level using z.infer:
          *
          *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
          *
@@ -130,13 +135,13 @@ declare module "express-serve-static-core" {
          * Raw verified internal JWT payload.
          * Set by RequireAuthMiddleware after InternalJwtVerifier.verifyInternal().
          *
-         * Prefer req.accessContext in route handlers.
-         * Access this only when you need raw JWT claims (e.g. jti for blacklisting).
+         * Prefer req.accessContext in route handlers and controllers.
+         * Access internalAuth only when you need raw JWT claims (e.g. jti).
          */
         internalAuth?: InternalJwtPayload;
         /**
-         * Clean access context — built from internalAuth + permission cache.
-         * This is what route handlers, controllers, and domain services use.
+         * Clean access context — built from internalAuth + Redis permission cache.
+         * This is what route handlers, controllers, and domain services consume.
          *
          *   if (isHumanContext(req.accessContext)) {
          *     const { accountId, accountRole, perms } = req.accessContext;

package/dist/types/express.types.js

@@ -1,20 +1,21 @@
 "use strict";
 /**
- * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
- * ───────────────────────────────────────────────
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES  (@discover-cloud/shared)
+ * ──────────────────────────────────────────────────────────────────────────
  * Single source of truth for everything attached to Express's Request object
  * and all internal JWT payload shapes.
  *
- * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ * Import in each service's entrypoint to activate the augmentation:
  *   import "@discover-cloud/shared/types/express";
  *
- * ─── Permission flow ────────────────────────────────────────────────
- *   JWT carries:        accountId + accountRole   (lean, no perms)
- *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
- *   AccessContext has:  perms                      (populated by auth middleware)
+ * ─── Permission flow ────────────────────────────────────────────────────
+ *   JWT carries:       accountId + accountRole    (lean payload, no perms)
+ *   Redis derives:     GlobalPermission[]          (role map on cache miss)
+ *   AccessContext has: perms                       (resolved by auth middleware)
  *
- *   perms never touch the JWT — they live in the permission cache and are
- *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ *   perms never touch the JWT — they live in the Redis permission cache and
+ *   are resolved into req.accessContext by RequireAuthMiddleware per request.
+ * ────────────────────────────────────────────────────────────────────────
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isHumanPayload = isHumanPayload;
@@ -24,8 +25,9 @@ exports.isMachineContext = isMachineContext;
 /* ====================================================================
    4. TYPE GUARDS
 
-   Use these over raw property checks — TypeScript narrows correctly
-   through them on both InternalJwtPayload and AccessContext.
+   Use these over raw property checks — TypeScript narrows the union
+   correctly through predicate functions on both InternalJwtPayload
+   and AccessContext.
 ==================================================================== */
 function isHumanPayload(payload) {
     return payload.isMachine === false;

package/dist/utils/date.utils.d.ts

@@ -1,11 +1,25 @@
 /**
- * DATE SERIALIZATION UTILS
- * ─────────────────────────
+ * DATE SERIALIZATION UTILS  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────────────
  * Converts Date objects to ISO 8601 strings for HTTP responses.
  * Use these in toDto() mappers — never call .toISOString() inline.
  *
- * Why: DTOs cross HTTP boundaries where JSON has no Date type.
- * Domain models keep Date internally; these helpers handle the boundary.
+ * Why centralise this?
+ *   DTOs cross HTTP boundaries where JSON has no Date type. Domain models
+ *   keep Date objects internally; these helpers handle the conversion at
+ *   the boundary in a single consistent place. If the serialisation format
+ *   ever needs to change (e.g. add milliseconds truncation, force UTC
+ *   suffix), there is one place to update.
+ */
+/**
+ * toIso
+ * Converts a Date to an ISO 8601 string.
+ * Use for non-nullable timestamp fields in DTOs.
  */
 export declare const toIso: (date: Date) => string;
+/**
+ * toIsoOrNull
+ * Converts a Date to an ISO 8601 string, or returns null if the value
+ * is absent. Use for nullable timestamp fields (e.g. revokedAt, deletedAt).
+ */
 export declare const toIsoOrNull: (date: Date | null | undefined) => string | null;

package/dist/utils/date.utils.js

@@ -1,16 +1,30 @@
 "use strict";
 /**
- * DATE SERIALIZATION UTILS
- * ─────────────────────────
+ * DATE SERIALIZATION UTILS  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────────────
  * Converts Date objects to ISO 8601 strings for HTTP responses.
  * Use these in toDto() mappers — never call .toISOString() inline.
  *
- * Why: DTOs cross HTTP boundaries where JSON has no Date type.
- * Domain models keep Date internally; these helpers handle the boundary.
+ * Why centralise this?
+ *   DTOs cross HTTP boundaries where JSON has no Date type. Domain models
+ *   keep Date objects internally; these helpers handle the conversion at
+ *   the boundary in a single consistent place. If the serialisation format
+ *   ever needs to change (e.g. add milliseconds truncation, force UTC
+ *   suffix), there is one place to update.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toIsoOrNull = exports.toIso = void 0;
+/**
+ * toIso
+ * Converts a Date to an ISO 8601 string.
+ * Use for non-nullable timestamp fields in DTOs.
+ */
 const toIso = (date) => date.toISOString();
 exports.toIso = toIso;
+/**
+ * toIsoOrNull
+ * Converts a Date to an ISO 8601 string, or returns null if the value
+ * is absent. Use for nullable timestamp fields (e.g. revokedAt, deletedAt).
+ */
 const toIsoOrNull = (date) => date ? date.toISOString() : null;
 exports.toIsoOrNull = toIsoOrNull;

package/dist/utils/env.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ENVIRONMENT HELPERS  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────
+ * Typed accessors for process.env values.
+ *
+ * Why not read process.env directly?
+ *   - process.env values are always string | undefined. Reading them inline
+ *     forces every callsite to handle undefined or cast — this pushes that
+ *     contract to one place.
+ *   - getEnv() fails fast at startup (before serving any traffic) if a
+ *     required variable is absent, surfacing misconfiguration immediately
+ *     rather than at runtime inside a request handler.
+ *   - Centralised access makes it straightforward to add validation, type
+ *     coercion, or secret-redaction logic later without touching callsites.
+ *
+ * Usage:
+ *   // Required — throws at startup if missing
+ *   const dbUrl     = getEnv("DATABASE_URL");
+ *   const jwtSecret = getEnv("JWT_SECRET");
+ *
+ *   // Optional — returns undefined (or a typed default) when absent
+ *   const logLevel  = getEnvOptional("LOG_LEVEL") ?? "info";
+ *   const port      = Number(getEnvOptional("PORT") ?? "3000");
+ */
+/**
+ * getEnv
+ * Returns the value of a required environment variable.
+ * Throws at call time (typically during service startup) if the variable
+ * is absent or empty — this is intentional: missing required config should
+ * crash the process before it begins serving traffic.
+ *
+ * Empty string ("") is treated as missing because it is almost always an
+ * accidental misconfiguration (e.g. `SECRET=` with no value in a .env file).
+ */
+export declare function getEnv(name: string): string;
+/**
+ * getEnvOptional
+ * Returns the value of an optional environment variable, or undefined
+ * if it is absent or empty. Use with a nullish coalescing default:
+ *
+ *   const logLevel = getEnvOptional("LOG_LEVEL") ?? "info";
+ *
+ * Returns undefined (not empty string) so callers can safely use `??`
+ * and `||` without needing to guard against empty strings separately.
+ */
+export declare function getEnvOptional(name: string): string | undefined;