@miguelmorales13/nestkit 0.4.0 → 0.5.0

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.0`. 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,21 @@
 
 
 var _chunkRF75KC63cjs = require('./chunk-RF75KC63.cjs');
-require('./chunk-MR2IFCZE.cjs');
+require('./chunk-KVBQBT3D.cjs');
 
 
 
 
-var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
-require('./chunk-KVBQBT3D.cjs');
+var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
+
+
+var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
+require('./chunk-MR2IFCZE.cjs');
 
 
 
 
-var _chunkSPTDXUEDcjs = require('./chunk-SPTDXUED.cjs');
+var _chunkV2M75FN3cjs = require('./chunk-V2M75FN3.cjs');
 
 
 var _chunk54ZXIB5Tcjs = require('./chunk-54ZXIB5T.cjs');
@@ -46,9 +49,6 @@ 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,21 @@ import {
   PgModule,
   withTenantScope
 } from "./chunk-VKOPDDCC.js";
-import "./chunk-NAK4WDKS.js";
-import {
-  REQUEST_ID_HEADER,
-  RequestIdMiddleware,
-  TrackingModule
-} from "./chunk-EYURGACO.js";
 import "./chunk-EPVKCBPT.js";
 import {
   SUPABASE_ANON_CLIENT,
   SUPABASE_SERVICE_ROLE_CLIENT,
   SupabaseModule
 } from "./chunk-PA24P76K.js";
+import {
+  BaseResponseDto
+} from "./chunk-XX2HPTRU.js";
+import "./chunk-NAK4WDKS.js";
+import {
+  REQUEST_ID_HEADER,
+  RequestIdMiddleware,
+  TrackingModule
+} from "./chunk-EYURGACO.js";
 import {
   applyNestKitDefaults
 } from "./chunk-AOCF5QCZ.js";
@@ -46,9 +49,6 @@ import {
   I18nModule,
   translateOr
 } from "./chunk-IYUUYCP5.js";
-import {
-  BaseResponseDto
-} from "./chunk-XX2HPTRU.js";
 import "./chunk-4MGIQFAJ.js";
 export {
   AppException,

package/dist/media/index.cjs

@@ -22,6 +22,12 @@ var _common = require('@nestjs/common');
 
 // src/media/media.service.ts
 
+
+// src/media/media.options.ts
+var MEDIA_OPTIONS = /* @__PURE__ */ Symbol("MEDIA_OPTIONS");
+var MEDIA_TTL = /* @__PURE__ */ Symbol("MEDIA_TTL");
+
+// src/media/media.service.ts
 var _crypto = require('crypto');
 var MediaService = class {
   constructor(ttlMs) {
@@ -29,9 +35,6 @@ var MediaService = class {
     this.logger = new (0, _common.Logger)(MediaService.name);
     this.store = /* @__PURE__ */ new Map();
   }
-  store_(data, contentType) {
-    return this.put(data, contentType);
-  }
   put(data, contentType) {
     this.sweep();
     const id = _crypto.randomUUID.call(void 0, ).replace(/-/g, "");
@@ -57,14 +60,16 @@ var MediaService = class {
   }
 };
 MediaService = exports.MediaService = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
-  _common.Injectable.call(void 0, )
+  _common.Injectable.call(void 0, ),
+  _chunk2REOCMUDcjs.__decorateParam.call(void 0, 0, _common.Inject.call(void 0, MEDIA_TTL))
 ], MediaService);
 
-// src/media/media.options.ts
-var MEDIA_OPTIONS = /* @__PURE__ */ Symbol("MEDIA_OPTIONS");
-
 // src/media/media.controller.ts
 var MediaController = class {
+  // Both dependencies are injected by explicit token, like the rest of this
+  // package. The bundler does not emit decorator metadata, so injecting by type
+  // alone leaves Nest unable to resolve the constructor at runtime — and the
+  // failure only shows when the consuming app boots, never at build time.
   constructor(media, options) {
     this.media = media;
     this.options = options;
@@ -99,6 +104,7 @@ _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
 ], MediaController.prototype, "serve", 1);
 MediaController = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
   _common.Controller.call(void 0, ),
+  _chunk2REOCMUDcjs.__decorateParam.call(void 0, 0, _common.Inject.call(void 0, MediaService)),
   _chunk2REOCMUDcjs.__decorateParam.call(void 0, 1, _common.Inject.call(void 0, MEDIA_OPTIONS))
 ], MediaController);
 
@@ -111,7 +117,8 @@ var MediaModule = class {
       controllers: [MediaController],
       providers: [
         { provide: MEDIA_OPTIONS, useValue: options },
-        { provide: MediaService, useFactory: () => new MediaService(_nullishCoalesce(options.ttlMs, () => ( ONE_HOUR))) }
+        { provide: MEDIA_TTL, useValue: _nullishCoalesce(options.ttlMs, () => ( ONE_HOUR)) },
+        MediaService
       ],
       exports: [MediaService]
     };
@@ -124,4 +131,5 @@ MediaModule = exports.MediaModule = _chunk2REOCMUDcjs.__decorateClass.call(void
 
 
 
-exports.MEDIA_OPTIONS = MEDIA_OPTIONS; exports.MediaModule = MediaModule; exports.MediaService = MediaService;
+
+exports.MEDIA_OPTIONS = MEDIA_OPTIONS; exports.MEDIA_TTL = MEDIA_TTL; exports.MediaModule = MediaModule; exports.MediaService = MediaService;

package/dist/media/index.d.ts

@@ -1,5 +1,5 @@
 export { MediaModule } from './media.module.js';
 export { MediaService } from './media.service.js';
-export { MEDIA_OPTIONS } from './media.options.js';
+export { MEDIA_OPTIONS, MEDIA_TTL } from './media.options.js';
 export type { MediaOptions } from './media.options.js';
 export type { StoredMedia } from './media.service.js';

package/dist/media/index.js

@@ -11,7 +11,7 @@ import {
   Controller,
   Get,
   Headers,
-  Inject,
+  Inject as Inject2,
   NotFoundException,
   Param,
   Post,
@@ -21,7 +21,13 @@ import {
 } from "@nestjs/common";
 
 // src/media/media.service.ts
-import { Injectable, Logger } from "@nestjs/common";
+import { Inject, Injectable, Logger } from "@nestjs/common";
+
+// src/media/media.options.ts
+var MEDIA_OPTIONS = /* @__PURE__ */ Symbol("MEDIA_OPTIONS");
+var MEDIA_TTL = /* @__PURE__ */ Symbol("MEDIA_TTL");
+
+// src/media/media.service.ts
 import { randomUUID } from "crypto";
 var MediaService = class {
   constructor(ttlMs) {
@@ -29,9 +35,6 @@ var MediaService = class {
     this.logger = new Logger(MediaService.name);
     this.store = /* @__PURE__ */ new Map();
   }
-  store_(data, contentType) {
-    return this.put(data, contentType);
-  }
   put(data, contentType) {
     this.sweep();
     const id = randomUUID().replace(/-/g, "");
@@ -57,14 +60,16 @@ var MediaService = class {
   }
 };
 MediaService = __decorateClass([
-  Injectable()
+  Injectable(),
+  __decorateParam(0, Inject(MEDIA_TTL))
 ], MediaService);
 
-// src/media/media.options.ts
-var MEDIA_OPTIONS = /* @__PURE__ */ Symbol("MEDIA_OPTIONS");
-
 // src/media/media.controller.ts
 var MediaController = class {
+  // Both dependencies are injected by explicit token, like the rest of this
+  // package. The bundler does not emit decorator metadata, so injecting by type
+  // alone leaves Nest unable to resolve the constructor at runtime — and the
+  // failure only shows when the consuming app boots, never at build time.
   constructor(media, options) {
     this.media = media;
     this.options = options;
@@ -99,7 +104,8 @@ __decorateClass([
 ], MediaController.prototype, "serve", 1);
 MediaController = __decorateClass([
   Controller(),
-  __decorateParam(1, Inject(MEDIA_OPTIONS))
+  __decorateParam(0, Inject2(MediaService)),
+  __decorateParam(1, Inject2(MEDIA_OPTIONS))
 ], MediaController);
 
 // src/media/media.module.ts
@@ -111,7 +117,8 @@ var MediaModule = class {
       controllers: [MediaController],
       providers: [
         { provide: MEDIA_OPTIONS, useValue: options },
-        { provide: MediaService, useFactory: () => new MediaService(options.ttlMs ?? ONE_HOUR) }
+        { provide: MEDIA_TTL, useValue: options.ttlMs ?? ONE_HOUR },
+        MediaService
       ],
       exports: [MediaService]
     };
@@ -122,6 +129,7 @@ MediaModule = __decorateClass([
 ], MediaModule);
 export {
   MEDIA_OPTIONS,
+  MEDIA_TTL,
   MediaModule,
   MediaService
 };

package/dist/media/media.options.d.ts

@@ -1,4 +1,5 @@
 export declare const MEDIA_OPTIONS: unique symbol;
+export declare const MEDIA_TTL: unique symbol;
 export interface MediaOptions {
     /**
      * Base URL the generated links point to, **including the global prefix** if

package/dist/media/media.service.d.ts

@@ -21,7 +21,6 @@ export declare class MediaService {
     private readonly logger;
     private readonly store;
     constructor(ttlMs: number);
-    store_(data: Buffer, contentType: string): string;
     put(data: Buffer, contentType: string): string;
     get(id: string): StoredMedia | undefined;
     /** Swept on write, which is the only moment the map can have grown. */

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;
+}