@codercito/object-storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,285 @@
+# @codercito/object-storage
+
+Abstracción tipada para object storage compatible con S3 (Amazon S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Backblaze B2) con helpers para construir URLs públicas via CDN.
+
+- ✅ Subida directa, `exists`, y presigned POST listos para uso en backend.
+- ✅ Tipado estricto con TypeScript, sin `any`.
+- ✅ Cero dependencias propias. El AWS SDK es `peerDependency` (no se duplica).
+- ✅ Sin logs internos: tú decides cómo loggear vía callback `onError`.
+- ✅ Diseñado para abrirse a otros providers manteniendo la misma interfaz.
+
+## Instalación
+
+```bash
+npm install @codercito/object-storage @aws-sdk/client-s3 @aws-sdk/s3-presigned-post
+```
+
+Los paquetes `@aws-sdk/*` son `peerDependencies`: la librería los espera instalados pero no los incluye en su bundle.
+
+## Uso básico
+
+```ts
+import { S3StorageService, CdnFileUrlService } from '@codercito/object-storage';
+
+// Configura el servicio - el consumidor decide de dónde vienen los valores
+const storage = new S3StorageService({
+    bucket: process.env.S3_BUCKET!,
+    region: process.env.S3_REGION!,
+    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+});
+
+const urls = new CdnFileUrlService(process.env.CDN_PUBLIC_URL!);
+
+// Subir un archivo
+await storage.put('avatars/user-123.jpg', buffer, {
+    contentType: 'image/jpeg',
+    cacheControl: 'public, max-age=31536000',
+});
+
+// Verificar existencia
+const exists = await storage.exists('avatars/user-123.jpg');
+
+// Construir URL pública
+const url = urls.getPublicUrl('avatars/user-123.jpg');
+// → https://cdn.miapp.com/avatars/user-123.jpg
+```
+
+## Subida directa desde el cliente (presigned POST)
+
+Genera credenciales en el backend para que el cliente suba directamente al storage sin pasar bytes por tu servidor:
+
+```ts
+// Backend (ej. API route de Next.js)
+const presigned = await storage.presignedPost({
+    key: `uploads/${userId}/${filename}`,
+    contentType: 'image/jpeg',
+    maxSizeBytes: 5 * 1024 * 1024,  // 5 MB
+    expiresIn: 600,                  // 10 minutos
+});
+
+// Devuélvelo al cliente
+return Response.json(presigned);
+```
+
+```ts
+// Cliente (browser)
+const formData = new FormData();
+Object.entries(presigned.fields).forEach(([k, v]) => formData.append(k, v));
+formData.append('file', file);
+
+await fetch(presigned.url, { method: 'POST', body: formData });
+```
+
+## Providers compatibles
+
+`S3StorageService` funciona con cualquier API S3-compatible cambiando el `endpoint`:
+
+### Cloudflare R2
+
+```ts
+const storage = new S3StorageService({
+    bucket: 'my-bucket',
+    region: 'auto',
+    endpoint: 'https://ACCOUNT_ID.r2.cloudflarestorage.com',
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+});
+```
+
+### MinIO (local development)
+
+```ts
+const storage = new S3StorageService({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    endpoint: 'http://localhost:9000',
+    accessKeyId: 'minioadmin',
+    secretAccessKey: 'minioadmin',
+    forcePathStyle: true,  // necesario para MinIO
+});
+```
+
+### DigitalOcean Spaces
+
+```ts
+const storage = new S3StorageService({
+    bucket: 'my-space',
+    region: 'nyc3',
+    endpoint: 'https://nyc3.digitaloceanspaces.com',
+    accessKeyId: process.env.DO_SPACES_KEY!,
+    secretAccessKey: process.env.DO_SPACES_SECRET!,
+});
+```
+
+## Manejo de errores
+
+La librería expone tres clases de error:
+
+```ts
+import {
+    StorageUploadError,
+    StoragePresignError,
+    StorageConfigError,
+} from '@codercito/object-storage';
+
+try {
+    await storage.put('a.jpg', buffer, { contentType: 'image/jpeg' });
+} catch (e) {
+    if (e instanceof StorageUploadError) {
+        console.error('Falló la subida', e.key, e.cause);
+    }
+}
+```
+
+`StorageConfigError` se lanza al construir el servicio si falta algún campo obligatorio.
+
+### Logging y observabilidad
+
+La librería **no escribe a `console`** por sí sola. Si quieres loggear los errores internos (antes de que se lancen), inyecta un callback `onError`:
+
+```ts
+import pino from 'pino';
+const logger = pino();
+
+const storage = new S3StorageService({
+    bucket: '...', region: '...',
+    accessKeyId: '...', secretAccessKey: '...',
+    onError: (event) => {
+        logger.error({
+            operation: event.operation,
+            key: event.key,
+            cause: event.cause,
+        }, 'Storage error');
+    },
+});
+```
+
+Esto te permite integrar la librería con Pino, Winston, Sentry, Datadog, etc. sin que la librería decida por ti.
+
+## Validar variables de entorno
+
+La librería no incluye un validador de env vars: cada proyecto tiene sus propios nombres y convenciones. Aquí un ejemplo con [zod](https://zod.dev) que puedes copiar a tu proyecto:
+
+```ts
+// src/env.ts
+import { z } from 'zod';
+
+const schema = z.object({
+    S3_BUCKET: z.string().min(1),
+    S3_REGION: z.string().default('auto'),
+    S3_ENDPOINT: z.string().url().optional(),
+    S3_ACCESS_KEY_ID: z.string().min(1),
+    S3_SECRET_ACCESS_KEY: z.string().min(1),
+    CDN_PUBLIC_URL: z.string().url(),
+});
+
+const parsed = schema.safeParse(process.env);
+if (!parsed.success) {
+    console.error('Invalid env', parsed.error.flatten().fieldErrors);
+    throw new Error('Invalid environment variables');
+}
+export const env = parsed.data;
+```
+
+Y úsalo:
+
+```ts
+import { env } from './env';
+import { S3StorageService } from '@codercito/object-storage';
+
+export const storage = new S3StorageService({
+    bucket: env.S3_BUCKET,
+    region: env.S3_REGION,
+    endpoint: env.S3_ENDPOINT,
+    accessKeyId: env.S3_ACCESS_KEY_ID,
+    secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+});
+```
+
+## API
+
+### `S3StorageService`
+
+```ts
+new S3StorageService(config: S3StorageConfig)
+```
+
+| Campo | Tipo | Requerido | Descripción |
+|-------|------|-----------|-------------|
+| `bucket` | `string` | ✅ | Nombre del bucket. |
+| `region` | `string` | ✅ | Región AWS o `'auto'` para R2. |
+| `accessKeyId` | `string` | ✅ | Credencial. |
+| `secretAccessKey` | `string` | ✅ | Credencial. |
+| `endpoint` | `string` | — | Endpoint custom (R2, MinIO, etc.). |
+| `forcePathStyle` | `boolean` | — | Necesario para MinIO. |
+| `onError` | `(event) => void` | — | Callback de errores internos. |
+
+#### `put(key, body, options): Promise<void>`
+
+Sube un objeto. La key se sanea automáticamente.
+
+`options` extiende `PutObjectCommandInput` del AWS SDK; los campos `contentType` y `cacheControl` se traducen a sus equivalentes (`ContentType`, `CacheControl`).
+
+#### `exists(key): Promise<boolean>`
+
+Devuelve `true` si el objeto existe. `false` en cualquier otro caso (incluye errores de red).
+
+#### `presignedPost(request): Promise<PresignedPostResult>`
+
+Genera credenciales para subida directa desde el cliente.
+
+| Campo | Default | Descripción |
+|-------|---------|-------------|
+| `key` | — | Path destino. |
+| `contentType` | — | MIME esperado, se valida en el POST. |
+| `maxSizeBytes` | `10485760` (10 MB) | Tamaño máximo permitido. |
+| `expiresIn` | `600` (10 min) | Validez en segundos. |
+
+### `CdnFileUrlService`
+
+```ts
+new CdnFileUrlService(baseUrl: string)
+```
+
+Construye URLs públicas concatenando `baseUrl` con la key. **No re-sanitiza la key** — debes pasar la misma con la que subiste el objeto.
+
+```ts
+const urls = new CdnFileUrlService('https://cdn.miapp.com');
+urls.getPublicUrl('avatars/user.jpg');
+// → 'https://cdn.miapp.com/avatars/user.jpg'
+```
+
+### `sanitizeKey(key): string`
+
+Normaliza una key:
+- Quita caracteres no permitidos (deja `[a-zA-Z0-9/_\-.]`).
+- Colapsa slashes duplicados.
+- Quita slashes al inicio y final.
+
+```ts
+sanitizeKey('/avatars//user 123!.jpg');
+// → 'avatars/user123.jpg'
+```
+
+## Tipos
+
+Todos los tipos están exportados:
+
+```ts
+import type {
+    IStorageService,
+    IFileUrlService,
+    S3StorageConfig,
+    PutObjectOptions,
+    PresignedPostRequest,
+    PresignedPostResult,
+    StorageErrorEvent,
+} from '@codercito/object-storage';
+```
+
+`IStorageService` es la interfaz principal; útil para inyectar implementaciones distintas (mocks en tests, etc.).
+
+## Licencia
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { PutObjectCommandInput } from '@aws-sdk/client-s3';
+
+/**
+ * Opciones para subir un objeto. Extiende `PutObjectCommandInput` del AWS SDK
+ * para permitir cualquier parámetro adicional.
+ */
+interface PutObjectOptions extends Partial<PutObjectCommandInput> {
+    contentType: string;
+    cacheControl?: string;
+}
+/**
+ * Parámetros para generar un presigned POST.
+ */
+interface PresignedPostRequest {
+    /** Key (path) donde se subirá el archivo. */
+    key: string;
+    /** MIME type esperado. Se valida en la condición del POST. */
+    contentType: string;
+    /**
+     * Tamaño máximo permitido en bytes.
+     * @default 10485760 (10 MB)
+     */
+    maxSizeBytes?: number;
+    /**
+     * Tiempo de validez del presigned POST, en segundos.
+     * @default 600 (10 minutos)
+     */
+    expiresIn?: number;
+}
+/**
+ * Resultado de un presigned POST. Se envía al cliente para que suba el archivo
+ * directamente al storage sin pasar por el backend.
+ */
+interface PresignedPostResult {
+    url: string;
+    fields: Record<string, string>;
+    key: string;
+}
+/**
+ * Evento que recibe el callback `onError` cuando algo falla internamente
+ * en una operación de storage. La librería no escribe a `console` por su cuenta;
+ * el consumidor decide cómo loggear.
+ */
+interface StorageErrorEvent {
+    /** Identificador corto del tipo de operación que falló. */
+    operation: 'upload_failed' | 'presign_failed';
+    /** Key del objeto involucrado. */
+    key: string;
+    /** Causa original lanzada por el SDK o la red. */
+    cause: unknown;
+}
+/**
+ * Configuración para `S3StorageService`. Compatible con S3, R2, MinIO,
+ * DigitalOcean Spaces y cualquier API S3-compatible.
+ */
+interface S3StorageConfig {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /**
+     * Endpoint custom (solo necesario para providers no-AWS como R2 o MinIO).
+     */
+    endpoint?: string;
+    /**
+     * Si `true`, fuerza path-style URLs (`endpoint/bucket/key` en vez de
+     * `bucket.endpoint/key`). Necesario para MinIO y algunos proxies.
+     * @default false
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Callback opcional que se invoca cuando ocurre un error interno.
+     * Permite al consumidor loggear o reportar a su sistema preferido
+     * (Pino, Sentry, Datadog, etc.) sin que la librería decida por él.
+     */
+    onError?: (event: StorageErrorEvent) => void;
+}
+/**
+ * Interface principal del servicio de storage. Permite agregar otros providers
+ * en el futuro (R2 nativo, GCS, filesystem local) sin romper a los consumidores.
+ */
+interface IStorageService {
+    /** Sube un objeto al storage. */
+    put(key: string, body: string | Buffer, options: PutObjectOptions): Promise<void>;
+    /** Devuelve `true` si el objeto existe en el storage. */
+    exists(key: string): Promise<boolean>;
+    /** Genera un presigned POST para subida directa desde el cliente. */
+    presignedPost(request: PresignedPostRequest): Promise<PresignedPostResult>;
+}
+
+/**
+ * Implementación de `IStorageService` para Amazon S3 y APIs S3-compatible
+ * (Cloudflare R2, MinIO, DigitalOcean Spaces, Backblaze B2).
+ */
+declare class S3StorageService implements IStorageService {
+    private readonly client;
+    private readonly bucket;
+    private readonly onError?;
+    constructor(config: S3StorageConfig);
+    put(key: string, body: string | Buffer, options: PutObjectOptions): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    presignedPost({ key, contentType, maxSizeBytes, expiresIn, }: PresignedPostRequest): Promise<PresignedPostResult>;
+}
+
+/**
+ * Servicio para construir URLs públicas a archivos almacenados.
+ * Útil cuando expones los objetos vía un CDN o el endpoint público del bucket.
+ */
+interface IFileUrlService {
+    getPublicUrl(key: string): string;
+}
+/**
+ * Implementación basada en una base URL fija (típicamente un CDN como
+ * Cloudflare, CloudFront, o el endpoint público de R2/S3).
+ *
+ * No re-saniza la key: asume que se pasa la misma key con la que se subió
+ * el objeto. Sanitizar dos veces puede generar URLs que no apuntan al objeto
+ * real si la sanitización modifica la key.
+ *
+ * @example
+ * ```ts
+ * const urls = new CdnFileUrlService('https://cdn.miapp.com');
+ * urls.getPublicUrl('avatars/user-123.jpg');
+ * // → 'https://cdn.miapp.com/avatars/user-123.jpg'
+ * ```
+ */
+declare class CdnFileUrlService implements IFileUrlService {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    getPublicUrl(key: string): string;
+}
+
+/**
+ * Normaliza una key para object storage:
+ * - Quita caracteres no permitidos (deja alfanuméricos, `/`, `_`, `-`, `.`).
+ * - Colapsa slashes duplicados (`a//b` → `a/b`).
+ * - Quita slashes al inicio y al final.
+ *
+ * Útil para sanear input del usuario antes de subir archivos.
+ *
+ * @example
+ * ```ts
+ * sanitizeKey('/avatars//user 123!.jpg')  // 'avatars/user123.jpg'
+ * ```
+ */
+declare function sanitizeKey(key: string): string;
+
+/**
+ * Error lanzado cuando una subida a storage falla.
+ * La causa original está disponible en `error.cause`.
+ */
+declare class StorageUploadError extends Error {
+    readonly key: string;
+    constructor(key: string, cause: unknown);
+}
+/**
+ * Error lanzado cuando la generación de un presigned POST falla.
+ */
+declare class StoragePresignError extends Error {
+    readonly key: string;
+    constructor(key: string, cause: unknown);
+}
+/**
+ * Error lanzado al construir un `S3StorageService` con configuración inválida.
+ */
+declare class StorageConfigError extends Error {
+    constructor(message: string);
+}
+
+export { CdnFileUrlService, type IFileUrlService, type IStorageService, type PresignedPostRequest, type PresignedPostResult, type PutObjectOptions, type S3StorageConfig, S3StorageService, StorageConfigError, type StorageErrorEvent, StoragePresignError, StorageUploadError, sanitizeKey };

package/dist/index.js

@@ -0,0 +1,131 @@
+import { S3Client, PutObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
+
+// src/s3-storage.ts
+
+// src/errors.ts
+var StorageUploadError = class extends Error {
+  constructor(key, cause) {
+    super(`Failed to upload object: ${key}`, { cause });
+    this.key = key;
+    this.name = "StorageUploadError";
+  }
+  key;
+};
+var StoragePresignError = class extends Error {
+  constructor(key, cause) {
+    super(`Failed to generate presigned POST for: ${key}`, { cause });
+    this.key = key;
+    this.name = "StoragePresignError";
+  }
+  key;
+};
+var StorageConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StorageConfigError";
+  }
+};
+
+// src/utils.ts
+function sanitizeKey(key) {
+  return key.replace(/[^a-zA-Z0-9/_\-.]/g, "").replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
+}
+
+// src/s3-storage.ts
+var DEFAULT_MAX_SIZE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_EXPIRES_IN_SECONDS = 600;
+var S3StorageService = class {
+  client;
+  bucket;
+  onError;
+  constructor(config) {
+    if (!config.bucket) throw new StorageConfigError("Missing bucket");
+    if (!config.region) throw new StorageConfigError("Missing region");
+    if (!config.accessKeyId) throw new StorageConfigError("Missing accessKeyId");
+    if (!config.secretAccessKey) throw new StorageConfigError("Missing secretAccessKey");
+    this.bucket = config.bucket;
+    this.onError = config.onError;
+    this.client = new S3Client({
+      region: config.region,
+      endpoint: config.endpoint,
+      forcePathStyle: config.forcePathStyle,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+  }
+  async put(key, body, options) {
+    const safeKey = sanitizeKey(key);
+    try {
+      const { contentType, cacheControl, ...rest } = options;
+      await this.client.send(
+        new PutObjectCommand({
+          ...rest,
+          Bucket: this.bucket,
+          Key: safeKey,
+          Body: body,
+          ContentType: contentType,
+          CacheControl: cacheControl
+        })
+      );
+    } catch (cause) {
+      this.onError?.({ operation: "upload_failed", key: safeKey, cause });
+      throw new StorageUploadError(safeKey, cause);
+    }
+  }
+  async exists(key) {
+    const safeKey = sanitizeKey(key);
+    try {
+      await this.client.send(
+        new HeadObjectCommand({ Bucket: this.bucket, Key: safeKey })
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async presignedPost({
+    key,
+    contentType,
+    maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,
+    expiresIn = DEFAULT_EXPIRES_IN_SECONDS
+  }) {
+    const safeKey = sanitizeKey(key);
+    try {
+      const { url, fields } = await createPresignedPost(this.client, {
+        Bucket: this.bucket,
+        Key: safeKey,
+        Conditions: [
+          ["content-length-range", 0, maxSizeBytes],
+          ["eq", "$Content-Type", contentType]
+        ],
+        Fields: {
+          "Content-Type": contentType
+        },
+        Expires: expiresIn
+      });
+      return { url, fields, key: safeKey };
+    } catch (cause) {
+      this.onError?.({ operation: "presign_failed", key: safeKey, cause });
+      throw new StoragePresignError(safeKey, cause);
+    }
+  }
+};
+
+// src/file-url.ts
+var CdnFileUrlService = class {
+  baseUrl;
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+  getPublicUrl(key) {
+    const cleanKey = key.replace(/^\/+/, "");
+    return `${this.baseUrl}/${cleanKey}`;
+  }
+};
+
+export { CdnFileUrlService, S3StorageService, StorageConfigError, StoragePresignError, StorageUploadError, sanitizeKey };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/utils.ts","../src/s3-storage.ts","../src/file-url.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Error lanzado cuando una subida a storage falla.\n * La causa original está disponible en `error.cause`.\n */\nexport class StorageUploadError extends Error {\n    constructor(public readonly key: string, cause: unknown) {\n        super(`Failed to upload object: ${key}`, { cause });\n        this.name = 'StorageUploadError';\n    }\n}\n\n/**\n * Error lanzado cuando la generación de un presigned POST falla.\n */\nexport class StoragePresignError extends Error {\n    constructor(public readonly key: string, cause: unknown) {\n        super(`Failed to generate presigned POST for: ${key}`, { cause });\n        this.name = 'StoragePresignError';\n    }\n}\n\n/**\n * Error lanzado al construir un `S3StorageService` con configuración inválida.\n */\nexport class StorageConfigError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = 'StorageConfigError';\n    }\n}\n","/**\n * Normaliza una key para object storage:\n * - Quita caracteres no permitidos (deja alfanuméricos, `/`, `_`, `-`, `.`).\n * - Colapsa slashes duplicados (`a//b` → `a/b`).\n * - Quita slashes al inicio y al final.\n *\n * Útil para sanear input del usuario antes de subir archivos.\n *\n * @example\n * ```ts\n * sanitizeKey('/avatars//user 123!.jpg')  // 'avatars/user123.jpg'\n * ```\n */\nexport function sanitizeKey(key: string): string {\n    return key\n        .replace(/[^a-zA-Z0-9/_\\-.]/g, '')\n        .replace(/\\/+/g, '/')\n        .replace(/^\\/|\\/$/g, '');\n}\n","import {\n    S3Client,\n    PutObjectCommand,\n    HeadObjectCommand,\n} from '@aws-sdk/client-s3';\nimport { createPresignedPost } from '@aws-sdk/s3-presigned-post';\n\nimport type {\n    IStorageService,\n    PutObjectOptions,\n    PresignedPostRequest,\n    PresignedPostResult,\n    S3StorageConfig,\n    StorageErrorEvent,\n} from './types';\n\nimport {\n    StorageUploadError,\n    StoragePresignError,\n    StorageConfigError,\n} from './errors';\n\nimport { sanitizeKey } from './utils';\n\nconst DEFAULT_MAX_SIZE_BYTES = 10 * 1024 * 1024;\nconst DEFAULT_EXPIRES_IN_SECONDS = 600;\n\n/**\n * Implementación de `IStorageService` para Amazon S3 y APIs S3-compatible\n * (Cloudflare R2, MinIO, DigitalOcean Spaces, Backblaze B2).\n */\nexport class S3StorageService implements IStorageService {\n    private readonly client: S3Client;\n    private readonly bucket: string;\n    private readonly onError?: (event: StorageErrorEvent) => void;\n\n    constructor(config: S3StorageConfig) {\n        if (!config.bucket) throw new StorageConfigError('Missing bucket');\n        if (!config.region) throw new StorageConfigError('Missing region');\n        if (!config.accessKeyId) throw new StorageConfigError('Missing accessKeyId');\n        if (!config.secretAccessKey) throw new StorageConfigError('Missing secretAccessKey');\n\n        this.bucket = config.bucket;\n        this.onError = config.onError;\n\n        this.client = new S3Client({\n            region: config.region,\n            endpoint: config.endpoint,\n            forcePathStyle: config.forcePathStyle,\n            credentials: {\n                accessKeyId: config.accessKeyId,\n                secretAccessKey: config.secretAccessKey,\n            },\n        });\n    }\n\n    async put(\n        key: string,\n        body: string | Buffer,\n        options: PutObjectOptions\n    ): Promise<void> {\n        const safeKey = sanitizeKey(key);\n\n        try {\n            const { contentType, cacheControl, ...rest } = options;\n\n            await this.client.send(\n                new PutObjectCommand({\n                    ...rest,\n                    Bucket: this.bucket,\n                    Key: safeKey,\n                    Body: body,\n                    ContentType: contentType,\n                    CacheControl: cacheControl,\n                })\n            );\n        } catch (cause) {\n            this.onError?.({ operation: 'upload_failed', key: safeKey, cause });\n            throw new StorageUploadError(safeKey, cause);\n        }\n    }\n\n    async exists(key: string): Promise<boolean> {\n        const safeKey = sanitizeKey(key);\n        try {\n            await this.client.send(\n                new HeadObjectCommand({ Bucket: this.bucket, Key: safeKey })\n            );\n            return true;\n        } catch {\n            // No distinguimos entre NotFound y otros errores: si algo falla,\n            // tratamos el objeto como inexistente. Si el consumidor necesita\n            // distinguir, puede observar `onError`.\n            return false;\n        }\n    }\n\n    async presignedPost({\n        key,\n        contentType,\n        maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,\n        expiresIn = DEFAULT_EXPIRES_IN_SECONDS,\n    }: PresignedPostRequest): Promise<PresignedPostResult> {\n        const safeKey = sanitizeKey(key);\n\n        try {\n            const { url, fields } = await createPresignedPost(this.client, {\n                Bucket: this.bucket,\n                Key: safeKey,\n                Conditions: [\n                    ['content-length-range', 0, maxSizeBytes],\n                    ['eq', '$Content-Type', contentType],\n                ],\n                Fields: {\n                    'Content-Type': contentType,\n                },\n                Expires: expiresIn,\n            });\n\n            return { url, fields, key: safeKey };\n        } catch (cause) {\n            this.onError?.({ operation: 'presign_failed', key: safeKey, cause });\n            throw new StoragePresignError(safeKey, cause);\n        }\n    }\n}\n","/**\n * Servicio para construir URLs públicas a archivos almacenados.\n * Útil cuando expones los objetos vía un CDN o el endpoint público del bucket.\n */\nexport interface IFileUrlService {\n    getPublicUrl(key: string): string;\n}\n\n/**\n * Implementación basada en una base URL fija (típicamente un CDN como\n * Cloudflare, CloudFront, o el endpoint público de R2/S3).\n *\n * No re-saniza la key: asume que se pasa la misma key con la que se subió\n * el objeto. Sanitizar dos veces puede generar URLs que no apuntan al objeto\n * real si la sanitización modifica la key.\n *\n * @example\n * ```ts\n * const urls = new CdnFileUrlService('https://cdn.miapp.com');\n * urls.getPublicUrl('avatars/user-123.jpg');\n * // → 'https://cdn.miapp.com/avatars/user-123.jpg'\n * ```\n */\nexport class CdnFileUrlService implements IFileUrlService {\n    private readonly baseUrl: string;\n\n    constructor(baseUrl: string) {\n        // Quitar trailing slash para evitar dobles slashes al concatenar\n        this.baseUrl = baseUrl.replace(/\\/+$/, '');\n    }\n\n    getPublicUrl(key: string): string {\n        // Quitar leading slash de la key para evitar dobles slashes\n        const cleanKey = key.replace(/^\\/+/, '');\n        return `${this.baseUrl}/${cleanKey}`;\n    }\n}\n"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@codercito/object-storage",
+  "version": "0.1.0",
+  "description": "Abstracción tipada para object storage (S3-compatible) con CDN URL helpers",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-presigned-post": "^3.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.616.0",
+    "@aws-sdk/s3-presigned-post": "^3.616.0",
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "s3",
+    "storage",
+    "object-storage",
+    "aws",
+    "r2",
+    "cloudflare",
+    "minio",
+    "presigned"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}