@adonis-agora/media 0.8.2 → 0.9.0

package/dist/src/define_config.d.ts

@@ -7,6 +7,7 @@ import { processors } from './processors/factory.js';
 import type { ImageProcessorFactory } from './processors/factory.js';
 import { stores } from './stores/factory.js';
 import type { LucidStoreConfig, StoreContext, StoreFactory } from './stores/factory.js';
+import { transformers } from './transformers/factory.js';
 import type { UploadMode } from './upload_mode.js';
 import { uploadSessions } from './upload_sessions/factory.js';
 import type { LucidUploadSessionStoreConfig, UploadSessionStoreContext, UploadSessionStoreFactory } from './upload_sessions/factory.js';
@@ -42,6 +43,61 @@ export interface MediaUploadsConfig {
      * disabled and no session store is built.
      */
     resumable?: MediaResumableConfig;
+    /**
+     * Session-backed direct upload settings (`media.direct`) — browser→S3 multipart through presigned
+     * part URLs, with the session (uploadId, part size, confirmed ETags) persisted server-side so an
+     * interrupted upload resumes after a page reload. Present ⇒ `media.direct` is available; when
+     * `routes.enabled`, the provider mounts the JSON endpoints. Absent ⇒ disabled, no session store
+     * is built. See {@link MediaDirectUploadConfig} for how this relates to TUS.
+     */
+    direct?: MediaDirectUploadConfig;
+}
+/**
+ * Session-backed direct upload configuration. The session store is the SAME SPI (and, with
+ * `uploadSessions.lucid()`, the same tables) the resumable (TUS) subsystem uses — the two flows are
+ * complements, not rivals: TUS streams every chunk THROUGH the app (works on any disk, byte-exact
+ * resume), while direct hands the browser presigned URLs and the bytes never touch the app (S3-only,
+ * resumes at part granularity, needs bucket CORS exposing `ETag`). For video-sized files on S3,
+ * direct halves the total bandwidth.
+ */
+export interface MediaDirectUploadConfig {
+    /**
+     * Name of the session store (a key of {@link stores} below). Omit to use the in-memory store
+     * (single-process, non-durable — sessions won't survive a restart, uploads in flight will).
+     */
+    store?: string;
+    /** Named session stores, built with the {@link uploadSessions} factory (lazy peers). */
+    stores?: Record<string, UploadSessionStoreFactory>;
+    /**
+     * Multipart part size in bytes. Falls back to `uploads.partSize`, then 20 MiB. S3 requires at
+     * least 5 MiB and at most 10,000 parts per upload.
+     */
+    partSize?: number;
+    /**
+     * Lifetime of presigned part URLs, in seconds. Falls back to `uploads.presignTtlSeconds`, then
+     * 3600. Expiry never strands an upload: `status()` re-issues fresh URLs for pending parts.
+     */
+    presignTtlSeconds?: number;
+    /** Session lifetime in seconds. Omit for sessions that never expire. */
+    sessionTtlSeconds?: number;
+    /** Mount the built-in direct-session HTTP routes. Opt-in. */
+    routes?: {
+        /** Register the routes. Default false. */
+        enabled?: boolean;
+        /** Path prefix for the routes. Default `/media/uploads/direct/sessions`. */
+        prefix?: string;
+        /** Disk uploads land on. Defaults to the media default disk (must be multipart-capable). */
+        disk?: string;
+        /** Reject initiations whose declared `size` exceeds this many bytes. */
+        maxSize?: number;
+        /**
+         * Collection these uploads are destined for. Set it to have `initiate` reject a declared
+         * `contentType` outside that collection's `acceptsMimeTypes` — before the multipart upload
+         * even opens. The collection config remains the single source of truth; nothing is restated
+         * here. Omit to accept any type (size limits still apply).
+         */
+        collection?: string;
+    };
 }
 /**
  * Resumable (TUS) upload configuration. The session store persists offset/length/metadata/expiry so
@@ -147,8 +203,8 @@ export interface MediaConfig {
      * so the heavy peer is imported lazily. Required only if any collection defines conversions.
      */
     imageProcessor?: ImageProcessor | ImageProcessorFactory;
