@lucaapp/service-utils 4.13.1 → 4.14.0

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export * from './lib/phone';
 export * from './lib/http';
 export * from './lib/jobs';
 export * from './lib/validation';
+export * from './lib/s3';
 export * from './types';

package/dist/index.js

@@ -34,4 +34,5 @@ __exportStar(require("./lib/phone"), exports);
 __exportStar(require("./lib/http"), exports);
 __exportStar(require("./lib/jobs"), exports);
 __exportStar(require("./lib/validation"), exports);
+__exportStar(require("./lib/s3"), exports);
 __exportStar(require("./types"), exports);

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

@@ -0,0 +1 @@
+export * from './s3';

package/dist/lib/s3/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./s3"), exports);

package/dist/lib/s3/s3.d.ts

@@ -0,0 +1,37 @@
+import { S3 } from '@aws-sdk/client-s3';
+import { Readable } from 'stream';
+/**
+ * Configuration for S3 client
+ */
+export interface S3Config {
+    accessKey?: string;
+    secretKey?: string;
+    endpoint: string;
+    region: string;
+    bucket: string;
+    protocol: 'https' | 'http';
+    forcePathStyle?: boolean;
+}
+/**
+ * Options for downloading files from S3
+ */
+export interface DownloadOptions {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+/**
+ * Create an S3 client from configuration
+ */
+export declare const createS3Client: (config: S3Config) => S3 | null;
+/**
+ * Download a file from S3 as a stream with timeout and retry support
+ *
+ * @param s3Client - Configured S3 client instance
+ * @param bucket - S3 bucket name
+ * @param key - S3 object key
+ * @param options - Download options (timeout, retries, retryDelay)
+ * @returns Readable stream of the file content
+ * @throws Error if S3 client is not configured or download fails after all retries
+ */
+export declare const downloadFileAsStream: (s3Client: S3 | null, bucket: string, key: string, options?: DownloadOptions) => Promise<Readable>;

package/dist/lib/s3/s3.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadFileAsStream = exports.createS3Client = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+/**
+ * Create an S3 client from configuration
+ */
+const createS3Client = (config) => {
+    if (!config.accessKey || !config.secretKey) {
+        return null;
+    }
+    const clientConfig = {
+        credentials: {
+            accessKeyId: config.accessKey,
+            secretAccessKey: config.secretKey,
+        },
+        endpoint: `${config.protocol}://${config.endpoint}`,
+        region: config.region,
+        maxAttempts: 3,
+    };
+    // Add forcePathStyle if specified (needed for S3-compatible services like MinIO)
+    if (config.forcePathStyle !== undefined) {
+        clientConfig.forcePathStyle = config.forcePathStyle;
+    }
+    return new client_s3_1.S3(clientConfig);
+};
+exports.createS3Client = createS3Client;
+/**
+ * Download a file from S3 as a stream with timeout and retry support
+ *
+ * @param s3Client - Configured S3 client instance
+ * @param bucket - S3 bucket name
+ * @param key - S3 object key
+ * @param options - Download options (timeout, retries, retryDelay)
+ * @returns Readable stream of the file content
+ * @throws Error if S3 client is not configured or download fails after all retries
+ */
+const downloadFileAsStream = async (s3Client, bucket, key, options = {}) => {
+    const { timeoutMs = 10000, retries = 0, retryDelay = 1000 } = options;
+    if (!s3Client) {
+        throw new Error('S3 client is not configured. Either set S3_REGION and S3_ENDPOINT (or use defaults) OR set USE_FILE_BASED_STORAGE=true');
+    }
+    const downloadParameters = {
+        Bucket: bucket,
+        Key: key,
+    };
+    const command = new client_s3_1.GetObjectCommand(downloadParameters);
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const abortController = new AbortController();
+        let timeoutId;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timeoutId = setTimeout(() => {
+                abortController.abort();
+                reject(new Error(`S3 download timeout after ${timeoutMs}ms for key: ${key}`));
+            }, timeoutMs);
+        });
+        try {
+            const s3Object = await Promise.race([
+                s3Client.send(command, { abortSignal: abortController.signal }),
+                timeoutPromise,
+            ]);
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            return s3Object.Body;
+        }
+        catch (error) {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            lastError = error;
+            if (attempt < retries) {
+                await new Promise(resolve => {
+                    setTimeout(resolve, retryDelay);
+                });
+            }
+        }
+    }
+    throw lastError;
+};
+exports.downloadFileAsStream = downloadFileAsStream;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "4.13.1",
+  "version": "4.14.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -20,6 +20,8 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "10.0.3",
     "@asteasolutions/zod-to-openapi": "6.1.0",
+    "@aws-sdk/client-s3": "^3.937.0",
+    "@aws-sdk/lib-storage": "^3.937.0",
     "@hapi/boom": "^10.0.1",
     "@sentry/node": "^9.10.1",
     "@tsconfig/node22": "22.0.0",
@@ -92,6 +94,7 @@
     "esbuild": "^0.25.10",
     "axios": "^1.12.2",
     "vite": "6.2.5",
-    "tar-fs": "2.1.4"
+    "tar-fs": "2.1.4",
+    "js-yaml": "4.1.1"
   }
 }