digitaltwin-core 0.14.2 → 1.0.0

package/dist/utils/logger.js

@@ -0,0 +1,92 @@
+/**
+ * Enumeration of available logging levels.
+ *
+ * Levels are ordered by severity, with lower numbers being more verbose.
+ *
+ * @enum {number}
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Debug messages - most verbose, includes internal state information */
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    /** Informational messages - general application flow */
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    /** Warning messages - potential issues that don't prevent operation */
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    /** Error messages - failures that affect functionality */
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    /** Silent mode - no logging output */
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+/**
+ * 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 class Logger {
+    /**
+     * 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, level = process.env.NODE_ENV === 'test' ? LogLevel.ERROR : LogLevel.INFO) {
+        this.componentName = componentName;
+        this.level = level;
+    }
+    /**
+     * Logs debug information for development and troubleshooting.
+     *
+     * @param {string} message - Debug message
+     * @param {any} data - Optional additional data to log
+     */
+    debug(message, data) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.log(`[${this.componentName}] DEBUG: ${message}`, data || '');
+        }
+    }
+    /**
+     * Logs informational messages about normal operation.
+     *
+     * @param {string} message - Information message
+     * @param {any} data - Optional additional data to log
+     */
+    info(message, data) {
+        if (this.level <= LogLevel.INFO) {
+            console.log(`[${this.componentName}] ${message}`, data || '');
+        }
+    }
+    /**
+     * Logs warning messages about potential issues.
+     *
+     * @param {string} message - Warning message
+     * @param {any} data - Optional additional data to log
+     */
+    warn(message, data) {
+        if (this.level <= LogLevel.WARN) {
+            console.warn(`[${this.componentName}] WARN: ${message}`, data || '');
+        }
+    }
+    /**
+     * Logs error messages about failures and exceptions.
+     *
+     * @param {string} message - Error message
+     * @param {any} error - Optional error object or additional data
+     */
+    error(message, error) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error(`[${this.componentName}] ERROR: ${message}`, error || '');
+        }
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,QAWX;AAXD,WAAY,QAAQ;IAChB,yEAAyE;IACzE,yCAAS,CAAA;IACT,wDAAwD;IACxD,uCAAQ,CAAA;IACR,uEAAuE;IACvE,uCAAQ,CAAA;IACR,0DAA0D;IAC1D,yCAAS,CAAA;IACT,sCAAsC;IACtC,2CAAU,CAAA;AACd,CAAC,EAXW,QAAQ,KAAR,QAAQ,QAWnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,MAAM;IACf;;;;;OAKG;IACH,YACqB,aAAqB,EACrB,QAAkB,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI;QADlF,kBAAa,GAAb,aAAa,CAAQ;QACrB,UAAK,GAAL,KAAK,CAA6E;IACpG,CAAC;IAEJ;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,IAAU;QAC7B,IAAI,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,aAAa,YAAY,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QACxE,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,IAAU;QAC5B,IAAI,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,aAAa,KAAK,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QACjE,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,IAAU;QAC5B,IAAI,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,WAAW,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAA;QACxE,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,KAAW;QAC9B,IAAI,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,YAAY,OAAO,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAA;QAC3E,CAAC;IACL,CAAC;CACJ"}

package/dist/utils/map_to_data_record.d.ts

@@ -0,0 +1,10 @@
+import type { StorageService } from '../storage/storage_service.js';
+import type { DataRecord } from '../types/data_record.js';
+import type { MetadataRow } from '../database/database_adapter.js';
+/**
+ * Convert a DB metadata row to a full DataRecord with lazy-loaded blob.
+ *
+ * Also maps asset-specific fields if present (for AssetsManager components).
+ */
+export declare function mapToDataRecord(row: MetadataRow | any, storage: StorageService): DataRecord;
+//# sourceMappingURL=map_to_data_record.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map_to_data_record.d.ts","sourceRoot":"","sources":["../../src/utils/map_to_data_record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAElE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,CAiC3F"}

