@miguelmorales13/nestkit 0.4.1 → 0.5.1

package/README.md

@@ -685,6 +685,45 @@ Requiere `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`; `SMTP_SECURE` e
 para forzar TLS directo). Elegí Nodemailer cuando ya tenés un proveedor SMTP propio (Gmail, SES,
 Mailgun, tu propio servidor) en vez de sumar otra cuenta de terceros.
 
+### `storage` — subida de archivos agnóstica del proveedor
+
+Almacenamiento de archivos con un puerto único (`StoragePort`) y varios adaptadores intercambiables:
+**local** (disco, para desarrollo), **S3-compatible** (AWS S3 y **Cloudflare R2**) y **Bunny.net**.
+Sirve cualquier tipo de archivo — imágenes, PDF y otros documentos, video, audio — sin suponer nada
+del contenido. Cambiar de R2 a Bunny (o al revés) es **una línea** en `StorageModule.forRoot(...)`:
+nada depende de un proveedor concreto, todo depende del puerto.
+
+Trae streaming en ambos sentidos (`putStream` para subir grandes/video sin cargarlos en memoria,
+`getStream` con **rango de bytes** para el seek de video/audio), subida **directa firmada** al
+proveedor (`signedUploadUrl`, para que un archivo pesado no pase por tu API), URLs de lectura
+firmadas (`signedReadUrl`), y `stat`/`exists`/`list`/`delete`.
+
+```ts
+// En el módulo raíz — elegí el proveedor acá y nada más cambia:
+StorageModule.forRoot({ provider: 'r2' })                       // lee R2_* del entorno
+StorageModule.forRoot({ provider: 'bunny' })                    // lee BUNNY_* del entorno
+StorageModule.forRoot({ provider: 'local', local: { root: '.storage' } })
+StorageModule.forRootAsync({ inject: [Config], useFactory: (c) => ({ provider: c.storageProvider }) })
+
+// En cualquier servicio:
+constructor(@Inject(STORAGE) private readonly storage: StoragePort) {}
+
+await this.storage.put(`${tenantId}/platillos/${id}.webp`, buffer, { contentType: 'image/webp' });
+const { stream, totalSize, contentRange } = await this.storage.getStream(key, { start, end }); // video
+const target = await this.storage.signedUploadUrl(key, { contentType: 'video/mp4' });          // subida directa
+const url = this.storage.publicUrl(key) ?? (await this.storage.signedReadUrl(key));
+```
+
+Los adaptadores S3/R2 cargan `@aws-sdk/client-s3` **de forma diferida** (solo si se usa ese
+proveedor), así que un proyecto con Bunny o local no necesita el SDK. Peer deps opcionales:
+`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`, `@aws-sdk/lib-storage` (solo para S3/R2);
+Bunny y local no requieren nada extra. Variables de entorno reconocidas: `STORAGE_PROVIDER`,
+`STORAGE_LOCAL_ROOT`/`STORAGE_PUBLIC_BASE_URL`, `S3_*`, `R2_*`, `BUNNY_*` (ver `resolveStorageOptions`).
+
+`signedUploadUrl` no existe en el adaptador local (un cliente no puede subir a tu disco) ni en Bunny
+Storage (no hay firma que oculte la contraseña de la zona); en esos casos se sube por la API, o se
+usa Bunny Stream/TUS para video grande.
+
 ## Subpaths disponibles
 
 | Subpath | Qué trae |
@@ -702,6 +741,7 @@ Mailgun, tu propio servidor) en vez de sumar otra cuenta de terceros.
 | `@miguelmorales13/nestkit/whatsapp` | `WhatsAppModule`, `WHATSAPP_CLIENT`, `WhatsAppClient` |
 | `@miguelmorales13/nestkit/stripe` | `StripeModule`, `STRIPE_CLIENT`, `createStripeWebhookController` |
 | `@miguelmorales13/nestkit/auth` | `AuthUserPort`, `BaseAuthService`, `createAuthController`, `TokenService`, `JwtAuthGuard`, `RolesGuard`, `RequireTenantGuard`, `CurrentUser`, `CurrentTenant`, `Roles` |
+| `@miguelmorales13/nestkit/storage` | `StorageModule`, `STORAGE`, `StoragePort`, adaptadores `LocalStorage`/`S3Storage`/`BunnyStorage` |
 | `@miguelmorales13/nestkit/email/resend` | `ResendModule`, `RESEND_CLIENT` |
 | `@miguelmorales13/nestkit/email/nodemailer` | `NodemailerModule`, `NODEMAILER_TRANSPORT` |
 | `@miguelmorales13/nestkit/i18n` | `I18nModule` (wrapper de `nestjs-i18n`), `translateOr` |
