@vlsdev/s3-portable 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# @vs/s3-portable
+
+Pacote TypeScript "portable" para padronizar integração com Amazon S3 em microserviços, com arquitetura em camadas (DDD + SOLID).
+
+## Instalação
+
+```bash
+npm i @vs/s3-portable
+```
+
+## Variáveis de ambiente esperadas
+
+```env
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_S3_BUCKET_NAME=...
+```
+
+## Uso rápido (via env)
+
+```ts
+import "dotenv/config";
+import { createS3ServiceFromEnv } from "@vs/s3-portable";
+
+const s3Service = createS3ServiceFromEnv();
+
+const body = await s3Service.downloadFile("meu-projeto", "documentos", "arquivo.pdf");
+const files = await s3Service.listFiles("meu-projeto", "documentos");
+await s3Service.deleteFile("meu-projeto", "documentos", "arquivo.pdf");
+const url = await s3Service.generateSignedUrl("meu-projeto", "documentos", "arquivo.pdf", 3600);
+```
+
+## Uso com configuração explícita
+
+```ts
+import { createS3Service } from "@vs/s3-portable";
+
+const s3Service = createS3Service({
+  region: "us-east-1",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  bucketName: process.env.AWS_S3_BUCKET_NAME!,
+});
+```
+
+## API
+
+- `downloadFile(project, path, fileName)`
+- `listFiles(project, path)`
+- `deleteFile(project, path, fileName)`
+- `generateSignedUrl(project, path, fileName, expiresIn?)`
+
+## Build
+
+```bash
+npm run build
+```
+
+## Publicacao privada no npm
+
+1. Login na conta correta:
+
+```bash
+npm whoami
+```
+
+2. Publicar com 2FA (OTP interativo):
+
+```bash
+npm run publish:private:otp
+```
+
+3. Ou publicar sem OTP usando token granular com permissao de publish + bypass 2FA:
+
+```bash
+npm run publish:private
+```
+
+### Troubleshooting E403 na publicacao
+
+Se aparecer:
+
+`403 Forbidden ... Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.`
+
+valide estes pontos:
+
+- O usuario autenticado tem permissao de publish no escopo `@vs` (owner/maintainer).
+- Se usar conta com 2FA obrigatorio para escrita, publique com OTP (`npm run publish:private:otp`).
+- Se usar token, ele precisa ser granular com permissao de publish para `@vs/*` e com bypass 2FA habilitado.
+- Remova credenciais antigas e relogue:
+
+```bash
+npm logout
+npm login
+```

package/dist/index.cjs