package/dist/utils/map_to_data_record.js

@@ -0,0 +1,36 @@
+/**
+ * Convert a DB metadata row to a full DataRecord with lazy-loaded blob.
+ *
+ * Also maps asset-specific fields if present (for AssetsManager components).
+ */
+export function mapToDataRecord(row, storage) {
+    return {
+        id: row.id,
+        name: row.name,
+        date: new Date(row.date),
+        contentType: row.type,
+        url: row.url,
+        data: () => storage.retrieve(row.url),
+        // Asset-specific fields (optional, only for AssetsManager)
+        description: row.description,
+        source: row.source,
+        owner_id: row.owner_id,
+        filename: row.filename,
+        // Default to true for backward compatibility with records created before is_public column
+        // SQLite stores booleans as 0/1, so we normalize to proper boolean
+        is_public: row.is_public === undefined || row.is_public === null ? true : Boolean(row.is_public),
+        // TilesetManager support
+        tileset_url: row.tileset_url || undefined,
+        // Legacy (deprecated)
+        file_index: row.file_index
+            ? typeof row.file_index === 'string'
+                ? JSON.parse(row.file_index)
+                : row.file_index
+            : undefined,
+        // Async upload support
+        upload_status: row.upload_status || null,
+        upload_error: row.upload_error || null,
+        upload_job_id: row.upload_job_id || null
+    };
+}
+//# sourceMappingURL=map_to_data_record.js.map

package/dist/utils/map_to_data_record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_to_data_record.js","sourceRoot":"","sources":["../../src/utils/map_to_data_record.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAsB,EAAE,OAAuB;IAC3E,OAAO;QACH,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;QACxB,WAAW,EAAE,GAAG,CAAC,IAAI;QACrB,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;QAErC,2DAA2D;QAC3D,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,0FAA0F;QAC1F,mEAAmE;QACnE,SAAS,EAAE,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QAEhG,yBAAyB;QACzB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QAEzC,sBAAsB;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;YACtB,CAAC,CAAC,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;gBAChC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;gBAC5B,CAAC,CAAC,GAAG,CAAC,UAAU;YACpB,CAAC,CAAC,SAAS;QAEf,uBAAuB;QACvB,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;QACxC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;QACtC,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;KAC3C,CAAA;AACL,CAAC"}

package/dist/utils/safe_async.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Utilities for safe async operations
+ * Provides error handling for non-critical operations like cleanup
+ */
+import { Logger } from './logger.js';
+/**
+ * Executes an async operation with error logging
+ * For cleanup operations where errors should not block execution
+ *
+ * @param operation - The async function to execute
+ * @param context - Description of the operation for logging
+ * @param logger - Optional logger instance
+ * @returns The result of the operation, or undefined if it failed
+ */
+export declare function safeAsync<T>(operation: () => Promise<T>, context: string, logger?: Logger): Promise<T | undefined>;
+/**
+ * Executes an async operation and returns a Result tuple
+ * Useful when you need to know if the operation failed but continue execution
+ *
+ * @param operation - The async function to execute
+ * @returns [result, undefined] on success, [undefined, error] on failure
+ */
+export declare function tryAsync<T>(operation: () => Promise<T>): Promise<[T, undefined] | [undefined, Error]>;
+/**
+ * Executes multiple cleanup operations in parallel, logging any failures
+ * All operations will be attempted even if some fail
+ *
+ * @param operations - Array of cleanup operations with context
+ * @param logger - Optional logger instance
+ */
+export declare function safeCleanup(operations: Array<{
+    operation: () => Promise<unknown>;
+    context: string;
+}>, logger?: Logger): Promise<void>;
+/**
+ * Retries an async operation with exponential backoff
+ *
+ * @param operation - The async function to execute
+ * @param options - Retry options
+ * @returns The result of the operation
+ * @throws The last error if all retries fail
+ */
+export declare function retryAsync<T>(operation: () => Promise<T>, options?: {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    context?: string;
+    logger?: Logger;
+}): Promise<T>;
+//# sourceMappingURL=safe_async.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safe_async.d.ts","sourceRoot":"","sources":["../../src/utils/safe_async.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAIpC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CASxB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAQ3G;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC7B,UAAU,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EACzE,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAC9B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE;IACL,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CACb,GACP,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/utils/safe_async.js

