@zintrust/core 2.4.1 → 2.4.2

package/src/common/AwsSigV4.js

@@ -0,0 +1,69 @@
+import { createHash, createHmac } from '../node-singletons/crypto.js';
+export const AwsSigV4 = Object.freeze({
+    sha256Hex(data) {
+        return createHash('sha256').update(data).digest('hex');
+    },
+    hmacSha256(key, data) {
+        return createHmac('sha256', key).update(data).digest();
+    },
+    toAmzDate(date) {
+        const yyyy = String(date.getUTCFullYear());
+        const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+        const dd = String(date.getUTCDate()).padStart(2, '0');
+        const hh = String(date.getUTCHours()).padStart(2, '0');
+        const mi = String(date.getUTCMinutes()).padStart(2, '0');
+        const ss = String(date.getUTCSeconds()).padStart(2, '0');
+        const dateStamp = `${yyyy}${mm}${dd}`;
+        const amzDate = `${dateStamp}T${hh}${mi}${ss}Z`;
+        return { amzDate, dateStamp };
+    },
+    deriveSigningKey(params) {
+        const kDate = this.hmacSha256(`AWS4${params.secretAccessKey}`, params.dateStamp);
+        const kRegion = this.hmacSha256(kDate, params.region);
+        const kService = this.hmacSha256(kRegion, params.service);
+        return this.hmacSha256(kService, 'aws4_request');
+    },
+    canonicalizeHeaders(headers) {
+        const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+        const canonicalHeaders = sortedHeaderKeys
+            .map((k) => `${k}:${String(headers[k]).trim().replaceAll(/\s+/g, ' ')}`)
+            .join('\n');
+        const signedHeaders = sortedHeaderKeys.join(';');
+        return { canonicalHeaders, signedHeaders };
+    },
+    buildAuthorization(params) {
+        const sessionToken = params.credentials.sessionToken;
+        if (typeof sessionToken === 'string' &&
+            sessionToken.trim() !== '' &&
+            params.headers['x-amz-security-token'] === undefined) {
+            params.headers['x-amz-security-token'] = sessionToken;
+        }
+        const { canonicalHeaders, signedHeaders } = this.canonicalizeHeaders(params.headers);
+        const canonicalRequest = [
+            params.method,
+            params.canonicalUri,
+            params.canonicalQueryString,
+            `${canonicalHeaders}\n`,
+            signedHeaders,
+            params.payloadHash,
+        ].join('\n');
+        const algorithm = 'AWS4-HMAC-SHA256';
+        const credentialScope = `${params.dateStamp}/${params.region}/${params.service}/aws4_request`;
+        const stringToSign = [
+            algorithm,
+            params.amzDate,
+            credentialScope,
+            this.sha256Hex(canonicalRequest),
+        ].join('\n');
+        const signingKey = this.deriveSigningKey({
+            secretAccessKey: params.credentials.secretAccessKey,
+            dateStamp: params.dateStamp,
+            region: params.region,
+            service: params.service,
+        });
+        const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+        const authorization = `${algorithm} Credential=${params.credentials.accessKeyId}/${credentialScope}, ` +
+            `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+        return { authorization, signedHeaders };
+    },
+});

package/src/common/ContextLoader.d.ts

@@ -0,0 +1,27 @@
+export type ContextLoaderBatchKey = string | number;
+export type ContextLoaderMode = 'sequential' | 'batch';
+export type ContextLoaderContext = Record<string, unknown>;
+export type ContextLoaderResolver<TValue = unknown, TContext extends ContextLoaderContext = ContextLoaderContext> = (context: Readonly<TContext>) => Promise<TValue>;
+export type ContextLoaderBatchResult<TKey extends ContextLoaderBatchKey = ContextLoaderBatchKey> = Map<TKey, unknown> | Record<string, unknown> | null | undefined;
+export type ContextLoaderBatchHandler<TKey extends ContextLoaderBatchKey = ContextLoaderBatchKey> = (keys: TKey[]) => Promise<ContextLoaderBatchResult<TKey>>;
+export type ContextLoaderPlan = {
+    load: <TValue = unknown>(key: string, resolver: ContextLoaderResolver<TValue>) => ContextLoaderPlan;
+    fromBatch: <TKey extends ContextLoaderBatchKey = ContextLoaderBatchKey>(name: string, key: TKey) => Promise<unknown>;
+    resolve: <TResolved extends ContextLoaderContext = ContextLoaderContext>() => Promise<Readonly<TResolved>>;
+};
+export type ContextLoaderInstance = {
+    load: <TValue = unknown>(key: string, resolver: ContextLoaderResolver<TValue>) => ContextLoaderPlan;
+    batch: (name: string, handler: ContextLoaderBatchHandler) => ContextLoaderInstance;
+    fromBatch: (name: string, key: ContextLoaderBatchKey) => Promise<unknown>;
+    hasBatch: (name: string) => boolean;
+    listBatches: () => string[];
+    unregisterBatch: (name: string) => void;
+    clearBatches: () => void;
+};
+export type ContextLoaderNamespace = {
+    create: (options?: {
+        mode?: ContextLoaderMode;
+    }) => ContextLoaderInstance;
+};
+export declare const ContextLoader: ContextLoaderNamespace;
+//# sourceMappingURL=ContextLoader.d.ts.map

package/src/common/ContextLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextLoader.d.ts","sourceRoot":"","sources":["../../../src/common/ContextLoader.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,CAAC;AACpD,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3D,MAAM,MAAM,qBAAqB,CAC/B,MAAM,GAAG,OAAO,EAChB,QAAQ,SAAS,oBAAoB,GAAG,oBAAoB,IAC1D,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,MAAM,wBAAwB,CAAC,IAAI,SAAS,qBAAqB,GAAG,qBAAqB,IAC3F,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,IAAI,GACJ,SAAS,CAAC;AAEd,MAAM,MAAM,yBAAyB,CAAC,IAAI,SAAS,qBAAqB,GAAG,qBAAqB,IAC9F,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,CAAC,MAAM,GAAG,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,qBAAqB,CAAC,MAAM,CAAC,KACpC,iBAAiB,CAAC;IACvB,SAAS,EAAE,CAAC,IAAI,SAAS,qBAAqB,GAAG,qBAAqB,EACpE,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,KACN,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,SAAS,SAAS,oBAAoB,GAAG,oBAAoB,OAAO,OAAO,CACnF,QAAQ,CAAC,SAAS,CAAC,CACpB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,CAAC,MAAM,GAAG,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,qBAAqB,CAAC,MAAM,CAAC,KACpC,iBAAiB,CAAC;IACvB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,KAAK,qBAAqB,CAAC;IACnF,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,WAAW,EAAE,MAAM,MAAM,EAAE,CAAC;IAC5B,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,iBAAiB,CAAA;KAAE,KAAK,qBAAqB,CAAC;CAC3E,CAAC;AAmQF,eAAO,MAAM,aAAa,EAAE,sBAE1B,CAAC"}

package/src/common/ContextLoader.js

@@ -0,0 +1,187 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { isFunction, isNonEmptyString, isObject } from '../helper/index.js';
+const scheduleMicrotask = (task) => {
+    if (typeof globalThis.queueMicrotask === 'function') {
+        globalThis.queueMicrotask(task);
+        return;
+    }
+    void Promise.resolve().then(task);
+};
+const normalizeBatchName = (name) => {
+    const normalized = String(name ?? '')
+        .trim()
+        .toLowerCase();
+    if (!isNonEmptyString(normalized)) {
+        throw ErrorFactory.createValidationError('ContextLoader batch name must be a non-empty string');
+    }
+    return normalized;
+};
+const normalizeLoadKey = (key) => {
+    const normalized = String(key ?? '').trim();
+    if (!isNonEmptyString(normalized)) {
+        throw ErrorFactory.createValidationError('ContextLoader load key must be a non-empty string');
+    }
+    return normalized;
+};
+const assertBatchKey = (key) => {
+    if (typeof key === 'string' && key.trim() !== '') {
+        return;
+    }
+    if (typeof key === 'number' && Number.isFinite(key)) {
+        return;
+    }
+    throw ErrorFactory.createValidationError('ContextLoader batch key must be a non-empty string or finite number');
+};
+const extractBatchValue = (result, key) => {
+    if (result instanceof Map) {
+        return result.has(key) ? (result.get(key) ?? null) : null;
+    }
+    if (isObject(result)) {
+        const recordKey = typeof key === 'number' ? String(key) : key;
+        return recordKey in result ? (result[recordKey] ?? null) : null;
+    }
+    return null;
+};
+const dedupeBatchKeys = (requests) => {
+    const seen = new Set();
+    const keys = [];
+    for (const request of requests) {
+        const signature = `${typeof request.key}:${String(request.key)}`;
+        if (seen.has(signature)) {
+            continue;
+        }
+        seen.add(signature);
+        keys.push(request.key);
+    }
+    return keys;
+};
+const freezeContext = (context) => {
+    return Object.freeze({ ...context });
+};
+const executePlanSteps = async (steps) => {
+    const resolved = await steps.reduce(async (accPromise, step) => {
+        const accumulated = await accPromise;
+        const snapshot = freezeContext(accumulated);
+        return {
+            ...accumulated,
+            [step.key]: await step.resolver(snapshot),
+        };
+    }, Promise.resolve({}));
+    return freezeContext(resolved);
+};
+const createFlushBatch = (batchHandlers, batchQueues) => {
+    return async (name) => {
+        const queue = batchQueues.get(name);
+        const handler = batchHandlers.get(name);
+        if (!queue || !handler) {
+            return;
+        }
+        const requests = queue.requests.splice(0);
+        queue.scheduled = false;
+        if (requests.length === 0) {
+            return;
+        }
+        try {
+            const keys = dedupeBatchKeys(requests);
+            const result = await handler(keys);
+            for (const request of requests) {
+                request.resolve(extractBatchValue(result, request.key));
+            }
+        }
+        catch (error) {
+            for (const request of requests) {
+                request.reject(error);
+            }
+        }
+    };
+};
+const createSequentialBatchPromise = async (handler, key) => {
+    return handler([key]).then((result) => extractBatchValue(result, key));
+};
+const createPlan = (root, steps) => {
+    let resolvePromise = null;
+    const plan = Object.freeze({
+        load(key, resolver) {
+            const normalizedKey = normalizeLoadKey(key);
+            if (!isFunction(resolver)) {
+                throw ErrorFactory.createValidationError('ContextLoader resolver must be a function');
+            }
+            if (steps.some((step) => step.key === normalizedKey)) {
+                throw ErrorFactory.createValidationError(`ContextLoader key already registered: ${normalizedKey}`);
+            }
+            return createPlan(root, [...steps, { key: normalizedKey, resolver }]);
+        },
+        async fromBatch(name, key) {
+            return root.fromBatch(name, key);
+        },
+        async resolve() {
+            resolvePromise ??= executePlanSteps(steps);
+            return resolvePromise;
+        },
+    });
+    return plan;
+};
+const create = (options = {}) => {
+    const mode = options.mode ?? 'sequential';
+    const batchHandlers = new Map();
+    const batchQueues = new Map();
+    const flushBatch = createFlushBatch(batchHandlers, batchQueues);
+    const root = Object.freeze({
+        load(key, resolver) {
+            const normalizedKey = normalizeLoadKey(key);
+            if (!isFunction(resolver)) {
+                throw ErrorFactory.createValidationError('ContextLoader resolver must be a function');
+            }
+            return createPlan(root, [{ key: normalizedKey, resolver }]);
+        },
+        batch(name, handler) {
+            const normalizedName = normalizeBatchName(name);
+            if (!isFunction(handler)) {
+                throw ErrorFactory.createValidationError('ContextLoader batch handler must be a function');
+            }
+            batchHandlers.set(normalizedName, handler);
+            return this;
+        },
+        async fromBatch(name, key) {
+            const normalizedName = normalizeBatchName(name);
+            assertBatchKey(key);
+            const handler = batchHandlers.get(normalizedName);
+            if (!handler) {
+                throw ErrorFactory.createConfigError(`ContextLoader batch not registered: ${normalizedName}`);
+            }
+            if (mode === 'sequential') {
+                return createSequentialBatchPromise(handler, key);
+            }
+            return new Promise((resolve, reject) => {
+                const queue = batchQueues.get(normalizedName) ?? { requests: [], scheduled: false };
+                queue.requests.push({ key, resolve, reject });
+                batchQueues.set(normalizedName, queue);
+                if (!queue.scheduled) {
+                    queue.scheduled = true;
+                    scheduleMicrotask(() => {
+                        void flushBatch(normalizedName);
+                    });
+                }
+            });
+        },
+        hasBatch(name) {
+            return batchHandlers.has(normalizeBatchName(name));
+        },
+        listBatches() {
+            return Array.from(batchHandlers.keys()).sort((left, right) => left.localeCompare(right));
+        },
+        unregisterBatch(name) {
+            const normalizedName = normalizeBatchName(name);
+            batchHandlers.delete(normalizedName);
+            batchQueues.delete(normalizedName);
+        },
+        clearBatches() {
+            batchHandlers.clear();
+            batchQueues.clear();
+        },
+    });
+    return root;
+};
+export const ContextLoader = Object.freeze({
+    create,
+});

package/src/common/ExternalServiceUtils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared Utilities for External Service Drivers
+ * Common patterns for API calls, environment variable reading, and error handling
+ */
+export type TracedFetchTraceOptions = {
+    source?: string;
+};
+/**
+ * Environment variable reader with fallback support
+ * Handles both Env.get() and process.env for maximum compatibility
+ */
+export declare const readEnvString: (key: string, fallback?: string) => string;
+/**
+ * Validate required parameters for external service calls
+ */
+export declare const validateRequiredParams: (params: Record<string, unknown>, required: string[]) => void;
+/**
+ * Create standardized API error response
+ */
+export declare const createApiError: (message: string, service: string) => Error;
+export declare const tracedFetch: (url: string, options: RequestInit, trace?: TracedFetchTraceOptions) => Promise<Response>;
+/**
+ * Common fetch wrapper with error handling
+ */
+export declare const safeFetch: (url: string, options: RequestInit, trace?: TracedFetchTraceOptions) => Promise<Response>;
+/**
+ * Standard API response builder
+ */
+export declare const buildApiResponse: <T>(success: boolean, data?: T, error?: string) => {
+    success: boolean;
+    data?: T;
+    error?: string;
+};
+/**
+ * Health check utilities
+ */
+export declare const HealthUtils: {
+    /**
+     * Get process uptime safely
+     */
+    getUptime(): number;
+    /**
+     * Get current timestamp
+     */
+    getTimestamp(): string;
+    /**
+     * Check if in production
+     */
+    isProduction(environment: string): boolean;
+    /**
+     * Build health response
+     */
+    buildHealthResponse(status: "healthy" | "unhealthy" | "alive" | "ready" | "not_ready", environment: string, extra?: Record<string, unknown>): {
+        status: "ready" | "healthy" | "unhealthy" | "alive" | "not_ready";
+        timestamp: string;
+        environment: string;
+    };
+    /**
+     * Build error health response
+     */
+    buildErrorResponse(status: "unhealthy" | "not_ready", environment: string, error: Error, extra?: Record<string, unknown>): {
+        status: "ready" | "healthy" | "unhealthy" | "alive" | "not_ready";
+        timestamp: string;
+        environment: string;
+    };
+};
+//# sourceMappingURL=ExternalServiceUtils.d.ts.map

package/src/common/ExternalServiceUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalServiceUtils.d.ts","sourceRoot":"","sources":["../../../src/common/ExternalServiceUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAkHF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,EAAE,iBAAa,KAAG,MAe1D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,MAAM,EAAE,KACjB,IAWF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,KAEjE,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,KAAK,MAAM,EACX,SAAS,WAAW,EACpB,QAAQ,uBAAuB,KAC9B,OAAO,CAAC,QAAQ,CAWlB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,SAAS,WAAW,EACpB,QAAQ,uBAAuB,KAC9B,OAAO,CAAC,QAAQ,CAclB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAChC,SAAS,OAAO,EAChB,OAAO,CAAC,EACR,QAAQ,MAAM,KACb;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAY9C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;iBACU,MAAM;IAMnB;;OAEG;oBACa,MAAM;IAItB;;OAEG;8BACuB,MAAM,GAAG,OAAO;IAI1C;;OAEG;gCAEO,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,WAAW,eACpD,MAAM,UACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;IAYjC;;OAEG;+BAEO,WAAW,GAAG,WAAW,eACpB,MAAM,SACZ,KAAK,UACJ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;CASlC,CAAC"}

package/src/common/ExternalServiceUtils.js

@@ -0,0 +1,217 @@
+/**
+ * Shared Utilities for External Service Drivers
+ * Common patterns for API calls, environment variable reading, and error handling
+ */
+import { SystemTraceBridge } from '../trace/SystemTraceBridge.js';
+import { Env } from '../config/env.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const isHeaderEntriesLike = (value) => {
+    return typeof value === 'object' && value !== null && 'entries' in value;
+};
+const isHeaderTuple = (value) => {
+    return (Array.isArray(value) &&
+        value.length === 2 &&
+        typeof value[0] === 'string' &&
+        typeof value[1] === 'string');
+};
+const isHeaderTupleArray = (value) => {
+    return Array.isArray(value) && value.every(isHeaderTuple);
+};
+const asHeadersInitLocal = (headers) => {
+    return headers;
+};
+const asBodyInitLocal = (body) => {
+    return body;
+};
+const headersToRecord = (headers) => {
+    if (headers === undefined)
+        return {};
+    if (headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (isHeaderEntriesLike(headers)) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (isHeaderTupleArray(headers)) {
+        return Object.fromEntries(headers);
+    }
+    return Object.fromEntries(Object.entries(headers).filter((entry) => typeof entry[1] === 'string'));
+};
+const bodyToTracePayload = (body) => {
+    if (body === null || body === undefined)
+        return undefined;
+    if (typeof body === 'string') {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    if (body instanceof URLSearchParams) {
+        return body.toString();
+    }
+    if (typeof FormData !== 'undefined' &&
+        body instanceof FormData &&
+        typeof body.entries === 'function') {
+        return Array.from(body.entries()).map(([key, value]) => [key, String(value)]);
+    }
+    return '[stream]';
+};
+const captureResponseBody = async (response) => {
+    try {
+        return await response.clone().text();
+    }
+    catch {
+        return undefined;
+    }
+};
+const emitTrace = async (url, options, trace, duration, response, error) => {
+    const responseBody = response ? await captureResponseBody(response) : undefined;
+    let traceError;
+    if (error instanceof Error) {
+        traceError = error.message;
+    }
+    else if (error !== undefined) {
+        traceError = String(error);
+    }
+    SystemTraceBridge.emitHttpClient({
+        source: trace?.source,
+        method: String(options.method ?? 'GET').toUpperCase(),
+        url,
+        requestHeaders: headersToRecord(asHeadersInitLocal(options.headers)),
+        responseStatus: response?.status,
+        duration,
+        requestBody: bodyToTracePayload(asBodyInitLocal(options.body)),
+        responseHeaders: headersToRecord(response?.headers),
+        responseBody,
+        error: traceError,
+    });
+};
+/**
+ * Environment variable reader with fallback support
+ * Handles both Env.get() and process.env for maximum compatibility
+ */
+export const readEnvString = (key, fallback = '') => {
+    const anyEnv = Env;
+    const fromEnv = typeof anyEnv.get === 'function' ? anyEnv.get(key, '') : '';
+    if (typeof fromEnv === 'string' && fromEnv.trim() !== '') {
+        return fromEnv;
+    }
+    const getEnv = anyEnv[key];
+    if (typeof getEnv === 'string' && getEnv.trim() !== '') {
+        return getEnv;
+    }
+    if (typeof process !== 'undefined') {
+        const raw = process.env?.[key];
+        if (typeof raw === 'string')
+            return raw;
+    }
+    return fallback;
+};
+/**
+ * Validate required parameters for external service calls
+ */
+export const validateRequiredParams = (params, required) => {
+    for (const param of required) {
+        const value = params[param];
+        if (value === null ||
+            value === undefined ||
+            (typeof value === 'string' && value.length === 0)) {
+            throw ErrorFactory.createValidationError(`${param} is required`);
+        }
+    }
+};
+/**
+ * Create standardized API error response
+ */
+export const createApiError = (message, service) => {
+    return ErrorFactory.createValidationError(`${service} API error: ${message}`);
+};
+export const tracedFetch = async (url, options, trace) => {
+    const startTime = Date.now();
+    try {
+        const response = await globalThis.fetch(url, options);
+        await emitTrace(url, options, trace, Date.now() - startTime, response);
+        return response;
+    }
+    catch (error) {
+        await emitTrace(url, options, trace, Date.now() - startTime, undefined, error);
+        throw error;
+    }
+};
+/**
+ * Common fetch wrapper with error handling
+ */
+export const safeFetch = async (url, options, trace) => {
+    try {
+        const response = await tracedFetch(url, options, trace);
+        if (!response.ok) {
+            throw ErrorFactory.createValidationError(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return response;
+    }
+    catch (error) {
+        throw ErrorFactory.createValidationError(error instanceof Error ? error.message : 'Unknown fetch error');
+    }
+};
+/**
+ * Standard API response builder
+ */
+export const buildApiResponse = (success, data, error) => {
+    const response = { success };
+    if (data !== undefined) {
+        response.data = data;
+    }
+    if (error !== undefined) {
+        response.error = error;
+    }
+    return response;
+};
+/**
+ * Health check utilities
+ */
+export const HealthUtils = {
+    /**
+     * Get process uptime safely
+     */
+    getUptime() {
+        return typeof process !== 'undefined' && typeof process.uptime === 'function'
+            ? process.uptime()
+            : 0;
+    },
+    /**
+     * Get current timestamp
+     */
+    getTimestamp() {
+        return new Date().toISOString();
+    },
+    /**
+     * Check if in production
+     */
+    isProduction(environment) {
+        return environment === 'production';
+    },
+    /**
+     * Build health response
+     */
+    buildHealthResponse(status, environment, extra) {
+        const base = {
+            status,
+            timestamp: HealthUtils.getTimestamp(),
+            environment,
+            ...extra,
+        };
+        return base;
+    },
+    /**
+     * Build error health response
+     */
+    buildErrorResponse(status, environment, error, extra) {
+        const isProd = HealthUtils.isProduction(environment);
+        return HealthUtils.buildHealthResponse(status, environment, {
+            error: isProd ? 'Service unavailable' : error.message,
+            ...extra,
+        });
+    },
+};

package/src/common/HealthRoutes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared Health Route Handlers
+ * Extracted to eliminate duplication between CoreRoutes.ts and routes/health.ts
+ */
+import type { IRouter } from '../routes/Router';
+/**
+ * Register all health routes
+ */
+export declare const registerHealthRoutes: (router: IRouter) => void;
+//# sourceMappingURL=HealthRoutes.d.ts.map

package/src/common/HealthRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthRoutes.d.ts","sourceRoot":"","sources":["../../../src/common/HealthRoutes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA6KnD;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,OAAO,KAAG,IAItD,CAAC"}