@@ -0,0 +1,265 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DomainError: () => DomainError,
+  S3Service: () => S3Service,
+  createS3Service: () => createS3Service,
+  createS3ServiceFromEnv: () => createS3ServiceFromEnv
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/domain/errors/DomainError.ts
+var DomainError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DomainError";
+  }
+};
+
+// src/domain/value-objects/S3ObjectPath.ts
+var normalizeSegment = (value, label) => {
+  const sanitized = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!sanitized) {
+    throw new DomainError(`${label} is required`);
+  }
+  if (sanitized.includes("..")) {
+    throw new DomainError(`${label} cannot contain ".."`);
+  }
+  return sanitized;
+};
+var S3ObjectPath = class {
+  static build(project, path, fileName) {
+    const projectPart = normalizeSegment(project, "project");
+    const pathPart = normalizeSegment(path, "path");
+    if (!fileName) {
+      return `${projectPart}/${pathPart}/`;
+    }
+    const filePart = normalizeSegment(fileName, "fileName");
+    return `${projectPart}/${pathPart}/${filePart}`;
+  }
+};
+
+// src/application/use-cases/DeleteFileUseCase.ts
+var DeleteFileUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a remoção de um arquivo.
+   *
+   * @param input Dados de identificação do arquivo.
+   * @returns Mensagem de confirmação de exclusão.
+   */
+  async execute(input) {
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    await this.gateway.deleteObject(objectKey);
+    return { message: "Arquivo deletado com sucesso" };
+  }
+};
+
+// src/application/use-cases/DownloadFileUseCase.ts
+var DownloadFileUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa o download de um arquivo.
+   *
+   * @param input Dados de identificação do arquivo.
+   * @returns Corpo do objeto retornado pelo SDK AWS (stream/blob).
+   */
+  async execute(input) {
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    return this.gateway.getObject(objectKey);
+  }
+};
+
+// src/application/use-cases/GenerateSignedUrlUseCase.ts
+var GenerateSignedUrlUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a geração da URL assinada.
+   *
+   * Regra de negócio: `expiresIn` deve ser maior que zero.
+   *
+   * @param input Dados de identificação do arquivo e expiração opcional.
+   * @returns URL assinada para download temporário.
+   */
+  async execute(input) {
+    const expiresIn = input.expiresIn ?? 3600;
+    if (expiresIn <= 0) {
+      throw new DomainError("expiresIn must be greater than zero");
+    }
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    return this.gateway.generateGetSignedUrl(objectKey, expiresIn);
+  }
+};
+
+// src/application/use-cases/ListFilesUseCase.ts
+var ListFilesUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a listagem de chaves no S3.
+   *
+   * @param input Dados de projeto e caminho.
+   * @returns Lista de chaves completas encontradas no bucket.
+   */
+  async execute(input) {
+    const prefix = S3ObjectPath.build(input.project, input.path);
+    return this.gateway.listObjects(prefix);
+  }
+};
+
+// src/facade/S3Service.ts
+var S3Service = class {
+  constructor(downloadFileUseCase, listFilesUseCase, deleteFileUseCase, generateSignedUrlUseCase) {
+    this.downloadFileUseCase = downloadFileUseCase;
+    this.listFilesUseCase = listFilesUseCase;
+    this.deleteFileUseCase = deleteFileUseCase;
+    this.generateSignedUrlUseCase = generateSignedUrlUseCase;
+  }
+  async downloadFile(project, path, fileName) {
+    return this.downloadFileUseCase.execute({ project, path, fileName });
+  }
+  async listFiles(project, path) {
+    return this.listFilesUseCase.execute({ project, path });
+  }
+  async deleteFile(project, path, fileName) {
+    return this.deleteFileUseCase.execute({ project, path, fileName });
+  }
+  async generateSignedUrl(project, path, fileName, expiresIn = 10800) {
+    return this.generateSignedUrlUseCase.execute({
+      project,
+      path,
+      fileName,
+      expiresIn
+    });
+  }
+};
+
+// src/infrastructure/aws/AwsS3StorageGateway.ts
+var import_client_s3 = require("@aws-sdk/client-s3");
+var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+var AwsS3StorageGateway = class {
+  constructor(config, client) {
+    this.config = config;
+    this.client = client ?? new import_client_s3.S3Client({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+  }
+  client;
+  async getObject(objectKey) {
+    const { Body } = await this.client.send(
+      new import_client_s3.GetObjectCommand({
+        Bucket: this.config.bucketName,
+        Key: objectKey
+      })
+    );
+    if (!Body) {
+      throw new Error(`Object "${objectKey}" returned empty body`);
+    }
+    return Body;
+  }
+  async listObjects(prefix) {
+    const { Contents } = await this.client.send(
+      new import_client_s3.ListObjectsV2Command({
+        Bucket: this.config.bucketName,
+        Prefix: prefix
+      })
+    );
+    return Contents?.map((file) => file.Key).filter((key) => Boolean(key)) ?? [];
+  }
+  async deleteObject(objectKey) {
+    await this.client.send(
+      new import_client_s3.DeleteObjectCommand({
+        Bucket: this.config.bucketName,
+        Key: objectKey
+      })
+    );
+  }
+  async generateGetSignedUrl(objectKey, expiresInSeconds) {
+    const command = new import_client_s3.GetObjectCommand({
+      Bucket: this.config.bucketName,
+      Key: objectKey
+    });
+    return (0, import_s3_request_presigner.getSignedUrl)(this.client, command, { expiresIn: expiresInSeconds });
+  }
+};
+
+// src/infrastructure/config/S3Config.ts
+var createS3Config = (input) => {
+  const config = {
+    region: input.region?.trim() ?? "",
+    accessKeyId: input.accessKeyId?.trim() ?? "",
+    secretAccessKey: input.secretAccessKey?.trim() ?? "",
+    bucketName: input.bucketName?.trim() ?? ""
+  };
+  if (!config.region) throw new DomainError("AWS region is required");
+  if (!config.accessKeyId) throw new DomainError("AWS access key id is required");
+  if (!config.secretAccessKey) throw new DomainError("AWS secret access key is required");
+  if (!config.bucketName) throw new DomainError("AWS S3 bucket name is required");
+  return config;
+};
+var createS3ConfigFromEnv = (env = process.env) => {
+  return createS3Config({
+    region: env.AWS_REGION,
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+    bucketName: env.AWS_S3_BUCKET_NAME
+  });
+};
+
+// src/index.ts
+var buildService = (config) => {
+  const gateway = new AwsS3StorageGateway(config);
+  const downloadFileUseCase = new DownloadFileUseCase(gateway);
+  const listFilesUseCase = new ListFilesUseCase(gateway);
+  const deleteFileUseCase = new DeleteFileUseCase(gateway);
+  const generateSignedUrlUseCase = new GenerateSignedUrlUseCase(gateway);
+  return new S3Service(
+    downloadFileUseCase,
+    listFilesUseCase,
+    deleteFileUseCase,
+    generateSignedUrlUseCase
+  );
+};
+var createS3Service = (config) => {
+  return buildService(createS3Config(config));
+};
+var createS3ServiceFromEnv = (env = process.env) => {
+  return buildService(createS3ConfigFromEnv(env));
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DomainError,
+  S3Service,
+  createS3Service,
+  createS3ServiceFromEnv
+});

package/dist/index.d.cts

@@ -0,0 +1,191 @@
+import { GetObjectCommandOutput } from '@aws-sdk/client-s3';
+
+/**
+ * Corpo retornado pelo S3 em operações de download.
+ * É não-nulo por contrato para simplificar os casos de uso.
+ */
+type S3ObjectBody = NonNullable<GetObjectCommandOutput["Body"]>;
+/**
+ * Porta de saída da aplicação para operações de armazenamento no S3.
+ * Casos de uso dependem desta interface, não da implementação AWS.
+ */
+interface S3StorageGateway {
+    /**
+     * Obtém o objeto do S3 a partir da chave completa.
+     *
+     * @param objectKey Chave completa do objeto (ex.: `projeto/pasta/arquivo.pdf`).
+     * @returns Corpo do arquivo em stream/blob conforme SDK AWS.
+     */
+    getObject(objectKey: string): Promise<S3ObjectBody>;
+    /**
+     * Lista chaves de objetos a partir de um prefixo.
+     *
+     * Em geral o prefixo termina com `/` para simular "pasta".
+     * Ex.: `projeto/pasta/`.
+     *
+     * @param prefix Prefixo de busca no bucket.
+     * @returns Lista de chaves completas encontradas.
+     */
+    listObjects(prefix: string): Promise<string[]>;
+    /**
+     * Remove um objeto do bucket pela chave completa.
+     *
+     * @param objectKey Chave completa do objeto a ser removido.
+     */
+    deleteObject(objectKey: string): Promise<void>;
+    /**
+     * Gera URL assinada para download (`GET`) de um objeto.
+     *
+     * @param objectKey Chave completa do objeto.
+     * @param expiresInSeconds Tempo de expiração da URL, em segundos.
+     * @returns URL temporária assinada.
+     */
+    generateGetSignedUrl(objectKey: string, expiresInSeconds: number): Promise<string>;
+}
+
+/**
+ * Dados necessários para remover um arquivo do S3.
+ */
+interface DeleteFileInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo a ser removido. */
+    fileName: string;
+}
+/**
+ * Caso de uso responsável por remover um objeto no S3.
+ */
+declare class DeleteFileUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a remoção de um arquivo.
+     *
+     * @param input Dados de identificação do arquivo.
+     * @returns Mensagem de confirmação de exclusão.
+     */
+    execute(input: DeleteFileInput): Promise<{
+        message: string;
+    }>;
+}
+
+/**
+ * Dados necessários para baixar um arquivo do S3.
+ */
+interface DownloadFileInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo a ser baixado. */
+    fileName: string;
+}
+/**
+ * Caso de uso responsável por baixar um objeto do S3.
+ * Constrói a chave no padrão de domínio e delega o acesso à porta de infraestrutura.
+ */
+declare class DownloadFileUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa o download de um arquivo.
+     *
+     * @param input Dados de identificação do arquivo.
+     * @returns Corpo do objeto retornado pelo SDK AWS (stream/blob).
+     */
+    execute(input: DownloadFileInput): Promise<S3ObjectBody>;
+}
+
+/**
+ * Dados necessários para gerar URL assinada de download.
+ */
+interface GenerateSignedUrlInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo para gerar a URL assinada. */
+    fileName: string;
+    /** Expiração da URL em segundos. Padrão: 3600. */
+    expiresIn?: number;
+}
+/**
+ * Caso de uso responsável por gerar URL assinada (GET) para um objeto do S3.
+ */
+declare class GenerateSignedUrlUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a geração da URL assinada.
+     *
+     * Regra de negócio: `expiresIn` deve ser maior que zero.
+     *
+     * @param input Dados de identificação do arquivo e expiração opcional.
+     * @returns URL assinada para download temporário.
+     */
+    execute(input: GenerateSignedUrlInput): Promise<string>;
+}
+
+/**
+ * Dados necessários para listar arquivos de um caminho lógico no S3.
+ */
+interface ListFilesInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico a ser listado dentro do projeto. */
+    path: string;
+}
+/**
+ * Caso de uso responsável por listar arquivos a partir de um prefixo.
+ */
+declare class ListFilesUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a listagem de chaves no S3.
+     *
+     * @param input Dados de projeto e caminho.
+     * @returns Lista de chaves completas encontradas no bucket.
+     */
+    execute(input: ListFilesInput): Promise<string[]>;
+}
+
+interface IS3Service {
+    downloadFile(project: string, path: string, fileName: string): Promise<S3ObjectBody>;
+    listFiles(project: string, path: string): Promise<string[]>;
+    deleteFile(project: string, path: string, fileName: string): Promise<{
+        message: string;
+    }>;
+    generateSignedUrl(project: string, path: string, fileName: string, expiresIn?: number): Promise<string>;
+}
+declare class S3Service implements IS3Service {
+    private readonly downloadFileUseCase;
+    private readonly listFilesUseCase;
+    private readonly deleteFileUseCase;
+    private readonly generateSignedUrlUseCase;
+    constructor(downloadFileUseCase: DownloadFileUseCase, listFilesUseCase: ListFilesUseCase, deleteFileUseCase: DeleteFileUseCase, generateSignedUrlUseCase: GenerateSignedUrlUseCase);
+    downloadFile(project: string, path: string, fileName: string): Promise<S3ObjectBody>;
+    listFiles(project: string, path: string): Promise<string[]>;
+    deleteFile(project: string, path: string, fileName: string): Promise<{
+        message: string;
+    }>;
+    generateSignedUrl(project: string, path: string, fileName: string, expiresIn?: number): Promise<string>;
+}
+
+interface S3Config {
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucketName: string;
+}
+
+declare class DomainError extends Error {
+    constructor(message: string);
+}
+
+declare const createS3Service: (config: S3Config) => S3Service;
+declare const createS3ServiceFromEnv: (env?: NodeJS.ProcessEnv) => S3Service;
+
+export { DomainError, type IS3Service, type S3Config, S3Service, createS3Service, createS3ServiceFromEnv };

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+import { GetObjectCommandOutput } from '@aws-sdk/client-s3';
+
+/**
+ * Corpo retornado pelo S3 em operações de download.
+ * É não-nulo por contrato para simplificar os casos de uso.
+ */
+type S3ObjectBody = NonNullable<GetObjectCommandOutput["Body"]>;
+/**
+ * Porta de saída da aplicação para operações de armazenamento no S3.
+ * Casos de uso dependem desta interface, não da implementação AWS.
+ */
+interface S3StorageGateway {
+    /**
+     * Obtém o objeto do S3 a partir da chave completa.
+     *
+     * @param objectKey Chave completa do objeto (ex.: `projeto/pasta/arquivo.pdf`).
+     * @returns Corpo do arquivo em stream/blob conforme SDK AWS.
+     */
+    getObject(objectKey: string): Promise<S3ObjectBody>;
+    /**
+     * Lista chaves de objetos a partir de um prefixo.
+     *
+     * Em geral o prefixo termina com `/` para simular "pasta".
+     * Ex.: `projeto/pasta/`.
+     *
+     * @param prefix Prefixo de busca no bucket.
+     * @returns Lista de chaves completas encontradas.
+     */
+    listObjects(prefix: string): Promise<string[]>;
+    /**
+     * Remove um objeto do bucket pela chave completa.
+     *
+     * @param objectKey Chave completa do objeto a ser removido.
+     */
+    deleteObject(objectKey: string): Promise<void>;
+    /**
+     * Gera URL assinada para download (`GET`) de um objeto.
+     *
+     * @param objectKey Chave completa do objeto.
+     * @param expiresInSeconds Tempo de expiração da URL, em segundos.
+     * @returns URL temporária assinada.
+     */
+    generateGetSignedUrl(objectKey: string, expiresInSeconds: number): Promise<string>;
+}
+
+/**
+ * Dados necessários para remover um arquivo do S3.
+ */
+interface DeleteFileInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo a ser removido. */
+    fileName: string;
+}
+/**
+ * Caso de uso responsável por remover um objeto no S3.
+ */
+declare class DeleteFileUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a remoção de um arquivo.
+     *
+     * @param input Dados de identificação do arquivo.
+     * @returns Mensagem de confirmação de exclusão.
+     */
+    execute(input: DeleteFileInput): Promise<{
+        message: string;
+    }>;
+}
+
+/**
+ * Dados necessários para baixar um arquivo do S3.
+ */
+interface DownloadFileInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo a ser baixado. */
+    fileName: string;
+}
+/**
+ * Caso de uso responsável por baixar um objeto do S3.
+ * Constrói a chave no padrão de domínio e delega o acesso à porta de infraestrutura.
+ */
+declare class DownloadFileUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa o download de um arquivo.
+     *
+     * @param input Dados de identificação do arquivo.
+     * @returns Corpo do objeto retornado pelo SDK AWS (stream/blob).
+     */
+    execute(input: DownloadFileInput): Promise<S3ObjectBody>;
+}
+
+/**
+ * Dados necessários para gerar URL assinada de download.
+ */
+interface GenerateSignedUrlInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico dentro do projeto (sem o nome do arquivo). */
+    path: string;
+    /** Nome final do arquivo para gerar a URL assinada. */
+    fileName: string;
+    /** Expiração da URL em segundos. Padrão: 3600. */
+    expiresIn?: number;
+}
+/**
+ * Caso de uso responsável por gerar URL assinada (GET) para um objeto do S3.
+ */
+declare class GenerateSignedUrlUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a geração da URL assinada.
+     *
+     * Regra de negócio: `expiresIn` deve ser maior que zero.
+     *
+     * @param input Dados de identificação do arquivo e expiração opcional.
+     * @returns URL assinada para download temporário.
+     */
+    execute(input: GenerateSignedUrlInput): Promise<string>;
+}
+
+/**
+ * Dados necessários para listar arquivos de um caminho lógico no S3.
+ */
+interface ListFilesInput {
+    /** Nome lógico do projeto (primeiro segmento da chave S3). */
+    project: string;
+    /** Caminho lógico a ser listado dentro do projeto. */
+    path: string;
+}
+/**
+ * Caso de uso responsável por listar arquivos a partir de um prefixo.
+ */
+declare class ListFilesUseCase {
+    private readonly gateway;
+    constructor(gateway: S3StorageGateway);
+    /**
+     * Executa a listagem de chaves no S3.
+     *
+     * @param input Dados de projeto e caminho.
+     * @returns Lista de chaves completas encontradas no bucket.
+     */
+    execute(input: ListFilesInput): Promise<string[]>;
+}
+
+interface IS3Service {
+    downloadFile(project: string, path: string, fileName: string): Promise<S3ObjectBody>;
+    listFiles(project: string, path: string): Promise<string[]>;
+    deleteFile(project: string, path: string, fileName: string): Promise<{
+        message: string;
+    }>;
+    generateSignedUrl(project: string, path: string, fileName: string, expiresIn?: number): Promise<string>;
+}
+declare class S3Service implements IS3Service {
+    private readonly downloadFileUseCase;
+    private readonly listFilesUseCase;
+    private readonly deleteFileUseCase;
+    private readonly generateSignedUrlUseCase;
+    constructor(downloadFileUseCase: DownloadFileUseCase, listFilesUseCase: ListFilesUseCase, deleteFileUseCase: DeleteFileUseCase, generateSignedUrlUseCase: GenerateSignedUrlUseCase);
+    downloadFile(project: string, path: string, fileName: string): Promise<S3ObjectBody>;
+    listFiles(project: string, path: string): Promise<string[]>;
+    deleteFile(project: string, path: string, fileName: string): Promise<{
+        message: string;
+    }>;
+    generateSignedUrl(project: string, path: string, fileName: string, expiresIn?: number): Promise<string>;
+}
+
+interface S3Config {
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucketName: string;
+}
+
+declare class DomainError extends Error {
+    constructor(message: string);
+}
+
+declare const createS3Service: (config: S3Config) => S3Service;
+declare const createS3ServiceFromEnv: (env?: NodeJS.ProcessEnv) => S3Service;
+
+export { DomainError, type IS3Service, type S3Config, S3Service, createS3Service, createS3ServiceFromEnv };

