@cepseudo/storage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Axel Hoffmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @cepseudo/storage
+
+[![npm version](https://img.shields.io/npm/v/@cepseudo/storage)](https://www.npmjs.com/package/@cepseudo/storage)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
+Abstract storage layer for the Digital Twin framework. Provides a unified API for persisting binary files (3D assets, collected data, tilesets) across local filesystem and S3-compatible cloud storage.
+
+## Installation
+
+```bash
+pnpm add @cepseudo/storage
+```
+
+For S3-compatible storage (OVH, AWS, MinIO), install the AWS SDK peer dependencies:
+
+```bash
+pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+```
+
+These are **optional** -- only required when using `OvhS3StorageService`. The local filesystem adapter has no additional dependencies.
+
+## Adapters
+
+| Feature | `LocalStorageService` | `OvhS3StorageService` |
+|---|---|---|
+| Backend | Local filesystem | S3-compatible (OVH, AWS, MinIO) |
+| Presigned URLs | No | Yes |
+| Batch delete | Sequential | S3 `DeleteObjects` (up to 1000/request) |
+| Public URLs | File path (requires static serving) | Direct HTTPS URL |
+| Path traversal protection | Yes | N/A (S3 key-based) |
+| CORS configuration | N/A | Built-in `configureCors()` |
+| Use case | Development / testing | Production |
+
+## Usage
+
+### Creating a storage service via factory
+
+`StorageServiceFactory` reads the `STORAGE_CONFIG` environment variable and returns the appropriate adapter.
+
+```typescript
+import { StorageServiceFactory } from '@cepseudo/storage'
+
+// STORAGE_CONFIG=local  --> LocalStorageService
+// STORAGE_CONFIG=ovh    --> OvhS3StorageService (requires OVH_* env vars)
+const storage = StorageServiceFactory.create()
+```
+
+**Environment variables for `local`:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `STORAGE_CONFIG` | -- | Set to `local` |
+| `LOCAL_STORAGE_DIR` | `data` | Base directory for file storage |
+
+**Environment variables for `ovh`:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `STORAGE_CONFIG` | -- | Set to `ovh` |
+| `OVH_ACCESS_KEY` | -- | S3 access key |
+| `OVH_SECRET_KEY` | -- | S3 secret key |
+| `OVH_ENDPOINT` | -- | S3 endpoint (e.g. `https://s3.gra.io.cloud.ovh.net`) |
+| `OVH_BUCKET` | -- | Bucket name |
+| `OVH_REGION` | `gra` | S3 region |
+
+### Direct adapter instantiation
+
+```typescript
+import { LocalStorageService, OvhS3StorageService } from '@cepseudo/storage'
+
+// Local filesystem
+const local = new LocalStorageService('./data')
+
+// OVH S3-compatible storage
+const s3 = new OvhS3StorageService({
+    accessKey: 'your-access-key',
+    secretKey: 'your-secret-key',
+    endpoint: 'https://s3.gra.io.cloud.ovh.net',
+    bucket: 'my-bucket',
+    region: 'gra'
+})
+```
+
+### Storing and retrieving files
+
+```typescript
+// Store with auto-generated timestamp filename
+const key = await storage.save(buffer, 'weather-sensor', 'json')
+// --> 'weather-sensor/2026-03-06T10-30-00-000Z.json'
+
+// Store at a specific path (preserves filename)
+await storage.saveWithPath(buffer, 'tilesets/42/tileset.json')
+
+// Retrieve
+const data = await storage.retrieve(key)
+
+// Delete
+await storage.delete(key)
+
+// Delete in batch (S3 adapter uses optimized bulk delete)
+await storage.deleteBatch(['path/a.json', 'path/b.json'])
+
+// Delete all files under a prefix
+const count = await storage.deleteByPrefix('tilesets/42')
+
+// Get public URL
+const url = storage.getPublicUrl('tilesets/42/tileset.json')
+// --> 'https://my-bucket.s3.gra.io.cloud.ovh.net/tilesets/42/tileset.json'
+```
+
+### Presigned URL upload flow
+
+Presigned URLs allow clients to upload files directly to S3, bypassing the backend server entirely. This is essential for large files (3D assets, tilesets).
+
+```typescript
+// 1. Check if the storage backend supports presigned URLs
+if (!storage.supportsPresignedUrls()) {
+    throw new Error('Storage backend does not support presigned URLs')
+}
+
+// 2. Generate a presigned PUT URL (valid for 5 minutes by default)
+const { url, key, expiresAt } = await storage.generatePresignedUploadUrl(
+    'assets/uploads/model.glb',   // target key
+    'model/gltf-binary',          // content type
+    300                            // expiry in seconds (optional, default 300)
+)
+
+// 3. Return url + key to the client; client uploads directly via HTTP PUT
+
+// 4. After upload, verify the file exists in storage
+const { exists, contentLength, contentType } = await storage.objectExists(key)
+```
+
+### CORS configuration (S3 only)
+
+For browser-based uploads via presigned URLs, the S3 bucket needs CORS rules. The factory configures this automatically, but you can also call it manually:
+
+```typescript
+await s3.configureCors(
+    ['https://your-domain.be'],       // allowed origins
+    ['GET', 'HEAD', 'PUT', 'POST'],   // allowed methods
+    ['*', 'Authorization']            // allowed headers
+)
+```
+
+## API Reference
+
+### `StorageService` (abstract)
+
+| Method | Returns | Description |
+|---|---|---|
+| `save(buffer, collectorName, extension?)` | `Promise<string>` | Store with auto-generated key |
+| `saveWithPath(buffer, relativePath)` | `Promise<string>` | Store at exact path |
+| `retrieve(path)` | `Promise<Buffer>` | Read file contents |
+| `delete(path)` | `Promise<void>` | Delete single file |
+| `deleteBatch(paths)` | `Promise<void>` | Delete multiple files |
+| `deleteByPrefix(prefix)` | `Promise<number>` | Delete all files under prefix |
+| `getPublicUrl(relativePath)` | `string` | Get public URL for file |
+| `supportsPresignedUrls()` | `boolean` | Whether presigned URLs are supported |
+| `generatePresignedUploadUrl(key, contentType, expiresIn?)` | `Promise<PresignedUploadResult>` | Generate presigned PUT URL |
+| `objectExists(key)` | `Promise<ObjectExistsResult>` | Check if object exists with metadata |
+
+### Types
+
+```typescript
+interface PresignedUploadResult {
+    url: string       // presigned PUT URL
+    key: string       // object key in storage
+    expiresAt: Date   // URL expiration timestamp
+}
+
+interface ObjectExistsResult {
+    exists: boolean
+    contentLength?: number   // file size in bytes
+    contentType?: string     // MIME type
+}
+
+interface OvhS3Config {
+    accessKey: string
+    secretKey: string
+    endpoint: string   // e.g. 'https://s3.gra.io.cloud.ovh.net'
+    region?: string    // e.g. 'gra' (default)
+    bucket: string
+}
+```
+
+## Peer Dependencies
+
+| Package | Required for | Required? |
+|---|---|---|
+| `@aws-sdk/client-s3` >= 3.0.0 | `OvhS3StorageService` | Optional |
+| `@aws-sdk/s3-request-presigner` >= 3.0.0 | Presigned URL generation | Optional |
+
+The AWS SDK packages are only loaded by `OvhS3StorageService`. If you only use `LocalStorageService`, they are not needed.
+
+## License
+
+MIT

package/dist/adapters/local_storage_service.d.ts

@@ -0,0 +1,57 @@
+import { StorageService } from '../storage_service.js';
+/**
+ * Local filesystem-based implementation of the StorageService.
+ * Saves files in a configured folder using a timestamp as filename.
+ */
+export declare class LocalStorageService extends StorageService {
+    #private;
+    private baseDir;
+    constructor(baseDir?: string);
+    /**
+     * Saves the given buffer to disk under a unique filename.
+     * @param buffer - Content to save
+     * @param collectorName - Name of the collector (used for folder)
+     * @param extension - Optional file extension (e.g. 'json', 'txt')
+     * @returns Relative path to the saved file
+     */
+    save(buffer: Buffer, collectorName: string, extension?: string): Promise<string>;
+    /**
+     * Retrieves a file as buffer using its relative path.
+     * @param relativePath - Filename previously returned by `save`
+     * @returns File content as Buffer
+     * @throws Error if path traversal is detected
+     */
+    retrieve(relativePath: string): Promise<Buffer>;
+    /**
+     * Deletes a stored file.
+     * @param relativePath - Filename previously returned by `save`
+     * @throws Error if path traversal is detected
+     */
+    delete(relativePath: string): Promise<void>;
+    /**
+     * Saves the given buffer to disk at a specific path (preserves filename).
+     * Unlike save(), this method does not auto-generate a timestamp filename.
+     * @param buffer - Content to save
+     * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
+     * @returns The same relative path that was provided
+     * @throws Error if path traversal is detected
+     */
+    saveWithPath(buffer: Buffer, relativePath: string): Promise<string>;
+    /**
+     * Returns a local file path for the stored file.
+     * Note: For local storage, this returns a relative file path, not an HTTP URL.
+     * In production, use a cloud storage service (OVH, S3) for public URLs.
+     * @param relativePath - The storage path of the file
+     * @returns The file path (relative to baseDir)
+     * @throws Error if path traversal is detected
+     */
+    getPublicUrl(relativePath: string): string;
+    /**
+     * Deletes all files under a given prefix (folder).
+     * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
+     * @returns Number of files deleted
+     * @throws Error if path traversal is detected
+     */
+    deleteByPrefix(prefix: string): Promise<number>;
+}
+//# sourceMappingURL=local_storage_service.d.ts.map

package/dist/adapters/local_storage_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local_storage_service.d.ts","sourceRoot":"","sources":["../../src/adapters/local_storage_service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAItD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;;IAGvC,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAe;IAqB5C;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAetF;;;;;OAKG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrD;;;;OAIG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD;;;;;;;OAOG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUzE;;;;;;;OAOG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAQ1C;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAgCxD"}

package/dist/adapters/local_storage_service.js

@@ -0,0 +1,132 @@
+import { StorageService } from '../storage_service.js';
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Local filesystem-based implementation of the StorageService.
+ * Saves files in a configured folder using a timestamp as filename.
+ */
+export class LocalStorageService extends StorageService {
+    #normalizedBase;
+    constructor(baseDir = 'data') {
+        super();
+        this.baseDir = baseDir;
+        this.#normalizedBase = path.resolve(this.baseDir);
+    }
+    /**
+     * Validates that a path does not escape the base directory (path traversal protection).
+     * @param relativePath - The relative path to validate
+     * @returns The resolved absolute path if valid
+     * @throws Error if path traversal is detected
+     */
+    #validatePath(relativePath) {
+        const resolved = path.resolve(this.#normalizedBase, relativePath);
+        if (!resolved.startsWith(this.#normalizedBase + path.sep) && resolved !== this.#normalizedBase) {
+            throw new Error(`Invalid path: path traversal detected for "${relativePath}"`);
+        }
+        return resolved;
+    }
+    /**
+     * Saves the given buffer to disk under a unique filename.
+     * @param buffer - Content to save
+     * @param collectorName - Name of the collector (used for folder)
+     * @param extension - Optional file extension (e.g. 'json', 'txt')
+     * @returns Relative path to the saved file
+     */
+    async save(buffer, collectorName, extension) {
+        const now = new Date();
+        const timestamp = now.toISOString().replace(/[:.]/g, '-');
+        const folder = collectorName || 'default';
+        const filename = extension ? `${timestamp}.${extension}` : timestamp;
+        const dirPath = path.join(this.baseDir, folder);
+        const filePath = path.join(dirPath, filename);
+        await fs.mkdir(dirPath, { recursive: true });
+        await fs.writeFile(filePath, buffer);
+        // return relative path (e.g., 'mycollector/2025-07-07T15-45-22-456Z.json')
+        return path.join(folder, filename);
+    }
+    /**
+     * Retrieves a file as buffer using its relative path.
+     * @param relativePath - Filename previously returned by `save`
+     * @returns File content as Buffer
+     * @throws Error if path traversal is detected
+     */
+    async retrieve(relativePath) {
+        const filePath = this.#validatePath(relativePath);
+        return fs.readFile(filePath);
+    }
+    /**
+     * Deletes a stored file.
+     * @param relativePath - Filename previously returned by `save`
+     * @throws Error if path traversal is detected
+     */
+    async delete(relativePath) {
+        const filePath = this.#validatePath(relativePath);
+        await fs.rm(filePath, { force: true });
+    }
+    /**
+     * Saves the given buffer to disk at a specific path (preserves filename).
+     * Unlike save(), this method does not auto-generate a timestamp filename.
+     * @param buffer - Content to save
+     * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
+     * @returns The same relative path that was provided
+     * @throws Error if path traversal is detected
+     */
+    async saveWithPath(buffer, relativePath) {
+        const filePath = this.#validatePath(relativePath);
+        const dirPath = path.dirname(filePath);
+        await fs.mkdir(dirPath, { recursive: true });
+        await fs.writeFile(filePath, buffer);
+        return relativePath;
+    }
+    /**
+     * Returns a local file path for the stored file.
+     * Note: For local storage, this returns a relative file path, not an HTTP URL.
+     * In production, use a cloud storage service (OVH, S3) for public URLs.
+     * @param relativePath - The storage path of the file
+     * @returns The file path (relative to baseDir)
+     * @throws Error if path traversal is detected
+     */
+    getPublicUrl(relativePath) {
+        // Validate path to prevent traversal (even though this just returns a string)
+        this.#validatePath(relativePath);
+        // For local storage, return the file path
+        // In a real deployment, you'd need Express static serving or similar
+        return path.join(this.baseDir, relativePath);
+    }
+    /**
+     * Deletes all files under a given prefix (folder).
+     * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
+     * @returns Number of files deleted
+     * @throws Error if path traversal is detected
+     */
+    async deleteByPrefix(prefix) {
+        const folderPath = this.#validatePath(prefix);
+        try {
+            // Check if folder exists
+            await fs.access(folderPath);
+            // Count files before deletion
+            const countFiles = async (dir) => {
+                let count = 0;
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        count += await countFiles(path.join(dir, entry.name));
+                    }
+                    else {
+                        count++;
+                    }
+                }
+                return count;
+            };
+            const fileCount = await countFiles(folderPath);
+            // Delete folder recursively
+            await fs.rm(folderPath, { recursive: true, force: true });
+            return fileCount;
+        }
+        catch {
+            // Folder doesn't exist
+            return 0;
+        }
+    }
+}
+//# sourceMappingURL=local_storage_service.js.map

package/dist/adapters/local_storage_service.js.map

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

package/dist/adapters/ovh_storage_service.d.ts

@@ -0,0 +1,86 @@
+import { StorageService } from '../storage_service.js';
+import type { PresignedUploadResult, ObjectExistsResult } from '../storage_service.js';
+export interface OvhS3Config {
+    accessKey: string;
+    secretKey: string;
+    endpoint: string;
+    region?: string;
+    bucket: string;
+    pathStyle?: boolean;
+}
+export declare class OvhS3StorageService extends StorageService {
+    #private;
+    constructor(config: OvhS3Config);
+    /**
+     * Uploads a file to the OVH S3-compatible object storage.
+     * @param buffer - File contents to upload
+     * @param collectorName - Folder/prefix to store under
+     * @param extension - Optional file extension (e.g. 'json')
+     * @returns The relative path (key) of the stored object
+     */
+    save(buffer: Buffer, collectorName: string, extension?: string): Promise<string>;
+    /**
+     * Downloads and returns a stored object as a Buffer.
+     * @param relativePath - The key/path of the object to retrieve
+     * @returns The object contents as a Buffer
+     */
+    retrieve(relativePath: string): Promise<Buffer>;
+    /**
+     * Deletes an object from the storage bucket.
+     * @param relativePath - The key/path of the object to delete
+     */
+    delete(relativePath: string): Promise<void>;
+    /**
+     * Uploads a file to OVH S3 at a specific path (preserves filename).
+     * Unlike save(), this method does not auto-generate a timestamp filename.
+     * Files are uploaded with public-read ACL for direct access (e.g., Cesium tilesets).
+     * @param buffer - File contents to upload
+     * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
+     * @returns The same relative path that was provided
+     */
+    saveWithPath(buffer: Buffer, relativePath: string): Promise<string>;
+    /**
+     * Deletes multiple objects in batch using S3 DeleteObjects API.
+     * Much faster than individual deletes - can delete up to 1000 objects per request.
+     * @param paths - Array of object keys to delete
+     */
+    deleteBatch(paths: string[]): Promise<void>;
+    /**
+     * Returns the public URL for a stored file.
+     * Constructs the OVH S3 public URL format: https://{bucket}.{endpoint_host}/{key}
+     * @param relativePath - The storage path/key of the file
+     * @returns The public URL to access the file directly
+     */
+    getPublicUrl(relativePath: string): string;
+    /**
+     * Deletes all objects under a given prefix (folder).
+     * Lists objects by prefix and deletes them in batches for performance.
+     * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
+     * @returns Number of files deleted
+     */
+    deleteByPrefix(prefix: string): Promise<number>;
+    /**
+     * This storage backend supports presigned URLs for direct client uploads.
+     */
+    supportsPresignedUrls(): boolean;
+    /**
+     * Generate a presigned PUT URL for direct client-to-S3 uploads.
+     */
+    generatePresignedUploadUrl(key: string, contentType: string, expiresInSeconds?: number): Promise<PresignedUploadResult>;
+    /**
+     * Check if an object exists in the S3 bucket using HeadObject.
+     */
+    objectExists(key: string): Promise<ObjectExistsResult>;
+    /**
+     * Configure CORS settings for the bucket.
+     * Required for browser-based access to public files (e.g., Cesium loading tilesets).
+     * Should be called once during application startup.
+     *
+     * @param allowedOrigins - List of allowed origins (default: ['*'])
+     * @param allowedMethods - List of allowed HTTP methods (default: ['GET', 'HEAD'])
+     * @param allowedHeaders - List of allowed headers (default: ['*', 'Authorization'])
+     * @returns true if successful, false otherwise
+     */
+    configureCors(allowedOrigins?: string[], allowedMethods?: string[], allowedHeaders?: string[]): Promise<boolean>;
+}
+//# sourceMappingURL=ovh_storage_service.d.ts.map

package/dist/adapters/ovh_storage_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ovh_storage_service.d.ts","sourceRoot":"","sources":["../../src/adapters/ovh_storage_service.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAMtF,MAAM,WAAW,WAAW;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,qBAAa,mBAAoB,SAAQ,cAAc;;gBAKvC,MAAM,EAAE,WAAW;IAkB/B;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBtF;;;;OAIG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBrD;;;OAGG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD;;;;;;;OAOG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAazE;;;;OAIG;IACY,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoC1D;;;;;OAKG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAO1C;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0CrD;;OAEG;IACM,qBAAqB,IAAI,OAAO;IAIzC;;OAEG;IACY,0BAA0B,CACrC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,gBAAgB,GAAE,MAAY,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IAajC;;OAEG;IACY,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsBrE;;;;;;;;;OASG;IACG,aAAa,CACf,cAAc,GAAE,MAAM,EAAU,EAChC,cAAc,GAAE,MAAM,EAA2B,EACjD,cAAc,GAAE,MAAM,EAA2B,GAClD,OAAO,CAAC,OAAO,CAAC;CAyBtB"}

package/dist/adapters/ovh_storage_service.js

@@ -0,0 +1,247 @@
+/**
+ * OVH Object Storage implementation of StorageService
+ * via S3-compatible API using @aws-sdk/client-s3
+ */
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, ListObjectsV2Command, HeadObjectCommand, PutBucketCorsCommand, ObjectCannedACL } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { StorageService } from '../storage_service.js';
+import { safeAsync, Logger } from '@cepseudo/shared';
+const logger = new Logger('OvhS3Storage');
+export class OvhS3StorageService extends StorageService {
+    #s3;
+    #bucket;
+    #endpoint;
+    constructor(config) {
+        super();
+        this.#bucket = config.bucket;
+        this.#endpoint = config.endpoint;
+        this.#s3 = new S3Client({
+            endpoint: config.endpoint,
+            region: config.region ?? 'gra',
+            credentials: {
+                accessKeyId: config.accessKey,
+                secretAccessKey: config.secretKey
+            },
+            forcePathStyle: config.pathStyle ?? false,
+            // Match Python boto3 config for OVH compatibility
+            requestChecksumCalculation: 'WHEN_REQUIRED',
+            responseChecksumValidation: 'WHEN_REQUIRED'
+        });
+    }
+    /**
+     * Uploads a file to the OVH S3-compatible object storage.
+     * @param buffer - File contents to upload
+     * @param collectorName - Folder/prefix to store under
+     * @param extension - Optional file extension (e.g. 'json')
+     * @returns The relative path (key) of the stored object
+     */
+    async save(buffer, collectorName, extension) {
+        const now = new Date();
+        const timestamp = now.toISOString().replace(/[:.]/g, '-');
+        const key = `${collectorName || 'default'}/${timestamp}${extension ? '.' + extension : ''}`;
+        await this.#s3.send(new PutObjectCommand({
+            Bucket: this.#bucket,
+            Key: key,
+            Body: buffer,
+            ACL: ObjectCannedACL.private
+        }));
+        return key;
+    }
+    /**
+     * Downloads and returns a stored object as a Buffer.
+     * @param relativePath - The key/path of the object to retrieve
+     * @returns The object contents as a Buffer
+     */
+    async retrieve(relativePath) {
+        const res = await this.#s3.send(new GetObjectCommand({
+            Bucket: this.#bucket,
+            Key: relativePath
+        }));
+        const chunks = [];
+        const stream = res.Body;
+        for await (const chunk of stream) {
+            chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    /**
+     * Deletes an object from the storage bucket.
+     * @param relativePath - The key/path of the object to delete
+     */
+    async delete(relativePath) {
+        await this.#s3.send(new DeleteObjectCommand({
+            Bucket: this.#bucket,
+            Key: relativePath
+        }));
+    }
+    /**
+     * Uploads a file to OVH S3 at a specific path (preserves filename).
+     * Unlike save(), this method does not auto-generate a timestamp filename.
+     * Files are uploaded with public-read ACL for direct access (e.g., Cesium tilesets).
+     * @param buffer - File contents to upload
+     * @param relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
+     * @returns The same relative path that was provided
+     */
+    async saveWithPath(buffer, relativePath) {
+        await this.#s3.send(new PutObjectCommand({
+            Bucket: this.#bucket,
+            Key: relativePath,
+            Body: buffer,
+            ACL: ObjectCannedACL.public_read
+        }));
+        return relativePath;
+    }
+    /**
+     * Deletes multiple objects in batch using S3 DeleteObjects API.
+     * Much faster than individual deletes - can delete up to 1000 objects per request.
+     * @param paths - Array of object keys to delete
+     */
+    async deleteBatch(paths) {
+        if (paths.length === 0)
+            return;
+        // S3 DeleteObjects supports max 1000 objects per request
+        const BATCH_SIZE = 1000;
+        const batches = [];
+        for (let i = 0; i < paths.length; i += BATCH_SIZE) {
+            batches.push(paths.slice(i, i + BATCH_SIZE));
+        }
+        // Process batches in parallel (but limit concurrency to avoid overwhelming the API)
+        const MAX_CONCURRENT = 5;
+        for (let i = 0; i < batches.length; i += MAX_CONCURRENT) {
+            const concurrentBatches = batches.slice(i, i + MAX_CONCURRENT);
+            await Promise.all(concurrentBatches.map((batch, index) => safeAsync(() => this.#s3.send(new DeleteObjectsCommand({
+                Bucket: this.#bucket,
+                Delete: {
+                    Objects: batch.map(key => ({ Key: key })),
+                    Quiet: true // Don't return info about each deleted object
+                }
+            })), `delete batch ${i + index + 1}/${batches.length}`, logger)));
+        }
+    }
+    /**
+     * Returns the public URL for a stored file.
+     * Constructs the OVH S3 public URL format: https://{bucket}.{endpoint_host}/{key}
+     * @param relativePath - The storage path/key of the file
+     * @returns The public URL to access the file directly
+     */
+    getPublicUrl(relativePath) {
+        // Extract host from endpoint (e.g., 'https://s3.gra.io.cloud.ovh.net' -> 's3.gra.io.cloud.ovh.net')
+        const endpointHost = this.#endpoint.replace(/^https?:\/\//, '');
+        // OVH S3 URL format: https://{bucket}.{endpoint_host}/{key}
+        return `https://${this.#bucket}.${endpointHost}/${relativePath}`;
+    }
+    /**
+     * Deletes all objects under a given prefix (folder).
+     * Lists objects by prefix and deletes them in batches for performance.
+     * @param prefix - The folder/prefix to delete (e.g., 'tilesets/123')
+     * @returns Number of files deleted
+     */
+    async deleteByPrefix(prefix) {
+        let totalDeleted = 0;
+        let continuationToken;
+        // Ensure prefix ends with '/' to avoid partial matches
+        const normalizedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+        do {
+            // List objects with prefix (max 1000 per request)
+            const listResponse = await this.#s3.send(new ListObjectsV2Command({
+                Bucket: this.#bucket,
+                Prefix: normalizedPrefix,
+                ContinuationToken: continuationToken
+            }));
+            const objects = listResponse.Contents || [];
+            if (objects.length === 0)
+                break;
+            // Delete objects in batch
+            const keys = objects.map(obj => obj.Key).filter((key) => !!key);
+            if (keys.length > 0) {
+                await this.#s3.send(new DeleteObjectsCommand({
+                    Bucket: this.#bucket,
+                    Delete: {
+                        Objects: keys.map(key => ({ Key: key })),
+                        Quiet: true
+                    }
+                }));
+                totalDeleted += keys.length;
+            }
+            continuationToken = listResponse.NextContinuationToken;
+        } while (continuationToken);
+        return totalDeleted;
+    }
+    /**
+     * This storage backend supports presigned URLs for direct client uploads.
+     */
+    supportsPresignedUrls() {
+        return true;
+    }
+    /**
+     * Generate a presigned PUT URL for direct client-to-S3 uploads.
+     */
+    async generatePresignedUploadUrl(key, contentType, expiresInSeconds = 300) {
+        const command = new PutObjectCommand({
+            Bucket: this.#bucket,
+            Key: key,
+            ContentType: contentType
+        });
+        const url = await getSignedUrl(this.#s3, command, { expiresIn: expiresInSeconds });
+        const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+        return { url, key, expiresAt };
+    }
+    /**
+     * Check if an object exists in the S3 bucket using HeadObject.
+     */
+    async objectExists(key) {
+        try {
+            const response = await this.#s3.send(new HeadObjectCommand({
+                Bucket: this.#bucket,
+                Key: key
+            }));
+            return {
+                exists: true,
+                contentLength: response.ContentLength,
+                contentType: response.ContentType
+            };
+        }
+        catch (error) {
+            const name = error?.name;
+            if (name === 'NotFound' || name === 'NoSuchKey') {
+                return { exists: false };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Configure CORS settings for the bucket.
+     * Required for browser-based access to public files (e.g., Cesium loading tilesets).
+     * Should be called once during application startup.
+     *
+     * @param allowedOrigins - List of allowed origins (default: ['*'])
+     * @param allowedMethods - List of allowed HTTP methods (default: ['GET', 'HEAD'])
+     * @param allowedHeaders - List of allowed headers (default: ['*', 'Authorization'])
+     * @returns true if successful, false otherwise
+     */
+    async configureCors(allowedOrigins = ['*'], allowedMethods = ['GET', 'HEAD', 'PUT'], allowedHeaders = ['*', 'Authorization']) {
+        try {
+            await this.#s3.send(new PutBucketCorsCommand({
+                Bucket: this.#bucket,
+                CORSConfiguration: {
+                    CORSRules: [
+                        {
+                            AllowedOrigins: allowedOrigins,
+                            AllowedMethods: allowedMethods,
+                            AllowedHeaders: allowedHeaders,
+                            ExposeHeaders: ['ETag', 'Content-Length'],
+                            MaxAgeSeconds: 3000
+                        }
+                    ]
+                }
+            }));
+            console.log('[OvhS3StorageService] CORS configured successfully');
+            return true;
+        }
+        catch (error) {
+            console.error('[OvhS3StorageService] Error configuring CORS:', error);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=ovh_storage_service.js.map

package/dist/adapters/ovh_storage_service.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { StorageService } from './storage_service.js';
+export type { PresignedUploadResult, ObjectExistsResult } from './storage_service.js';
+export { StorageServiceFactory } from './storage_factory.js';
+export { LocalStorageService } from './adapters/local_storage_service.js';
+export { OvhS3StorageService } from './adapters/ovh_storage_service.js';
+export type { OvhS3Config } from './adapters/ovh_storage_service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACrF,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAG5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AACvE,YAAY,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Storage service base class and factory
+export { StorageService } from './storage_service.js';
+export { StorageServiceFactory } from './storage_factory.js';
+// Storage adapters
+export { LocalStorageService } from './adapters/local_storage_service.js';
+export { OvhS3StorageService } from './adapters/ovh_storage_service.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,mBAAmB;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA"}

package/dist/storage_factory.d.ts

@@ -0,0 +1,14 @@
+import type { StorageService } from './storage_service.js';
+export declare class StorageServiceFactory {
+    /**
+     * Creates and returns an instance of StorageService
+     * based on the STORAGE_CONFIG environment variable.
+     *
+     * - 'local': returns a LocalStorageService
+     * - 'ovh': returns an OvhS3StorageService
+     *
+     * @throws Error if STORAGE_CONFIG is not supported
+     */
+    static create(): StorageService;
+}
+//# sourceMappingURL=storage_factory.d.ts.map

package/dist/storage_factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage_factory.d.ts","sourceRoot":"","sources":["../src/storage_factory.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAI1D,qBAAa,qBAAqB;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,IAAI,cAAc;CA4BlC"}

package/dist/storage_factory.js

@@ -0,0 +1,41 @@
+/**
+ * Factory class for creating the appropriate StorageService
+ * implementation based on environment configuration.
+ */
+import { Env, safeAsync, Logger } from '@cepseudo/shared';
+import { OvhS3StorageService } from './adapters/ovh_storage_service.js';
+import { LocalStorageService } from './adapters/local_storage_service.js';
+const logger = new Logger('StorageFactory');
+export class StorageServiceFactory {
+    /**
+     * Creates and returns an instance of StorageService
+     * based on the STORAGE_CONFIG environment variable.
+     *
+     * - 'local': returns a LocalStorageService
+     * - 'ovh': returns an OvhS3StorageService
+     *
+     * @throws Error if STORAGE_CONFIG is not supported
+     */
+    static create() {
+        const env = Env.config;
+        switch (env.STORAGE_CONFIG) {
+            case 'local':
+                return new LocalStorageService(env.LOCAL_STORAGE_DIR || 'data');
+            case 'ovh': {
+                const ovhStorage = new OvhS3StorageService({
+                    accessKey: env.OVH_ACCESS_KEY,
+                    secretKey: env.OVH_SECRET_KEY,
+                    endpoint: env.OVH_ENDPOINT,
+                    bucket: env.OVH_BUCKET,
+                    region: env.OVH_REGION ?? 'gra'
+                });
+                // Configure CORS for browser access (non-blocking)
+                safeAsync(() => ovhStorage.configureCors(['*'], ['GET', 'HEAD', 'PUT'], ['*', 'Authorization']), 'configure OVH CORS', logger);
+                return ovhStorage;
+            }
+            default:
+                throw new Error(`Unsupported STORAGE_CONFIG: ${env.STORAGE_CONFIG}`);
+        }
+    }
+}
+//# sourceMappingURL=storage_factory.js.map

package/dist/storage_factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage_factory.js","sourceRoot":"","sources":["../src/storage_factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAA;AAGzE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAA;AAE3C,MAAM,OAAO,qBAAqB;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM;QACT,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAA;QAEtB,QAAQ,GAAG,CAAC,cAAc,EAAE,CAAC;YACzB,KAAK,OAAO;gBACR,OAAO,IAAI,mBAAmB,CAAC,GAAG,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAA;YAEnE,KAAK,KAAK,CAAC,CAAC,CAAC;gBACT,MAAM,UAAU,GAAG,IAAI,mBAAmB,CAAC;oBACvC,SAAS,EAAE,GAAG,CAAC,cAAc;oBAC7B,SAAS,EAAE,GAAG,CAAC,cAAc;oBAC7B,QAAQ,EAAE,GAAG,CAAC,YAAY;oBAC1B,MAAM,EAAE,GAAG,CAAC,UAAU;oBACtB,MAAM,EAAE,GAAG,CAAC,UAAU,IAAI,KAAK;iBAClC,CAAC,CAAA;gBACF,mDAAmD;gBACnD,SAAS,CACL,GAAG,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,EACrF,oBAAoB,EACpB,MAAM,CACT,CAAA;gBACD,OAAO,UAAU,CAAA;YACrB,CAAC;YAED;gBACI,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,cAAc,EAAE,CAAC,CAAA;QAC5E,CAAC;IACL,CAAC;CACJ"}

package/dist/storage_service.d.ts

@@ -0,0 +1,196 @@
+export interface PresignedUploadResult {
+    url: string;
+    key: string;
+    expiresAt: Date;
+}
+export interface ObjectExistsResult {
+    exists: boolean;
+    contentLength?: number;
+    contentType?: string;
+}
+/**
+ * Abstract base class for storage service implementations.
+ *
+ * Defines the contract for persisting and retrieving binary data in the Digital Twin framework.
+ * Concrete implementations provide storage backends like local filesystem, AWS S3, Azure Blob, etc.
+ *
+ * @abstract
+ * @class StorageService
+ *
+ * @example
+ * ```typescript
+ * // Implement for specific storage backend
+ * class S3StorageService extends StorageService {
+ *   async save(buffer: Buffer, collectorName: string, extension?: string): Promise<string> {
+ *     // Upload to S3 bucket
+ *     return 's3://bucket/path/to/file'
+ *   }
+ *
+ *   async retrieve(path: string): Promise<Buffer> {
+ *     // Download from S3
+ *     return buffer
+ *   }
+ *
+ *   async delete(path: string): Promise<void> {
+ *     // Delete from S3
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StorageService {
+    /**
+     * Persists binary data and returns a unique identifier for retrieval.
+     *
+     * The storage implementation should ensure the returned path/URL is unique
+     * and can be used later to retrieve the exact same data.
+     *
+     * @abstract
+     * @param {Buffer} buffer - Binary data to store
+     * @param {string} collectorName - Component name for organizing storage (used as folder/prefix)
+     * @param {string} extension - Optional file extension for proper content handling
+     * @returns {Promise<string>} Unique storage identifier (path, URL, or key)
+     * @throws {Error} When storage operation fails
+     *
+     * @example
+     * ```typescript
+     * const buffer = Buffer.from('{"temperature": 23.5}')
+     * const path = await storage.save(buffer, 'weather-sensor', 'json')
+     * // Returns: '/storage/weather-sensor/2024-01-15_14-30-00.json'
+     * ```
+     */
+    abstract save(buffer: Buffer, collectorName: string, extension?: string): Promise<string>;
+    /**
+     * Retrieves previously stored binary data.
+     *
+     * Uses the identifier returned by save() to fetch the original data.
+     *
+     * @abstract
+     * @param {string} path - Storage identifier from save() operation
+     * @returns {Promise<Buffer>} The original binary data
+     * @throws {Error} When file doesn't exist or retrieval fails
+     *
+     * @example
+     * ```typescript
+     * const path = '/storage/weather-sensor/2024-01-15_14-30-00.json'
+     * const data = await storage.retrieve(path)
+     * const json = JSON.parse(data.toString())
+     * ```
+     */
+    abstract retrieve(path: string): Promise<Buffer>;
+    /**
+     * Removes stored data permanently.
+     *
+     * Deletes the data associated with the given storage identifier.
+     *
+     * @abstract
+     * @param {string} path - Storage identifier from save() operation
+     * @returns {Promise<void>}
+     * @throws {Error} When deletion fails or path doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const path = '/storage/weather-sensor/old-data.json'
+     * await storage.delete(path)
+     * ```
+     */
+    abstract delete(path: string): Promise<void>;
+    /**
+     * Persists binary data at a specific path (no auto-generated filename).
+     *
+     * Unlike save(), this method stores the file at the exact path specified,
+     * preserving the original filename and directory structure.
+     * Useful for extracting archives where file paths must be preserved.
+     *
+     * @param {Buffer} buffer - Binary data to store
+     * @param {string} relativePath - Full relative path including filename (e.g., 'tilesets/123/tileset.json')
+     * @returns {Promise<string>} The same path that was provided (for consistency)
+     * @throws {Error} When storage operation fails
+     *
+     * @example
+     * ```typescript
+     * const buffer = Buffer.from('{"asset": {"version": "1.0"}}')
+     * const path = await storage.saveWithPath(buffer, 'tilesets/123/tileset.json')
+     * // Returns: 'tilesets/123/tileset.json'
+     * ```
+     */
+    abstract saveWithPath(buffer: Buffer, relativePath: string): Promise<string>;
+    /**
+     * Deletes multiple files in batch for better performance.
+     *
+     * Default implementation calls delete() sequentially, but storage backends
+     * can override this with optimized bulk delete operations (e.g., S3 DeleteObjects).
+     *
+     * @param {string[]} paths - Array of storage identifiers to delete
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await storage.deleteBatch([
+     *   'tilesets/123/tileset.json',
+     *   'tilesets/123/tile_0.b3dm',
+     *   'tilesets/123/tile_1.b3dm'
+     * ])
+     * ```
+     */
+    deleteBatch(paths: string[]): Promise<void>;
+    /**
+     * Returns the public URL for a stored file.
+     *
+     * For cloud storage (S3, OVH, Azure), this returns the direct HTTP URL.
+     * For local storage, this may return a relative path or throw an error.
+     *
+     * @abstract
+     * @param {string} relativePath - The storage path/key of the file
+     * @returns {string} The public URL to access the file directly
+     *
+     * @example
+     * ```typescript
+     * const url = storage.getPublicUrl('tilesets/123/tileset.json')
+     * // Returns: 'https://bucket.s3.region.cloud.ovh.net/tilesets/123/tileset.json'
+     * ```
+     */
+    abstract getPublicUrl(relativePath: string): string;
+    /**
+     * Deletes all files under a given prefix/folder.
+     *
+     * This is more efficient than deleteBatch() when you don't know all file paths,
+     * as it lists objects by prefix and deletes them in bulk.
+     * Useful for deleting entire tilesets or component data.
+     *
+     * @abstract
+     * @param {string} prefix - The folder/prefix to delete (e.g., 'tilesets/123')
+     * @returns {Promise<number>} Number of files deleted
+     *
+     * @example
+     * ```typescript
+     * const count = await storage.deleteByPrefix('tilesets/123')
+     * // Deletes all files starting with 'tilesets/123/'
+     * console.log(`Deleted ${count} files`)
+     * ```
+     */
+    abstract deleteByPrefix(prefix: string): Promise<number>;
+    /**
+     * Whether this storage backend supports presigned URLs for direct uploads.
+     * Override in subclasses that support presigned URLs (e.g., S3-compatible storage).
+     */
+    supportsPresignedUrls(): boolean;
+    /**
+     * Generate a presigned PUT URL for direct client-to-storage uploads.
+     * Override in subclasses that support presigned URLs.
+     *
+     * @param key - The object key (path) in storage
+     * @param contentType - MIME type of the file to upload
+     * @param expiresInSeconds - URL validity duration (default: 300s = 5min)
+     * @returns Presigned upload URL, key, and expiration date
+     */
+    generatePresignedUploadUrl(_key: string, _contentType: string, _expiresInSeconds?: number): Promise<PresignedUploadResult>;
+    /**
+     * Check if an object exists in storage and return its metadata.
+     * Override in subclasses that support presigned URLs.
+     *
+     * @param key - The object key (path) in storage
+     * @returns Whether the object exists, with optional size and content type
+     */
+    objectExists(_key: string): Promise<ObjectExistsResult>;
+}
+//# sourceMappingURL=storage_service.d.ts.map

