pluga-plg 0.1.8 → 0.2.0

package/.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "env": {
+    "commonjs": true,
+    "es6": true,
+    "node": true,
+    "jest": true
+  },
+  "extends": "airbnb-base",
+  "globals": {
+    "Atomics": "readonly",
+    "SharedArrayBuffer": "readonly"
+  },
+  "parserOptions": {
+    "ecmaVersion": 2022
+  },
+  "rules": {
+    "func-names": "off",
+    "no-await-in-loop": "off",
+    "no-console": "off",
+    "no-param-reassign": "off",
+    "no-restricted-syntax": "off",
+    "prefer-arrow-callback": "off"
+  }
+}

package/README.md

@@ -1,37 +1,273 @@
+
 # pluga-plg
 
 Pluga developer platform toolbox
 
-### Erros customizados:
-Existem tipos específicos de erros que são tratados de diferentes maneiras dentro da plataforma da Pluga. Os detalhes sobre os tipos de  erros suportados e como podem ser utilizados dentro do seu código estão descritos abaixo:
+## 📦 Setup
+
+```bash
+  npm install pluga-plg
+```
+## 🔧 Configuration
+
+If you are using the `storageService` (>= 0.2.0), define the following in the environment:
+
+```env
+AWS_S3_BUCKET=bucket-name
+AWS_REGION=region
+AWS_ACCESS_KEY_ID=access-key
+AWS_SECRET_ACCESS_KEY=secret-key
+```
+## plg.errors
 
-#### AuthError
-Erro de autenticação, geralmente necessita de uma ação manual do cliente. Devem ser utilizados em casos onde problema de autenticação impede o funcionamento da integração.
+### Custom Errors:
+There are specific types of errors that are handled differently within the Pluga platform. Details about the supported error types and how they can be used in your code are described below:
+
+<details>
+<summary>AuthError</summary>
+Authentication error, usually requires manual action from the client. Should be used in cases where an authentication issue prevents the integration from functioning.
 
 ```javascript
   plg.errors.authError(message: String)
 ```
+</details>
 
-#### Error
-Tipo genérico de erro, erros desse tipo deixam o evento em estado de falha. Devem ser utilizados quando o problema na integração exija uma correção manual por parte do cliente.
+<details>
+<summary>Error</summary>
+Generic error type. Errors of this type put the event in a failed state. Should be used when an integration issue requires manual correction by the client.
 
 ```javascript
   plg.errors.error(message: String)
 ```
+</details>
 
-#### RateLimitError
+<details>
+<summary>RateLimitError</summary>
 
-Erros desse tipo permitem que a Pluga realize o processamento dos eventos automaticamente em um momento futuro. Devem ser utilizados quando um recurso torna-se indisponível por conta do limite de uso por exemplo. Você deve fornecer o tempo necessário (em segundos) para que o recurso esteja disponível novamente.
+Errors of this type allow Pluga to process the events automatically at a later time. Should be used when a resource becomes unavailable due to usage limits, for example. You must provide the necessary time (in seconds) for the resource to become available again.
 
 ```javascript
   plg.errors.rateLimitError(message: String, remaining: Integer(seconds))
 ```
+</details>
 
-#### TransientError
+<details>
+<summary>TransientError</summary>
 
-Erros temporários ou transitórios que podem ocorrer por instabilidades, quedas, etc, e que não exigem nenhuma ação manual para o seu correto funcionamento. Eventos com erros desse tipo são reprocessados automaticamente pela plataforma da Pluga.
+Temporary or transient errors that may occur due to instabilities, outages, etc., and do not require any manual action for proper functioning. Events with this type of error are automatically reprocessed by the Pluga platform.
 
 ```javascript
   plg.errors.transientError(message: String)
 ```
