@discover-cloud/shared 1.2.9 → 1.4.0

package/dist/utils/env.utils.js

@@ -1,61 +0,0 @@
-"use strict";
-/**
- * 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");
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getEnv = getEnv;
-exports.getEnvOptional = getEnvOptional;
-/**
- * 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).
- */
-function getEnv(name) {
-    const value = process.env[name];
-    if (!value) {
-        throw new Error(`Missing required environment variable: ${name}. ` +
-            `Ensure it is set in your .env file or deployment environment.`);
-    }
-    return value;
-}
-/**
- * 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.
- */
-function getEnvOptional(name) {
-    const value = process.env[name];
-    // Normalise empty string to undefined — same convention as getEnv.
-    return value === "" ? undefined : value;
-}

package/dist/utils/logger.utils.d.ts

@@ -1,66 +0,0 @@
-/**
- * LOGGER INTERFACE  (@discover-cloud/shared)
- * ────────────────────────────────────────────
- * A minimal logger contract that shared code can depend on.
- * Each service injects its own concrete implementation (pino, winston, etc.).
- *
- * Shared classes (RequireAuthMiddleware, PermissionCacheService, etc.)
- * accept ILogger via constructor injection — they never import a concrete
- * logger directly, keeping the shared package dependency-free.
- *
- * ─── Usage in shared classes ────────────────────────────────────────
- *   class RequireAuthMiddleware {
- *     constructor(
- *       private readonly verifier: InternalJwtVerifier,
- *       private readonly logger: ILogger = noopLogger,
- *     ) {}
- *   }
- *
- * ─── Wiring in each service ─────────────────────────────────────────
- *   import pino from "pino";
- *   const logger = pino({ level: "info" });
- *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, logger);
- *
- *   // pino satisfies ILogger — its method signatures are compatible.
- *
- * ─── Signature convention ───────────────────────────────────────────
- *   Follows pino's overloaded signature:
- *     logger.info({ userId }, "User logged in")  — object first, then message
- *     logger.info("Simple message")              — string only
- *
- *   This matches pino natively and means a pino instance can be passed
- *   directly without any wrapping.
- */
-export interface ILogger {
-    debug(obj: object, msg?: string): void;
-    debug(msg: string): void;
-    info(obj: object, msg?: string): void;
-    info(msg: string): void;
-    warn(obj: object, msg?: string): void;
-    warn(msg: string): void;
-    error(obj: object, msg?: string): void;
-    error(msg: string): void;
-}
-/**
- * noopLogger
- * Silent no-op implementation — the safe default when no logger is injected.
- * All log calls are discarded. Use in tests and library consumers that
- * don't want log noise.
- */
-export declare const noopLogger: ILogger;
-/**
- * consoleLogger
- * Thin console wrapper that follows the pino (obj, msg?) calling convention.
- * Useful for local development and simple services that don't need structured
- * logging — pass this instead of wiring up pino.
- *
- * Output order mirrors pino: message first, then the context object on a
- * separate argument so it appears as structured context in most terminals.
- *
- *   consoleLogger.info({ userId: "abc" }, "User logged in")
- *   → console.info("User logged in", { userId: "abc" })
- *
- *   consoleLogger.info("Simple message")
- *   → console.info("Simple message")
- */
-export declare const consoleLogger: ILogger;

package/dist/utils/logger.utils.js