package/dist/storage_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage_service.d.ts","sourceRoot":"","sources":["../src/storage_service.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,qBAAqB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,cAAc;IAChC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAEzF;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAEhD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAE5E;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAEnD;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAExD;;;OAGG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;;;;;;;OAQG;IACG,0BAA0B,CAC5B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,iBAAiB,GAAE,MAAY,GAChC,OAAO,CAAC,qBAAqB,CAAC;IAIjC;;;;;;OAMG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGhE"}

package/dist/storage_service.js

@@ -0,0 +1,86 @@
+import { safeAsync, Logger } from '@cepseudo/shared';
+const logger = new Logger('StorageService');
+/**
+ * Abstract base class for storage service implementations.
+ *
+ * Defines the contract for persisting and retrieving binary data in the Digital Twin framework.
+ * Concrete implementations provide storage backends like local filesystem, AWS S3, Azure Blob, etc.
+ *
+ * @abstract
+ * @class StorageService
+ *
+ * @example
+ * ```typescript
+ * // Implement for specific storage backend
+ * class S3StorageService extends StorageService {
+ *   async save(buffer: Buffer, collectorName: string, extension?: string): Promise<string> {
+ *     // Upload to S3 bucket
+ *     return 's3://bucket/path/to/file'
+ *   }
+ *
+ *   async retrieve(path: string): Promise<Buffer> {
+ *     // Download from S3
+ *     return buffer
+ *   }
+ *
+ *   async delete(path: string): Promise<void> {
+ *     // Delete from S3
+ *   }
+ * }
+ * ```
+ */
+export class StorageService {
+    /**
+     * Deletes multiple files in batch for better performance.
+     *
+     * Default implementation calls delete() sequentially, but storage backends
+     * can override this with optimized bulk delete operations (e.g., S3 DeleteObjects).
+     *
+     * @param {string[]} paths - Array of storage identifiers to delete
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await storage.deleteBatch([
+     *   'tilesets/123/tileset.json',
+     *   'tilesets/123/tile_0.b3dm',
+     *   'tilesets/123/tile_1.b3dm'
+     * ])
+     * ```
+     */
+    async deleteBatch(paths) {
+        // Default parallel implementation - subclasses can override with bulk operations
+        // Individual failures are logged but don't prevent other deletions
+        await Promise.all(paths.map(path => safeAsync(() => this.delete(path), `delete file ${path}`, logger)));
+    }
+    /**
+     * Whether this storage backend supports presigned URLs for direct uploads.
+     * Override in subclasses that support presigned URLs (e.g., S3-compatible storage).
+     */
+    supportsPresignedUrls() {
+        return false;
+    }
+    /**
+     * Generate a presigned PUT URL for direct client-to-storage uploads.
+     * Override in subclasses that support presigned URLs.
+     *
+     * @param key - The object key (path) in storage
+     * @param contentType - MIME type of the file to upload
+     * @param expiresInSeconds - URL validity duration (default: 300s = 5min)
+     * @returns Presigned upload URL, key, and expiration date
+     */
+    async generatePresignedUploadUrl(_key, _contentType, _expiresInSeconds = 300) {
+        throw new Error('Presigned URLs are not supported by this storage backend');
+    }
+    /**
+     * Check if an object exists in storage and return its metadata.
+     * Override in subclasses that support presigned URLs.
+     *
+     * @param key - The object key (path) in storage
+     * @returns Whether the object exists, with optional size and content type
+     */
+    async objectExists(_key) {
+        throw new Error('Object existence check is not supported by this storage backend');
+    }
+}
+//# sourceMappingURL=storage_service.js.map