+</details>
+
+## plg.files
+
+### plg.files.remote
+
+The `files.remote` module provides integration with Amazon S3 for file management.
+
+<details>
+<summary>async upload</summary>
+
+Send a local file to a S3 bucket.
+
+```
+  plg.files.remote.upload({ fileKey: String, filePath: String })
+```
+
+#### Params
+
+| Name     | Type   | Required | Description |
+|----------|--------|-------------|-----------|
+| fileKey   | string | Yes          | The unique key (name) for the file in the S3 bucket |
+| filePath | string | Yes        | The local path of the file to upload |
+
+#### Return
+
+```json
+{
+  "fileKey": "string"
+}
+```
+
+#### Errors
+
+
+| type | When it occurs | Example message |
+|--------------|---------------|-------------------|
+| `Error`      | Local path does not exist | - |
+| `Error`      | Internal errors in the AWS SDK | - |
+
+</details>
+
+<details>
+<summary>async download </summary>
+
+Download a file from an Amazon S3 bucket and save it to a local path.
+
+```
+  plg.files.remote.download({ 
+      fileKey: String, 
+      pathToWrite: String
+      sizeLimit: Number
+  })
+```
+
+#### Params
+
+| Name        | Type     | Required | Description |
+|-------------|----------|-------------|-----------|
+| fileKey      | string   | Yes          | The unique key (name) for the file in the S3 bucket |
+| pathToWrite | string   | Yes           | Local path where the downloaded file will be saved |
+| sizeLimit   | number   | No           | Optional maximum allowed file size in bytes. If exceeded, the download will fail |
+
+#### Return
+
+```json
+{
+  "success": true
+}
+```
+
+#### Errors
+
+| type | When it occurs | Example message |
+|--------------|---------------|-------------------|
+| `Error`      | Local path does not exist | - |
+| `Error`      | Internal errors in the AWS SDK | - |
+| `Error`      | File exceeds size limit specified in the `sizeLimit` param  | `File size limit exceeded. File size: ${fileSize} bytes, limit: ${sizeLimit} bytes.` |
+
+</details>
+
+<details>
+<summary>async getSignedUrl</summary> 
+
+Generate a temporary signed URL to download a file from S3.
+
+```
+  plg.files.remote.getSignedUrl({ 
+      fileKey: String, 
+      expiresIn: Number
+  })
+```
+
+#### Params
+
+| Name      | Type     | Required | Description |
+|-----------|----------|-------------|-----------|
+| fileKey    | string   | Yes          | The unique key (name) for the file in the S3 bucket |
+| expiresIn | number   | No         | Optional expiration time in seconds. Default: 1800 (30 minutes) |
+
+#### Return
+
+If the file exists:
+
+```json
+{
+  "fileKey": "string",
+  "signedUrl": "string",
+  "expiresIn": "number"
+}
+```
+
+If file does not exists returns `null`
+
+#### Errors
+
+| type | When it occurs | Example message |
+|--------------|---------------|-------------------|
+| `Error`      | Internal errors in the AWS SDK | - |
+
+</details>
+
+<details>
+<summary>async fileExists </summary>
+
+Checks if a file exists in S3 bucket.
+
+```
+  plg.files.remote.fileExists({ 
+      fileKey: String
+  })
+```
+
+#### Params
+
+| Name   | Type     | Required | Description |
+|--------|----------|-------------|-----------|
+| fileKey | string   | Yes          | The unique key (name) for the file in the S3 bucket |
+
+#### Retorno
+
+```json
+true // if the file exists
+false // if the file does not exist
+```
+
+#### Errors
+
+| type | When it occurs | Example message |
+|--------------|---------------|-------------------|
+| `Error`      | Internal errors in the AWS SDK, except for 404, which is treated as false | - |
+
+</details>
+
+### plg.files.local
+
+The `files.local` module enables local file handling.
+
+<details>
+<summary><strong>async downloadStream</strong></summary>
+
+Download a file from a URL as a stream and save it locally.
+
+```javascript
+plg.files.local.downloadStream({
+  pathToWrite: String,
+  downloadRequestParams: {
+    downloadUrl: String,
+    headers?: Object,
+  },
+  callbacks?: {
+    onData?: Function,
+    onEnd?: Function,
+  },
+})
+```
+
+#### Params
+
+| Name                              | Type     | Required | Description                                                                                       |
+| --------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- |
+| pathToWrite                       | string   | Yes      | Local path where the downloaded file will be saved.                                               |
+| downloadRequestParams             | object   | Yes      | Object containing the download URL and optional HTTP headers.                                     |
+| downloadRequestParams.downloadUrl | string   | Yes      | Public URL used to download the file.                                                             |
+| downloadRequestParams.headers     | object   | No       | Optional HTTP headers to be sent with the download request.                                       |
+| callbacks                         | object   | No       | Optional callbacks executed during the download lifecycle.                                        |
+| callbacks.onData                  | function | No       | Executed for each received data chunk. Receives `(dataChunk, currentDownloadedBytesCount)`.       |
+| callbacks.onEnd                   | function | No       | Executed when the download finishes. If it returns a value, the promise resolves with that value. |
+
+
+#### Return by default
+```json
+{
+  "success": true
+}
+```
+
+- Note: If `onEndCallback` returns a value, the promise resolves with that value instead
+
+#### Errors
+
+
+| Type                  | When it occurs                                                      | Example                                                        |
+| --------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `Error`               | Local path to write does not exist or is not writable               | —                                                              |
+| `Error`               | Download URL provided is not public or request fails                | —                                                              |
+| `onDataCallback`      | Error thrown inside `callbacks.onData`                              | `{ "type": "onDataCallback", "error": <original error> }`      |
+| `onEndCallback`       | Error thrown inside `callbacks.onEnd`                               | `{ "type": "onEndCallback", "error": <original error> }`       |
+| `StreamPipelineError` | Stream pipeline fails (connection drop, timeout, write error, etc.) | `{ "type": "StreamPipelineError", "error": <original error> }` |
+
 
