@modern-admin/feature-upload 0.1.0

package/dist/nest/upload.module.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ModernAdminUploadModule — registers `UploadController` plus the sweeper
+ * background task that purges orphaned pending uploads.
+ *
+ * Import alongside `ModernAdminModule.forRoot()` in the host application:
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     ModernAdminModule.forRoot({ global: true, ... }),
+ *     ModernAdminUploadModule.forRoot({ pendingTtlMs: 60 * 60 * 1000 }),
+ *     // feature modules that use uploadFeature() ...
+ *   ],
+ * })
+ * export class AdminModule {}
+ * ```
+ *
+ * The module depends on `MODERN_ADMIN` and `ModernAdminAuthGuard` being
+ * available in the DI tree, which is satisfied when `ModernAdminModule.forRoot`
+ * is registered with `global: true` (the recommended default).
+ */
+import { type DynamicModule } from '@nestjs/common';
+import { type ModernAdminUploadModuleOptions } from './upload.tokens.js';
+export type { ModernAdminUploadModuleOptions } from './upload.tokens.js';
+export declare class ModernAdminUploadModule {
+    static forRoot(options?: ModernAdminUploadModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=upload.module.d.ts.map

package/dist/nest/upload.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.module.d.ts","sourceRoot":"","sources":["../../src/nest/upload.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,gBAAgB,CAAA;AAG3D,OAAO,EAAyB,KAAK,8BAA8B,EAAE,MAAM,oBAAoB,CAAA;AAE/F,YAAY,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAA;AAExE,qBACa,uBAAuB;IAClC,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,8BAAmC,GAAG,aAAa;CAY5E"}

package/dist/nest/upload.module.js

@@ -0,0 +1,51 @@
+/**
+ * ModernAdminUploadModule — registers `UploadController` plus the sweeper
+ * background task that purges orphaned pending uploads.
+ *
+ * Import alongside `ModernAdminModule.forRoot()` in the host application:
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     ModernAdminModule.forRoot({ global: true, ... }),
+ *     ModernAdminUploadModule.forRoot({ pendingTtlMs: 60 * 60 * 1000 }),
+ *     // feature modules that use uploadFeature() ...
+ *   ],
+ * })
+ * export class AdminModule {}
+ * ```
+ *
+ * The module depends on `MODERN_ADMIN` and `ModernAdminAuthGuard` being
+ * available in the DI tree, which is satisfied when `ModernAdminModule.forRoot`
+ * is registered with `global: true` (the recommended default).
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var ModernAdminUploadModule_1;
+import { Module } from '@nestjs/common';
+import { UploadController } from './upload.controller.js';
+import { UploadSweeperService } from './upload-sweeper.service.js';
+import { UPLOAD_MODULE_OPTIONS } from './upload.tokens.js';
+let ModernAdminUploadModule = ModernAdminUploadModule_1 = class ModernAdminUploadModule {
+    static forRoot(options = {}) {
+        return {
+            module: ModernAdminUploadModule_1,
+            global: options.global ?? false,
+            controllers: [UploadController],
+            providers: [
+                { provide: UPLOAD_MODULE_OPTIONS, useValue: options },
+                UploadSweeperService,
+            ],
+            exports: [UPLOAD_MODULE_OPTIONS],
+        };
+    }
+};
+ModernAdminUploadModule = ModernAdminUploadModule_1 = __decorate([
+    Module({})
+], ModernAdminUploadModule);
+export { ModernAdminUploadModule };
+//# sourceMappingURL=upload.module.js.map

package/dist/nest/upload.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.module.js","sourceRoot":"","sources":["../../src/nest/upload.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;AAEH,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,EAAE,qBAAqB,EAAuC,MAAM,oBAAoB,CAAA;AAKxF,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAClC,MAAM,CAAC,OAAO,CAAC,UAA0C,EAAE;QACzD,OAAO;YACL,MAAM,EAAE,yBAAuB;YAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;YAC/B,WAAW,EAAE,CAAC,gBAAgB,CAAC;YAC/B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBACrD,oBAAoB;aACrB;YACD,OAAO,EAAE,CAAC,qBAAqB,CAAC;SACjC,CAAA;IACH,CAAC;CACF,CAAA;AAbY,uBAAuB;IADnC,MAAM,CAAC,EAAE,CAAC;GACE,uBAAuB,CAanC"}