@@ -0,0 +1,90 @@
+/**
+ * Utilities for safe async operations
+ * Provides error handling for non-critical operations like cleanup
+ */
+import { Logger } from './logger.js';
+const defaultLogger = new Logger('SafeAsync');
+/**
+ * Executes an async operation with error logging
+ * For cleanup operations where errors should not block execution
+ *
+ * @param operation - The async function to execute
+ * @param context - Description of the operation for logging
+ * @param logger - Optional logger instance
+ * @returns The result of the operation, or undefined if it failed
+ */
+export async function safeAsync(operation, context, logger) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const log = logger ?? defaultLogger;
+        const message = error instanceof Error ? error.message : String(error);
+        log.warn(`Non-critical error in ${context}: ${message}`);
+        return undefined;
+    }
+}
+/**
+ * Executes an async operation and returns a Result tuple
+ * Useful when you need to know if the operation failed but continue execution
+ *
+ * @param operation - The async function to execute
+ * @returns [result, undefined] on success, [undefined, error] on failure
+ */
+export async function tryAsync(operation) {
+    try {
+        const result = await operation();
+        return [result, undefined];
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        return [undefined, err];
+    }
+}
+/**
+ * Executes multiple cleanup operations in parallel, logging any failures
+ * All operations will be attempted even if some fail
+ *
+ * @param operations - Array of cleanup operations with context
+ * @param logger - Optional logger instance
+ */
+export async function safeCleanup(operations, logger) {
+    const log = logger ?? defaultLogger;
+    const results = await Promise.allSettled(operations.map(({ operation, context }) => operation().catch(error => {
+        const message = error instanceof Error ? error.message : String(error);
+        log.warn(`Cleanup failed for ${context}: ${message}`);
+        throw error;
+    })));
+    const failures = results.filter(r => r.status === 'rejected').length;
+    if (failures > 0) {
+        log.warn(`${failures}/${operations.length} cleanup operations failed`);
+    }
+}
+/**
+ * Retries an async operation with exponential backoff
+ *
+ * @param operation - The async function to execute
+ * @param options - Retry options
+ * @returns The result of the operation
+ * @throws The last error if all retries fail
+ */
+export async function retryAsync(operation, options = {}) {
+    const { maxRetries = 3, initialDelayMs = 100, maxDelayMs = 5000, context = 'operation', logger } = options;
+    const log = logger ?? defaultLogger;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries) {
+                const delay = Math.min(initialDelayMs * Math.pow(2, attempt), maxDelayMs);
+                log.warn(`${context} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms: ${lastError.message}`);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=safe_async.js.map

package/dist/utils/safe_async.js.map

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

package/dist/utils/servable_endpoint.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Decorator for marking methods as HTTP endpoint handlers
+ *
+ * This utility provides a decorator to annotate component methods as HTTP endpoints
+ * that should be automatically registered with the digital twin engine's router.
+ */
+/**
+ * Configuration interface for the servable endpoint decorator.
+ */
+interface ServableEndpointConfig {
+    /** URL path for this endpoint (e.g., '/api/data/:id') */
+    path: string;
+    /** HTTP method (defaults to 'get') */
+    method?: string;
+    /** Response content type (defaults to 'application/json') */
+    responseType?: string;
+}
+/**
+ * Decorator that marks a method as an HTTP endpoint handler.
+ *
+ * This decorator allows component methods to be automatically discovered
+ * and registered as HTTP endpoints by the digital twin engine. The decorated
+ * method will be called when HTTP requests are made to the specified path.
+ *
+ * @param config - Configuration object specifying the endpoint details
+ * @param config.path - URL path pattern for this endpoint
+ * @param config.method - HTTP method (defaults to 'GET')
+ * @param config.responseType - Response content type (defaults to 'application/json')
+ *
+ * @returns Method decorator function
+ *
+ * @example
+ * ```typescript
+ * class WeatherCollector extends Collector {
+ *   @servableEndpoint({
+ *     path: '/api/weather/current',
+ *     method: 'get',
+ *     responseType: 'application/json'
+ *   })
+ *   getCurrentWeather(req: Request) {
+ *     return {
+ *       status: 200,
+ *       content: { temperature: 22, humidity: 65 }
+ *     };
+ *   }
+ *
+ *   @servableEndpoint({
+ *     path: '/api/weather/history/:date',
+ *     method: 'get'
+ *   })
+ *   getWeatherHistory(req: Request) {
+ *     const date = req.params.date;
+ *     return {
+ *       status: 200,
+ *       content: this.getHistoricalData(date)
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare function servableEndpoint(config: ServableEndpointConfig): (target: any, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => any;
+export {};
+//# sourceMappingURL=servable_endpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"servable_endpoint.d.ts","sourceRoot":"","sources":["../../src/utils/servable_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,UAAU,sBAAsB;IAC5B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IAEZ,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,IAC1C,QAAQ,GAAG,EAAE,aAAa,MAAM,GAAG,MAAM,EAAE,aAAa,kBAAkB,KAAG,GAAG,CAkBpG"}

package/dist/utils/servable_endpoint.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Decorator for marking methods as HTTP endpoint handlers
+ *
+ * This utility provides a decorator to annotate component methods as HTTP endpoints
+ * that should be automatically registered with the digital twin engine's router.
+ */
+/**
+ * Decorator that marks a method as an HTTP endpoint handler.
+ *
+ * This decorator allows component methods to be automatically discovered
+ * and registered as HTTP endpoints by the digital twin engine. The decorated
+ * method will be called when HTTP requests are made to the specified path.
+ *
+ * @param config - Configuration object specifying the endpoint details
+ * @param config.path - URL path pattern for this endpoint
+ * @param config.method - HTTP method (defaults to 'GET')
+ * @param config.responseType - Response content type (defaults to 'application/json')
+ *
+ * @returns Method decorator function
+ *
+ * @example
+ * ```typescript
+ * class WeatherCollector extends Collector {
+ *   @servableEndpoint({
+ *     path: '/api/weather/current',
+ *     method: 'get',
+ *     responseType: 'application/json'
+ *   })
+ *   getCurrentWeather(req: Request) {
+ *     return {
+ *       status: 200,
+ *       content: { temperature: 22, humidity: 65 }
+ *     };
+ *   }
+ *
+ *   @servableEndpoint({
+ *     path: '/api/weather/history/:date',
+ *     method: 'get'
+ *   })
+ *   getWeatherHistory(req: Request) {
+ *     const date = req.params.date;
+ *     return {
+ *       status: 200,
+ *       content: this.getHistoricalData(date)
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export function servableEndpoint(config) {
+    return function (target, propertyKey, descriptor) {
+        const ctor = target.constructor;
+        // Initialize endpoints array if it doesn't exist
+        if (!ctor.__endpoints) {
+            ctor.__endpoints = [];
+        }
+        // Add endpoint configuration to the constructor metadata
+        ctor.__endpoints.push({
+            method: (config.method || 'get').toUpperCase(),
+            path: config.path,
+            responseType: config.responseType,
+            handlerName: propertyKey.toString()
+        });
+        return descriptor;
+    };
+}
+//# sourceMappingURL=servable_endpoint.js.map

package/dist/utils/servable_endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"servable_endpoint.js","sourceRoot":"","sources":["../../src/utils/servable_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA8B;IAC3D,OAAO,UAAU,MAAW,EAAE,WAA4B,EAAE,UAA+B;QACvF,MAAM,IAAI,GAAG,MAAM,CAAC,WAAkB,CAAA;QAEtC,iDAAiD;QACjD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACpB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAA;QACzB,CAAC;QAED,yDAAyD;QACzD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;YAClB,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE;YAC9C,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,WAAW,EAAE,WAAW,CAAC,QAAQ,EAAE;SACtC,CAAC,CAAA;QAEF,OAAO,UAAU,CAAA;IACrB,CAAC,CAAA;AACL,CAAC"}

package/dist/utils/zip_utils.d.ts

@@ -0,0 +1,66 @@
+import type { StorageService } from '../storage/storage_service.js';
+/**
+ * Result of extracting and storing a ZIP archive
+ */
+export interface ExtractedArchiveResult {
+    /** The root/main file path (e.g., 'tileset.json') */
+    root_file?: string;
+    /** Total number of files extracted */
+    file_count: number;
+}
+/**
+ * Extracts the content of a zip file as a stream (for large files)
+ * @param zipBuffer - The content of the zip file as Buffer
+ * @returns A generator yielding tuples containing the name and content of each file in the zip file
+ */
+export declare function extractZipContentStream(zipBuffer: Buffer): AsyncGenerator<[string, string | Buffer]>;
+/**
+ * Converts a zip file to a dictionary containing all files and their contents
+ * @param zipBuffer - The content of the zip file as Buffer
+ * @returns A dictionary containing the content of the zip file
+ */
+export declare function zipToDict(zipBuffer: Buffer): Promise<Record<string, string | Buffer>>;
+/**
+ * Detects the root file for 3D Tiles tilesets
+ * Looks for tileset.json or similar entry point files
+ * @param files - List of file paths in the archive
+ * @returns The path to the root file, or undefined if not found
+ */
+export declare function detectTilesetRootFile(files: string[]): string | undefined;
+/**
+ * Normalizes file paths from ZIP archives
+ * Removes leading directory if all files share the same root folder
+ * @param files - Original file paths from the archive
+ * @returns Normalized file paths (original -> normalized)
+ */
+export declare function normalizeArchivePaths(files: string[]): Map<string, string>;
+/**
+ * Extracts a ZIP archive and stores each file individually using the storage service.
+ *
+ * This function:
+ * 1. Extracts all files from the ZIP
+ * 2. Normalizes paths (removes common root directory if present)
+ * 3. Stores each file using the storage service with a unique base path
+ * 4. Returns the root file path and file count
+ *
+ * Files are uploaded in parallel batches for performance.
+ *
+ * @param zipBuffer - The ZIP file content as a Buffer
+ * @param storage - The storage service to use for saving files
+ * @param basePath - Base path/folder for storing extracted files (e.g., 'tilesets/1234567890')
+ * @returns ExtractedArchiveResult with root file and file count
+ *
+ * @example
+ * ```typescript
+ * const result = await extractAndStoreArchive(zipBuffer, storage, 'tilesets/1234567890')
+ * // result.root_file = 'tileset.json'
+ * // result.file_count = 42
+ *
+ * // Files are stored at:
+ * // tilesets/1234567890/tileset.json
+ * // tilesets/1234567890/tiles/tile_0.b3dm
+ * // etc.
+ * ```
+ */
+export declare function extractAndStoreArchive(zipBuffer: Buffer, storage: StorageService, basePath: string): Promise<ExtractedArchiveResult>;
+//# sourceMappingURL=zip_utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"zip_utils.d.ts","sourceRoot":"","sources":["../../src/utils/zip_utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAEnE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAuB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAqB3G;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAQ3F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAezE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,sBAAsB,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,sBAAsB,CAAC,CAuEjC"}