@adonis-agora/media 0.10.3 → 0.11.0

package/dist/src/dashboard/service.d.ts

@@ -0,0 +1,215 @@
+import type { Readable } from 'node:stream';
+import type { MediaRecord } from '../media_record.js';
+import type { MediaListOptions, MediaListPage } from '../media_store.js';
+import type { UploadSession } from '../resumable_upload.js';
+import type { Disk, MultipartPart } from '../types.js';
+import type { ObjectInsightProvider } from './object_insights.js';
+import type { CollectionFilter, CollectionListResponse, CollectionsSummaryResponse, DiskListResponse, MediaDetailResponse, ObjectDetailResponse, ObjectInsightsResponse, ObjectListResponse, Topology, UploadDetailResponse, UploadListResponse } from './types.js';
+/** TTL of the signed URLs handed to the browser for object preview/download. */
+export declare const URL_TTL_SECONDS = 300;
+/** Cap on the get→put streaming path used for cross-disk copy/move (drivers can't copy across disks). */
+export declare const MAX_TRANSFER_BYTES: number;
+/** Page size for the flat sweep that recursive folder delete/copy/move paginates over. */
+export declare const FOLDER_SWEEP_LIMIT = 1000;
+/** Page size for the client-side scan behind {@link DashboardService.collectionsSummary}. */
+export declare const COLLECTIONS_SUMMARY_PAGE_SIZE = 200;
+/** Hard cap on records scanned by {@link DashboardService.collectionsSummary} — beyond this the
+ *  rollup is partial rather than unbounded. */
+export declare const COLLECTIONS_SUMMARY_SCAN_LIMIT = 5000;
+/** Ceiling for a console (direct) upload — buffered in memory, so bounded to protect the process
+ *  heap. Larger files belong on the resumable (TUS) upload path, not this convenience upload. */
+export declare const MAX_UPLOAD_BYTES: number;
+/** The slice of `MediaManager` the dashboard depends on — kept structural so it's trivial to fake in tests. */
+export interface MediaManagerLike {
+    readonly storage: {
+        readonly defaultDisk: string;
+        disk(name?: string): Disk;
+    };
+    readonly hasResumable: boolean;
+    readonly resumable: {
+        list(filter?: {
+            disk?: string;
+            keyPrefix?: string;
+        }): Promise<UploadSession[]>;
+        /** Discard an in-flight session (native multipart + buffered parts), then drop its record. */
+        abort(id: string): Promise<void>;
+        /** All recorded parts for a session (multipart-capable disks); empty for a buffered session. */
+        listParts(id: string): Promise<MultipartPart[]>;
+    };
+    /** The persistence SPI — the console reads stored records via the cross-owner `list`, and a single
+     *  record (+ delete) for the record-detail drill-in. */
+    readonly store: {
+        list(options?: MediaListOptions): Promise<MediaListPage>;
+        find(id: string): Promise<MediaRecord | null>;
+        delete(id: string): Promise<void>;
+    };
+}
+export interface DashboardServiceOptions {
+    /** Disk names the console may browse/act on. The first entry (or the manager default) is the default. */
+    diskNames: string[];
+    /** Whether mutating actions (copy/move/delete) are permitted. */
+    actions: boolean;
+}
+/** An error carrying an HTTP status for the provider to surface verbatim. */
+export declare class DashboardError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * All dashboard read/action logic, expressed over a structural {@link MediaManagerLike}. It reads the
+ * *real* `@adonis-agora/media` surface — disk `list`/`stat`/`getSignedUrl`/`copy`/`move`/`deleteMany`
+ * and the resumable `UploadSessionStore.list()` — and never invents its own persistence. The provider
+ * is a thin HTTP shell around this; the logic is pure and unit-tested without booting AdonisJS.
+ */
+export declare class DashboardService {
+    private readonly manager;
+    private readonly options;
+    /** Host-registered {@link ObjectInsightProvider}s, from `config/media_dashboard.ts`'s `objectInsights`. */
+    private readonly insightProviders;
+    constructor(manager: MediaManagerLike, options: DashboardServiceOptions, 
+    /** Host-registered {@link ObjectInsightProvider}s, from `config/media_dashboard.ts`'s `objectInsights`. */
+    insightProviders?: ObjectInsightProvider[]);
+    /** Coarse capability topology for the SPA to enable/disable affordances. */
+    topology(): Topology;
+    /** Enumerate the exposed disks with their capabilities (non-extended disks report `list:false`). */
+    disks(): DiskListResponse;
+    /** List one page of a bucket under `prefix` (cursor-based, folders rolled up on the `/` delimiter). */
+    objects(diskName: string, params?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ObjectListResponse>;
+    /** Object metadata + a short-lived signed URL for preview/download. */
+    object(diskName: string, key: string): Promise<ObjectDetailResponse>;
+    /**
+     * The object's raw byte stream plus the metadata the provider needs to serve it inline. Backs the
+     * console's same-origin preview proxy so text/PDF render in the browser instead of downloading
+     * (and so a CORS-locked bucket is still previewable).
+     */
+    objectStream(diskName: string, key: string): Promise<{
+        stream: Readable;
+        contentType: string;
+        size: number;
+    }>;
+    /**
+     * What the HOST knows about this object, from every registered `objectInsights` provider (see
+     * `config/media_dashboard.ts`). `{ insights: [] }` when none are registered. A provider that
+     * throws is skipped and logged — annotation must never be able to stop an admin opening a file, and
+     * providers run concurrently so one host lookup being slow doesn't serialize the others.
+     */
+    objectInsights(diskName: string, key: string): Promise<ObjectInsightsResponse>;
+    /** In-progress resumable uploads, projected from the session store (empty when unconfigured). */
+    uploads(filter?: {
+        disk?: string;
+        prefix?: string;
+    }): Promise<UploadListResponse>;
+    /** Full detail (+ recorded parts) of one resumable upload session. */
+    uploadDetail(id: string): Promise<UploadDetailResponse>;
+    /**
+     * Cancels a resumable session: discards its native multipart upload (or buffered parts) and drops
+     * its record, so it stops appearing as in-progress. Actions-gated.
+     */
+    abortUpload(id: string): Promise<void>;
+    /**
+     * One cursor-paginated page of stored media-library records across owners/collections, projected to
+     * the SPA's {@link MediaEntry}. Delegates to the real {@link MediaStore.list} — no bespoke query.
+     */
+    collections(params?: CollectionFilter & {
+        cursor?: string;
+        limit?: number;
+    }): Promise<CollectionListResponse>;
+    /**
+     * Per-collection rollup (record count + total bytes) for the console's collection chips.
+     * `MediaStore` has no aggregate query, so this walks `list()` in batches and sums client-side —
+     * bounded at {@link COLLECTIONS_SUMMARY_SCAN_LIMIT} records so a very large library degrades to a
+     * partial (still useful) summary instead of an unbounded scan.
+     */
+    collectionsSummary(): Promise<CollectionsSummaryResponse>;
+    /**
+     * Full detail of one stored `MediaRecord`, plus signed URLs for its generated conversions. Only
+     * conversions carrying a concrete `{disk, path}` artifact get a link — a metadata-only conversion
+     * (probe results with no output file) has nothing to preview.
+     */
+    mediaRecord(id: string): Promise<MediaDetailResponse>;
+    /** Deletes a stored `MediaRecord`. Actions-gated (does not touch its underlying disk object). */
+    deleteMediaRecord(id: string): Promise<void>;
+    /** Server-side copy (same disk) or streamed cross-disk copy. Original is kept. */
+    copy(body: {
+        disk: string;
+        from: string;
+        to: string;
+        toDisk?: string;
+    }): Promise<void>;
+    /** Server-side move (same disk) or streamed cross-disk move. Source is deleted after transfer. */
+    move(body: {
+        disk: string;
+        from: string;
+        to: string;
+        toDisk?: string;
+    }): Promise<void>;
+    /** Batched delete of many keys on one disk. */
+    remove(body: {
+        disk: string;
+        keys: string[];
+    }): Promise<void>;
+    /**
+     * Writes an object from a byte stream (a browser upload) — the console's convenience upload,
+     * distinct from the resumable TUS path. The caller supplies the full key (prefix + filename).
+     * Bounded at {@link MAX_UPLOAD_BYTES} so a runaway upload can't exhaust the process heap. Actions-gated.
+     */
+    putObject(diskName: string, key: string, body: AsyncIterable<Uint8Array>, contentType?: string): Promise<void>;
+    /**
+     * Create a "folder" — a zero-byte marker object at `<prefix>/`, which S3-style delimiter listing
+     * surfaces as a navigable folder. Normalizes to exactly one trailing slash (so the key never
+     * double-slashes); rejects an empty prefix. Actions-gated.
+     */
+    createFolder(body: {
+        disk: string;
+        prefix: string;
+    }): Promise<void>;
+    /**
+     * Recursively delete a "folder": every object under `<prefix>/` (nested included) plus the
+     * zero-byte marker itself. Sweeps with an EMPTY delimiter so the driver lists keys FLAT — the
+     * default `/` delimiter would roll nested keys up into folder prefixes and the sweep would miss
+     * them, deleting only direct children. Paginates until the disk reports no more, then deletes the
+     * marker explicitly (its key equals the sweep prefix, which `list` filters out). Actions-gated.
+     */
+    deleteFolder(body: {
+        disk: string;
+        prefix: string;
+    }): Promise<void>;
+    /** Copy a whole "folder" (every object under `<from>/`, nested included) to `<to>/`, same or cross disk. */
+    copyFolder(body: {
+        disk: string;
+        from: string;
+        to: string;
+        toDisk?: string;
+    }): Promise<void>;
+    /** Move a whole "folder" (every object under `<from>/`, nested included) to `<to>/`, same or cross disk. */
+    moveFolder(body: {
+        disk: string;
+        from: string;
+        to: string;
+        toDisk?: string;
+    }): Promise<void>;
+    private transfer;
+    /**
+     * Relocate a single object, same disk or across disks. Same-disk uses the driver's native
+     * `copy`/`move` (server-side, no bytes through the app). Cross-disk has no driver primitive, so the
+     * object is streamed through the app (get→put, capped at {@link MAX_TRANSFER_BYTES}); a `move` then
+     * deletes the source. Callers gate actions.
+     */
+    private transferKey;
+    /**
+     * Shared engine for {@link copyFolder}/{@link moveFolder}. Same flat-listing sweep as
+     * {@link deleteFolder}; each key is relocated via {@link transferKey} (so cross-disk works
+     * transparently), preserving its path relative to the source. On the SAME disk, rejects a
+     * destination inside the source (which would recurse forever); across disks that can't happen. The
+     * destination folder marker is written, and for a move the source marker removed, so both listings
+     * stay consistent. Actions-gated.
+     */
+    private transferFolder;
+    private extended;
+    private assertActions;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/src/dashboard/service.d.ts.map

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