package/dist/nest/upload.tokens.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DI tokens + option types shared between `ModernAdminUploadModule`,
+ * `UploadController`, and the sweeper service.
+ */
+export declare const UPLOAD_MODULE_OPTIONS: unique symbol;
+export interface ModernAdminUploadModuleOptions {
+    /** Mark this module as global. Defaults to false. */
+    global?: boolean;
+    /**
+     * TTL applied to freshly uploaded files before the sweeper deletes them.
+     * Default: 1 hour.  Files are confirmed (TTL becomes irrelevant) as soon
+     * as the parent record is saved, via the action hooks installed by
+     * `uploadFeature`.
+     */
+    pendingTtlMs?: number;
+    /**
+     * Interval at which the sweeper runs. Default: 5 minutes.  Set to `0` to
+     * disable the periodic sweeper entirely (the registry still works — entries
+     * just never expire).
+     */
+    sweepIntervalMs?: number;
+}
+//# sourceMappingURL=upload.tokens.d.ts.map

package/dist/nest/upload.tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.tokens.d.ts","sourceRoot":"","sources":["../../src/nest/upload.tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,qBAAqB,eAAmD,CAAA;AAErF,MAAM,WAAW,8BAA8B;IAC7C,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}

package/dist/nest/upload.tokens.js

@@ -0,0 +1,6 @@
+/**
+ * DI tokens + option types shared between `ModernAdminUploadModule`,
+ * `UploadController`, and the sweeper service.
+ */
+export const UPLOAD_MODULE_OPTIONS = Symbol.for('modern-admin.upload.module-options');
+//# sourceMappingURL=upload.tokens.js.map

package/dist/nest/upload.tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.tokens.js","sourceRoot":"","sources":["../../src/nest/upload.tokens.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAA"}

package/dist/pending-registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PendingUploadsRegistry — tracks files that were uploaded to storage but have
+ * not yet been "confirmed" by saving the parent record.
+ *
+ * Why
+ * ---
+ * Uploads happen *before* the form is submitted (the user picks a file, the
+ * editor calls `POST /upload`, gets back a key, stores it in form state). If
+ * the user then abandons the form (closes the tab, navigates away, server
+ * rejects the create payload, etc.), the file ends up orphaned in storage.
+ *
+ * How
+ * ---
+ * - The controller calls `track(key, providerId, ttlMs)` after every successful
+ *   upload, recording an expiry timestamp.
+ * - The action hooks installed by `uploadFeature` call `confirm(keys)` from
+ *   `new.after` / `edit.after` once the record is saved, removing the keys
+ *   from the pending set so they will not be swept.
+ * - The user-initiated `DELETE /upload?…` endpoint calls `cancel(key)` to
+ *   immediately remove the file from storage when the user removes a freshly
+ *   uploaded file *before* saving.
+ * - A periodic sweeper started by `ModernAdminUploadModule.forRoot()` calls
+ *   `sweep()` to delete files whose pending entry has expired. This handles
+ *   abandoned forms, browser crashes, and any other path that bypasses
+ *   client-side cleanup.
+ *
+ * The registry is a process-level singleton (same pattern as
+ * `UploadProviderRegistry`).
+ *
+ * TODO(roadmap): swap the in-process `Map` for a Redis-backed store and move
+ * the sweeper driver (`UploadSweeperService`) onto BullMQ. This is required
+ * for multi-instance deployments where one Nest replica serves the upload
+ * request and a different replica processes the form submission — without a
+ * shared store the second replica would not see the pending entry, the
+ * confirm hook would no-op, and the file would be swept on the originator.
+ * BullMQ also gives us crash-safe scheduling and retries.
+ */
+export declare const PendingUploadsRegistry: {
+    /** Mark `key` as a freshly-uploaded, unconfirmed file. */
+    track(key: string, providerId: string, ttlMs: number): void;
+    /** Whether `key` is currently in the pending set (helper for tests / cancel). */
+    has(key: string): boolean;
+    /** Confirm one or more keys — they leave pending without being deleted. */
+    confirm(keys: ReadonlyArray<string>): void;
+    /**
+     * Cancel a single pending key — deletes the file from storage and removes
+     * the entry. No-op if the key is not pending (already confirmed or unknown).
+     */
+    cancel(key: string): Promise<boolean>;
+    /**
+     * Sweep expired entries — delete each from storage and from the registry.
+     * Returns the number of files swept.
+     */
+    sweep(now?: number): Promise<number>;
+    /** For test cleanup. */
+    clear(): void;
+    /** Number of currently-pending entries (for tests / introspection). */
+    size(): number;
+};
+//# sourceMappingURL=pending-registry.d.ts.map

