@adonis-agora/media 0.8.2 → 0.10.0

package/dist/src/define_config.d.ts

@@ -7,6 +7,8 @@ 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 { DirectUploadPolicy } from './types.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 +44,76 @@ 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;
+        /**
+         * Middleware applied to every built-in direct-session route (the provider passes them straight
+         * to the AdonisJS route group). Typed framework-neutrally as `unknown[]` so this config never
+         * imports AdonisJS — guard the routes here (e.g. `middleware.auth()`), since the handler itself
+         * performs NO authorization.
+         */
+        middleware?: readonly unknown[];
+        /**
+         * Lazily load a {@link DirectUploadPolicy} that owns the app-specific decisions (key resolution,
+         * what the upload becomes on completion, error→HTTP mapping). A thunk so the policy module — and
+         * anything it imports — loads only when the routes mount. The provider reads its default export.
+         */
+        policy?: () => Promise<{
+            default: DirectUploadPolicy<unknown, unknown>;
+        }>;
+    };
 }
 /**
  * Resumable (TUS) upload configuration. The session store persists offset/length/metadata/expiry so
@@ -147,8 +219,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 +230,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;AAGzD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAoO9D;;;;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/diagnostics.d.ts

@@ -91,4 +91,11 @@ export interface MediaDiagnosticPayloads {
  * into the library.
  */
 export declare function publishMedia<E extends MediaDiagnosticEvent>(event: E, payload: MediaDiagnosticPayloads[E]): void;
+/**
+ * Wrap a unit of media work in a structural trace span (`upload.policy.*` and friends). When a
+ * diagnostics trace slot is installed it observes the call (lib hard-coded to `'media'`); otherwise
+ * the wrapped function runs directly. Unlike {@link publishMedia}, errors are NOT swallowed — a
+ * traced policy hook must surface its failure to the caller so the handler can map it.
+ */
+export declare function traceMedia<T>(event: string, fn: () => T, payload?: unknown): T;
 //# sourceMappingURL=diagnostics.d.ts.map

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

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

package/dist/src/diagnostics.js

@@ -5,6 +5,13 @@
  * and emitting is an inert no-op.
  */
 const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
+/**
+ * The `@adonis-agora/diagnostics` trace capability, published on this global slot. Like
+ * {@link EMIT_SLOT} it is read STRUCTURALLY — media never imports the diagnostics package.
+ * A trace slot wraps a unit of work so an observer can time/inspect it; when no slot is
+ * installed the wrapped function simply runs and its result (or error) passes through.
+ */
+const TRACE_SLOT = Symbol.for('@agora/diagnostics:trace');
 /**
  * Every media milestone published on `agora:media:<event>`. The single runtime source for the
  * {@link MediaDiagnosticEvent} union — a Telescope watcher iterates this to subscribe/claim.
@@ -87,4 +94,17 @@ export function publishMedia(event, payload) {
         }
     }
 }
+/**
+ * Wrap a unit of media work in a structural trace span (`upload.policy.*` and friends). When a
+ * diagnostics trace slot is installed it observes the call (lib hard-coded to `'media'`); otherwise
+ * the wrapped function runs directly. Unlike {@link publishMedia}, errors are NOT swallowed — a
+ * traced policy hook must surface its failure to the caller so the handler can map it.
+ */
+export function traceMedia(event, fn, payload) {
+    const trace = globalThis[TRACE_SLOT];
+    if (typeof trace === 'function') {
+        return trace('media', event, fn, payload);
+    }
+    return fn();
+}
 //# sourceMappingURL=diagnostics.js.map

package/dist/src/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAGxD;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,QAAQ;IACR,QAAQ;IACR,YAAY;IACZ,mBAAmB;IACnB,mBAAmB;IACnB,cAAc;IACd,iBAAiB;IACjB,iBAAiB;IACjB,cAAc;CACN,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE5D,iLAAiL;AACjL,SAAS,cAAc;IACrB,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,IAAI,QAAQ,GAAG,CAAC,CAAC,WAAW,CAAoC,CAAC;IACjE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QACrC,CAAC,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC;IAC5B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAyB;IAC7D,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,IAAI,KAAK,IAAI,CAAC;gBAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAChC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,+IAA+I;AAC/I,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,MAAM,QAAQ,GAAI,UAAsC,CAAC,WAAW,CAEvD,CAAC;IACd,OAAO,QAAQ,EAAE,GAAG,CAAC,SAAS,KAAK,EAAE,CAAC,IAAI,KAAK,CAAC;AAClD,CAAC;AA4ED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAQ,EACR,OAAmC;IAEnC,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;IACtF,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"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"}

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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"}