package/dist/index.js

@@ -0,0 +1,240 @@
+// src/domain/errors/DomainError.ts
+var DomainError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DomainError";
+  }
+};
+
+// src/domain/value-objects/S3ObjectPath.ts
+var normalizeSegment = (value, label) => {
+  const sanitized = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!sanitized) {
+    throw new DomainError(`${label} is required`);
+  }
+  if (sanitized.includes("..")) {
+    throw new DomainError(`${label} cannot contain ".."`);
+  }
+  return sanitized;
+};
+var S3ObjectPath = class {
+  static build(project, path, fileName) {
+    const projectPart = normalizeSegment(project, "project");
+    const pathPart = normalizeSegment(path, "path");
+    if (!fileName) {
+      return `${projectPart}/${pathPart}/`;
+    }
+    const filePart = normalizeSegment(fileName, "fileName");
+    return `${projectPart}/${pathPart}/${filePart}`;
+  }
+};
+
+// src/application/use-cases/DeleteFileUseCase.ts
+var DeleteFileUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a remoção de um arquivo.
+   *
+   * @param input Dados de identificação do arquivo.
+   * @returns Mensagem de confirmação de exclusão.
+   */
+  async execute(input) {
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    await this.gateway.deleteObject(objectKey);
+    return { message: "Arquivo deletado com sucesso" };
+  }
+};
+
+// src/application/use-cases/DownloadFileUseCase.ts
+var DownloadFileUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa o download de um arquivo.
+   *
+   * @param input Dados de identificação do arquivo.
+   * @returns Corpo do objeto retornado pelo SDK AWS (stream/blob).
+   */
+  async execute(input) {
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    return this.gateway.getObject(objectKey);
+  }
+};
+
+// src/application/use-cases/GenerateSignedUrlUseCase.ts
+var GenerateSignedUrlUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a geração da URL assinada.
+   *
+   * Regra de negócio: `expiresIn` deve ser maior que zero.
+   *
+   * @param input Dados de identificação do arquivo e expiração opcional.
+   * @returns URL assinada para download temporário.
+   */
+  async execute(input) {
+    const expiresIn = input.expiresIn ?? 3600;
+    if (expiresIn <= 0) {
+      throw new DomainError("expiresIn must be greater than zero");
+    }
+    const objectKey = S3ObjectPath.build(input.project, input.path, input.fileName);
+    return this.gateway.generateGetSignedUrl(objectKey, expiresIn);
+  }
+};
+
+// src/application/use-cases/ListFilesUseCase.ts
+var ListFilesUseCase = class {
+  constructor(gateway) {
+    this.gateway = gateway;
+  }
+  /**
+   * Executa a listagem de chaves no S3.
+   *
+   * @param input Dados de projeto e caminho.
+   * @returns Lista de chaves completas encontradas no bucket.
+   */
+  async execute(input) {
+    const prefix = S3ObjectPath.build(input.project, input.path);
+    return this.gateway.listObjects(prefix);
+  }
+};
+
+// src/facade/S3Service.ts
+var S3Service = class {
+  constructor(downloadFileUseCase, listFilesUseCase, deleteFileUseCase, generateSignedUrlUseCase) {
+    this.downloadFileUseCase = downloadFileUseCase;
+    this.listFilesUseCase = listFilesUseCase;
+    this.deleteFileUseCase = deleteFileUseCase;
+    this.generateSignedUrlUseCase = generateSignedUrlUseCase;
+  }
+  async downloadFile(project, path, fileName) {
+    return this.downloadFileUseCase.execute({ project, path, fileName });
+  }
+  async listFiles(project, path) {
+    return this.listFilesUseCase.execute({ project, path });
+  }
+  async deleteFile(project, path, fileName) {
+    return this.deleteFileUseCase.execute({ project, path, fileName });
+  }
+  async generateSignedUrl(project, path, fileName, expiresIn = 10800) {
+    return this.generateSignedUrlUseCase.execute({
+      project,
+      path,
+      fileName,
+      expiresIn
+    });
+  }
+};
+
+// src/infrastructure/aws/AwsS3StorageGateway.ts
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  S3Client
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+var AwsS3StorageGateway = class {
+  constructor(config, client) {
+    this.config = config;
+    this.client = client ?? new S3Client({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+  }
+  client;
+  async getObject(objectKey) {
+    const { Body } = await this.client.send(
+      new GetObjectCommand({
+        Bucket: this.config.bucketName,
+        Key: objectKey
+      })
+    );
+    if (!Body) {
+      throw new Error(`Object "${objectKey}" returned empty body`);
+    }
+    return Body;
+  }
+  async listObjects(prefix) {
+    const { Contents } = await this.client.send(
+      new ListObjectsV2Command({
+        Bucket: this.config.bucketName,
+        Prefix: prefix
+      })
+    );
+    return Contents?.map((file) => file.Key).filter((key) => Boolean(key)) ?? [];
+  }
+  async deleteObject(objectKey) {
+    await this.client.send(
+      new DeleteObjectCommand({
+        Bucket: this.config.bucketName,
+        Key: objectKey
+      })
+    );
+  }
+  async generateGetSignedUrl(objectKey, expiresInSeconds) {
+    const command = new GetObjectCommand({
+      Bucket: this.config.bucketName,
+      Key: objectKey
+    });
+    return getSignedUrl(this.client, command, { expiresIn: expiresInSeconds });
+  }
+};
+
+// src/infrastructure/config/S3Config.ts
+var createS3Config = (input) => {
+  const config = {
+    region: input.region?.trim() ?? "",
+    accessKeyId: input.accessKeyId?.trim() ?? "",
+    secretAccessKey: input.secretAccessKey?.trim() ?? "",
+    bucketName: input.bucketName?.trim() ?? ""
+  };
+  if (!config.region) throw new DomainError("AWS region is required");
+  if (!config.accessKeyId) throw new DomainError("AWS access key id is required");
+  if (!config.secretAccessKey) throw new DomainError("AWS secret access key is required");
+  if (!config.bucketName) throw new DomainError("AWS S3 bucket name is required");
+  return config;
+};
+var createS3ConfigFromEnv = (env = process.env) => {
+  return createS3Config({
+    region: env.AWS_REGION,
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+    bucketName: env.AWS_S3_BUCKET_NAME
+  });
+};
+
+// src/index.ts
+var buildService = (config) => {
+  const gateway = new AwsS3StorageGateway(config);
+  const downloadFileUseCase = new DownloadFileUseCase(gateway);
+  const listFilesUseCase = new ListFilesUseCase(gateway);
+  const deleteFileUseCase = new DeleteFileUseCase(gateway);
+  const generateSignedUrlUseCase = new GenerateSignedUrlUseCase(gateway);
+  return new S3Service(
+    downloadFileUseCase,
+    listFilesUseCase,
+    deleteFileUseCase,
+    generateSignedUrlUseCase
+  );
+};
+var createS3Service = (config) => {
+  return buildService(createS3Config(config));
+};
+var createS3ServiceFromEnv = (env = process.env) => {
+  return buildService(createS3ConfigFromEnv(env));
+};
+export {
+  DomainError,
+  S3Service,
+  createS3Service,
+  createS3ServiceFromEnv
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vlsdev/s3-portable",
+  "version": "1.0.0",
+  "description": "Portable S3 service package for microservices.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+  "access": "public",
+  "registry": "https://registry.npmjs.org/"
+},
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck",
+    "publish:private": "npm publish",
+    "publish:private:otp": "npm publish --otp"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.870.0",
+    "@aws-sdk/s3-request-presigner": "^3.870.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2"
+  }
+}