@onivoro/server-aws-firehose 24.33.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Onivoro
+
+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,292 @@
+# @onivoro/server-aws-firehose
+
+AWS S3 integration for NestJS applications with file upload/download capabilities.
+
+## Installation
+
+```bash
+npm install @onivoro/server-aws-firehose
+```
+
+## Overview
+
+This library provides AWS S3 integration for NestJS applications, offering file upload, download, deletion, and pre-signed URL generation.
+
+## Module Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ServerAwsS3Module } from '@onivoro/server-aws-firehose';
+
+@Module({
+  imports: [
+    ServerAwsS3Module.configure()
+  ]
+})
+export class AppModule {}
+```
+
+## Configuration
+
+The module uses environment-based configuration:
+
+```typescript
+export class ServerAwsS3Config {
+  AWS_REGION: string;
+  AWS_PROFILE?: string;  // Optional AWS profile
+  AWS_S3_BUCKET: string;  // Default bucket name
+  AWS_S3_PREFIX?: string; // Optional prefix for all keys
+}
+```
+
+## Service
+
+### S3Service
+
+The service provides file operations:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { S3Service } from '@onivoro/server-aws-firehose';
+
+@Injectable()
+export class FileStorageService {
+  constructor(private readonly s3Service: S3Service) {}
+
+  // Upload a file
+  async uploadFile(key: string, body: Buffer | string, contentType: string) {
+    const result = await this.s3Service.upload(key, body, contentType);
+    return result;
+  }
+
+  // Upload a public file
+  async uploadPublicFile(key: string, body: Buffer | string, contentType: string) {
+    const result = await this.s3Service.uploadPublic(key, body, contentType);
+    return result;
+  }
+
+  // Download a file
+  async downloadFile(key: string) {
+    const fileContent = await this.s3Service.download(key);
+    return fileContent;
+  }
+
+  // Get a pre-signed download URL
+  async getDownloadUrl(key: string, expiresIn: number = 3600) {
+    const url = await this.s3Service.getPresignedDownloadUrl(key, expiresIn);
+    return url;
+  }
+
+  // Delete a single file
+  async deleteFile(key: string) {
+    await this.s3Service.delete(key);
+  }
+
+  // Delete files by prefix
+  async deleteFilesByPrefix(prefix: string) {
+    await this.s3Service.deleteByPrefix(prefix);
+  }
+}
+```
+
+## Available Methods
+
+### Upload Operations
+- **upload(key: string, body: Buffer | string, contentType: string, bucket?: string)** - Upload a private file
+- **uploadPublic(key: string, body: Buffer | string, contentType: string, bucket?: string)** - Upload a publicly accessible file
+
+### Download Operations
+- **download(key: string, bucket?: string)** - Download file content
+- **getPresignedDownloadUrl(key: string, expiresInSeconds?: number, bucket?: string)** - Generate pre-signed download URL
+
+### Delete Operations
+- **delete(key: string, bucket?: string)** - Delete a single object
+- **deleteByPrefix(prefix: string, bucket?: string)** - Delete all objects with a specific prefix
+
+## Direct Client Access
+
+The service exposes the underlying S3 client for advanced operations:
+
+```typescript
+import {
+  ListObjectsV2Command,
+  CopyObjectCommand,
+  HeadObjectCommand,
+  GetObjectTaggingCommand
+} from '@aws-sdk/client-firehose';
+
+@Injectable()
+export class AdvancedS3Service {
+  constructor(private readonly s3Service: S3Service) {}
+
+  // List objects in bucket
+  async listObjects(prefix?: string) {
+    const command = new ListObjectsV2Command({
+      Bucket: process.env.AWS_S3_BUCKET,
+      Prefix: prefix
+    });
+
+    return await this.s3Service.s3Client.send(command);
+  }
+
+  // Copy object
+  async copyObject(sourceKey: string, destinationKey: string) {
+    const command = new CopyObjectCommand({
+      Bucket: process.env.AWS_S3_BUCKET,
+      CopySource: `${process.env.AWS_S3_BUCKET}/${sourceKey}`,
+      Key: destinationKey
+    });
+
+    return await this.s3Service.s3Client.send(command);
+  }
+
+  // Get object metadata
+  async getObjectMetadata(key: string) {
+    const command = new HeadObjectCommand({
+      Bucket: process.env.AWS_S3_BUCKET,
+      Key: key
+    });
+
+    return await this.s3Service.s3Client.send(command);
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { Module, Injectable, Controller, Post, Get, Delete, Param, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { ServerAwsS3Module, S3Service } from '@onivoro/server-aws-firehose';
+
+@Module({
+  imports: [ServerAwsS3Module.configure()],
+  controllers: [DocumentController],
+  providers: [DocumentService]
+})
+export class DocumentModule {}
+
+@Injectable()
+export class DocumentService {
+  constructor(private readonly s3Service: S3Service) {}
+
+  async uploadDocument(userId: string, file: Express.Multer.File) {
+    const key = `documents/${userId}/${Date.now()}-${file.originalname}`;
+
+    try {
+      // Upload to S3
+      const result = await this.s3Service.upload(
+        key,
+        file.buffer,
+        file.mimetype
+      );
+
+      return {
+        key,
+        location: result.Location,
+        etag: result.ETag
+      };
+    } catch (error) {
+      console.error('Upload failed:', error);
+      throw error;
+    }
+  }
+
+  async getDocumentUrl(key: string) {
+    // Generate URL valid for 1 hour
+    const url = await this.s3Service.getPresignedDownloadUrl(key, 3600);
+    return { url };
+  }
+
+  async deleteUserDocuments(userId: string) {
+    const prefix = `documents/${userId}/`;
+    await this.s3Service.deleteByPrefix(prefix);
+  }
+
+  async uploadPublicAvatar(userId: string, imageBuffer: Buffer) {
+    const key = `avatars/${userId}.jpg`;
+
+    const result = await this.s3Service.uploadPublic(
+      key,
+      imageBuffer,
+      'image/jpeg'
+    );
+
+    return {
+      key,
+      publicUrl: result.Location
+    };
+  }
+}
+
+@Controller('documents')
+export class DocumentController {
+  constructor(private readonly documentService: DocumentService) {}
+
+  @Post('upload')
+  @UseInterceptors(FileInterceptor('file'))
+  async uploadDocument(
+    @UploadedFile() file: Express.Multer.File
+  ) {
+    const userId = 'user123'; // Get from auth context
+    return await this.documentService.uploadDocument(userId, file);
+  }
+
+  @Get(':key/url')
+  async getDocumentUrl(@Param('key') key: string) {
+    return await this.documentService.getDocumentUrl(key);
+  }
+
+  @Delete('user/:userId')
+  async deleteUserDocuments(@Param('userId') userId: string) {
+    await this.documentService.deleteUserDocuments(userId);
+    return { message: 'Documents deleted successfully' };
+  }
+}
+```
+
+## Environment Variables
+
+```bash
+# Required
+AWS_REGION=us-east-1
+AWS_S3_BUCKET=my-bucket-name
+
+# Optional
+AWS_PROFILE=my-profile
+AWS_S3_PREFIX=my-app/  # Prefix for all keys
+```
+
+## Error Handling
+
+```typescript
+try {
+  await s3Service.download('non-existent-key');
+} catch (error) {
+  if (error.name === 'NoSuchKey') {
+    console.error('File not found');
+  } else if (error.name === 'AccessDenied') {
+    console.error('Permission denied');
+  }
+}
+```
+
+## Limitations
+
+- No multipart upload support (large files must be handled manually)
+- No built-in bucket management operations
+- No object tagging or versioning support
+- Limited to basic CRUD operations
+- For advanced features, use the exposed `s3Client` directly
+
+## Best Practices
+
+1. **Key Naming**: Use a consistent key naming strategy (e.g., `type/userId/timestamp-filename`)
+2. **Content Types**: Always specify correct content types for proper browser handling
+3. **Security**: Use pre-signed URLs for temporary access instead of public uploads when possible
+4. **Cleanup**: Implement lifecycle policies for automatic object expiration
+5. **Error Handling**: Always handle S3 errors appropriately
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onivoro/server-aws-firehose",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "24.33.9",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onivoro/monorepo.git"
+  },
+  "dependencies": {
+    "@onivoro/server-aws-credential-providers": "24.33.9",
+    "@onivoro/server-common": "24.33.9",
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-firehose": "*",
+    "@aws-sdk/s3-request-presigner": "*",
+    "@nestjs/common": "*"
+  },
+  "files": [
+    "**/*.js",
+    "**/*.d.ts",
+    "**/*.js.map",
+    "README.md"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib/server-aws-firehose-config.class';
+export * from './lib/services/firehose.service';
+export * from './lib/server-aws-firehose.module';
+//# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/server-aws-firehose-config.class"), exports);
+tslib_1.__exportStar(require("./lib/services/firehose.service"), exports);
+tslib_1.__exportStar(require("./lib/server-aws-firehose.module"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../libs/server/aws-firehose/src/index.ts"],"names":[],"mappings":";;;AAAA,iFAAuD;AAEvD,0EAAgD;AAEhD,2EAAiD"}

package/src/lib/server-aws-firehose-config.class.d.ts

@@ -0,0 +1,6 @@
+export declare class ServerAwsFirehoseConfig {
+    AWS_FIREHOSE_NAME: string;
+    AWS_PROFILE?: string;
+    AWS_REGION: string;
+}
+//# sourceMappingURL=server-aws-firehose-config.class.d.ts.map

package/src/lib/server-aws-firehose-config.class.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerAwsFirehoseConfig = void 0;
+class ServerAwsFirehoseConfig {
+    AWS_FIREHOSE_NAME;
+    AWS_PROFILE;
+    AWS_REGION;
+}
+exports.ServerAwsFirehoseConfig = ServerAwsFirehoseConfig;
+//# sourceMappingURL=server-aws-firehose-config.class.js.map

package/src/lib/server-aws-firehose-config.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-aws-firehose-config.class.js","sourceRoot":"","sources":["../../../../../../libs/server/aws-firehose/src/lib/server-aws-firehose-config.class.ts"],"names":[],"mappings":";;;AAAA,MAAa,uBAAuB;IAChC,iBAAiB,CAAS;IAC1B,WAAW,CAAU;IACrB,UAAU,CAAS;CACtB;AAJD,0DAIC"}

package/src/lib/server-aws-firehose.module.d.ts

@@ -0,0 +1,5 @@
+import { ServerAwsFirehoseConfig } from './server-aws-firehose-config.class';
+export declare class ServerAwsFirehoseModule {
+    static configure(config: ServerAwsFirehoseConfig): any;
+}
+//# sourceMappingURL=server-aws-firehose.module.d.ts.map

package/src/lib/server-aws-firehose.module.js

@@ -0,0 +1,38 @@
+"use strict";
+var ServerAwsFirehoseModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerAwsFirehoseModule = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const client_firehose_1 = require("@aws-sdk/client-firehose");
+const server_common_1 = require("@onivoro/server-common");
+const server_aws_firehose_config_class_1 = require("./server-aws-firehose-config.class");
+const server_aws_credential_providers_1 = require("@onivoro/server-aws-credential-providers");
+const firehose_service_1 = require("./services/firehose.service");
+let firehoseClient = null;
+let ServerAwsFirehoseModule = ServerAwsFirehoseModule_1 = class ServerAwsFirehoseModule {
+    static configure(config) {
+        return (0, server_common_1.moduleFactory)({
+            imports: [server_aws_credential_providers_1.ServerAwsCredentialProvidersModule.configure(config)],
+            module: ServerAwsFirehoseModule_1,
+            providers: [
+                firehose_service_1.FirehoseService,
+                { provide: server_aws_firehose_config_class_1.ServerAwsFirehoseConfig, useValue: config },
+                {
+                    provide: client_firehose_1.FirehoseClient,
+                    useFactory: (credentials) => firehoseClient ||
+                        (firehoseClient = new client_firehose_1.FirehoseClient({
+                            region: config.AWS_REGION,
+                            credentials
+                        })),
+                    inject: [server_aws_credential_providers_1.AwsCredentials]
+                },
+            ]
+        });
+    }
+};
+exports.ServerAwsFirehoseModule = ServerAwsFirehoseModule;
+exports.ServerAwsFirehoseModule = ServerAwsFirehoseModule = ServerAwsFirehoseModule_1 = tslib_1.__decorate([
+    (0, common_1.Module)({})
+], ServerAwsFirehoseModule);
+//# sourceMappingURL=server-aws-firehose.module.js.map

package/src/lib/server-aws-firehose.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-aws-firehose.module.js","sourceRoot":"","sources":["../../../../../../libs/server/aws-firehose/src/lib/server-aws-firehose.module.ts"],"names":[],"mappings":";;;;;AAAA,2CAAwC;AACxC,8DAA0D;AAC1D,0DAAuD;AACvD,yFAA6E;AAC7E,8FAA8G;AAC9G,kEAA8D;AAE9D,IAAI,cAAc,GAA0B,IAAI,CAAC;AAG1C,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAClC,MAAM,CAAC,SAAS,CAAC,MAA+B;QAC9C,OAAO,IAAA,6BAAa,EAAC;YACnB,OAAO,EAAE,CAAC,oEAAkC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC/D,MAAM,EAAE,yBAAuB;YAC/B,SAAS,EAAE;gBACT,kCAAe;gBACf,EAAE,OAAO,EAAE,0DAAuB,EAAE,QAAQ,EAAE,MAAM,EAAE;gBACtD;oBACE,OAAO,EAAE,gCAAc;oBACvB,UAAU,EAAE,CAAC,WAA2B,EAAE,EAAE,CAC1C,cAAc;wBACd,CAAC,cAAc,GAAG,IAAI,gCAAc,CAAC;4BACnC,MAAM,EAAE,MAAM,CAAC,UAAU;4BACzB,WAAW;yBACZ,CAAC,CAAC;oBACL,MAAM,EAAE,CAAC,gDAAc,CAAC;iBACzB;aACF;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AArBY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,uBAAuB,CAqBnC"}

package/src/lib/services/firehose.service.d.ts

@@ -0,0 +1,9 @@
+import { FirehoseClient } from '@aws-sdk/client-firehose';
+import { ServerAwsFirehoseConfig } from '../server-aws-firehose-config.class';
+export declare class FirehoseService {
+    private config;
+    private firehoseClient;
+    constructor(config: ServerAwsFirehoseConfig, firehoseClient: FirehoseClient);
+    putRecord(data: any, eventId: string): Promise<void>;
+}
+//# sourceMappingURL=firehose.service.d.ts.map

package/src/lib/services/firehose.service.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirehoseService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const client_firehose_1 = require("@aws-sdk/client-firehose");
+const server_aws_firehose_config_class_1 = require("../server-aws-firehose-config.class");
+let FirehoseService = class FirehoseService {
+    config;
+    firehoseClient;
+    constructor(config, firehoseClient) {
+        this.config = config;
+        this.firehoseClient = firehoseClient;
+    }
+    async putRecord(data, eventId) {
+        const record = JSON.stringify(data) + '\n';
+        try {
+            const command = new client_firehose_1.PutRecordCommand({
+                DeliveryStreamName: this.config.AWS_FIREHOSE_NAME,
+                Record: {
+                    Data: Buffer.from(record),
+                },
+            });
+            await this.firehoseClient.send(command);
+        }
+        catch (error) {
+            console.error({
+                detail: 'failed to put record to Firehose',
+                error: error?.message,
+            });
+            throw error;
+        }
+    }
+};
+exports.FirehoseService = FirehoseService;
+exports.FirehoseService = FirehoseService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [server_aws_firehose_config_class_1.ServerAwsFirehoseConfig,
+        client_firehose_1.FirehoseClient])
+], FirehoseService);
+//# sourceMappingURL=firehose.service.js.map