package/dist/pending-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-registry.d.ts","sourceRoot":"","sources":["../src/pending-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAaH,eAAO,MAAM,sBAAsB;IACjC,0DAA0D;eAC/C,MAAM,cAAc,MAAM,SAAS,MAAM,GAAG,IAAI;IAI3D,iFAAiF;aACxE,MAAM,GAAG,OAAO;IAIzB,2EAA2E;kBAC7D,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAI1C;;;OAGG;gBACe,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc3C;;;OAGG;gBACc,MAAM,GAAgB,OAAO,CAAC,MAAM,CAAC;IAkBtD,wBAAwB;aACf,IAAI;IAIb,uEAAuE;YAC/D,MAAM;CAGf,CAAA"}

package/dist/pending-registry.js

@@ -0,0 +1,106 @@
+/**
+ * PendingUploadsRegistry — tracks files that were uploaded to storage but have
+ * not yet been "confirmed" by saving the parent record.
+ *
+ * Why
+ * ---
+ * Uploads happen *before* the form is submitted (the user picks a file, the
+ * editor calls `POST /upload`, gets back a key, stores it in form state). If
+ * the user then abandons the form (closes the tab, navigates away, server
+ * rejects the create payload, etc.), the file ends up orphaned in storage.
+ *
+ * How
+ * ---
+ * - The controller calls `track(key, providerId, ttlMs)` after every successful
+ *   upload, recording an expiry timestamp.
+ * - The action hooks installed by `uploadFeature` call `confirm(keys)` from
+ *   `new.after` / `edit.after` once the record is saved, removing the keys
+ *   from the pending set so they will not be swept.
+ * - The user-initiated `DELETE /upload?…` endpoint calls `cancel(key)` to
+ *   immediately remove the file from storage when the user removes a freshly
+ *   uploaded file *before* saving.
+ * - A periodic sweeper started by `ModernAdminUploadModule.forRoot()` calls
+ *   `sweep()` to delete files whose pending entry has expired. This handles
+ *   abandoned forms, browser crashes, and any other path that bypasses
+ *   client-side cleanup.
+ *
+ * The registry is a process-level singleton (same pattern as
+ * `UploadProviderRegistry`).
+ *
+ * TODO(roadmap): swap the in-process `Map` for a Redis-backed store and move
+ * the sweeper driver (`UploadSweeperService`) onto BullMQ. This is required
+ * for multi-instance deployments where one Nest replica serves the upload
+ * request and a different replica processes the form submission — without a
+ * shared store the second replica would not see the pending entry, the
+ * confirm hook would no-op, and the file would be swept on the originator.
+ * BullMQ also gives us crash-safe scheduling and retries.
+ */
+import { UploadProviderRegistry } from './registry.js';
+const _pending = new Map();
+export const PendingUploadsRegistry = {
+    /** Mark `key` as a freshly-uploaded, unconfirmed file. */
+    track(key, providerId, ttlMs) {
+        _pending.set(key, { providerId, expiresAt: Date.now() + ttlMs });
+    },
+    /** Whether `key` is currently in the pending set (helper for tests / cancel). */
+    has(key) {
+        return _pending.has(key);
+    },
+    /** Confirm one or more keys — they leave pending without being deleted. */
+    confirm(keys) {
+        for (const k of keys)
+            _pending.delete(k);
+    },
+    /**
+     * Cancel a single pending key — deletes the file from storage and removes
+     * the entry. No-op if the key is not pending (already confirmed or unknown).
+     */
+    async cancel(key) {
+        const entry = _pending.get(key);
+        if (!entry)
+            return false;
+        _pending.delete(key);
+        const cfg = UploadProviderRegistry.get(entry.providerId);
+        if (!cfg)
+            return false;
+        try {
+            await cfg.provider.delete(key);
+        }
+        catch {
+            // Non-fatal — best-effort cleanup.
+        }
+        return true;
+    },
+    /**
+     * Sweep expired entries — delete each from storage and from the registry.
+     * Returns the number of files swept.
+     */
+    async sweep(now = Date.now()) {
+        let swept = 0;
+        for (const [key, entry] of _pending) {
+            if (entry.expiresAt <= now) {
+                _pending.delete(key);
+                const cfg = UploadProviderRegistry.get(entry.providerId);
+                if (!cfg)
+                    continue;
+                try {
+                    await cfg.provider.delete(key);
+                    swept++;
+                }
+                catch {
+                    // Non-fatal.
+                }
+            }
+        }
+        return swept;
+    },
+    /** For test cleanup. */
+    clear() {
+        _pending.clear();
+    },
+    /** Number of currently-pending entries (for tests / introspection). */
+    size() {
+        return _pending.size;
+    },
+};
+//# sourceMappingURL=pending-registry.js.map

