@miguelmorales13/nestkit 0.4.0 → 0.5.0

package/dist/storage/storage.port.d.ts

@@ -0,0 +1,136 @@
+import type { Readable } from 'node:stream';
+/**
+ * DI token for the storage adapter. Inject with `@Inject(STORAGE)`.
+ *
+ * `StoragePort` is the single provider-agnostic interface every adapter (local
+ * filesystem, S3/R2, Bunny.net, or a future one) implements. Consumers depend on
+ * this port and never on a concrete provider, so switching from R2 to Bunny (or
+ * back) is a one-line change in `StorageModule.forRoot(...)` — no call site moves.
+ */
+export declare const STORAGE: unique symbol;
+/** Options for a write (`put`/`putStream`/`signedUploadUrl`). */
+export interface PutOptions {
+    /** MIME type stored with the object (`image/webp`, `application/pdf`, `video/mp4`, …). */
+    contentType?: string;
+    /** `Cache-Control` header the object is served with (e.g. `public, max-age=31536000, immutable`). */
+    cacheControl?: string;
+    /** `Content-Disposition` (e.g. `attachment; filename="factura.pdf"`) for downloads. */
+    contentDisposition?: string;
+    /** Arbitrary metadata, stored where the provider supports it. */
+    metadata?: Record<string, string>;
+    /**
+     * Byte length of the payload. Optional for `put` (a Buffer knows its size) but
+     * some providers require it up front when streaming a body of unknown length.
+     */
+    contentLength?: number;
+}
+/** What is known about a stored object. */
+export interface ObjectInfo {
+    key: string;
+    /** Size in bytes. */
+    size: number;
+    contentType?: string;
+    lastModified?: Date;
+    etag?: string;
+}
+/**
+ * A half-open-ish byte range, HTTP semantics: `start` and `end` are both
+ * INCLUSIVE. `{ start: 0, end: 1023 }` is the first 1024 bytes. `end` omitted
+ * means "to the end of the object". Used to serve video/audio seek requests.
+ */
+export interface ByteRange {
+    start: number;
+    end?: number;
+}
+/** The result of opening an object for reading as a stream. */
+export interface ReadStream {
+    stream: Readable;
+    contentType?: string;
+    /** Bytes in THIS response (the range length when a range was requested). */
+    contentLength?: number;
+    /** Total size of the whole object, regardless of range. */
+    totalSize?: number;
+    /** Present only when a range was served: the `Content-Range` header value. */
+    contentRange?: string;
+    lastModified?: Date;
+    etag?: string;
+}
+/**
+ * A short-lived target a browser (or any client) can upload to DIRECTLY, without
+ * the file passing through the API. Essential for large files (video): the API
+ * hands back this target, the client PUTs/POSTs the bytes straight to the
+ * provider, and the API is never a proxy for gigabytes.
+ */
+export interface SignedUploadTarget {
+    /** URL to upload to. */
+    url: string;
+    /** HTTP method to use. `PUT` for presigned-URL providers; `POST` for form-policy uploads. */
+    method: 'PUT' | 'POST';
+    /** Headers the client MUST send (e.g. `Content-Type`) for the signature to match. */
+    headers?: Record<string, string>;
+    /** For `POST` form uploads (S3 POST policy): fields to include in the multipart form before the file. */
+    fields?: Record<string, string>;
+    /** The key the object will land at. */
+    key: string;
+    /** When the target stops being valid. */
+    expiresAt: Date;
+}
+/** A page of `list()` results. */
+export interface ListResult {
+    objects: ObjectInfo[];
+    /** Opaque cursor for the next page; absent when there are no more. */
+    cursor?: string;
+}
+/**
+ * Provider-agnostic file storage. Handles any file type — images, PDFs and other
+ * documents, video, audio, archives — the port makes no assumption about content.
+ * Adapters: local filesystem (dev), S3-compatible (AWS S3 and Cloudflare R2), and
+ * Bunny.net.
+ *
+ * Keys are forward-slash paths WITHOUT a leading slash, e.g.
+ * `tenant-123/videos/clip.mp4`. The caller composes keys; never build one from an
+ * untrusted filename (path traversal). Adapters store objects verbatim under the key.
+ */
+export interface StoragePort {
+    /** Store `data` at `key`, overwriting if it exists. Returns what is known about the stored object. */
+    put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<ObjectInfo>;
+    /**
+     * Store a readable stream at `key` (large uploads, video). The adapter uses
+     * multipart under the hood where the provider needs it, so the whole file never
+     * has to sit in memory.
+     */
+    putStream(key: string, stream: Readable, options?: PutOptions): Promise<ObjectInfo>;
+    /** Read the whole object into memory. Prefer `getStream` for anything large. */
+    get(key: string): Promise<Buffer>;
+    /** Open the object as a stream, optionally a byte range (for seeking media). */
+    getStream(key: string, range?: ByteRange): Promise<ReadStream>;
+    /** Metadata about the object, or `null` if it does not exist. */
+    stat(key: string): Promise<ObjectInfo | null>;
+    /** Whether an object exists at `key`. */
+    exists(key: string): Promise<boolean>;
+    /** Delete the object. Idempotent: deleting a missing key does not throw. */
+    delete(key: string): Promise<void>;
+    /** List objects under `prefix`, paginated. */
+    list(prefix: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult>;
+    /**
+     * A short-lived URL to READ a private object. For a public bucket/zone prefer
+     * `publicUrl`. `ttlSeconds` defaults to one hour.
+     */
+    signedReadUrl(key: string, ttlSeconds?: number): Promise<string>;
+    /**
+     * A short-lived target for a client to UPLOAD directly to the provider.
+     * Not every provider supports this the same way — see each adapter.
+     */
+    signedUploadUrl(key: string, options?: PutOptions & {
+        ttlSeconds?: number;
+    }): Promise<SignedUploadTarget>;
+    /**
+     * The stable public URL for `key`, or `null` when the store is private (no
+     * public base URL / pull zone configured). For private stores, use
+     * `signedReadUrl` instead.
+     */
+    publicUrl(key: string): string | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miguelmorales13/nestkit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -110,6 +110,11 @@
       "types": "./dist/media/index.d.ts",
       "import": "./dist/media/index.js",
       "require": "./dist/media/index.cjs"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js",
+      "require": "./dist/storage/index.cjs"
     }
   },
   "scripts": {
@@ -131,9 +136,21 @@
     "class-validator": "^0.15.0",
     "class-transformer": "^0.5.1",
     "resend": "^6.20.0",
-    "nodemailer": "^9.0.5"
+    "nodemailer": "^9.0.5",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@aws-sdk/lib-storage": "^3.0.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -171,6 +188,9 @@
     "jsonwebtoken": "^9.0.3"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1121.0",
+    "@aws-sdk/lib-storage": "^3.1121.0",
+    "@aws-sdk/s3-request-presigner": "^3.1121.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/swagger": "^11.0.0",