+</details>

package/__tests__/files/local/axiosService.test.js

@@ -0,0 +1,45 @@
+const axios = require('../../../lib/axios');
+const AxiosService = require('../../../lib/files/local/axiosService');
+
+jest.mock('../../../lib/axios');
+
+describe('AxiosService', () => {
+  let service;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    service = new AxiosService();
+  });
+
+  it('downloads a file as stream using axios', async () => {
+    const fakeStream = { fake: 'stream' };
+
+    axios.mockResolvedValue({
+      data: fakeStream,
+    });
+
+    const params = {
+      downloadRequestParams: {
+        downloadUrl: 'https://example.com/file.txt',
+        headers: {
+          Authorization: 'Bearer token',
+        },
+      },
+    };
+
+    const result = await service.download(params);
+
+    expect(axios).toHaveBeenCalledWith({
+      method: 'get',
+      url: 'https://example.com/file.txt',
+      responseType: 'stream',
+      headers: {
+        Authorization: 'Bearer token',
+      },
+    });
+
+    expect(result).toEqual({
+      stream: fakeStream,
+    });
+  });
+});

package/__tests__/files/remote/s3Service.test.js

@@ -0,0 +1,151 @@
+const fs = require('fs');
+const {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+} = require('@aws-sdk/client-s3');
+const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+const { PassThrough } = require('stream');
+
+const S3Service = require('../../../lib/files/remote/s3Service');
+
+jest.mock('fs', () => ({
+  createReadStream: jest.fn(),
+}));
+
+jest.mock('@aws-sdk/client-s3', () => ({
+  S3Client: jest.fn(),
+  PutObjectCommand: jest.fn((params) => params),
+  GetObjectCommand: jest.fn((params) => params),
+  HeadObjectCommand: jest.fn((params) => params),
+}));
+
+jest.mock('@aws-sdk/s3-request-presigner', () => ({
+  getSignedUrl: jest.fn(),
+}));
+
+describe('S3Service', () => {
+  let mockSend;
+  let s3Service;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mockSend = jest.fn();
+    S3Client.mockImplementation(() => ({ send: mockSend }));
+
+    s3Service = new S3Service({
+      client: new S3Client(),
+      bucket: 'foo-bucket',
+    });
+  });
+
+  describe('upload', () => {
+    it('uploads file to S3', async () => {
+      const mockStream = {};
+      fs.createReadStream.mockReturnValue(mockStream);
+      mockSend.mockResolvedValue({});
+
+      const result = await s3Service.upload({
+        fileKey: 'foo',
+        filePath: '/tmp/bar',
+      });
+
+      expect(fs.createReadStream).toHaveBeenCalledWith('/tmp/bar');
+      expect(PutObjectCommand).toHaveBeenCalledWith({
+        Bucket: 'foo-bucket',
+        Key: 'foo',
+        Body: mockStream,
+      });
+      expect(result).toEqual({ fileKey: 'foo' });
+    });
+  });
+
+  describe('download', () => {
+    it('downloads and writes file to disk', async () => {
+      const mockReadStream = new PassThrough();
+      mockReadStream.end('foo bar');
+
+      mockSend.mockResolvedValue({
+        Body: mockReadStream,
+        ContentLength: 100,
+      });
+
+      const result = await s3Service.download({
+        fileKey: 'foo',
+      });
+
+      expect(GetObjectCommand).toHaveBeenCalledWith({
+        Bucket: 'foo-bucket',
+        Key: 'foo',
+      });
+
+      expect(result).toEqual({
+        stream: mockReadStream,
+      });
+    });
+
+    it('throws error when size exceeds limit', async () => {
+      mockSend.mockResolvedValue({
+        Body: {},
+        ContentLength: 9999,
+      });
+
+      await expect(
+        s3Service.download({
+          fileKey: 'foo',
+          pathToWrite: '/tmp/y',
+          sizeLimit: 10,
+        }),
+      ).rejects.toThrow('File size limit exceeded');
+    });
+  });
+
+  describe('fileExists', () => {
+    it('returns true if file exists', async () => {
+      mockSend.mockResolvedValue({});
+
+      const exists = await s3Service.fileExists({ fileKey: 'foo' });
+
+      expect(exists).toBe(true);
+    });
+
+    it('returns false if file does not exist', async () => {
+      const error = new Error('Not found');
+      error.name = 'NotFound';
+      mockSend.mockRejectedValue(error);
+
+      const exists = await s3Service.fileExists({ fileKey: 'foo' });
+
+      expect(exists).toBe(false);
+    });
+  });
+
+  describe('getSignedUrl', () => {
+    it('returns signedUrl if file exists', async () => {
+      mockSend.mockResolvedValue({});
+      getSignedUrl.mockResolvedValue('http://signed-url.com');
+
+      const result = await s3Service.getSignedUrl({
+        fileKey: 'foo',
+        expiresIn: 123,
+      });
+
+      expect(result).toEqual({
+        fileKey: 'foo',
+        signedUrl: 'http://signed-url.com',
+        expiresIn: 123,
+      });
+    });
+
+    it('returns null if file does not exist', async () => {
+      const error = new Error('Not found');
+      error.name = 'NotFound';
+      mockSend.mockRejectedValue(error);
+
+      const result = await s3Service.getSignedUrl({ fileKey: 'foo' });
+
+      expect(result).toBeNull();
+    });
+  });
+});