@@ -709,7 +749,5 @@ Mailgun, tu propio servidor) en vez de sumar otra cuenta de terceros.
 
 ## Estado del paquete
 
-`0.3.0`, no publicado en npm todavía (repo privado, se prueba localmente con `bun link` antes de
-publicar). Sin adaptador Mongo real. Sin tests unitarios propios — es un paquete nuevo sin
-consumidor productivo todavía; la primera integración real (ej. en `hr-pymes-saas`) es la que va a
-ejercitar el código de verdad.
+`0.5.1`. Sin adaptador Mongo real. Sin tests unitarios propios — es un paquete nuevo; la primera
+integración real (ej. en `hr-pymes-saas` o `cuota`) es la que ejercita el código de verdad.

package/dist/index.cjs

@@ -3,18 +3,22 @@
 
 
 var _chunkRF75KC63cjs = require('./chunk-RF75KC63.cjs');
-require('./chunk-MR2IFCZE.cjs');
 
 
 
 
-var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
-require('./chunk-KVBQBT3D.cjs');
+var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
 
 
 
+var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
 
-var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
+
+
+
+var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
+require('./chunk-MR2IFCZE.cjs');
+require('./chunk-KVBQBT3D.cjs');
 
 
 var _chunk54ZXIB5Tcjs = require('./chunk-54ZXIB5T.cjs');
@@ -25,6 +29,9 @@ var _chunkTJHRABMLcjs = require('./chunk-TJHRABML.cjs');
 
 
 var _chunk3CLYZC3Tcjs = require('./chunk-3CLYZC3T.cjs');
+
+
+var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
 require('./chunk-7SOM7EZP.cjs');
 
 
@@ -42,13 +49,6 @@ var _chunkZA56XBCKcjs = require('./chunk-ZA56XBCK.cjs');
 
 
 var _chunkR7BVS6CIcjs = require('./chunk-R7BVS6CI.cjs');
-
-
-
-var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
-
-
-var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
 require('./chunk-2REOCMUD.cjs');
 
 

package/dist/index.js

@@ -3,18 +3,22 @@ import {
   PgModule,
   withTenantScope
 } from "./chunk-VKOPDDCC.js";
-import "./chunk-NAK4WDKS.js";
+import {
+  SUPABASE_ANON_CLIENT,
+  SUPABASE_SERVICE_ROLE_CLIENT,
+  SupabaseModule
+} from "./chunk-PA24P76K.js";
+import {
+  I18nModule,
+  translateOr
+} from "./chunk-IYUUYCP5.js";
 import {
   REQUEST_ID_HEADER,
   RequestIdMiddleware,
   TrackingModule
 } from "./chunk-EYURGACO.js";
+import "./chunk-NAK4WDKS.js";
 import "./chunk-EPVKCBPT.js";
-import {
-  SUPABASE_ANON_CLIENT,
-  SUPABASE_SERVICE_ROLE_CLIENT,
-  SupabaseModule
-} from "./chunk-PA24P76K.js";
 import {
   applyNestKitDefaults
 } from "./chunk-AOCF5QCZ.js";
@@ -25,6 +29,9 @@ import {
   BaseCrudService,
   createCrudController
 } from "./chunk-JOVBJDJ2.js";