@@ -1,97 +0,0 @@
-"use strict";
-/**
- * LOGGER INTERFACE  (@discover-cloud/shared)
- * ────────────────────────────────────────────
- * A minimal logger contract that shared code can depend on.
- * Each service injects its own concrete implementation (pino, winston, etc.).
- *
- * Shared classes (RequireAuthMiddleware, PermissionCacheService, etc.)
- * accept ILogger via constructor injection — they never import a concrete
- * logger directly, keeping the shared package dependency-free.
- *
- * ─── Usage in shared classes ────────────────────────────────────────
- *   class RequireAuthMiddleware {
- *     constructor(
- *       private readonly verifier: InternalJwtVerifier,
- *       private readonly logger: ILogger = noopLogger,
- *     ) {}
- *   }
- *
- * ─── Wiring in each service ─────────────────────────────────────────
- *   import pino from "pino";
- *   const logger = pino({ level: "info" });
- *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, logger);
- *
- *   // pino satisfies ILogger — its method signatures are compatible.
- *
- * ─── Signature convention ───────────────────────────────────────────
- *   Follows pino's overloaded signature:
- *     logger.info({ userId }, "User logged in")  — object first, then message
- *     logger.info("Simple message")              — string only
- *
- *   This matches pino natively and means a pino instance can be passed
- *   directly without any wrapping.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.consoleLogger = exports.noopLogger = void 0;
-/**
- * noopLogger
- * Silent no-op implementation — the safe default when no logger is injected.
- * All log calls are discarded. Use in tests and library consumers that
- * don't want log noise.
- */
-exports.noopLogger = {
-    debug: () => { },
-    info: () => { },
-    warn: () => { },
-    error: () => { },
-};
-/**
- * consoleLogger
- * Thin console wrapper that follows the pino (obj, msg?) calling convention.
- * Useful for local development and simple services that don't need structured
- * logging — pass this instead of wiring up pino.
- *
- * Output order mirrors pino: message first, then the context object on a
- * separate argument so it appears as structured context in most terminals.
- *
- *   consoleLogger.info({ userId: "abc" }, "User logged in")
- *   → console.info("User logged in", { userId: "abc" })
- *
- *   consoleLogger.info("Simple message")
- *   → console.info("Simple message")
- */
-exports.consoleLogger = {
-    debug: (objOrMsg, msg) => {
-        if (typeof objOrMsg === "string") {
-            console.debug(objOrMsg);
-        }
-        else {
-            console.debug(msg ?? "", objOrMsg);
-        }
-    },
-    info: (objOrMsg, msg) => {
-        if (typeof objOrMsg === "string") {
-            console.info(objOrMsg);
-        }
-        else {
-            console.info(msg ?? "", objOrMsg);
-        }
-    },
-    warn: (objOrMsg, msg) => {
-        if (typeof objOrMsg === "string") {
-            console.warn(objOrMsg);
-        }
-        else {
-            console.warn(msg ?? "", objOrMsg);
-        }
-    },
-    error: (objOrMsg, msg) => {
-        if (typeof objOrMsg === "string") {
-            console.error(objOrMsg);
-        }
-        else {
-            console.error(msg ?? "", objOrMsg);
-        }
-    },
-};

package/dist/utils/response.d.ts

@@ -1,4 +0,0 @@
-import { Response } from "express";
-export declare const success: <T>(res: Response, data: T, statusCode?: number) => Response<any, Record<string, any>>;
-export declare const failure: (res: Response, message: string, code: string, // <-- Added to match the DTO requirement
-statusCode?: number, details?: unknown) => Response<any, Record<string, any>>;

package/dist/utils/response.js

@@ -1,35 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.failure = exports.success = void 0;
-const success = (res, data, statusCode = 200) => {
-    // Cast to Request to access properties safely, assuming module augmentation
-    const req = res.req;
-    const response = {
-        success: true,
-        data,
-        meta: {
-            requestId: req.id ?? "unknown", // Fallback if middleware failed
-            timestamp: new Date().toISOString()
-        }
-    };
-    return res.status(statusCode).json(response);
-};
-exports.success = success;
-const failure = (res, message, code, // <-- Added to match the DTO requirement
-statusCode = 400, details) => {
-    const req = res.req;
-    const response = {
-        success: false,
-        error: {
-            code, // <-- Added here
-            message,
-            details: details ?? null
-        },
-        meta: {
-            requestId: req.id ?? "unknown",
-            timestamp: new Date().toISOString()
-        }
-    };
-    return res.status(statusCode).json(response);
-};
-exports.failure = failure;

package/dist/utils/response.utils.d.ts