package/__tests__/files/storageService.test.js

@@ -0,0 +1,89 @@
+const StorageService = require('../../lib/files/storageService');
+
+describe('Storage service', () => {
+  let client;
+  let service;
+  const params = { foo: 'bar ' };
+  const successResp = { success: true };
+  let streamFileWriter;
+
+  beforeEach(() => {
+    client = {
+      upload: jest.fn(),
+      download: jest.fn(),
+      fileExists: jest.fn(),
+      getSignedUrl: jest.fn(),
+    };
+
+    service = new StorageService(client);
+  });
+
+  beforeEach(() => {
+    client = {
+      upload: jest.fn(),
+      download: jest.fn(),
+      getSignedUrl: jest.fn(),
+      fileExists: jest.fn(),
+    };
+
+    streamFileWriter = {
+      writeToDisk: jest.fn(),
+    };
+
+    service = new StorageService(client, streamFileWriter);
+  });
+
+  describe('upload', () => {
+    it('delegates upload to client', async () => {
+      client.upload.mockResolvedValue(successResp);
+
+      const response = await service.upload(params);
+
+      expect(client.upload).toHaveBeenCalledWith(params);
+
+      expect(response).toEqual(successResp);
+    });
+  });
+
+  describe('download', () => {
+    it('downloads stream from client and writes it to disk', async () => {
+      const stream = { fake: 'stream' };
+      const expectedResult = { success: true };
+
+      client.download.mockReturnValue({ stream });
+      streamFileWriter.writeToDisk.mockResolvedValue(expectedResult);
+
+      const result = await service.download(params);
+
+      expect(client.download).toHaveBeenCalledWith(params);
+      expect(streamFileWriter.writeToDisk).toHaveBeenCalledWith({
+        stream,
+        ...params,
+      });
+      expect(result).toBe(expectedResult);
+    });
+  });
+
+  describe('fileExists', () => {
+    it('delegates fileExists to client', async () => {
+      client.fileExists.mockResolvedValue(successResp);
+
+      const response = await service.fileExists(params);
+
+      expect(client.fileExists).toHaveBeenCalledWith(params);
+      expect(response).toBe(successResp);
+    });
+  });
+
+  describe('getSignedUrl', () => {
+    it('delegates getSignedUrl to client', async () => {
+      client.getSignedUrl.mockResolvedValue(successResp);
+
+      const response = await service.getSignedUrl(params);
+
+      expect(client.getSignedUrl).toHaveBeenCalledWith(params);
+
+      expect(response).toEqual(successResp);
+    });
+  });
+});