-    /** Collection definitions (MIME whitelist, single-file replace, conversions). */
-    collections?: MediaCollectionConfig[];
+    /** Collection definitions (MIME whitelist, single-file replace, conversions, transformers). */
+    collections?: readonly MediaCollectionConfig[];
     /** Key prefix for column attachments created via the `AttachmentManager`. Default `attachments`. */
     attachmentKeyPrefix?: string;
     /** Emit `agora:media:*` diagnostics events (default true). */
@@ -158,8 +214,35 @@ export interface MediaConfig {
     /** How stored media is served back (`auto`/`public`/`signed`/`proxy` + signed-URL TTL). */
     delivery?: MediaDeliveryConfig;
 }
-/** Identity helper giving `config/media.ts` full type-checking. */
-export declare function defineConfig(config?: MediaConfig): MediaConfig;
-export { stores, processors, disks, uploadSessions };
+/**
+ * Identity helper giving `config/media.ts` full type-checking. The `const` type parameter keeps
+ * collection/conversion/transformer names as literal types, so {@link InferConversions} /
+ * {@link InferTransformers} can extract them from `typeof config` — no `as const` needed.
+ */
+export declare function defineConfig<const T extends MediaConfig>(config?: T): T;
+/** The collection literal types of a config (helper for the `Infer*` utilities). */
+type CollectionOf<T extends MediaConfig> = T['collections'] extends readonly (infer C extends MediaCollectionConfig)[] ? C : never;
+/**
+ * Union of the transformer names a config declares — for typing job payloads, `transform()` call
+ * sites, and route params against the config instead of restating strings:
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   collections: [{ name: 'videos', transformers: [transformers.hls(), transformers.probe()] }],
+ * })
+ * type AppTransformer = InferTransformers<typeof config> // 'hls' | 'probe'
+ * ```
+ */
+export type InferTransformers<T extends MediaConfig> = NonNullable<CollectionOf<T>['transformers']>[number]['name'];
+/**
+ * Union of every conversion name a config declares — image presets and transformers alike, since
+ * both persist under `record.conversions`:
+ *
+ * ```ts
+ * type AppConversion = InferConversions<typeof config> // 'thumb' | 'og' | 'hls' | 'probe'
+ * ```
+ */
+export type InferConversions<T extends MediaConfig> = NonNullable<CollectionOf<T>['conversions']>[number]['name'] | InferTransformers<T>;
+export { stores, processors, disks, uploadSessions, transformers };
 export type { StoreContext, StoreFactory, LucidStoreConfig, ImageProcessorFactory, DiskFactory, S3DiskConfig, S3Credentials, UploadMode, DeliveryMode, UploadSessionStoreContext, UploadSessionStoreFactory, LucidUploadSessionStoreConfig, };
 //# sourceMappingURL=define_config.d.ts.map

package/dist/src/define_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"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"}

package/dist/src/define_config.js

@@ -1,10 +1,15 @@
 import { disks } from './disks/factory.js';
 import { processors } from './processors/factory.js';
 import { stores } from './stores/factory.js';
+import { transformers } from './transformers/factory.js';
 import { uploadSessions } from './upload_sessions/factory.js';
-/** Identity helper giving `config/media.ts` full type-checking. */
+/**
+ * Identity helper giving `config/media.ts` full type-checking. The `const` type parameter keeps
+ * collection/conversion/transformer names as literal types, so {@link InferConversions} /
+ * {@link InferTransformers} can extract them from `typeof config` — no `as const` needed.
+ */
 export function defineConfig(config = {}) {
     return config;
 }
-export { stores, processors, disks, uploadSessions };
+export { stores, processors, disks, uploadSessions, transformers };
 //# sourceMappingURL=define_config.js.map

package/dist/src/define_config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAI3C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA+J9D,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAAC,SAAsB,EAAE;IACnD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAI3C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAuN9D;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAA8B,SAAY,EAAO;IAC3E,OAAO,MAAM,CAAC;AAChB,CAAC;AAmCD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/direct_upload.d.ts

