@volcanicminds/tools 0.0.3 → 0.0.5

package/README.md

@@ -19,46 +19,120 @@ npm install @volcanicminds/tools
 npm run upgrade-deps
 ```
 
-## Environment
-
-```bash
-# or automatically use LOG_LEVEL
-SOME_KEY=true
-```
-
 ## Usage
 
-This package supports both root imports and sub-path imports to optimize bundle size.
-
-### Import everything
-
-```typescript
-import { mfa, log } from '@volcanicminds/tools'
-```
+This package supports both root imports and sub-path imports to optimize bundle size and tree-shaking.
 
-### Import specific features (Recommended for smaller bundles)
+### Import specific features (Recommended)
 
 ```typescript
 import * as mfa from '@volcanicminds/tools/mfa'
+import { Mailer } from '@volcanicminds/tools/mailer'
 import * as logger from '@volcanicminds/tools/logger'
 ```
 
+---
+
 ## Features
 
 ### MFA (Multi-Factor Authentication)
 
-Utilities for generating secrets, QR codes, and verifying TOTP tokens.
+Utilities for generating secrets, QR codes, and verifying TOTP tokens based on `otpauth`.
 
 ```typescript
 import * as mfa from '@volcanicminds/tools/mfa'
 
-// Generate Setup
-const { secret, uri, qrCode } = await mfa.generateSetupDetails('MyApp', 'user@example.com')
+// 1. Generate a generic base32 secret (Optional, useful if you need to store it before setup)
+const secret = mfa.generateSecret()
+
+// 2. Generate Setup Details for the User (returns secret, otpauth URI, and QR Code Data URL)
+// If secret is omitted, a new one is generated automatically.
+const setup = await mfa.generateSetupDetails('MyApp', 'user@example.com', secret)
+
+console.log(setup.secret) // Save this to DB
+console.log(setup.qrCode) // Send this to Frontend to display QR
+
+// 3. Verify a Token provided by the user
+const userToken = '123456' // From input
+const isValid = mfa.verifyToken(userToken, setup.secret)
 