+import {
+  BaseResponseDto
+} from "./chunk-XX2HPTRU.js";
 import "./chunk-DQYAIQQ5.js";
 import {
   ConflictAppException,
@@ -42,13 +49,6 @@ import {
 import {
   AppException
 } from "./chunk-YFYHLYHN.js";
-import {
-  I18nModule,
-  translateOr
-} from "./chunk-IYUUYCP5.js";
-import {
-  BaseResponseDto
-} from "./chunk-XX2HPTRU.js";
 import "./chunk-4MGIQFAJ.js";
 export {
   AppException,

package/dist/storage/adapters/bunny.storage.d.ts

@@ -0,0 +1,34 @@
+import { Readable } from 'node:stream';
+import type { BunnyStorageOptions } from '../storage.options.js';
+import type { ByteRange, ListResult, ObjectInfo, PutOptions, ReadStream, SignedUploadTarget, StoragePort } from '../storage.port.js';
+/**
+ * Bunny.net Storage adapter. Objects live in a Storage Zone (write/read via the
+ * Storage API) and are served publicly through the Pull Zone bound to it.
+ *
+ * Uses `fetch` only — no SDK. Streaming works both ways: `putStream` streams the
+ * body up, `getStream` streams it down. Direct signed UPLOADS are not offered:
+ * Bunny Storage has no presigned-PUT that avoids exposing the zone password, so
+ * uploads go through your API (or use Bunny Stream/TUS for large video).
+ */
+export declare class BunnyStorage implements StoragePort {
+    private readonly base;
+    private readonly apiKey;
+    private readonly pullZoneUrl?;
+    private readonly tokenSecurityKey?;
+    constructor(options: BunnyStorageOptions);
+    private url;
+    put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<ObjectInfo>;
+    putStream(key: string, stream: Readable, options?: PutOptions): Promise<ObjectInfo>;
+    get(key: string): Promise<Buffer>;
+    getStream(key: string, range?: ByteRange): Promise<ReadStream>;
+    stat(key: string): Promise<ObjectInfo | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    private listRaw;
+    list(prefix: string, options?: {
+        limit?: number;
+    }): Promise<ListResult>;
+    publicUrl(key: string): string | null;
+    signedReadUrl(key: string, ttlSeconds?: number): Promise<string>;
+    signedUploadUrl(): Promise<SignedUploadTarget>;
+}

package/dist/storage/adapters/local.storage.d.ts

@@ -0,0 +1,31 @@
+import type { Readable } from 'node:stream';
+import type { LocalStorageOptions } from '../storage.options.js';
+import type { ByteRange, ListResult, ObjectInfo, ReadStream, SignedUploadTarget, StoragePort } from '../storage.port.js';
+/**
+ * Filesystem-backed storage for development. Serves streams and byte ranges from
+ * disk. Content-Type is not persisted (the filesystem has no place for it), so
+ * `stat`/`getStream` return it only when the caller can infer it elsewhere.
+ *
+ * Not for production: there is no durability story, no CDN, and `signedUploadUrl`
+ * is unsupported (a client can't PUT to your disk). Use S3/R2 or Bunny there.
+ */
+export declare class LocalStorage implements StoragePort {
+    private readonly root;
+    private readonly publicBaseUrl?;
+    constructor(options: LocalStorageOptions);
+    /** Resolve a key to an absolute path, refusing anything that escapes the root. */
+    private pathOf;
+    put(key: string, data: Buffer | Uint8Array): Promise<ObjectInfo>;
+    putStream(key: string, stream: Readable): Promise<ObjectInfo>;
+    get(key: string): Promise<Buffer>;
+    getStream(key: string, range?: ByteRange): Promise<ReadStream>;
+    stat(key: string): Promise<ObjectInfo | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: {
+        limit?: number;
+    }): Promise<ListResult>;
+    publicUrl(key: string): string | null;
+    signedReadUrl(key: string): Promise<string>;
+    signedUploadUrl(): Promise<SignedUploadTarget>;
+}

package/dist/storage/adapters/s3.storage.d.ts

@@ -0,0 +1,37 @@
+import type { Readable } from 'node:stream';
+import type { S3StorageOptions } from '../storage.options.js';
+import type { ByteRange, ListResult, ObjectInfo, PutOptions, ReadStream, SignedUploadTarget, StoragePort } from '../storage.port.js';
+/**
+ * S3-compatible storage. Works with AWS S3 and any S3 API implementation —
+ * notably Cloudflare R2 (see `createR2Storage`) and MinIO.
+ *
+ * The AWS SDK is imported LAZILY, the first time it's needed, so an app that only
+ * uses the Bunny or local adapter never loads `@aws-sdk/*`. Install
+ * `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner` and `@aws-sdk/lib-storage`
+ * (optional peer deps) to use this adapter.
+ */
+export declare class S3Storage implements StoragePort {
+    private readonly bucket;
+    private readonly publicBaseUrl?;
+    private clientPromise?;
+    private readonly config;
+    constructor(options: S3StorageOptions);
+    /** Lazily construct (and memoize) the S3 client, loading the SDK on first use. */
+    private client;
+    put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<ObjectInfo>;
+    putStream(key: string, stream: Readable, options?: PutOptions): Promise<ObjectInfo>;
+    get(key: string): Promise<Buffer>;
+    getStream(key: string, range?: ByteRange): Promise<ReadStream>;
+    stat(key: string): Promise<ObjectInfo | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult>;
+    signedReadUrl(key: string, ttlSeconds?: number): Promise<string>;
+    signedUploadUrl(key: string, options?: PutOptions & {
+        ttlSeconds?: number;
+    }): Promise<SignedUploadTarget>;
+    publicUrl(key: string): string | null;
+}