@@ -0,0 +1,177 @@
+import type { MediaCollectionRegistry } from './media_collection.js';
+import type { UploadSession, UploadSessionListFilter, UploadSessionStore } from './resumable_upload.js';
+import type { StorageManager } from './storage_manager.js';
+import type { MultipartPart } from './types.js';
+/**
+ * Default part size: 20 MiB. Between S3's 5 MiB minimum and a reasonable payload per browser `PUT`;
+ * with S3's 10,000-part cap it covers files up to ~195 GiB. Larger than the proxy default (8 MiB)
+ * on purpose — direct parts don't occupy app memory, so the only cost of a bigger part is a bigger
+ * retry unit.
+ */
+export declare const DEFAULT_DIRECT_PART_SIZE: number;
+/** S3's minimum part size (every part but the last). Enforced at `initiate` — see {@link UploadPartSizeError}. */
+export declare const MIN_DIRECT_PART_SIZE: number;
+/** S3's cap on parts per multipart upload. */
+export declare const MAX_DIRECT_PARTS = 10000;
+/** A part the client should `PUT`: its number and the presigned URL that authorizes exactly that. */
+export interface DirectUploadPartUrl {
+    partNumber: number;
+    url: string;
+}
+export interface DirectUploadInitiateInput {
+    /** Disk name; defaults to the manager's default disk. Must be multipart-capable. */
+    disk?: string | undefined;
+    /** Final object key. Resolve it server-side (per user/tenant) — never trust a client-sent key. */
+    key: string;
+    /** Content-Type stamped on the final object, and checked against `collection`'s whitelist. */
+    contentType?: string | undefined;
+    /** Total file size in bytes. Required: it fixes the part count both sides slice by. */
+    size: number;
+    /**
+     * Collection this upload is destined for. When the manager holds a collection registry, the
+     * declared `contentType` is checked against that collection's `acceptsMimeTypes` HERE — before
+     * the multipart upload is opened, before a single byte moves. Mirrors the TUS `POST` gate: fast
+     * feedback and bandwidth economy, not the security boundary — `attachExisting` re-validates the
+     * real bytes at attach time.
+     */
+    collection?: string | undefined;
+    /** Public/private visibility for the final object. */
+    visibility?: 'public' | 'private' | undefined;
+    /** Override the manager's part size for this upload. Same S3 bounds apply. */
+    partSize?: number | undefined;
+    /** Extra metadata persisted on the session (keys under `direct:` are reserved). */
+    metadata?: Record<string, string> | undefined;
+}
+/** What {@link DirectUploadManager.initiate} hands back — everything the client needs to start `PUT`ing. */
+export interface DirectUploadCreatedSession {
+    /** Session id — the handle for `status`/`confirmPart`/`complete`/`abort`. */
+    id: string;
+    key: string;
+    disk: string;
+    /** The agreed slice size. The client MUST cut the file with exactly this. */
+    partSize: number;
+    size: number;
+    totalParts: number;
+    /** One presigned URL per part, 1-based, in order. */
+    parts: DirectUploadPartUrl[];
+    expiresAt?: Date | undefined;
+}
+/**
+ * The resume answer: what is already confirmed (ETags the server holds) and what is still pending
+ * (with FRESH presigned URLs). A client that lost its state — page reload, new tab, new device —
+ * asks this and continues from the parts that are missing, re-uploading nothing.
+ */
+export interface DirectUploadStatus {
+    id: string;
+    key: string;
+    disk: string;
+    partSize: number;
+    size: number;
+    totalParts: number;
+    contentType?: string | undefined;
+    /** Parts whose ETags the session holds — already uploaded and confirmed. */
+    completedParts: MultipartPart[];
+    /** Parts still missing, each with a freshly presigned URL (expiry never strands an upload). */
+    pendingParts: DirectUploadPartUrl[];
+    expiresAt?: Date | undefined;
+}
+export interface DirectUploadManagerOptions {
+    storage: StorageManager;
+    /**
+     * Session persistence — the SAME SPI (and, with the Lucid driver, the same tables) the resumable
+     * (TUS) subsystem uses. The store must implement `addPart`/`listParts`; both bundled drivers do.
+     */
+    sessions: UploadSessionStore;
+    /** Collection registry (`media.collections`) for the `initiate` MIME gate. Omit ⇒ no gate here. */
+    collections?: MediaCollectionRegistry | undefined;
+    /** Default part size in bytes. Default 20 MiB ({@link DEFAULT_DIRECT_PART_SIZE}). */
+    partSize?: number | undefined;
+    /** Lifetime of presigned part URLs, in seconds. Default 3600. */
+    presignTtlSeconds?: number | undefined;
+    /** Session lifetime in seconds. Omit for sessions that never expire. */
+    sessionTtlSeconds?: number | undefined;
+    idGenerator?: (() => string) | undefined;
+    /** Injectable clock (tests drive expiry deterministically). Default `() => new Date()`. */
+    clock?: (() => Date) | undefined;
+    /** Emit `upload.*` diagnostics events (default true). */
+    emitDiagnostics?: boolean | undefined;
+}
+/**
+ * Session-backed direct-to-S3 multipart uploads: the browser `PUT`s every byte straight to storage
+ * through presigned part URLs, and the app only coordinates — open, presign, collect ETags, close.
+ * The app's bandwidth cost is a handful of JSON round-trips regardless of file size, which is the
+ * entire point for video-sized files: the TUS path streams every chunk THROUGH the app (2× the
+ * bytes: client→app, app→S3), where this path streams none.
+ *
+ * What this adds over the raw primitives on {@link UploadManager} (`initiateDirect` & friends) is
+ * the **persisted session**: `uploadId`, the agreed `partSize` and every confirmed part ETag live
+ * in an {@link UploadSessionStore} — the same SPI the TUS engine persists its offsets in — instead
+ * of in the client's memory. A page reload no longer orphans the upload: the client asks
+ * {@link status} and gets back the confirmed ETags plus fresh URLs for what is missing.
+ *
+ * Framework-free, like {@link ResumableUploadManager}: the `DirectUploadHandler` maps it onto HTTP
+ * and the AdonisJS provider mounts that. `MediaManager.completeDirectUploadToLibrary` bridges a
+ * finished session into the media library through `attachExisting` — where the collection's
+ * whitelist checks the REAL bytes, exactly like every other upload path.
+ */
+export declare class DirectUploadManager {
+    #private;
+    private readonly storage;
+    private readonly sessions;
+    private readonly collections;
+    private readonly partSize;
+    private readonly presignTtlSeconds;
+    private readonly ttlSeconds;
+    private readonly newId;
+    private readonly now;
+    private readonly emitDiagnostics;
+    constructor(options: DirectUploadManagerOptions);
+    /**
+     * Open a direct upload: validate everything that can be validated without bytes, start the native
+     * multipart upload, persist the session, and presign every part URL in one batch (presigning is
+     * local computation — see `sigv4.ts` — so a 10,000-part batch costs no S3 round-trips).
+     */
+    initiate(input: DirectUploadInitiateInput): Promise<DirectUploadCreatedSession>;
+    /**
+     * Record one part the client finished `PUT`ing (its S3 `ETag` response header). This is what makes
+     * the session resumable: an ETag the server holds survives any client-side loss of state. Safe to
+     * retry — confirming the same part again overwrites its ETag.
+     */
+    confirmPart(id: string, part: MultipartPart): Promise<{
+        offset: number;
+        completedParts: number;
+    }>;
+    /**
+     * Where the upload stands, framed for resumption: the ETags already confirmed and a FRESH
+     * presigned URL for every part still missing. After a page reload the client calls this, slices
+     * the file with the returned `partSize`, uploads only `pendingParts`, and completes.
+     */
+    status(id: string): Promise<DirectUploadStatus>;
+    /**
+     * Assemble the parts into the final object and close the session. `parts` supplements what the
+     * session already holds (a client may hand over ETags it never got to confirm — e.g. it raced
+     * completion against its last confirms); on overlap the caller's ETag wins. Every part number in
+     * `1..totalParts` must be accounted for, or this throws {@link UploadPartsIncompleteError} naming
+     * the gaps — BEFORE the S3 round-trip that would report an opaque `InvalidPart`.
+     *
+     * This is the raw primitive (the object exists, no media record). To land in the library, use
+     * `MediaManager.completeDirectUploadToLibrary`, which chains `attachExisting` — collection
+     * whitelist against the real bytes included.
+     */
+    complete(id: string, parts?: MultipartPart[]): Promise<{
+        key: string;
+        disk: string;
+        size: number;
+    }>;
+    /**
+     * Discard an in-flight upload: abort the native multipart upload (S3 frees the stored parts and
+     * stops charging for them) and drop the session. The S3 abort is best-effort — a bucket lifecycle
+     * rule may have already reaped the upload (`NoSuchUpload`), and a session that can no longer be
+     * aborted remotely must still be deletable locally.
+     */
+    abort(id: string): Promise<void>;
+    /** In-progress direct sessions, optionally filtered. Empty when the store cannot enumerate. */
+    list(filter?: UploadSessionListFilter): Promise<UploadSession[]>;
+    private emit;
+}
+//# sourceMappingURL=direct_upload.d.ts.map