-// Verify Token
-const isValid = mfa.verifyToken('123456', secret)
+if (isValid) {
+  // Proceed with login/action
+}
+
+// 4. Generate a valid token (Useful for testing or recovery codes)
+const currentToken = mfa.generateToken(setup.secret)
 ```
 
-## Logging
+---
+
+### Mailer
+
+A wrapper around `nodemailer` designed for simplicity and configuration injection. It automatically handles HTML-to-Text conversion if the text body is missing.
 
-Use Pino logger if in your project you have a `global.log` with a valid instance.
+#### Configuration & Initialization
+
+```typescript
+import { Mailer } from '@volcanicminds/tools/mailer'
+
+// Initialize with a config object (not bound to process.env)
+const mailer = new Mailer({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false, // true for 465, false for other ports
+  auth: {
+    user: 'my-user',
+    pass: 'my-password'
+  },
+  defaultFrom: '"My Service" <noreply@example.com>', // Optional: used if not specified in send()
+  defaultReplyTo: 'support@example.com' // Optional
+})
+
+// Optional: Verify connection on startup
+const isConnected = await mailer.verifyConnection()
+if (isConnected) console.log('SMTP Ready')
+```
+
+#### Sending Emails
+
+```typescript
+try {
+  const info = await mailer.send({
+    // Optional if defaultFrom is set in config, otherwise Mandatory
+    from: '"Support Team" <support@example.com>',
+
+    to: 'user@destination.com', // Can be a string or array of strings
+    cc: ['manager@destination.com'],
+    subject: 'Welcome to Volcanic Tools',
+
+    // Text version is automatically generated from HTML if omitted,
+    // converting <br> to newlines and stripping tags.
+    text: 'Hello, World! Welcome aboard.',
+    html: '<p>Hello, <strong>World</strong>!<br/>Welcome aboard.</p>',
+
+    attachments: [
+      {
+        filename: 'license.txt',
+        content: 'MIT License...'
+      }
+    ]
+  })
+
+  console.log('Message sent: %s', info.messageId)
+} catch (error) {
+  console.error('Error sending email:', error)
+}
+```
+
+---
+
+### Logging
+
+Use Pino logger wrapper if in your project you have a `global.log` with a valid instance.
+
+```typescript
+import * as log from '@volcanicminds/tools/logger'
+
+log.info('Application started')
+log.error({ err: new Error('Oops') }, 'Something went wrong')
+```

package/dist/index.d.ts

@@ -1,3 +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,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,3 +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,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/mailer/index.d.ts

@@ -0,0 +1,43 @@
+export interface MailerConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    defaultFrom?: string;
+    defaultReplyTo?: string;
+    tls?: {
+        rejectUnauthorized?: boolean;
+        ciphers?: string;
+    };
+}
+export interface MailAttachment {
+    filename: string;
+    content?: string | Buffer;
+    path?: string;
+    contentType?: string;
+    cid?: string;
+}
+export interface MailOptions {
+    to: string | string[];
+    subject: string;
+    html: string;
+    text?: string;
+    from?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: MailAttachment[];
+}
+export declare class Mailer {
+    private transporter;
+    private defaultFrom?;
+    private defaultReplyTo?;
+    constructor(config: MailerConfig);
+    private stripHtml;
+    send(options: MailOptions): Promise<any>;
+    verifyConnection(): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/mailer/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,GAAG,CAAC,EAAE;QACJ,kBAAkB,CAAC,EAAE,OAAO,CAAA;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;CAC/B;AAMD,qBAAa,MAAM;IACjB,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,cAAc,CAAC,CAAQ;gBAEnB,MAAM,EAAE,YAAY;IAqBhC,OAAO,CAAC,SAAS;IAcJ,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAwCxC,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;CASlD"}

package/dist/lib/mailer/index.js

@@ -0,0 +1,73 @@
+import nodemailer from 'nodemailer';
+export class Mailer {
+    transporter;
+    defaultFrom;
+    defaultReplyTo;
+    constructor(config) {
+        this.defaultFrom = config.defaultFrom;
+        this.defaultReplyTo = config.defaultReplyTo;
+        this.transporter = nodemailer.createTransport({
+            host: config.host,
+            port: config.port,
+            secure: config.secure ?? config.port === 465,
+            auth: config.auth
+                ? {
+                    user: config.auth.user,
+                    pass: config.auth.pass
+                }
+                : undefined,
+            tls: config.tls
+        });
+    }
+    stripHtml(html) {
+        if (!html)
+            return '';
+        return html
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<\/p>/gi, '\n\n')
+            .replace(/<[^>]*>?/gm, '')
+            .trim();
+    }
+    async send(options) {
+        const from = options.from || this.defaultFrom;
+        const replyTo = options.replyTo || this.defaultReplyTo;
+        if (!from) {
+            throw new Error('Email "from" address is required (either in options or config.defaultFrom)');
+        }
+        const mailPayload = {
+            from,
+            to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+            subject: options.subject,
+            html: options.html,
+            text: options.text || this.stripHtml(options.html),
+            attachments: options.attachments
+        };
+        if (options.cc) {
+            mailPayload.cc = Array.isArray(options.cc) ? options.cc.join(', ') : options.cc;
+        }
+        if (options.bcc) {
+            mailPayload.bcc = Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc;
+        }
+        if (replyTo) {
+            mailPayload.replyTo = replyTo;
+        }
+        try {
+            const info = await this.transporter.sendMail(mailPayload);
+            return info;
+        }
+        catch (error) {
+            throw new Error(`Failed to send email to ${mailPayload.to}: ${error.message}`);
+        }
+    }
+    async verifyConnection() {
+        try {
+            await this.transporter.verify();
+            return true;
+        }
+        catch (error) {
+            console.error('Mailer connection verification failed:', error);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

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

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,33 @@
+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 declare class TransferManager {
+    private server;
+    private config;
+    constructor(config: TransferConfig);
+    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;AAGD,MAAM,MAAM,qBAAqB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,cAAc,KAAK,IAAI,CAAA;AAEtH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,cAAc;IAYlC,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,71 @@
+import { Server, EVENTS } from '@tus/server';
+import { FileStore } from '@tus/file-store';
+import { S3Store } from '@tus/s3-store';
+export class TransferManager {
+    server;
+    config;
+    constructor(config) {
+        this.config = config;
+        const store = this.createStore();
+        this.server = new Server({
+            path: config.path,
+            datastore: store,
+            maxSize: config.maxSize,
+            respectForwardedHeaders: true
+        });
+    }
+    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/mailer/index.ts

@@ -0,0 +1,132 @@
+import nodemailer, { Transporter, SendMailOptions } from 'nodemailer'
+
+export interface MailerConfig {
+  host: string
+  port: number
+  secure?: boolean // true for 465, false for other ports
+  auth?: {
+    user: string
+    pass: string
+  }
+  defaultFrom?: string
+  defaultReplyTo?: string
+  tls?: {
+    rejectUnauthorized?: boolean
+    ciphers?: string
+  }
+}
+
+export interface MailAttachment {
+  filename: string
+  content?: string | Buffer
+  path?: string
+  contentType?: string
+  cid?: string
+}
+
+export interface MailOptions {
+  to: string | string[]
+  subject: string
+  html: string
+  text?: string // If not provided, it will be generated from html
+  from?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+  attachments?: MailAttachment[]
+}
+
+/**
+ * Mailer class wrapper around nodemailer.
+ * Designed to be tree-shakeable and configuration-driven without relying on process.env directly.
+ */
+export class Mailer {
+  private transporter: Transporter
+  private defaultFrom?: string
+  private defaultReplyTo?: string
+
+  constructor(config: MailerConfig) {
+    this.defaultFrom = config.defaultFrom
+    this.defaultReplyTo = config.defaultReplyTo
+
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure ?? config.port === 465, // Default secure if port is 465
+      auth: config.auth
+        ? {
+            user: config.auth.user,
+            pass: config.auth.pass
+          }
+        : undefined,
+      tls: config.tls
+    })
+  }
+
+  /**
+   * Helper to strip HTML tags for plain text fallback
+   */
+  private stripHtml(html: string): string {
+    if (!html) return ''
+    return html
+      .replace(/<br\s*\/?>/gi, '\n') // Replace <br> with newlines
+      .replace(/<\/p>/gi, '\n\n') // Replace </p> with double newlines
+      .replace(/<[^>]*>?/gm, '') // Remove all other tags
+      .trim()
+  }
+
+  /**
+   * Sends an email.
+   * @param options Mail options including to, subject, html, etc.
+   * @returns The info object from nodemailer.
+   */
+  public async send(options: MailOptions): Promise<any> {
+    const from = options.from || this.defaultFrom
+    const replyTo = options.replyTo || this.defaultReplyTo
+
+    if (!from) {
+      throw new Error('Email "from" address is required (either in options or config.defaultFrom)')
+    }
+
+    const mailPayload: SendMailOptions = {
+      from,
+      to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+      subject: options.subject,
+      html: options.html,
+      text: options.text || this.stripHtml(options.html),
+      attachments: options.attachments
+    }
+
+    if (options.cc) {
+      mailPayload.cc = Array.isArray(options.cc) ? options.cc.join(', ') : options.cc
+    }
+
+    if (options.bcc) {
+      mailPayload.bcc = Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc
+    }
+
+    if (replyTo) {
+      mailPayload.replyTo = replyTo
+    }
+
+    try {
+      const info = await this.transporter.sendMail(mailPayload)
+      return info
+    } catch (error: any) {
+      throw new Error(`Failed to send email to ${mailPayload.to}: ${error.message}`)
+    }
+  }
+
+  /**
+   * Verifies the connection configuration.
+   */
+  public async verifyConnection(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch (error) {
+      console.error('Mailer connection verification failed:', error)
+      return false
+    }
+  }
+}

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,115 @@
+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
+  }
+}
+
+// Updated definition to handle 'string' ID from POST_TERMINATE
+export type TransferEventCallback = (uploadOrId: Upload | string, req?: IncomingMessage, res?: ServerResponse) => void
+
+export class TransferManager {
+  private server: Server
+  private config: TransferConfig
+
+  constructor(config: TransferConfig) {
+    this.config = config
+    const store = this.createStore()
+
+    this.server = new Server({
+      path: config.path,
+      datastore: store,
+      maxSize: config.maxSize,
+      respectForwardedHeaders: true
+    })
+  }
+
+  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.3",
+  "version": "0.0.5",
   "description": "Tools for the volcanic (minds) backend",
   "keywords": [
     "volcanic",
@@ -10,7 +10,15 @@
     "esm",
     "mfa",
     "otp",
-    "totp"
+    "totp",
+    "mailer",
+    "nodemailer",
+    "storage",
+    "minio",
+    "s3",
+    "tus",
+    "upload",
+    "transfer"
   ],
   "homepage": "https://volcanicminds.com",
   "bugs": {
@@ -41,10 +49,25 @@
       "import": "./dist/lib/mfa/index.js",
       "require": "./dist/lib/mfa/index.js"
     },
+    "./mailer": {
+      "types": "./dist/lib/mailer/index.d.ts",
+      "import": "./dist/lib/mailer/index.js",
+      "require": "./dist/lib/mailer/index.js"
+    },
     "./logger": {
       "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",
@@ -69,18 +92,26 @@
     "combine": "node combine.js"
   },
   "dependencies": {
-    "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/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"
@@ -95,8 +126,17 @@
       "mfa": [
         "dist/lib/mfa/index.d.ts"
       ],
+      "mailer": [
+        "dist/lib/mailer/index.d.ts"
+      ],
       "logger": [
         "dist/lib/util/logger.d.ts"
+      ],
+      "storage": [
+        "dist/lib/storage/index.d.ts"
+      ],
+      "transfer": [
+        "dist/lib/transfer/index.d.ts"
       ]
     }
   }