@volcanicminds/tools 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * as mfa from './lib/mfa/index.js';
 export * as mailer from './lib/mailer/index.js';
 export * as log from './lib/util/logger.js';
+export * as storage from './lib/storage/index.js';
+export * as transfer from './lib/transfer/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA;AAC3C,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -1,4 +1,6 @@
 export * as mfa from './lib/mfa/index.js';
 export * as mailer from './lib/mailer/index.js';
 export * as log from './lib/util/logger.js';
+export * as storage from './lib/storage/index.js';
+export * as transfer from './lib/transfer/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA;AAC3C,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA"}

package/dist/lib/storage/index.d.ts

@@ -0,0 +1,40 @@
+import { Client, BucketItemStat } from 'minio';
+import { Readable } from 'stream';
+export interface StorageConfig {
+    endPoint: string;
+    port: number;
+    useSSL: boolean;
+    accessKey: string;
+    secretKey: string;
+    bucket: string;
+    region?: string;
+    pathStyle?: boolean;
+}
+export interface UploadOptions {
+    size?: number;
+    contentType?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface UploadedObjectInfo {
+    etag: string;
+    versionId: string | null;
+}
+export declare class StorageManager {
+    private client;
+    private bucket;
+    private region;
+    constructor(config: StorageConfig);
+    getClient(): Client;
+    getBucketName(): string;
+    verifyConnection(): Promise<boolean>;
+    ensureBucket(bucketName?: string): Promise<void>;
+    uploadFile(objectName: string, stream: Readable | Buffer | string, options?: UploadOptions): Promise<UploadedObjectInfo>;
+    getFileUrl(objectName: string, expiry?: number): Promise<string>;
+    getUploadUrl(objectName: string, expiry?: number): Promise<string>;
+    deleteFile(objectName: string): Promise<void>;
+    deleteFiles(objectNames: string[]): Promise<void>;
+    fileExists(objectName: string): Promise<boolean>;
+    getFileStream(objectName: string): Promise<Readable>;
+    getFileStat(objectName: string): Promise<BucketItemStat>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqC,cAAc,EAAE,MAAM,OAAO,CAAA;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CACrD;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAQ;gBAEV,MAAM,EAAE,aAAa;IAiB1B,SAAS,IAAI,MAAM;IAInB,aAAa,IAAI,MAAM;IAIjB,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAUpC,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhD,UAAU,CACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EAClC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;IAgBjB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9E,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhF,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIpD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAGtE"}

package/dist/lib/storage/index.js

@@ -0,0 +1,84 @@
+import { Client } from 'minio';
+export class StorageManager {
+    client;
+    bucket;
+    region;
+    constructor(config) {
+        this.bucket = config.bucket;
+        this.region = config.region || 'us-east-1';
+        const clientOptions = {
+            endPoint: config.endPoint,
+            port: config.port,
+            useSSL: config.useSSL,
+            accessKey: config.accessKey,
+            secretKey: config.secretKey,
+            region: this.region,
+            pathStyle: config.pathStyle
+        };
+        this.client = new Client(clientOptions);
+    }
+    getClient() {
+        return this.client;
+    }
+    getBucketName() {
+        return this.bucket;
+    }
+    async verifyConnection() {
+        try {
+            await this.client.listBuckets();
+            return true;
+        }
+        catch (error) {
+            console.error('Storage connection verification failed:', error);
+            return false;
+        }
+    }
+    async ensureBucket(bucketName) {
+        const targetBucket = bucketName || this.bucket;
+        try {
+            const exists = await this.client.bucketExists(targetBucket);
+            if (!exists) {
+                await this.client.makeBucket(targetBucket, this.region);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to ensure bucket ${targetBucket}: ${error}`);
+        }
+    }
+    async uploadFile(objectName, stream, options = {}) {
+        await this.ensureBucket();
+        const metaData = options.metadata || {};
+        return this.client.putObject(this.bucket, objectName, stream, options.size, metaData);
+    }
+    async getFileUrl(objectName, expiry = 24 * 60 * 60) {
+        return this.client.presignedGetObject(this.bucket, objectName, expiry);
+    }
+    async getUploadUrl(objectName, expiry = 24 * 60 * 60) {
+        return this.client.presignedPutObject(this.bucket, objectName, expiry);
+    }
+    async deleteFile(objectName) {
+        await this.client.removeObject(this.bucket, objectName);
+    }
+    async deleteFiles(objectNames) {
+        await this.client.removeObjects(this.bucket, objectNames);
+    }
+    async fileExists(objectName) {
+        try {
+            await this.client.statObject(this.bucket, objectName);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'NotFound') {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async getFileStream(objectName) {
+        return this.client.getObject(this.bucket, objectName);
+    }
+    async getFileStat(objectName) {
+        return this.client.statObject(this.bucket, objectName);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/storage/index.js.map

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

package/dist/lib/transfer/index.d.ts

@@ -0,0 +1,36 @@
+import { Server, Upload } from '@tus/server';
+import type { IncomingMessage, ServerResponse } from 'http';
+export interface TransferConfig {
+    driver: 'local' | 's3';
+    maxSize?: number;
+    path: string;
+    local?: {
+        directory: string;
+    };
+    s3?: {
+        bucket: string;
+        endPoint: string;
+        port?: number;
+        useSSL?: boolean;
+        accessKey: string;
+        secretKey: string;
+        region?: string;
+        partSize?: number;
+    };
+}
+export type TransferEventCallback = (uploadOrId: Upload | string, req?: IncomingMessage, res?: ServerResponse) => void;
+export type TransferValidator = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare class TransferManager {
+    private server;
+    private config;
+    private validator;
+    constructor(config: TransferConfig);
+    setValidator(validator: TransferValidator): void;
+    private createStore;
+    getServer(): Server;
+    onUploadCreate(callback: TransferEventCallback): void;
+    onUploadFinish(callback: TransferEventCallback): void;
+    onUploadTerminate(callback: TransferEventCallback): void;
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/transfer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/transfer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAU,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAE3D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IAGZ,KAAK,CAAC,EAAE;QACN,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;IAGD,EAAE,CAAC,EAAE;QACH,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;QACjB,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,CAAA;CACF;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,cAAc,KAAK,IAAI,CAAA;AACtH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE5F,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAiC;gBAEtC,MAAM,EAAE,cAAc;IAiB3B,YAAY,CAAC,SAAS,EAAE,iBAAiB;IAIhD,OAAO,CAAC,WAAW;IAsCZ,SAAS,IAAI,MAAM;IAMnB,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAMrD,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAMrD,iBAAiB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAQxD,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxE"}

package/dist/lib/transfer/index.js

@@ -0,0 +1,80 @@
+import { Server, EVENTS } from '@tus/server';
+import { FileStore } from '@tus/file-store';
+import { S3Store } from '@tus/s3-store';
+export class TransferManager {
+    server;
+    config;
+    validator = null;
+    constructor(config) {
+        this.config = config;
+        const store = this.createStore();
+        this.server = new Server({
+            path: config.path,
+            datastore: store,
+            maxSize: config.maxSize,
+            respectForwardedHeaders: true,
+            onIncomingRequest: async (req, res) => {
+                if (this.validator) {
+                    await this.validator(req, res);
+                }
+            }
+        });
+    }
+    setValidator(validator) {
+        this.validator = validator;
+    }
+    createStore() {
+        if (this.config.driver === 'local') {
+            if (!this.config.local?.directory) {
+                throw new Error('TransferManager: Local driver requires "directory" path');
+            }
+            return new FileStore({
+                directory: this.config.local.directory
+            });
+        }
+        if (this.config.driver === 's3') {
+            if (!this.config.s3) {
+                throw new Error('TransferManager: S3 driver requires s3 config object');
+            }
+            const { endPoint, port, useSSL, accessKey, secretKey, bucket, region, partSize } = this.config.s3;
+            const protocol = useSSL ? 'https:' : 'http:';
+            const endpointUrl = port ? `${protocol}//${endPoint}:${port}` : `${protocol}//${endPoint}`;
+            return new S3Store({
+                partSize: partSize || 8 * 1024 * 1024,
+                s3ClientConfig: {
+                    bucket: bucket,
+                    region: region || 'us-east-1',
+                    endpoint: endpointUrl,
+                    credentials: {
+                        accessKeyId: accessKey,
+                        secretAccessKey: secretKey
+                    },
+                    forcePathStyle: true
+                }
+            });
+        }
+        throw new Error(`TransferManager: Unsupported driver ${this.config.driver}`);
+    }
+    getServer() {
+        return this.server;
+    }
+    onUploadCreate(callback) {
+        this.server.on(EVENTS.POST_CREATE, (req, res, upload) => {
+            callback(upload, req, res);
+        });
+    }
+    onUploadFinish(callback) {
+        this.server.on(EVENTS.POST_FINISH, (req, res, upload) => {
+            callback(upload, req, res);
+        });
+    }
+    onUploadTerminate(callback) {
+        this.server.on(EVENTS.POST_TERMINATE, (req, res, id) => {
+            callback(id, req, res);
+        });
+    }
+    handle(req, res) {
+        return this.server.handle(req, res);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/transfer/index.js.map

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

package/lib/storage/index.ts

@@ -0,0 +1,135 @@
+import { Client, ClientOptions, ItemBucketMetadata, BucketItemStat } from 'minio'
+import { Readable } from 'stream'
+
+export interface StorageConfig {
+  endPoint: string
+  port: number
+  useSSL: boolean
+  accessKey: string
+  secretKey: string
+  bucket: string
+  region?: string
+  pathStyle?: boolean
+}
+
+export interface UploadOptions {
+  size?: number
+  contentType?: string
+  metadata?: Record<string, string | number | boolean>
+}
+
+// Definizione manuale del tipo di ritorno di putObject
+// Necessario perché @types/minio non esporta 'UploadedObjectInfo' o 'Result' pubblicamente
+export interface UploadedObjectInfo {
+  etag: string
+  versionId: string | null
+}
+
+export class StorageManager {
+  private client: Client
+  private bucket: string
+  private region: string
+
+  constructor(config: StorageConfig) {
+    this.bucket = config.bucket
+    this.region = config.region || 'us-east-1'
+
+    const clientOptions: ClientOptions = {
+      endPoint: config.endPoint,
+      port: config.port,
+      useSSL: config.useSSL,
+      accessKey: config.accessKey,
+      secretKey: config.secretKey,
+      region: this.region,
+      pathStyle: config.pathStyle
+    }
+
+    this.client = new Client(clientOptions)
+  }
+
+  public getClient(): Client {
+    return this.client
+  }
+
+  public getBucketName(): string {
+    return this.bucket
+  }
+
+  public async verifyConnection(): Promise<boolean> {
+    try {
+      await this.client.listBuckets()
+      return true
+    } catch (error) {
+      console.error('Storage connection verification failed:', error)
+      return false
+    }
+  }
+
+  public async ensureBucket(bucketName?: string): Promise<void> {
+    const targetBucket = bucketName || this.bucket
+    try {
+      const exists = await this.client.bucketExists(targetBucket)
+      if (!exists) {
+        await this.client.makeBucket(targetBucket, this.region)
+      }
+    } catch (error) {
+      throw new Error(`Failed to ensure bucket ${targetBucket}: ${error}`)
+    }
+  }
+
+  public async uploadFile(
+    objectName: string,
+    stream: Readable | Buffer | string,
+    options: UploadOptions = {}
+  ): Promise<UploadedObjectInfo> {
+    await this.ensureBucket()
+
+    const metaData = options.metadata || {}
+
+    // Casting a any/Promise<UploadedObjectInfo> per compatibilità TS
+    // putObject ritorna un oggetto compatibile con l'interfaccia definita sopra
+    return this.client.putObject(
+      this.bucket,
+      objectName,
+      stream,
+      options.size,
+      metaData as ItemBucketMetadata
+    ) as Promise<UploadedObjectInfo>
+  }
+
+  public async getFileUrl(objectName: string, expiry: number = 24 * 60 * 60): Promise<string> {
+    return this.client.presignedGetObject(this.bucket, objectName, expiry)
+  }
+
+  public async getUploadUrl(objectName: string, expiry: number = 24 * 60 * 60): Promise<string> {
+    return this.client.presignedPutObject(this.bucket, objectName, expiry)
+  }
+
+  public async deleteFile(objectName: string): Promise<void> {
+    await this.client.removeObject(this.bucket, objectName)
+  }
+
+  public async deleteFiles(objectNames: string[]): Promise<void> {
+    await this.client.removeObjects(this.bucket, objectNames)
+  }
+
+  public async fileExists(objectName: string): Promise<boolean> {
+    try {
+      await this.client.statObject(this.bucket, objectName)
+      return true
+    } catch (error: any) {
+      if (error.code === 'NotFound') {
+        return false
+      }
+      throw error
+    }
+  }
+
+  public async getFileStream(objectName: string): Promise<Readable> {
+    return this.client.getObject(this.bucket, objectName)
+  }
+
+  public async getFileStat(objectName: string): Promise<BucketItemStat> {
+    return this.client.statObject(this.bucket, objectName)
+  }
+}

package/lib/transfer/index.ts

@@ -0,0 +1,125 @@
+import { Server, EVENTS, Upload } from '@tus/server'
+import { FileStore } from '@tus/file-store'
+import { S3Store } from '@tus/s3-store'
+import type { IncomingMessage, ServerResponse } from 'http'
+
+export interface TransferConfig {
+  driver: 'local' | 's3'
+  maxSize?: number // Bytes
+  path: string // URL Path prefix (e.g. /files)
+
+  // Local Config
+  local?: {
+    directory: string
+  }
+
+  // S3/Minio Config
+  s3?: {
+    bucket: string
+    endPoint: string
+    port?: number
+    useSSL?: boolean
+    accessKey: string
+    secretKey: string
+    region?: string
+    partSize?: number // Minimum 5MB for S3
+  }
+}
+
+export type TransferEventCallback = (uploadOrId: Upload | string, req?: IncomingMessage, res?: ServerResponse) => void
+export type TransferValidator = (req: IncomingMessage, res: ServerResponse) => Promise<void>
+
+export class TransferManager {
+  private server: Server
+  private config: TransferConfig
+  private validator: TransferValidator | null = null
+
+  constructor(config: TransferConfig) {
+    this.config = config
+    const store = this.createStore()
+
+    this.server = new Server({
+      path: config.path,
+      datastore: store,
+      maxSize: config.maxSize,
+      respectForwardedHeaders: true,
+      onIncomingRequest: async (req, res) => {
+        if (this.validator) {
+          await this.validator(req as unknown as IncomingMessage, res as unknown as ServerResponse)
+        }
+      }
+    })
+  }
+
+  public setValidator(validator: TransferValidator) {
+    this.validator = validator
+  }
+
+  private createStore() {
+    if (this.config.driver === 'local') {
+      if (!this.config.local?.directory) {
+        throw new Error('TransferManager: Local driver requires "directory" path')
+      }
+      return new FileStore({
+        directory: this.config.local.directory
+      })
+    }
+
+    if (this.config.driver === 's3') {
+      if (!this.config.s3) {
+        throw new Error('TransferManager: S3 driver requires s3 config object')
+      }
+
+      const { endPoint, port, useSSL, accessKey, secretKey, bucket, region, partSize } = this.config.s3
+
+      const protocol = useSSL ? 'https:' : 'http:'
+      const endpointUrl = port ? `${protocol}//${endPoint}:${port}` : `${protocol}//${endPoint}`
+
+      return new S3Store({
+        partSize: partSize || 8 * 1024 * 1024,
+        s3ClientConfig: {
+          bucket: bucket, // Required inside s3ClientConfig by @tus/s3-store types
+          region: region || 'us-east-1',
+          endpoint: endpointUrl,
+          credentials: {
+            accessKeyId: accessKey,
+            secretAccessKey: secretKey
+          },
+          forcePathStyle: true
+        }
+      })
+    }
+
+    throw new Error(`TransferManager: Unsupported driver ${this.config.driver}`)
+  }
+
+  public getServer(): Server {
+    return this.server
+  }
+
+  // Hook system wrappers with double casting (as unknown) to bypass TS structural check
+
+  public onUploadCreate(callback: TransferEventCallback): void {
+    this.server.on(EVENTS.POST_CREATE, (req, res, upload) => {
+      callback(upload, req as unknown as IncomingMessage, res as unknown as ServerResponse)
+    })
+  }
+
+  public onUploadFinish(callback: TransferEventCallback): void {
+    this.server.on(EVENTS.POST_FINISH, (req, res, upload) => {
+      callback(upload, req as unknown as IncomingMessage, res as unknown as ServerResponse)
+    })
+  }
+
+  public onUploadTerminate(callback: TransferEventCallback): void {
+    // Note: POST_TERMINATE passes 'id' (string) instead of 'upload' object in recent tus versions
+    this.server.on(EVENTS.POST_TERMINATE, (req, res, id) => {
+      callback(id, req as unknown as IncomingMessage, res as unknown as ServerResponse)
+    })
+  }
+
+  // Handle Request helper
+  public handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    return this.server.handle(req, res)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanicminds/tools",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Tools for the volcanic (minds) backend",
   "keywords": [
     "volcanic",
@@ -12,7 +12,13 @@
     "otp",
     "totp",
     "mailer",
-    "nodemailer"
+    "nodemailer",
+    "storage",
+    "minio",
+    "s3",
+    "tus",
+    "upload",
+    "transfer"
   ],
   "homepage": "https://volcanicminds.com",
   "bugs": {
@@ -52,6 +58,16 @@
       "types": "./dist/lib/util/logger.d.ts",
       "import": "./dist/lib/util/logger.js",
       "require": "./dist/lib/util/logger.js"
+    },
+    "./storage": {
+      "types": "./dist/lib/storage/index.d.ts",
+      "import": "./dist/lib/storage/index.js",
+      "require": "./dist/lib/storage/index.js"
+    },
+    "./transfer": {
+      "types": "./dist/lib/transfer/index.d.ts",
+      "import": "./dist/lib/transfer/index.js",
+      "require": "./dist/lib/transfer/index.js"
     }
   },
   "main": "dist/index.js",
@@ -76,20 +92,26 @@
     "combine": "node combine.js"
   },
   "dependencies": {
-    "nodemailer": "^6.10.1",
-    "otpauth": "^9.3.5",
+    "@aws-sdk/client-s3": "^3.954.0",
+    "@tus/file-store": "^2.0.0",
+    "@tus/s3-store": "^2.0.1",
+    "@tus/server": "^2.3.0",
+    "minio": "^8.0.6",
+    "nodemailer": "^7.0.11",
+    "otpauth": "^9.4.1",
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.1",
-    "@types/nodemailer": "^6.4.14",
-    "@types/qrcode": "^1.5.5",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^9.39.2",
+    "@types/minio": "^7.1.1",
+    "@types/node": "^25.0.3",
+    "@types/nodemailer": "^7.0.4",
+    "@types/qrcode": "^1.5.6",
+    "eslint": "^9.39.2",
     "globals": "^16.5.0",
-    "tsx": "^4.19.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.48.0"
+    "typescript-eslint": "^8.50.0"
   },
   "engines": {
     "node": ">=24"
@@ -109,6 +131,12 @@
       ],
       "logger": [
         "dist/lib/util/logger.d.ts"
+      ],
+      "storage": [
+        "dist/lib/storage/index.d.ts"
+      ],
+      "transfer": [
+        "dist/lib/transfer/index.d.ts"
       ]
     }
   }