package/dist/src/direct_upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct_upload.d.ts","sourceRoot":"","sources":["../../src/direct_upload.ts"],"names":[],"mappings":"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"}

package/dist/src/direct_upload.js

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import { publishMedia } from './diagnostics.js';
+import { MimeNotAllowedError, UploadNotSupportedError, UploadPartOutOfRangeError, UploadPartSizeError, UploadPartsIncompleteError, UploadSessionExpiredError, UploadSessionNotFoundError, } from './errors.js';
+import { isMultipartCapable } from './multipart.js';
+/**
+ * Default part size: 20 MiB. Between S3's 5 MiB minimum and a reasonable payload per browser `PUT`;
+ * with S3's 10,000-part cap it covers files up to ~195 GiB. Larger than the proxy default (8 MiB)
+ * on purpose — direct parts don't occupy app memory, so the only cost of a bigger part is a bigger
+ * retry unit.
+ */
+export const DEFAULT_DIRECT_PART_SIZE = 20 * 1024 * 1024;
+/** S3's minimum part size (every part but the last). Enforced at `initiate` — see {@link UploadPartSizeError}. */
+export const MIN_DIRECT_PART_SIZE = 5 * 1024 * 1024;
+/** S3's cap on parts per multipart upload. */
+export const MAX_DIRECT_PARTS = 10_000;
+/**
+ * Default presigned part-URL lifetime (1 hour). Deliberately not sized to "the whole upload on a
+ * slow connection": {@link DirectUploadManager.status} re-issues fresh URLs for whatever is still
+ * pending, so an expired URL costs one status round-trip, not the upload.
+ */
+const DEFAULT_PRESIGN_TTL_SECONDS = 3600;
+/** Session-metadata key marking a session as a direct upload and carrying its agreed part size. */
+const PART_SIZE_METADATA_KEY = 'direct:partSize';
+/**
+ * Session-backed direct-to-S3 multipart uploads: the browser `PUT`s every byte straight to storage
+ * through presigned part URLs, and the app only coordinates — open, presign, collect ETags, close.
+ * The app's bandwidth cost is a handful of JSON round-trips regardless of file size, which is the
+ * entire point for video-sized files: the TUS path streams every chunk THROUGH the app (2× the
+ * bytes: client→app, app→S3), where this path streams none.
+ *
+ * What this adds over the raw primitives on {@link UploadManager} (`initiateDirect` & friends) is
+ * the **persisted session**: `uploadId`, the agreed `partSize` and every confirmed part ETag live
+ * in an {@link UploadSessionStore} — the same SPI the TUS engine persists its offsets in — instead
+ * of in the client's memory. A page reload no longer orphans the upload: the client asks
+ * {@link status} and gets back the confirmed ETags plus fresh URLs for what is missing.
+ *
+ * Framework-free, like {@link ResumableUploadManager}: the `DirectUploadHandler` maps it onto HTTP
+ * and the AdonisJS provider mounts that. `MediaManager.completeDirectUploadToLibrary` bridges a
+ * finished session into the media library through `attachExisting` — where the collection's
+ * whitelist checks the REAL bytes, exactly like every other upload path.
+ */
+export class DirectUploadManager {
+    storage;
+    sessions;
+    collections;
+    partSize;
+    presignTtlSeconds;
+    ttlSeconds;
+    newId;
+    now;
+    emitDiagnostics;
+    constructor(options) {
+        this.storage = options.storage;
+        this.sessions = options.sessions;
+        this.collections = options.collections;
+        this.partSize = options.partSize ?? DEFAULT_DIRECT_PART_SIZE;
+        this.presignTtlSeconds = options.presignTtlSeconds ?? DEFAULT_PRESIGN_TTL_SECONDS;
+        this.ttlSeconds = options.sessionTtlSeconds;
+        this.newId = options.idGenerator ?? (() => randomUUID());
+        this.now = options.clock ?? (() => new Date());
+        this.emitDiagnostics = options.emitDiagnostics ?? true;
+    }
+    /**
+     * Open a direct upload: validate everything that can be validated without bytes, start the native
+     * multipart upload, persist the session, and presign every part URL in one batch (presigning is
+     * local computation — see `sigv4.ts` — so a 10,000-part batch costs no S3 round-trips).
+     */
+    async initiate(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName);
+        if (typeof this.sessions.addPart !== 'function' ||
+            typeof this.sessions.listParts !== 'function') {
+            throw new UploadNotSupportedError(diskName, 'direct upload part recording');
+        }
+        if (!Number.isInteger(input.size) || input.size <= 0) {
+            throw new RangeError(`Direct upload size must be a positive integer, got ${input.size}`);
+        }
+        const partSize = input.partSize ?? this.partSize;
+        if (!Number.isInteger(partSize) || partSize < MIN_DIRECT_PART_SIZE) {
+            throw new UploadPartSizeError(`${partSize} bytes is below S3's ${MIN_DIRECT_PART_SIZE}-byte minimum`);
+        }
+        const totalParts = Math.max(1, Math.ceil(input.size / partSize));
+        if (totalParts > MAX_DIRECT_PARTS) {
+            throw new UploadPartSizeError(`${input.size} bytes at ${partSize} bytes/part needs ${totalParts} parts, over S3's cap of ${MAX_DIRECT_PARTS} — increase partSize`);
+        }
+        // The cheapest possible rejection, before the multipart upload even opens. Only the DECLARED
+        // type can be checked here (there are no bytes yet); the collection config stays the single
+        // source of truth, and attach-time validation of the real content remains the final barrier.
+        if (input.collection !== undefined && this.collections !== undefined) {
+            const accepts = this.collections.get(input.collection).acceptsMimeTypes;
+            if (accepts && input.contentType !== undefined && !accepts.includes(input.contentType)) {
+                throw new MimeNotAllowedError(input.collection, input.contentType);
+            }
+        }
+        const putOptions = input.contentType !== undefined || input.visibility !== undefined
+            ? {
+                ...(input.contentType !== undefined ? { contentType: input.contentType } : {}),
+                ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
+            }
+            : undefined;
+        const { uploadId } = await disk.createMultipartUpload(input.key, putOptions);
+        const createdAt = this.now();
+        const session = await this.sessions.create({
+            id: this.newId(),
+            disk: diskName,
+            key: input.key,
+            contentType: input.contentType,
+            size: input.size,
+            offset: 0,
+            parts: 0,
+            multipartUploadId: uploadId,
+            createdAt,
+            ...(this.ttlSeconds !== undefined
+                ? { expiresAt: new Date(createdAt.getTime() + this.ttlSeconds * 1000) }
+                : {}),
+            metadata: { ...input.metadata, [PART_SIZE_METADATA_KEY]: String(partSize) },
+        });
+        const parts = await this.#presignParts(disk, session, Array.from({ length: totalParts }, (_, index) => index + 1));
+        this.emit('upload.start', {
+            id: session.id,
+            disk: diskName,
+            key: input.key,
+            mode: 'direct',
+            size: input.size,
+            contentType: input.contentType,
+        });
+        return {
+            id: session.id,
+            key: session.key,
+            disk: diskName,
+            partSize,
+            size: input.size,
+            totalParts,
+            parts,
+            expiresAt: session.expiresAt,
+        };
+    }
+    /**
+     * Record one part the client finished `PUT`ing (its S3 `ETag` response header). This is what makes
+     * the session resumable: an ETag the server holds survives any client-side loss of state. Safe to
+     * retry — confirming the same part again overwrites its ETag.
+     */
+    async confirmPart(id, part) {
+        const session = await this.#require(id);
+        const { partSize, totalParts } = this.#geometry(session);
+        if (!Number.isInteger(part.partNumber) || part.partNumber < 1 || part.partNumber > totalParts) {
+            throw new UploadPartOutOfRangeError(part.partNumber, totalParts);
+        }
+        await this.sessions.addPart?.(id, { partNumber: part.partNumber, etag: part.etag });
+        // Recompute progress from what is actually recorded (parts confirm in any order and in
+        // parallel), so offset means "bytes safely on S3" rather than a linear cursor.
+        const confirmed = (await this.sessions.listParts?.(id)) ?? [];
+        session.parts = confirmed.length;
+        session.offset = confirmed.reduce((sum, recorded) => sum + this.#partBytes(session, partSize, totalParts, recorded.partNumber), 0);
+        await this.sessions.update(session);
+        this.emit('upload.progress', {
+            id: session.id,
+            offset: session.offset,
+            parts: session.parts,
+            size: session.size,
+        });
+        return { offset: session.offset, completedParts: confirmed.length };
+    }
+    /**
+     * Where the upload stands, framed for resumption: the ETags already confirmed and a FRESH
+     * presigned URL for every part still missing. After a page reload the client calls this, slices
+     * the file with the returned `partSize`, uploads only `pendingParts`, and completes.
+     */
+    async status(id) {
+        const session = await this.#require(id);
+        const disk = this.storage.disk(session.disk);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(session.disk);
+        const { partSize, totalParts } = this.#geometry(session);
+        const completedParts = [...((await this.sessions.listParts?.(id)) ?? [])].sort((a, b) => a.partNumber - b.partNumber);
+        const confirmedNumbers = new Set(completedParts.map((part) => part.partNumber));
+        const pendingNumbers = Array.from({ length: totalParts }, (_, index) => index + 1).filter((partNumber) => !confirmedNumbers.has(partNumber));
+        return {
+            id: session.id,
+            key: session.key,
+            disk: session.disk,
+            partSize,
+            size: session.size,
+            totalParts,
+            contentType: session.contentType,
+            completedParts,
+            pendingParts: await this.#presignParts(disk, session, pendingNumbers),
+            expiresAt: session.expiresAt,
+        };
+    }
+    /**
+     * Assemble the parts into the final object and close the session. `parts` supplements what the
+     * session already holds (a client may hand over ETags it never got to confirm — e.g. it raced
+     * completion against its last confirms); on overlap the caller's ETag wins. Every part number in
+     * `1..totalParts` must be accounted for, or this throws {@link UploadPartsIncompleteError} naming
+     * the gaps — BEFORE the S3 round-trip that would report an opaque `InvalidPart`.
+     *
+     * This is the raw primitive (the object exists, no media record). To land in the library, use
+     * `MediaManager.completeDirectUploadToLibrary`, which chains `attachExisting` — collection
+     * whitelist against the real bytes included.
+     */
+    async complete(id, parts = []) {
+        const session = await this.#require(id);
+        const disk = this.storage.disk(session.disk);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(session.disk);
+        const { totalParts } = this.#geometry(session);
+        const byNumber = new Map();
+        for (const recorded of (await this.sessions.listParts?.(id)) ?? []) {
+            byNumber.set(recorded.partNumber, recorded);
+        }
+        for (const given of parts)
+            byNumber.set(given.partNumber, given);
+        const missing = Array.from({ length: totalParts }, (_, index) => index + 1).filter((partNumber) => !byNumber.has(partNumber));
+        if (missing.length > 0)
+            throw new UploadPartsIncompleteError(id, missing);
+        const assembled = [...byNumber.values()].sort((a, b) => a.partNumber - b.partNumber);
+        await disk.completeMultipartUpload(session.key, session.multipartUploadId, assembled);
+        await this.sessions.delete(id);
+        this.emit('upload.complete', { id: session.id, disk: session.disk, key: session.key });
+        return { key: session.key, disk: session.disk, size: session.size };
+    }
+    /**
+     * Discard an in-flight upload: abort the native multipart upload (S3 frees the stored parts and
+     * stops charging for them) and drop the session. The S3 abort is best-effort — a bucket lifecycle
+     * rule may have already reaped the upload (`NoSuchUpload`), and a session that can no longer be
+     * aborted remotely must still be deletable locally.
+     */
+    async abort(id) {
+        const session = await this.sessions.get(id);
+        if (!session)
+            return;
+        const disk = this.storage.disk(session.disk);
+        if (session.multipartUploadId && isMultipartCapable(disk)) {
+            await disk.abortMultipartUpload(session.key, session.multipartUploadId).catch(() => { });
+        }
+        await this.sessions.delete(id);
+        this.emit('upload.abort', { id: session.id, disk: session.disk, key: session.key });
+    }
+    /** In-progress direct sessions, optionally filtered. Empty when the store cannot enumerate. */
+    async list(filter) {
+        const sessions = (await this.sessions.list?.(filter)) ?? [];
+        return sessions.filter((session) => session.metadata?.[PART_SIZE_METADATA_KEY] !== undefined);
+    }
+    /** Presign a `PUT` URL for each given part number, in one local batch. */
+    async #presignParts(disk, session, partNumbers) {
+        const urls = [];
+        for (const partNumber of partNumbers) {
+            urls.push({
+                partNumber,
+                url: await disk.presignUploadPart(session.key, session.multipartUploadId, partNumber, this.presignTtlSeconds),
+            });
+        }
+        return urls;
+    }
+    /** The agreed slicing for a session, recovered from its persisted metadata. */
+    #geometry(session) {
+        const partSize = Number(session.metadata?.[PART_SIZE_METADATA_KEY]);
+        const size = session.size;
+        return { partSize, totalParts: Math.max(1, Math.ceil(size / partSize)) };
+    }
+    /** Byte length of one part: `partSize`, except the last part which takes the remainder. */
+    #partBytes(session, partSize, totalParts, partNumber) {
+        const size = session.size;
+        return partNumber === totalParts ? size - (totalParts - 1) * partSize : partSize;
+    }
+    /**
+     * Load a session, requiring it to be a DIRECT one: the store may be shared with the TUS engine
+     * (the Lucid driver even shares tables), so a session lacking the direct part-size marker — or a
+     * declared size, or a native upload id — is "not found" here, never misinterpreted. An expired
+     * session is treated as gone: native upload aborted, record deleted,
+     * {@link UploadSessionExpiredError} thrown.
+     */
+    async #require(id) {
+        const session = await this.sessions.get(id);
+        if (!session ||
+            session.multipartUploadId === undefined ||
+            session.size === undefined ||
+            !Number.isFinite(Number(session.metadata?.[PART_SIZE_METADATA_KEY]))) {
+            throw new UploadSessionNotFoundError(id);
+        }
+        if (session.expiresAt && session.expiresAt.getTime() <= this.now().getTime()) {
+            const disk = this.storage.disk(session.disk);
+            if (isMultipartCapable(disk)) {
+                await disk.abortMultipartUpload(session.key, session.multipartUploadId).catch(() => { });
+            }
+            await this.sessions.delete(id);
+            throw new UploadSessionExpiredError(id);
+        }
+        return session;
+    }
+    emit(event, payload) {
+        if (this.emitDiagnostics)
+            publishMedia(event, payload);
+    }
+}
+//# sourceMappingURL=direct_upload.js.map