@@ -1,54 +0,0 @@
-import { Response, Request } from "express";
-/**
- * RESPONSE HELPERS  (@discover-cloud/shared)
- * ────────────────────────────────────────────
- * Typed wrappers around res.json() that enforce the ApiSuccessResponse
- * and ApiErrorResponse envelope shapes across all services.
- *
- * Both helpers accept req explicitly rather than reading res.req — this
- * makes the dependency visible at the call site and avoids the res.req
- * cast anti-pattern.
- *
- * requestId fallback:
- *   req.id is set by requestId middleware. The randomUUID() fallback should
- *   never fire in a correctly wired service — if it does, it means requestId
- *   middleware was not registered before this helper was called. The fallback
- *   keeps the response well-formed but the generated ID won't correlate with
- *   any upstream trace. Check middleware registration order if you see UUIDs
- *   in responses that don't match the x-request-id header.
- */
-/**
- * success
- * Wraps data in an ApiSuccessResponse envelope and sends it.
- *
- * @param res        - Express response object
- * @param req        - Express request object (for requestId + timestamp)
- * @param data       - The response payload; typed as T for type inference
- * @param statusCode - HTTP status code (default 200)
- *
- * Usage:
- *   success<CloudAccountDto>(res, req, accountDto);
- *   success<PaginatedResponseDto<CloudAccountDto>>(res, req, paginatedResult, 200);
- *   success<MessageResponseDto>(res, req, { message: "Deleted" }, 200);
- */
-export declare const success: <T>(res: Response, req: Request, data: T, statusCode?: number) => void;
-/**
- * failure
- * Wraps an error in an ApiErrorResponse envelope and sends it.
- *
- * @param res        - Express response object
- * @param req        - Express request object (for requestId + timestamp)
- * @param message    - Human-readable error description
- * @param code       - Machine-readable error code (maps to AppError.code)
- * @param statusCode - HTTP status code (default 400)
- * @param details    - Optional structured context (e.g. Zod flatten() output).
- *                     Never put secrets, stack traces, or raw DB errors here.
- *
- * details is omitted from the response body when not provided — this avoids
- * "details": null noise in responses and keeps the shape clean for clients.
- *
- * Usage:
- *   failure(res, req, "Account not found", "NOT_FOUND", 404);
- *   failure(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
- */
-export declare const failure: (res: Response, req: Request, message: string, code: string, statusCode?: number, details?: unknown) => void;

package/dist/utils/response.utils.js

@@ -1,85 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.failure = exports.success = void 0;
-const crypto_1 = require("crypto");
-/**
- * RESPONSE HELPERS  (@discover-cloud/shared)
- * ────────────────────────────────────────────
- * Typed wrappers around res.json() that enforce the ApiSuccessResponse
- * and ApiErrorResponse envelope shapes across all services.
- *
- * Both helpers accept req explicitly rather than reading res.req — this
- * makes the dependency visible at the call site and avoids the res.req
- * cast anti-pattern.
- *
- * requestId fallback:
- *   req.id is set by requestId middleware. The randomUUID() fallback should
- *   never fire in a correctly wired service — if it does, it means requestId
- *   middleware was not registered before this helper was called. The fallback
- *   keeps the response well-formed but the generated ID won't correlate with
- *   any upstream trace. Check middleware registration order if you see UUIDs
- *   in responses that don't match the x-request-id header.
- */
-/**
- * success
- * Wraps data in an ApiSuccessResponse envelope and sends it.
- *
- * @param res        - Express response object
- * @param req        - Express request object (for requestId + timestamp)
- * @param data       - The response payload; typed as T for type inference
- * @param statusCode - HTTP status code (default 200)
- *
- * Usage:
- *   success<CloudAccountDto>(res, req, accountDto);
- *   success<PaginatedResponseDto<CloudAccountDto>>(res, req, paginatedResult, 200);
- *   success<MessageResponseDto>(res, req, { message: "Deleted" }, 200);
- */
-const success = (res, req, data, statusCode = 200) => {
-    const response = {
-        success: true,
-        data,
-        meta: {
-            requestId: req.id ?? (0, crypto_1.randomUUID)(),
-            timestamp: new Date().toISOString(),
-        },
-    };
-    res.status(statusCode).json(response);
-};
-exports.success = success;
-/**
- * failure
- * Wraps an error in an ApiErrorResponse envelope and sends it.
- *
- * @param res        - Express response object
- * @param req        - Express request object (for requestId + timestamp)
- * @param message    - Human-readable error description
- * @param code       - Machine-readable error code (maps to AppError.code)
- * @param statusCode - HTTP status code (default 400)
- * @param details    - Optional structured context (e.g. Zod flatten() output).
- *                     Never put secrets, stack traces, or raw DB errors here.
- *
- * details is omitted from the response body when not provided — this avoids
- * "details": null noise in responses and keeps the shape clean for clients.
- *
- * Usage:
- *   failure(res, req, "Account not found", "NOT_FOUND", 404);
- *   failure(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
- */
-const failure = (res, req, message, code, statusCode = 400, details) => {
-    const response = {
-        success: false,
-        error: {
-            code,
-            message,
-            // Spread details only when present — omitting the key entirely is
-            // cleaner than sending "details": undefined (which JSON.stringify drops anyway).
-            ...(details !== undefined ? { details } : {}),
-        },
-        meta: {
-            requestId: req.id ?? (0, crypto_1.randomUUID)(),
-            timestamp: new Date().toISOString(),
-        },
-    };
-    res.status(statusCode).json(response);
-};
-exports.failure = failure;