digitaltwin-core 0.14.2 → 1.0.0

package/dist/utils/graceful_shutdown.d.ts

@@ -0,0 +1,44 @@
+import type { DigitalTwinEngine } from '../engine/digital_twin_engine.js';
+export interface ShutdownOptions {
+    /** Timeout before forcing exit (default: 30000ms) */
+    timeout?: number;
+    /** Signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    signals?: NodeJS.Signals[];
+    /** Custom cleanup function to run before stopping engine */
+    onShutdown?: () => Promise<void>;
+    /** Custom logger function (default: console.log) */
+    logger?: (msg: string) => void;
+}
+/**
+ * Setup graceful shutdown handlers for a DigitalTwinEngine
+ *
+ * This helper registers signal handlers for graceful shutdown in production.
+ * It handles SIGTERM (from Kubernetes/Docker) and SIGINT (Ctrl+C) by default.
+ *
+ * @param engine The DigitalTwinEngine instance to shut down
+ * @param options Configuration options
+ * @returns Cleanup function to remove signal handlers
+ *
+ * @example
+ * ```typescript
+ * import { DigitalTwinEngine, setupGracefulShutdown } from 'digitaltwin-core'
+ *
+ * const engine = new DigitalTwinEngine({ ... })
+ *
+ * // Setup graceful shutdown before starting
+ * const cleanup = setupGracefulShutdown(engine, {
+ *     timeout: 30000,
+ *     signals: ['SIGTERM', 'SIGINT', 'SIGQUIT'],
+ *     onShutdown: async () => {
+ *         console.log('Performing custom cleanup...')
+ *     }
+ * })
+ *
+ * await engine.start()
+ *
+ * // Later, if you need to remove handlers:
+ * // cleanup()
+ * ```
+ */
+export declare function setupGracefulShutdown(engine: DigitalTwinEngine, options?: ShutdownOptions): () => void;
+//# sourceMappingURL=graceful_shutdown.d.ts.map

package/dist/utils/graceful_shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful_shutdown.d.ts","sourceRoot":"","sources":["../../src/utils/graceful_shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AAEzE,MAAM,WAAW,eAAe;IAC5B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;IAC1B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAChC,oDAAoD;IACpD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,IAAI,CAuD1G"}

package/dist/utils/graceful_shutdown.js