package/dist/pending-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-registry.js","sourceRoot":"","sources":["../src/pending-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAStD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAA;AAEhD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,0DAA0D;IAC1D,KAAK,CAAC,GAAW,EAAE,UAAkB,EAAE,KAAa;QAClD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,iFAAiF;IACjF,GAAG,CAAC,GAAW;QACb,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,2EAA2E;IAC3E,OAAO,CAAC,IAA2B;QACjC,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QACxB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACpB,MAAM,GAAG,GAAG,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QACxD,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAA;QACtB,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;QAClC,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBAC3B,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACpB,MAAM,GAAG,GAAG,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;gBACxD,IAAI,CAAC,GAAG;oBAAE,SAAQ;gBAClB,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;oBAC9B,KAAK,EAAE,CAAA;gBACT,CAAC;gBAAC,MAAM,CAAC;oBACP,aAAa;gBACf,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,wBAAwB;IACxB,KAAK;QACH,QAAQ,CAAC,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,uEAAuE;IACvE,IAAI;QACF,OAAO,QAAQ,CAAC,IAAI,CAAA;IACtB,CAAC;CACF,CAAA"}

package/dist/providers/local.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LocalUploadProvider — stores files on the local filesystem.
+ *
+ * Files are written to `uploadDir` with a UUID-based filename to avoid
+ * collisions. Set `baseUrl` to the public URL prefix where the directory is
+ * served as static files (e.g. `'/uploads'` or `'http://localhost:3000/uploads'`).
+ *
+ * @example
+ * new LocalUploadProvider({ uploadDir: './public/uploads', baseUrl: '/uploads' })
+ */
+import type { IUploadProvider, UploadedFile } from '../types.js';
+export interface LocalUploadOptions {
+    /**
+     * Absolute or process-relative path to the directory where files are stored.
+     * Created automatically on first upload.
+     */
+    uploadDir: string;
+    /**
+     * Public URL prefix (without trailing slash) where uploaded files can be
+     * accessed. Used to construct the `url` returned by the upload endpoint and
+     * the `urlTemplate` for the frontend.
+     *
+     * @example '/uploads'
+     * @example 'https://static.example.com/uploads'
+     */
+    baseUrl?: string;
+}
+export declare class LocalUploadProvider implements IUploadProvider {
+    private readonly options;
+    constructor(options: LocalUploadOptions);
+    upload(file: UploadedFile, key?: string): Promise<string>;
+    getUrl(key: string): string;
+    delete(key: string): Promise<void>;
+    urlTemplate(): string;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/providers/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/providers/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEhE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,qBAAa,mBAAoB,YAAW,eAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,kBAAkB;IAElD,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAKrB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC,WAAW,IAAI,MAAM;CAItB"}

package/dist/providers/local.js

@@ -0,0 +1,44 @@
+/**
+ * LocalUploadProvider — stores files on the local filesystem.
+ *
+ * Files are written to `uploadDir` with a UUID-based filename to avoid
+ * collisions. Set `baseUrl` to the public URL prefix where the directory is
+ * served as static files (e.g. `'/uploads'` or `'http://localhost:3000/uploads'`).
+ *
+ * @example
+ * new LocalUploadProvider({ uploadDir: './public/uploads', baseUrl: '/uploads' })
+ */
+import { mkdir, writeFile, unlink } from 'node:fs/promises';
+import { join, extname, dirname } from 'node:path';
+import { uuidv7 } from '@modern-admin/core';
+export class LocalUploadProvider {
+    constructor(options) {
+        this.options = options;
+    }
+    async upload(file, key) {
+        const resolvedKey = key ?? `${uuidv7()}${extname(file.originalName)}`;
+        const dest = join(this.options.uploadDir, resolvedKey);
+        // Create the full directory tree (handles nested keys like 'avatars/2024/01/uuid.jpg').
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, file.buffer);
+        return resolvedKey;
+    }
+    getUrl(key) {
+        const base = this.options.baseUrl ?? '/uploads';
+        return `${base}/${key}`;
+    }
+    async delete(key) {
+        try {
+            await unlink(join(this.options.uploadDir, key));
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    urlTemplate() {
+        const base = this.options.baseUrl ?? '/uploads';
+        return `${base}/{key}`;
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/providers/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/providers/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAoB3C,MAAM,OAAO,mBAAmB;IAC9B,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAE5D,KAAK,CAAC,MAAM,CAAC,IAAkB,EAAE,GAAY;QAC3C,MAAM,WAAW,GAAG,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAA;QACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAA;QACtD,wFAAwF;QACxF,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAClC,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,UAAU,CAAA;QAC/C,OAAO,GAAG,IAAI,IAAI,GAAG,EAAE,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAA;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAA;QACjE,CAAC;IACH,CAAC;IAED,WAAW;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,UAAU,CAAA;QAC/C,OAAO,GAAG,IAAI,QAAQ,CAAA;IACxB,CAAC;CACF"}

package/dist/providers/s3.d.ts

@@ -0,0 +1,96 @@
+/**
+ * S3UploadProvider — stores files in an AWS S3 bucket (or any S3-compatible
+ * service such as MinIO, Cloudflare R2, DigitalOcean Spaces, etc.).
+ *
+ * Requires `@aws-sdk/client-s3` to be installed in the host project.
+ * For streaming multipart upload of large files, also install `@aws-sdk/lib-storage`.
+ * For pre-signed URLs (private buckets), install `@aws-sdk/s3-request-presigner`.
+ *
+ * @example AWS S3 — public bucket
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1', acl: 'public-read' })
+ *
+ * @example AWS S3 — private bucket with pre-signed URLs (60 min expiry)
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1', signed: { expiresIn: 3600 } })
+ *
+ * @example MinIO / custom endpoint
+ * new S3UploadProvider({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true,
+ *   publicBaseUrl: 'http://localhost:9000/my-bucket',
+ * })
+ *
+ * @example Inject a pre-configured S3Client (share across providers)
+ * const s3 = new S3Client({ region: 'us-east-1' })
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1' }, s3)
+ */
+import type { IUploadProvider, UploadedFile } from '../types.js';
+export interface S3UploadOptions {
+    /** S3 bucket name. */
+    bucket: string;
+    /** AWS region (e.g. `'us-east-1'`). */
+    region: string;
+    /** AWS access key id. Falls back to environment / credential chain. */
+    accessKeyId?: string;
+    /** AWS secret access key. Falls back to environment / credential chain. */
+    secretAccessKey?: string;
+    /**
+     * Custom endpoint for S3-compatible services.
+     * @example 'http://localhost:9000'
+     * @example 'https://nyc3.digitaloceanspaces.com'
+     */
+    endpoint?: string;
+    /** Force path-style URLs (required for some MinIO / custom endpoint setups). */
+    forcePathStyle?: boolean;
+    /** Optional key prefix / "folder". Without trailing slash. */
+    prefix?: string;
+    /**
+     * Canned ACL applied to every uploaded object, e.g. `'public-read'`.
+     * Omit for private buckets — use `signed` instead.
+     */
+    acl?: string;
+    /**
+     * Override the public base URL used for `getUrl()` and `urlTemplate()`.
+     * Useful when files are served via CloudFront or a custom CDN.
+     * Without trailing slash.
+     * @example 'https://cdn.example.com'
+     */
+    publicBaseUrl?: string;
+    /**
+     * Generate pre-signed URLs instead of public URLs.
+     * Required for private S3 buckets. Needs `@aws-sdk/s3-request-presigner`.
+     *
+     * - `true` uses the default expiry (3600 s / 1 hour).
+     * - Pass `{ expiresIn: seconds }` to customise.
+     *
+     * When `signed` is set, `urlTemplate()` is not implemented (each URL is
+     * unique and time-limited) and `getUrl()` is async.
+     *
+     * @example
+     * signed: true          // 1-hour pre-signed URLs
+     * signed: { expiresIn: 60 * 60 * 24 }  // 24-hour pre-signed URLs
+     */
+    signed?: boolean | {
+        expiresIn?: number;
+    };
+}
+export declare class S3UploadProvider implements IUploadProvider {
+    private readonly options;
+    private readonly injectedClient?;
+    private _client;
+    constructor(options: S3UploadOptions, injectedClient?: any | undefined);
+    private client;
+    upload(file: UploadedFile, key?: string): Promise<string>;
+    getUrl(key: string): Promise<string>;
+    delete(key: string): Promise<void>;
+    /**
+     * URL template for the frontend. Only available when `signed` is NOT set
+     * (public buckets). For private buckets each URL is unique + time-limited,
+     * so the frontend must call the upload endpoint to get a fresh URL.
+     */
+    urlTemplate(): string | undefined;
+    private signedUrl;
+    private publicBaseUrl;
+}
+//# sourceMappingURL=s3.d.ts.map

package/dist/providers/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/providers/s3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEhE,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1C;AAED,qBAAa,gBAAiB,YAAW,eAAe;IAKpD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAIxB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAPlC,OAAO,CAAC,OAAO,CAAY;gBAGR,OAAO,EAAE,eAAe,EAIxB,cAAc,CAAC,EAAE,GAAG,YAAA;YAIzB,MAAM;IA4Bd,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2CzD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOpC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;;;OAIG;IACH,WAAW,IAAI,MAAM,GAAG,SAAS;YAKnB,SAAS;IA0BvB,OAAO,CAAC,aAAa;CAKtB"}

package/dist/providers/s3.js

@@ -0,0 +1,164 @@
+/**
+ * S3UploadProvider — stores files in an AWS S3 bucket (or any S3-compatible
+ * service such as MinIO, Cloudflare R2, DigitalOcean Spaces, etc.).
+ *
+ * Requires `@aws-sdk/client-s3` to be installed in the host project.
+ * For streaming multipart upload of large files, also install `@aws-sdk/lib-storage`.
+ * For pre-signed URLs (private buckets), install `@aws-sdk/s3-request-presigner`.
+ *
+ * @example AWS S3 — public bucket
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1', acl: 'public-read' })
+ *
+ * @example AWS S3 — private bucket with pre-signed URLs (60 min expiry)
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1', signed: { expiresIn: 3600 } })
+ *
+ * @example MinIO / custom endpoint
+ * new S3UploadProvider({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true,
+ *   publicBaseUrl: 'http://localhost:9000/my-bucket',
+ * })
+ *
+ * @example Inject a pre-configured S3Client (share across providers)
+ * const s3 = new S3Client({ region: 'us-east-1' })
+ * new S3UploadProvider({ bucket: 'my-bucket', region: 'us-east-1' }, s3)
+ */
+import { extname } from 'node:path';
+import { uuidv7 } from '@modern-admin/core';
+export class S3UploadProvider {
+    constructor(options, 
+    // Accept a pre-configured S3Client instance (share across providers /
+    // inject in tests). When omitted the provider creates its own client.
+    injectedClient) {
+        this.options = options;
+        this.injectedClient = injectedClient;
+        this._client = null;
+    }
+    async client() {
+        if (this.injectedClient)
+            return this.injectedClient;
+        if (this._client)
+            return this._client;
+        let S3Client;
+        try {
+            const mod = await import('@aws-sdk/client-s3');
+            S3Client = mod.S3Client;
+        }
+        catch {
+            throw new Error('[modern-admin/feature-upload] S3UploadProvider requires @aws-sdk/client-s3. ' +
+                'Install it: bun add @aws-sdk/client-s3');
+        }
+        const cfg = {
+            region: this.options.region,
+            ...(this.options.endpoint ? { endpoint: this.options.endpoint } : {}),
+            ...(this.options.forcePathStyle ? { forcePathStyle: true } : {}),
+        };
+        if (this.options.accessKeyId && this.options.secretAccessKey) {
+            cfg.credentials = {
+                accessKeyId: this.options.accessKeyId,
+                secretAccessKey: this.options.secretAccessKey,
+            };
+        }
+        this._client = new S3Client(cfg);
+        return this._client;
+    }
+    async upload(file, key) {
+        const c = await this.client();
+        const ext = extname(file.originalName);
+        const prefix = this.options.prefix ? `${this.options.prefix}/` : '';
+        const resolvedKey = key ?? `${prefix}${uuidv7()}${ext}`;
+        // Prefer @aws-sdk/lib-storage for streaming multipart uploads (large files).
+        // Fall back to PutObjectCommand if lib-storage is not installed.
+        try {
+            const libStorage = await import('@aws-sdk/lib-storage');
+            const Upload = libStorage.Upload;
+            const input = {
+                Bucket: this.options.bucket,
+                Key: resolvedKey,
+                Body: file.buffer,
+                ContentType: file.mimeType,
+            };
+            if (this.options.acl)
+                input.ACL = this.options.acl;
+            const uploader = new Upload({ client: c, params: input });
+            await uploader.done();
+        }
+        catch (err) {
+            // lib-storage not installed — fall back to PutObjectCommand.
+            if (err.code === 'ERR_MODULE_NOT_FOUND' ||
+                String(err).includes('Cannot find module')) {
+                const sdk = await import('@aws-sdk/client-s3');
+                const PutObjectCommand = sdk.PutObjectCommand;
+                const input = {
+                    Bucket: this.options.bucket,
+                    Key: resolvedKey,
+                    Body: file.buffer,
+                    ContentType: file.mimeType,
+                    ContentLength: file.size,
+                };
+                if (this.options.acl)
+                    input.ACL = this.options.acl;
+                await c.send(new PutObjectCommand(input));
+            }
+            else {
+                throw err;
+            }
+        }
+        return resolvedKey;
+    }
+    async getUrl(key) {
+        if (this.options.signed) {
+            return this.signedUrl(key);
+        }
+        return `${this.publicBaseUrl()}/${key}`;
+    }
+    async delete(key) {
+        try {
+            const sdk = await import('@aws-sdk/client-s3');
+            const c = await this.client();
+            const DeleteObjectCommand = sdk.DeleteObjectCommand;
+            await c.send(new DeleteObjectCommand({ Bucket: this.options.bucket, Key: key }));
+        }
+        catch {
+            // Ignore — file may not exist.
+        }
+    }
+    /**
+     * URL template for the frontend. Only available when `signed` is NOT set
+     * (public buckets). For private buckets each URL is unique + time-limited,
+     * so the frontend must call the upload endpoint to get a fresh URL.
+     */
+    urlTemplate() {
+        if (this.options.signed)
+            return undefined;
+        return `${this.publicBaseUrl()}/{key}`;
+    }
+    async signedUrl(key) {
+        let getSignedUrl;
+        try {
+            const mod = await import('@aws-sdk/s3-request-presigner');
+            getSignedUrl = mod.getSignedUrl;
+        }
+        catch {
+            throw new Error('[modern-admin/feature-upload] Signed URLs require @aws-sdk/s3-request-presigner. ' +
+                'Install it: bun add @aws-sdk/s3-request-presigner');
+        }
+        const sdk = await import('@aws-sdk/client-s3');
+        const c = await this.client();
+        const GetObjectCommand = sdk.GetObjectCommand;
+        const expiresIn = typeof this.options.signed === 'object'
+            ? (this.options.signed.expiresIn ?? 3600)
+            : 3600;
+        return getSignedUrl(c, new GetObjectCommand({ Bucket: this.options.bucket, Key: key }), { expiresIn });
+    }
+    publicBaseUrl() {
+        if (this.options.publicBaseUrl)
+            return this.options.publicBaseUrl;
+        if (this.options.endpoint)
+            return `${this.options.endpoint}/${this.options.bucket}`;
+        return `https://${this.options.bucket}.s3.${this.options.region}.amazonaws.com`;
+    }
+}
+//# sourceMappingURL=s3.js.map