package/src/lib/services/firehose.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firehose.service.js","sourceRoot":"","sources":["../../../../../../../libs/server/aws-firehose/src/lib/services/firehose.service.ts"],"names":[],"mappings":";;;;AAAA,2CAA4C;AAC5C,8DAA4E;AAC5E,0FAA8E;AAGvE,IAAM,eAAe,GAArB,MAAM,eAAe;IAEhB;IACA;IAFV,YACU,MAA+B,EAC/B,cAA8B;QAD9B,WAAM,GAAN,MAAM,CAAyB;QAC/B,mBAAc,GAAd,cAAc,CAAgB;IACrC,CAAC;IAEJ,KAAK,CAAC,SAAS,CACb,IAAS,EACT,OAAe;QAEf,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAE3C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,kCAAgB,CAAC;gBACnC,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;gBACjD,MAAM,EAAE;oBACN,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;iBAC1B;aACF,CAAC,CAAC;YAEH,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC;gBACZ,MAAM,EAAE,kCAAkC;gBAC1C,KAAK,EAAE,KAAK,EAAE,OAAO;aACtB,CAAC,CAAC;YACH,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF,CAAA;AA7BY,0CAAe;0BAAf,eAAe;IAD3B,IAAA,mBAAU,GAAE;6CAGO,0DAAuB;QACf,gCAAc;GAH7B,eAAe,CA6B3B"}