package/__tests__/files/streamFileWriter.test.js

@@ -0,0 +1,137 @@
+const fs = require('fs');
+const { PassThrough } = require('stream');
+
+const StreamFileWriter = require('../../lib/files/streamFileWriter');
+
+jest.mock('fs', () => ({
+  createWriteStream: jest.fn(),
+}));
+
+describe('Stream file writer', () => {
+  it('writes stream to disk successfully without callbacks', async () => {
+    const readStream = new PassThrough();
+    readStream.end('hello');
+
+    const writeStream = new PassThrough();
+    fs.createWriteStream.mockReturnValue(writeStream);
+
+    const result = await StreamFileWriter.writeToDisk({
+      stream: readStream,
+      pathToWrite: '/tmp/file.txt',
+    });
+
+    expect(fs.createWriteStream).toHaveBeenCalledWith('/tmp/file.txt');
+    expect(result).toEqual({ success: true });
+  });
+
+  describe('Callbacks', () => {
+    it('calls onData callback with accumulated bytes', async () => {
+      const readStream = new PassThrough();
+      const writeStream = new PassThrough();
+      fs.createWriteStream.mockReturnValue(writeStream);
+
+      const onData = jest.fn();
+
+      const promise = StreamFileWriter.writeToDisk({
+        stream: readStream,
+        pathToWrite: '/tmp/file.txt',
+        callbacks: { onData },
+      });
+
+      readStream.write(Buffer.from('foo'));
+      readStream.write(Buffer.from('bar'));
+      readStream.end();
+
+      await promise;
+
+      expect(onData).toHaveBeenNthCalledWith(1, expect.any(Buffer), 3);
+      expect(onData).toHaveBeenNthCalledWith(2, expect.any(Buffer), 6);
+    });
+
+    it('resolves with onEnd return value when provided', async () => {
+      const readStream = new PassThrough();
+      readStream.end('done');
+
+      const writeStream = new PassThrough();
+      fs.createWriteStream.mockReturnValue(writeStream);
+
+      const onEnd = jest.fn(() => ({ finished: true }));
+
+      const result = await StreamFileWriter.writeToDisk({
+        stream: readStream,
+        pathToWrite: '/tmp/file.txt',
+        callbacks: { onEnd },
+      });
+
+      expect(onEnd).toHaveBeenCalled();
+      expect(result).toEqual({ finished: true });
+    });
+  });
+
+  describe('Errors', () => {
+    it('throws typed error when onData throws', async () => {
+      const readStream = new PassThrough();
+      const writeStream = new PassThrough();
+      fs.createWriteStream.mockReturnValue(writeStream);
+
+      const onData = jest.fn(() => {
+        throw new Error('onData failed');
+      });
+
+      const promise = StreamFileWriter.writeToDisk({
+        stream: readStream,
+        pathToWrite: '/tmp/file.txt',
+        callbacks: { onData },
+      });
+
+      readStream.write(Buffer.from('boom'));
+
+      await expect(promise).rejects.toMatchObject({
+        type: 'onDataCallback',
+      });
+    });
+
+    it('throws typed error when onEnd throws', async () => {
+      const readStream = new PassThrough();
+      readStream.end('done');
+
+      const writeStream = new PassThrough();
+      fs.createWriteStream.mockReturnValue(writeStream);
+
+      const onEnd = jest.fn(() => {
+        throw new Error('onEnd failed');
+      });
+
+      await expect(
+        StreamFileWriter.writeToDisk({
+          stream: readStream,
+          pathToWrite: '/tmp/file.txt',
+          callbacks: { onEnd },
+        }),
+      ).rejects.toMatchObject({
+        type: 'onEndCallback',
+      });
+
+      expect(onEnd).toHaveBeenCalled();
+    });
+
+    it('wraps pipeline errors with StreamPipelineError', async () => {
+      const readStream = new PassThrough();
+
+      const writeStream = new PassThrough();
+      fs.createWriteStream.mockReturnValue(writeStream);
+
+      const pipelineError = new Error('pipeline failed');
+      writeStream.destroy(pipelineError);
+
+      await expect(
+        StreamFileWriter.writeToDisk({
+          stream: readStream,
+          pathToWrite: '/tmp/file.txt',
+        }),
+      ).rejects.toMatchObject({
+        type: 'StreamPipelineError',
+      });
+    });
+  });
+});