@@ -0,0 +1,79 @@
+/**
+ * Setup graceful shutdown handlers for a DigitalTwinEngine
+ *
+ * This helper registers signal handlers for graceful shutdown in production.
+ * It handles SIGTERM (from Kubernetes/Docker) and SIGINT (Ctrl+C) by default.
+ *
+ * @param engine The DigitalTwinEngine instance to shut down
+ * @param options Configuration options
+ * @returns Cleanup function to remove signal handlers
+ *
+ * @example
+ * ```typescript
+ * import { DigitalTwinEngine, setupGracefulShutdown } from 'digitaltwin-core'
+ *
+ * const engine = new DigitalTwinEngine({ ... })
+ *
+ * // Setup graceful shutdown before starting
+ * const cleanup = setupGracefulShutdown(engine, {
+ *     timeout: 30000,
+ *     signals: ['SIGTERM', 'SIGINT', 'SIGQUIT'],
+ *     onShutdown: async () => {
+ *         console.log('Performing custom cleanup...')
+ *     }
+ * })
+ *
+ * await engine.start()
+ *
+ * // Later, if you need to remove handlers:
+ * // cleanup()
+ * ```
+ */
+export function setupGracefulShutdown(engine, options = {}) {
+    const { timeout = 30000, signals = ['SIGTERM', 'SIGINT'], onShutdown, logger = console.log } = options;
+    let isShuttingDown = false;
+    const shutdown = async (signal) => {
+        if (isShuttingDown) {
+            logger(`[Shutdown] Already shutting down, ignoring ${signal}`);
+            return;
+        }
+        isShuttingDown = true;
+        logger(`[Shutdown] Received ${signal}, initiating graceful shutdown...`);
+        // Set global timeout for force exit
+        const forceExitTimer = setTimeout(() => {
+            logger('[Shutdown] Timeout exceeded, forcing exit');
+            process.exit(1);
+        }, timeout);
+        forceExitTimer.unref();
+        try {
+            // Run custom shutdown logic first
+            if (onShutdown) {
+                await onShutdown();
+            }
+            // Stop the engine
+            await engine.stop();
+            clearTimeout(forceExitTimer);
+            logger('[Shutdown] Graceful shutdown completed');
+            process.exit(0);
+        }
+        catch (error) {
+            logger(`[Shutdown] Error during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    };
+    // Register signal handlers
+    const handlers = new Map();
+    signals.forEach(signal => {
+        const handler = () => shutdown(signal);
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    });
+    // Return cleanup function
+    return () => {
+        handlers.forEach((handler, signal) => {
+            process.removeListener(signal, handler);
+        });
+        handlers.clear();
+    };
+}
+//# sourceMappingURL=graceful_shutdown.js.map

package/dist/utils/graceful_shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful_shutdown.js","sourceRoot":"","sources":["../../src/utils/graceful_shutdown.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAyB,EAAE,UAA2B,EAAE;IAC1F,MAAM,EAAE,OAAO,GAAG,KAAK,EAAE,OAAO,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAA;IAEtG,IAAI,cAAc,GAAG,KAAK,CAAA;IAE1B,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;QACtC,IAAI,cAAc,EAAE,CAAC;YACjB,MAAM,CAAC,8CAA8C,MAAM,EAAE,CAAC,CAAA;YAC9D,OAAM;QACV,CAAC;QAED,cAAc,GAAG,IAAI,CAAA;QACrB,MAAM,CAAC,uBAAuB,MAAM,mCAAmC,CAAC,CAAA;QAExE,oCAAoC;QACpC,MAAM,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;YACnC,MAAM,CAAC,2CAA2C,CAAC,CAAA;YACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,CAAC,EAAE,OAAO,CAAC,CAAA;QACX,cAAc,CAAC,KAAK,EAAE,CAAA;QAEtB,IAAI,CAAC;YACD,kCAAkC;YAClC,IAAI,UAAU,EAAE,CAAC;gBACb,MAAM,UAAU,EAAE,CAAA;YACtB,CAAC;YAED,kBAAkB;YAClB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;YAEnB,YAAY,CAAC,cAAc,CAAC,CAAA;YAC5B,MAAM,CAAC,wCAAwC,CAAC,CAAA;YAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,CAAC,qCAAqC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;YACrG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,CAAC;IACL,CAAC,CAAA;IAED,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAA;IAEtD,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACrB,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACtC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC7B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,0BAA0B;IAC1B,OAAO,GAAG,EAAE;QACR,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACjC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC3C,CAAC,CAAC,CAAA;QACF,QAAQ,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC,CAAA;AACL,CAAC"}

package/dist/utils/http_responses.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview HTTP response utilities for consistent API responses
+ *
+ * This module provides helper functions to create standardized DataResponse objects,
+ * reducing boilerplate code in component handlers and ensuring consistent API responses.
+ */
+import type { DataResponse } from '../components/types.js';
+/**
+ * HTTP status codes commonly used in the Digital Twin framework.
+ */
+export declare const HttpStatus: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly MULTI_STATUS: 207;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly INTERNAL_SERVER_ERROR: 500;
+};
+export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+/**
+ * Creates a JSON response with the specified status and data.
+ *
+ * @param status - HTTP status code
+ * @param data - Data to serialize as JSON
+ * @returns DataResponse with JSON content type
+ *
+ * @example
+ * ```typescript
+ * return jsonResponse(200, { message: 'Success' })
+ * return jsonResponse(400, { error: 'Invalid input' })
+ * ```
+ */
+export declare function jsonResponse(status: number, data: object): DataResponse;
+/**
+ * Creates a successful JSON response (HTTP 200).
+ *
+ * @param data - Data to serialize as JSON
+ * @returns DataResponse with status 200
+ *
+ * @example
+ * ```typescript
+ * return successResponse({ message: 'Asset uploaded successfully' })
+ * ```
+ */
+export declare function successResponse(data: object): DataResponse;
+/**
+ * Creates an error response from an Error object or string.
+ *
+ * @param error - Error object or error message string
+ * @param status - HTTP status code (default: 500)
+ * @returns DataResponse with error message
+ *
+ * @example
+ * ```typescript
+ * return errorResponse(new Error('Something went wrong'))
+ * return errorResponse('Invalid input', 400)
+ * ```
+ */
+export declare function errorResponse(error: unknown, status?: number): DataResponse;
+/**
+ * Creates a 400 Bad Request response.
+ *
+ * @param message - Error message describing what's wrong with the request
+ * @returns DataResponse with status 400
+ *
+ * @example
+ * ```typescript
+ * return badRequestResponse('Missing required fields: description, source')
+ * ```
+ */
+export declare function badRequestResponse(message: string): DataResponse;
+/**
+ * Creates a 401 Unauthorized response.
+ *
+ * @param message - Error message (default: 'Authentication required')
+ * @returns DataResponse with status 401
+ *
+ * @example
+ * ```typescript
+ * return unauthorizedResponse()
+ * return unauthorizedResponse('Invalid authentication headers')
+ * ```
+ */
+export declare function unauthorizedResponse(message?: string): DataResponse;
+/**
+ * Creates a 403 Forbidden response.
+ *
+ * @param message - Error message describing why access is denied
+ * @returns DataResponse with status 403
+ *
+ * @example
+ * ```typescript
+ * return forbiddenResponse('You can only modify your own assets')
+ * ```
+ */
+export declare function forbiddenResponse(message: string): DataResponse;
+/**
+ * Creates a 404 Not Found response.
+ *
+ * @param message - Error message (default: 'Resource not found')
+ * @returns DataResponse with status 404
+ *
+ * @example
+ * ```typescript
+ * return notFoundResponse('Asset not found')
+ * ```
+ */
+export declare function notFoundResponse(message?: string): DataResponse;
+/**
+ * Creates a validation error response (HTTP 422 Unprocessable Entity).
+ *
+ * Used when request data fails schema validation.
+ *
+ * @param message - Validation error message
+ * @param errors - Optional array of field-level validation errors
+ * @returns DataResponse with status 422
+ *
+ * @example
+ * ```typescript
+ * return validationErrorResponse('id: must be a positive number')
+ * return validationErrorResponse('Validation failed', [{ field: 'id', message: 'must be positive' }])
+ * ```
+ */
+export declare function validationErrorResponse(message: string, errors?: Array<{
+    field: string;
+    message: string;
+}>): DataResponse;
+/**
+ * Creates a plain text response.
+ *
+ * @param status - HTTP status code
+ * @param content - Text content
+ * @returns DataResponse with text/plain content type
+ *
+ * @example
+ * ```typescript
+ * return textResponse(404, 'Asset not found')
+ * ```
+ */
+export declare function textResponse(status: number, content: string): DataResponse;
+/**
+ * Creates a binary/file response.
+ *
+ * @param content - File content as Buffer
+ * @param contentType - MIME type of the file
+ * @param filename - Optional filename for Content-Disposition header (triggers download)
+ * @returns DataResponse with appropriate content type
+ *
+ * @example
+ * ```typescript
+ * // For display/use in browser
+ * return fileResponse(buffer, 'model/gltf-binary')
+ *
+ * // For download
+ * return fileResponse(buffer, 'model/gltf-binary', 'model.glb')
+ * ```
+ */
+export declare function fileResponse(content: Buffer, contentType: string, filename?: string): DataResponse;
+/**
+ * Creates a 207 Multi-Status response for batch operations.
+ *
+ * @param message - Summary message
+ * @param results - Array of individual operation results
+ * @returns DataResponse with status 207
+ *
+ * @example
+ * ```typescript
+ * return multiStatusResponse('3/5 assets uploaded successfully', results)
+ * ```
+ */
+export declare function multiStatusResponse(message: string, results: unknown[]): DataResponse;
+//# sourceMappingURL=http_responses.d.ts.map

package/dist/utils/http_responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_responses.d.ts","sourceRoot":"","sources":["../../src/utils/http_responses.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAG1D;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;CAUb,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAA;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAMvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAE1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAM3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,MAAkC,GAAG,YAAY,CAE9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,MAA6B,GAAG,YAAY,CAErF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,YAAY,CAMd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAM1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAYlG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,YAAY,CAErF"}

package/dist/utils/http_responses.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview HTTP response utilities for consistent API responses
+ *
+ * This module provides helper functions to create standardized DataResponse objects,
+ * reducing boilerplate code in component handlers and ensuring consistent API responses.
+ */
+import { DigitalTwinError } from '../errors/index.js';
+/**
+ * HTTP status codes commonly used in the Digital Twin framework.
+ */
+export const HttpStatus = {
+    OK: 200,
+    CREATED: 201,
+    MULTI_STATUS: 207,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    UNPROCESSABLE_ENTITY: 422,
+    INTERNAL_SERVER_ERROR: 500
+};
+/**
+ * Creates a JSON response with the specified status and data.
+ *
+ * @param status - HTTP status code
+ * @param data - Data to serialize as JSON
+ * @returns DataResponse with JSON content type
+ *
+ * @example
+ * ```typescript
+ * return jsonResponse(200, { message: 'Success' })
+ * return jsonResponse(400, { error: 'Invalid input' })
+ * ```
+ */
+export function jsonResponse(status, data) {
+    return {
+        status,
+        content: JSON.stringify(data),
+        headers: { 'Content-Type': 'application/json' }
+    };
+}
+/**
+ * Creates a successful JSON response (HTTP 200).
+ *
+ * @param data - Data to serialize as JSON
+ * @returns DataResponse with status 200
+ *
+ * @example
+ * ```typescript
+ * return successResponse({ message: 'Asset uploaded successfully' })
+ * ```
+ */
+export function successResponse(data) {
+    return jsonResponse(HttpStatus.OK, data);
+}
+/**
+ * Creates an error response from an Error object or string.
+ *
+ * @param error - Error object or error message string
+ * @param status - HTTP status code (default: 500)
+ * @returns DataResponse with error message
+ *
+ * @example
+ * ```typescript
+ * return errorResponse(new Error('Something went wrong'))
+ * return errorResponse('Invalid input', 400)
+ * ```
+ */
+export function errorResponse(error, status) {
+    // Use statusCode from DigitalTwinError if available
+    const statusCode = error instanceof DigitalTwinError ? error.statusCode : (status ?? HttpStatus.INTERNAL_SERVER_ERROR);
+    const message = error instanceof Error ? error.message : String(error);
+    return jsonResponse(statusCode, { error: message });
+}
+/**
+ * Creates a 400 Bad Request response.
+ *
+ * @param message - Error message describing what's wrong with the request
+ * @returns DataResponse with status 400
+ *
+ * @example
+ * ```typescript
+ * return badRequestResponse('Missing required fields: description, source')
+ * ```
+ */
+export function badRequestResponse(message) {
+    return jsonResponse(HttpStatus.BAD_REQUEST, { error: message });
+}
+/**
+ * Creates a 401 Unauthorized response.
+ *
+ * @param message - Error message (default: 'Authentication required')
+ * @returns DataResponse with status 401
+ *
+ * @example
+ * ```typescript
+ * return unauthorizedResponse()
+ * return unauthorizedResponse('Invalid authentication headers')
+ * ```
+ */
+export function unauthorizedResponse(message = 'Authentication required') {
+    return jsonResponse(HttpStatus.UNAUTHORIZED, { error: message });
+}
+/**
+ * Creates a 403 Forbidden response.
+ *
+ * @param message - Error message describing why access is denied
+ * @returns DataResponse with status 403
+ *
+ * @example
+ * ```typescript
+ * return forbiddenResponse('You can only modify your own assets')
+ * ```
+ */
+export function forbiddenResponse(message) {
+    return jsonResponse(HttpStatus.FORBIDDEN, { error: message });
+}
+/**
+ * Creates a 404 Not Found response.
+ *
+ * @param message - Error message (default: 'Resource not found')
+ * @returns DataResponse with status 404
+ *
+ * @example
+ * ```typescript
+ * return notFoundResponse('Asset not found')
+ * ```
+ */
+export function notFoundResponse(message = 'Resource not found') {
+    return jsonResponse(HttpStatus.NOT_FOUND, { error: message });
+}
+/**
+ * Creates a validation error response (HTTP 422 Unprocessable Entity).
+ *
+ * Used when request data fails schema validation.
+ *
+ * @param message - Validation error message
+ * @param errors - Optional array of field-level validation errors
+ * @returns DataResponse with status 422
+ *
+ * @example
+ * ```typescript
+ * return validationErrorResponse('id: must be a positive number')
+ * return validationErrorResponse('Validation failed', [{ field: 'id', message: 'must be positive' }])
+ * ```
+ */
+export function validationErrorResponse(message, errors) {
+    const body = { error: message };
+    if (errors) {
+        body.errors = errors;
+    }
+    return jsonResponse(HttpStatus.UNPROCESSABLE_ENTITY, body);
+}
+/**
+ * Creates a plain text response.
+ *
+ * @param status - HTTP status code
+ * @param content - Text content
+ * @returns DataResponse with text/plain content type
+ *
+ * @example
+ * ```typescript
+ * return textResponse(404, 'Asset not found')
+ * ```
+ */
+export function textResponse(status, content) {
+    return {
+        status,
+        content,
+        headers: { 'Content-Type': 'text/plain' }
+    };
+}
+/**
+ * Creates a binary/file response.
+ *
+ * @param content - File content as Buffer
+ * @param contentType - MIME type of the file
+ * @param filename - Optional filename for Content-Disposition header (triggers download)
+ * @returns DataResponse with appropriate content type
+ *
+ * @example
+ * ```typescript
+ * // For display/use in browser
+ * return fileResponse(buffer, 'model/gltf-binary')
+ *
+ * // For download
+ * return fileResponse(buffer, 'model/gltf-binary', 'model.glb')
+ * ```
+ */
+export function fileResponse(content, contentType, filename) {
+    const headers = { 'Content-Type': contentType };
+    if (filename) {
+        headers['Content-Disposition'] = `attachment; filename="${filename}"`;
+    }
+    return {
+        status: HttpStatus.OK,
+        content,
+        headers
+    };
+}
+/**
+ * Creates a 207 Multi-Status response for batch operations.
+ *
+ * @param message - Summary message
+ * @param results - Array of individual operation results
+ * @returns DataResponse with status 207
+ *
+ * @example
+ * ```typescript
+ * return multiStatusResponse('3/5 assets uploaded successfully', results)
+ * ```
+ */
+export function multiStatusResponse(message, results) {
+    return jsonResponse(HttpStatus.MULTI_STATUS, { message, results });
+}
+//# sourceMappingURL=http_responses.js.map

package/dist/utils/http_responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_responses.js","sourceRoot":"","sources":["../../src/utils/http_responses.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { Logger, LogLevel } from './logger.js';
+export { mapToDataRecord } from './map_to_data_record.js';
+export { servableEndpoint } from './servable_endpoint.js';
+export { extractZipContentStream, zipToDict, detectTilesetRootFile, normalizeArchivePaths, extractAndStoreArchive } from './zip_utils.js';
+export type { ExtractedArchiveResult } from './zip_utils.js';
+export { HttpStatus, jsonResponse, successResponse, errorResponse, badRequestResponse, unauthorizedResponse, forbiddenResponse, notFoundResponse, textResponse, fileResponse, multiStatusResponse } from './http_responses.js';
+export type { HttpStatusCode } from './http_responses.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EACH,uBAAuB,EACvB,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACzB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,EACH,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACtB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+export { Logger, LogLevel } from './logger.js';
+export { mapToDataRecord } from './map_to_data_record.js';
+export { servableEndpoint } from './servable_endpoint.js';
+export { extractZipContentStream, zipToDict, detectTilesetRootFile, normalizeArchivePaths, extractAndStoreArchive } from './zip_utils.js';
+export { HttpStatus, jsonResponse, successResponse, errorResponse, badRequestResponse, unauthorizedResponse, forbiddenResponse, notFoundResponse, textResponse, fileResponse, multiStatusResponse } from './http_responses.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EACH,uBAAuB,EACvB,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACzB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACH,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACtB,MAAM,qBAAqB,CAAA"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Enumeration of available logging levels.
+ *
+ * Levels are ordered by severity, with lower numbers being more verbose.
+ *
+ * @enum {number}
+ */
+export declare enum LogLevel {
+    /** Debug messages - most verbose, includes internal state information */
+    DEBUG = 0,
+    /** Informational messages - general application flow */
+    INFO = 1,
+    /** Warning messages - potential issues that don't prevent operation */
+    WARN = 2,
+    /** Error messages - failures that affect functionality */
+    ERROR = 3,
+    /** Silent mode - no logging output */
+    SILENT = 4
+}
+/**
+ * Simple logger class for Digital Twin framework components.
+ *
+ * Provides structured logging with component identification and configurable levels.
+ * Automatically adjusts log level based on environment (silent in tests).
+ *
+ * @class Logger
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger('MyCollector', LogLevel.DEBUG)
+ * logger.info('Starting data collection')
+ * logger.error('Failed to connect', error)
+ * ```
+ */
+export declare class Logger {
+    private readonly componentName;
+    private readonly level;
+    /**
+     * Creates a new logger instance for a component.
+     *
+     * @param {string} componentName - Name of the component for log prefixing
+     * @param {LogLevel} level - Minimum log level to output (defaults based on NODE_ENV)
+     */
+    constructor(componentName: string, level?: LogLevel);
+    /**
+     * Logs debug information for development and troubleshooting.
+     *
+     * @param {string} message - Debug message
+     * @param {any} data - Optional additional data to log
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Logs informational messages about normal operation.
+     *
+     * @param {string} message - Information message
+     * @param {any} data - Optional additional data to log
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Logs warning messages about potential issues.
+     *
+     * @param {string} message - Warning message
+     * @param {any} data - Optional additional data to log
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Logs error messages about failures and exceptions.
+     *
+     * @param {string} message - Error message
+     * @param {any} error - Optional error object or additional data
+     */
+    error(message: string, error?: any): void;
+}
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oBAAY,QAAQ;IAChB,yEAAyE;IACzE,KAAK,IAAI;IACT,wDAAwD;IACxD,IAAI,IAAI;IACR,uEAAuE;IACvE,IAAI,IAAI;IACR,0DAA0D;IAC1D,KAAK,IAAI;IACT,sCAAsC;IACtC,MAAM,IAAI;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,MAAM;IAQX,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAR1B;;;;;OAKG;gBAEkB,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,QAA2E;IAGvG;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAMjC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAMhC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAMhC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG;CAKrC"}