package/dist/storage_service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage_service.js","sourceRoot":"","sources":["../src/storage_service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAA;AAc3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAgB,cAAc;IAiFhC;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,WAAW,CAAC,KAAe;QAC7B,iFAAiF;QACjF,mEAAmE;QACnE,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,eAAe,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAC3G,CAAC;IAwCD;;;OAGG;IACH,qBAAqB;QACjB,OAAO,KAAK,CAAA;IAChB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,0BAA0B,CAC5B,IAAY,EACZ,YAAoB,EACpB,oBAA4B,GAAG;QAE/B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;IAC/E,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY;QAC3B,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAA;IACtF,CAAC;CACJ"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@cepseudo/storage",
+  "version": "1.0.0",
+  "description": "Storage service abstraction for Digital Twin framework (local filesystem, OVH S3)",
+  "license": "MIT",
+  "author": "Axel Hoffmann",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "test": "node -r ./bin/set-test-env.cjs --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
+    "lint": "eslint src tests --no-error-on-unmatched-pattern",
+    "lint:fix": "eslint src tests --fix --no-error-on-unmatched-pattern"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@cepseudo/shared": "workspace:*"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "@aws-sdk/s3-request-presigner": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1002.0",
+    "@aws-sdk/s3-request-presigner": "^3.1002.0",
+    "@japa/assert": "^4.1.0",
+    "@japa/runner": "^4.3.0",
+    "testcontainers": "^10.0.0",
+    "ts-node-maintained": "^10.9.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CePseudoBE/digitaltwin.git",
+    "directory": "packages/storage"
+  },
+  "keywords": [
+    "digitaltwin",
+    "storage",
+    "s3",
+    "ovh",
+    "presigned-url"
+  ],
+  "bugs": {
+    "url": "https://github.com/CePseudoBE/digitaltwin/issues"
+  },
+  "homepage": "https://github.com/CePseudoBE/digitaltwin#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}