package/index.js

@@ -1,9 +1,11 @@
 const axios = require('./lib/axios');
 const errors = require('./lib/errors');
-const package = require('./package.json');
+const files = require('./lib/files');
+const packge = require('./package.json');
 
 module.exports = {
-  axios: axios,
-  errors: errors,
-  version: package.version,
+  axios,
+  errors,
+  files,
+  version: packge.version,
 };

package/lib/files/index.js

@@ -0,0 +1,7 @@
+const local = require('./local');
+const remote = require('./remote');
+
+module.exports = {
+  local,
+  remote,
+};

package/lib/files/local/axiosService.js

@@ -0,0 +1,19 @@
+/* eslint-disable class-methods-use-this */
+const axios = require('../../axios');
+
+class AxiosService {
+  async download({
+    downloadRequestParams: { downloadUrl, headers },
+  }) {
+    const res = await axios({
+      method: 'get',
+      url: downloadUrl,
+      responseType: 'stream',
+      headers,
+    });
+
+    return { stream: res.data };
+  }
+}
+
+module.exports = AxiosService;

package/lib/files/local/index.js

@@ -0,0 +1,10 @@
+const StorageService = require('../storageService');
+const AxiosService = require('./axiosService');
+
+const service = new StorageService(new AxiosService());
+
+async function downloadStream(params) {
+  return service.download(params);
+}
+
+module.exports = { downloadStream };

package/lib/files/remote/index.js

@@ -0,0 +1,7 @@
+const StorageService = require('../storageService');
+const S3Service = require('./s3Service');
+
+const s3Service = new S3Service();
+const storageService = new StorageService(s3Service);
+
+module.exports = storageService;

package/lib/files/remote/s3Service.js

