@vlsdev/s3-portable 1.0.0 → 1.0.2

package/README.md

@@ -1,43 +1,46 @@
-# @vs/s3-portable
+# @vlsdev/s3-portable
 
-Pacote TypeScript "portable" para padronizar integração com Amazon S3 em microserviços, com arquitetura em camadas (DDD + SOLID).
+Portable S3 service for Node.js microservices with TypeScript, DDD layers, and SOLID-oriented design.
 
-## Instalação
+## Install
 
 ```bash
-npm i @vs/s3-portable
+npm i @vlsdev/s3-portable
 ```
 
-## Variáveis de ambiente esperadas
+## Requirements
+
+- Node.js 18+
+- AWS credentials with S3 permissions (`s3:GetObject`, `s3:ListBucket`, `s3:DeleteObject`)
+
+## Environment variables
 
 ```env
 AWS_REGION=us-east-1
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-AWS_S3_BUCKET_NAME=...
+AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
+AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
+AWS_S3_BUCKET_NAME=your-bucket
 ```
 
-## Uso rápido (via env)
+## Quick start (from env)
 
 ```ts
 import "dotenv/config";
-import { createS3ServiceFromEnv } from "@vs/s3-portable";
+import { createS3ServiceFromEnv } from "@vlsdev/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);
+const files = await s3Service.listFiles("billing-service", "invoices");
+console.log(files);
 ```
 
-## Uso com configuração explícita
+## Explicit config
 
 ```ts
-import { createS3Service } from "@vs/s3-portable";
+import { createS3Service } from "@vlsdev/s3-portable";
 
 const s3Service = createS3Service({
-  region: "us-east-1",
+  region: process.env.AWS_REGION!,
   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
   bucketName: process.env.AWS_S3_BUCKET_NAME!,
@@ -46,51 +49,78 @@ const s3Service = createS3Service({
 
 ## API
 
-- `downloadFile(project, path, fileName)`
-- `listFiles(project, path)`
-- `deleteFile(project, path, fileName)`
-- `generateSignedUrl(project, path, fileName, expiresIn?)`
+### `downloadFile(project, path, fileName)`
 
-## Build
+Returns the S3 object body stream.
 
-```bash
-npm run build
+```ts
+const body = await s3Service.downloadFile("billing-service", "invoices", "invoice-1.pdf");
 ```
 
-## Publicacao privada no npm
+### `listFiles(project, path)`
 
-1. Login na conta correta:
+Returns object keys under `project/path/`.
 
-```bash
-npm whoami
+```ts
+const keys = await s3Service.listFiles("billing-service", "invoices");
 ```
 
-2. Publicar com 2FA (OTP interativo):
+### `deleteFile(project, path, fileName)`
 
-```bash
-npm run publish:private:otp
+Deletes a file and returns a success message.
+
+```ts
+await s3Service.deleteFile("billing-service", "invoices", "invoice-1.pdf");
 ```
 
-3. Ou publicar sem OTP usando token granular com permissao de publish + bypass 2FA:
+### `generateSignedUrl(project, path, fileName, expiresIn?)`
 
-```bash
-npm run publish:private
+Generates a signed GET URL (default expiration: `3600` seconds).
+
+```ts
+const url = await s3Service.generateSignedUrl(
+  "billing-service",
+  "invoices",
+  "invoice-1.pdf",
+  900
+);
 ```
 
-### Troubleshooting E403 na publicacao
+## Express example
 
-Se aparecer:
+```ts
+import express from "express";
+import "dotenv/config";
+import { createS3ServiceFromEnv } from "@vlsdev/s3-portable";
 
-`403 Forbidden ... Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.`
+const app = express();
+const s3 = createS3ServiceFromEnv();
 
-valide estes pontos:
+app.get("/files/:project/:path/:fileName/url", async (req, res) => {
+  const { project, path, fileName } = req.params;
+  const url = await s3.generateSignedUrl(project, path, fileName, 300);
+  res.json({ url });
+});
 
-- 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:
+app.listen(3000);
+```
 
-```bash
-npm logout
-npm login
+## Error handling
+
+This package throws:
+- `DomainError` for invalid input/configuration
+- AWS SDK errors for infrastructure failures
+
+```ts
+import { DomainError } from "@vlsdev/s3-portable";
+
+try {
+  await s3Service.generateSignedUrl("p", "docs", "file.pdf", 0);
+} catch (error) {
+  if (error instanceof DomainError) {
+    console.error("Validation error:", error.message);
+  }
+}
 ```
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlsdev/s3-portable",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Portable S3 service package for microservices.",
   "license": "MIT",
   "type": "module",
@@ -15,9 +15,9 @@
     }
   },
   "publishConfig": {
-  "access": "public",
-  "registry": "https://registry.npmjs.org/"
-},
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "files": [
     "dist"
   ],
@@ -25,8 +25,10 @@
     "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"
+    "publish:public": "npm publish --access public",
+    "version:patch": "npm version patch --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version",
+    "version:major": "npm version major --no-git-tag-version"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.870.0",