@@ -0,0 +1,93 @@
+/* eslint-disable class-methods-use-this */
+const fs = require('fs');
+const {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+} = require('@aws-sdk/client-s3');
+const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+
+class S3Service {
+  #DEFAULT_URL_EXPIRATION_IN_SECONDS = 30 * 60;
+
+  #client;
+
+  #bucket;
+
+  constructor({ client = null, bucket = null } = {}) {
+    this.#bucket = bucket || process.env.AWS_S3_BUCKET;
+    this.#client = client || new S3Client({
+      region: process.env.AWS_REGION,
+      credentials: {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      },
+    });
+  }
+
+  async upload({ fileKey, filePath }) {
+    const fileStream = fs.createReadStream(filePath);
+    await this.#runCommand(
+      new PutObjectCommand({
+        Bucket: this.#bucket,
+        Key: fileKey,
+        Body: fileStream,
+      }),
+    );
+    return { fileKey };
+  }
+
+  async download({ fileKey, sizeLimit }) {
+    const file = await this.#runCommand(
+      new GetObjectCommand({ Bucket: this.#bucket, Key: fileKey }),
+    );
+
+    this.#validateSize(file.ContentLength, sizeLimit);
+    return { stream: file.Body };
+  }
+
+  async getSignedUrl({ fileKey, expiresIn = this.#DEFAULT_URL_EXPIRATION_IN_SECONDS }) {
+    if (await this.fileExists({ fileKey })) {
+      const command = new GetObjectCommand({ Bucket: this.#bucket, Key: fileKey });
+      const url = await getSignedUrl(this.#client, command, { expiresIn });
+      return { fileKey, signedUrl: url, expiresIn };
+    }
+    return null;
+  }
+
+  async fileExists({ fileKey }) {
+    try {
+      await this.#runCommand(new HeadObjectCommand({ Bucket: this.#bucket, Key: fileKey }));
+      return true;
+    } catch (error) {
+      if (error.name === 'NotFound' || error.$metadata?.httpStatusCode === 404) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  #validateSize(fileSize, sizeLimit) {
+    if (!sizeLimit) return;
+    if (fileSize != null && fileSize > sizeLimit) {
+      throw new Error('File size limit exceeded');
+    }
+  }
+
+  #writeStreamToDisk(readStream, pathToWrite) {
+    return new Promise((resolve, reject) => {
+      const writeStream = fs.createWriteStream(pathToWrite);
+      readStream
+        .pipe(writeStream)
+        .on('finish', resolve)
+        .on('error', reject);
+    });
+  }
+
+  async #runCommand(command) {
+    return this.#client.send(command);
+  }
+}
+
+module.exports = S3Service;

package/lib/files/storageService.js

@@ -0,0 +1,31 @@
+const StreamFileWriter = require('./streamFileWriter');
+
+class StorageService {
+  #client;
+
+  #streamFileWriter;
+
+  constructor(client, streamFileWriter = StreamFileWriter) {
+    this.#client = client;
+    this.#streamFileWriter = streamFileWriter;
+  }
+
+  async upload(params) {
+    return this.#client.upload(params);
+  }
+
+  async download(params) {
+    const { stream } = this.#client.download(params);
+    return this.#streamFileWriter.writeToDisk({ stream, ...params });
+  }
+
+  async getSignedUrl(params) {
+    return this.#client.getSignedUrl(params);
+  }
+
+  async fileExists(params) {
+    return this.#client.fileExists(params);
+  }
+}
+
+module.exports = StorageService;

package/lib/files/streamFileWriter.js

@@ -0,0 +1,88 @@
+/* eslint-disable class-methods-use-this */
+const fs = require('fs');
+const { pipeline } = require('stream');
+const { promisify } = require('util');
+
+const pipelineAsync = promisify(pipeline);
+
+const Errors = {
+  ON_DATA: 'onDataCallback',
+  ON_END: 'onEndCallback',
+  PIPELINE: 'StreamPipelineError',
+};
+
+class StreamFileWriter {
+  static async writeToDisk({ stream, pathToWrite, callbacks = {} }) {
+    const writableStream = fs.createWriteStream(pathToWrite);
+    let callbackError = null;
+
+    if (callbacks.onData) {
+      this.#attachOnData(stream, callbacks.onData, (err) => {
+        callbackError = err;
+      });
+    }
+
+    try {
+      await pipelineAsync(stream, writableStream);
+
+      this.#throwIfCallbackFailed(callbackError);
+
+      return callbacks.onEnd
+        ? this.#handleOnEnd(callbacks.onEnd)
+        : { success: true };
+    } catch (err) {
+      this.#throwIfCallbackFailed(callbackError);
+
+      throw this.#normalizePipelineError(err);
+    }
+  }
+
+  static #attachOnData(stream, onData, reportCallbackError) {
+    let downloadedBytes = 0;
+
+    const onDataHandler = (chunk) => {
+      downloadedBytes += chunk.length;
+
+      try {
+        onData(chunk, downloadedBytes);
+      } catch (err) {
+        reportCallbackError(
+          this.#buildError(Errors.ON_DATA, err),
+        );
+
+        stream.off('data', onDataHandler);
+        stream.destroy(err);
+      }
+    };
+
+    stream.on('data', onDataHandler);
+  }
+
+  static #handleOnEnd(onEnd) {
+    try {
+      return onEnd() ?? { success: true };
+    } catch (err) {
+      throw this.#buildError(Errors.ON_END, err);
+    }
+  }
+
+  static #throwIfCallbackFailed(callbackError) {
+    if (callbackError) {
+      throw callbackError;
+    }
+  }
+
+  static #normalizePipelineError(err) {
+    if (err?.type && err?.error) {
+      return err;
+    }
+
+    return this.#buildError(Errors.PIPELINE, err);
+  }
+
+  static #buildError(type, error) {
+    return { type, error };
+  }
+}
+
+module.exports = StreamFileWriter;

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "pluga-plg",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Pluga developer platform toolbox",
   "main": "index.js",
   "author": "Pluga <tech@pluga.co> (pluga.co)",
   "contributors": [
     "Leonardo Camelo (github.com/leocamelo)",
     "Renan Machado (github.com/renanmac)",
-    "Alexandre Camillo (github.com/alexandrecamillo)"
+    "Alexandre Camillo (github.com/alexandrecamillo)",
+    "Mayara Araujo (github.com/mayaraujom)"
   ],
   "license": "MIT",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.934.0",
+    "@aws-sdk/s3-request-presigner": "^3.934.0",
     "axios": "^1.7.4"
+  },
+  "scripts": {
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "eslint": "8.56.0",
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-plugin-import": "2.29.1"
   }
 }