@mieweb/pulsevault 0.0.2 → 0.1.1

package/dist/storage/s3.js

@@ -0,0 +1,438 @@
+import { createHash } from 'node:crypto';
+import { parseUploadKind } from './types.js';
+const SIDECAR_VERSION = 1;
+/** Key prefix inside the bucket that holds the per-upload sidecar objects. */
+const PULSEVAULT_META_PREFIX = '.pulsevault';
+/** Default presigned playback URL lifetime (15 minutes). */
+const DEFAULT_PRESIGN_TTL_SECONDS = 900;
+/** Default cap on the in-memory metadata cache before evicting the oldest entry. */
+const DEFAULT_META_CACHE_LIMIT = 10_000;
+/** Map a file extension to the `Content-Type` the playback URL should return. */
+function extToContentType(ext) {
+    switch (ext) {
+        case '.mp4':
+            return 'video/mp4';
+        case '.zip':
+            return 'application/zip';
+        case '.vtt':
+            return 'text/vtt';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.png':
+            return 'image/png';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/** Project a `Sidecar` into the shape kept in the in-memory cache. */
+function sidecarToCachedMeta(sidecar, ready) {
+    return {
+        ext: sidecar.ext,
+        ready,
+        kind: sidecar.kind ?? 'video',
+        relatedTo: sidecar.relatedTo,
+        checksum: sidecar.checksum,
+    };
+}
+/**
+ * Build an S3/R2-backed storage adapter.
+ *
+ * Async because it lazily imports the optional `@aws-sdk/*` and
+ * `@tus/s3-store` packages — `await` it before registering the plugin:
+ *
+ * ```ts
+ * const storage = await createS3Storage({
+ *   bucket: "pulse-videos",
+ *   endpoint: `https://${ACCOUNT}.r2.cloudflarestorage.com`,
+ *   accessKeyId: process.env.R2_ACCESS_KEY,
+ *   secretAccessKey: process.env.R2_SECRET_KEY,
+ * });
+ * await app.register(pulseVault, { storage, prefix: "/pulsevault", maxUploadSize: Infinity });
+ * ```
+ */
+export async function createS3Storage(opts) {
+    let s3;
+    let presigner;
+    let s3store;
+    try {
+        [s3, presigner, s3store] = await Promise.all([
+            import('@aws-sdk/client-s3'),
+            import('@aws-sdk/s3-request-presigner'),
+            import('@tus/s3-store'),
+        ]);
+    }
+    catch (err) {
+        throw new Error('createS3Storage requires the optional packages `@aws-sdk/client-s3`, ' +
+            '`@aws-sdk/s3-request-presigner`, and `@tus/s3-store`. Install them with:\n' +
+            '  npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @tus/s3-store\n' +
+            `(original error: ${err instanceof Error ? err.message : String(err)})`);
+    }
+    const { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand } = s3;
+    const { getSignedUrl } = presigner;
+    const { S3Store } = s3store;
+    const bucket = opts.bucket;
+    const presignTtl = opts.presignTtlSeconds ?? DEFAULT_PRESIGN_TTL_SECONDS;
+    const metaCacheLimit = opts.metaCacheLimit ?? DEFAULT_META_CACHE_LIMIT;
+    const credentials = opts.accessKeyId && opts.secretAccessKey
+        ? {
+            accessKeyId: opts.accessKeyId,
+            secretAccessKey: opts.secretAccessKey,
+            ...(opts.sessionToken ? { sessionToken: opts.sessionToken } : {}),
+        }
+        : undefined;
+    const clientConfig = {
+        region: opts.region ?? (opts.endpoint ? 'auto' : undefined),
+        ...(opts.endpoint ? { endpoint: opts.endpoint } : {}),
+        forcePathStyle: opts.forcePathStyle ?? Boolean(opts.endpoint),
+        ...(credentials ? { credentials } : {}),
+        ...opts.clientConfig,
+    };
+    // Our own client, used for sidecar I/O, ranged header reads, deletes, and
+    // presigning. The TUS datastore creates its own client from the same config.
+    const client = new S3Client(clientConfig);
+    const datastore = new S3Store({
+        ...(opts.partSize ? { partSize: opts.partSize } : {}),
+        s3ClientConfig: { ...clientConfig, bucket },
+    });
+    // Metadata cache keyed by artifactId, mirroring the local adapter: populated
+    // eagerly on reserve and lazily from the sidecar on a cache-miss, so the GET
+    // hot path avoids a per-request round-trip to the bucket. Bounded with
+    // simple insertion-order eviction, same rationale as the local adapter.
+    const metaCache = new Map();
+    const cacheSet = (artifactId, meta) => {
+        metaCache.delete(artifactId);
+        metaCache.set(artifactId, meta);
+        if (metaCache.size > metaCacheLimit) {
+            const oldest = metaCache.keys().next().value;
+            if (oldest !== undefined)
+                metaCache.delete(oldest);
+        }
+    };
+    const sidecarKey = (artifactId) => `${PULSEVAULT_META_PREFIX}/${artifactId}.json`;
+    /** Object key for the artifact bytes — also the TUS file id / multipart key. */
+    const artifactKey = (artifactId, kind, ext) => `${kind}/${artifactId}${ext}`;
+    const writeSidecar = async (artifactId, sidecar) => {
+        await client.send(new PutObjectCommand({
+            Bucket: bucket,
+            Key: sidecarKey(artifactId),
+            Body: JSON.stringify(sidecar),
+            ContentType: 'application/json',
+        }));
+    };
+    const readSidecar = async (artifactId) => {
+        let raw;
+        try {
+            const res = await client.send(new GetObjectCommand({ Bucket: bucket, Key: sidecarKey(artifactId) }));
+            raw = (await bodyToBuffer(res.Body)).toString('utf8');
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.ext !== 'string')
+                return null;
+            if (typeof parsed.filename !== 'string')
+                return null;
+            const status = parsed.status === 'uploading' ? 'uploading' : 'ready';
+            const kind = parseUploadKind(parsed.kind);
+            return {
+                version: SIDECAR_VERSION,
+                ext: parsed.ext,
+                filename: parsed.filename,
+                status,
+                kind,
+                relatedTo: typeof parsed.relatedTo === 'string' ? parsed.relatedTo : undefined,
+                checksum: typeof parsed.checksum === 'string' ? parsed.checksum : undefined,
+            };
+        }
+        catch {
+            // Malformed sidecar — treat as absent; `reserveUpload` rewrites it.
+            return null;
+        }
+    };
+    const loadMeta = async (artifactId) => {
+        const cached = metaCache.get(artifactId);
+        if (cached)
+            return cached;
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar)
+            return null;
+        const meta = sidecarToCachedMeta(sidecar, sidecar.status === 'ready');
+        cacheSet(artifactId, meta);
+        return meta;
+    };
+    const reserveUpload = async ({ artifactId, filename, ext, kind, relatedTo, checksum, }) => {
+        const sidecar = {
+            version: SIDECAR_VERSION,
+            ext,
+            filename,
+            status: 'uploading',
+            kind,
+            relatedTo,
+            checksum,
+        };
+        // Fast-path rejection for the common case. Not atomic by itself (two concurrent
+        // requests can both observe no existing meta before either writes) — the conditional
+        // write below closes that race on backends that support it — but it's also the only
+        // enforcement on S3-compatible backends that silently ignore `IfNoneMatch` instead of
+        // erroring.
+        const existing = await loadMeta(artifactId);
+        if (existing) {
+            throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
+                statusCode: 409,
+                status_code: 409,
+            });
+        }
+        // Collision guard: `IfNoneMatch: "*"` makes the write itself atomically fail
+        // (PreconditionFailed) if a sidecar object already exists for this artifactId, closing
+        // the race the check above can't close by itself. Surfaces as HTTP 409 via @tus/server's
+        // error path, same as before.
+        try {
+            await client.send(new PutObjectCommand({
+                Bucket: bucket,
+                Key: sidecarKey(artifactId),
+                Body: JSON.stringify(sidecar),
+                ContentType: 'application/json',
+                IfNoneMatch: '*',
+            }));
+        }
+        catch (err) {
+            if (isPreconditionFailed(err)) {
+                throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
+                    statusCode: 409,
+                    status_code: 409,
+                });
+            }
+            if (!isConditionalWriteUnsupported(err))
+                throw err;
+            // Some S3-compatible backends don't support conditional writes — fall back to the
+            // previous check-then-write. Weaker (the original TOCTOU window reopens) but keeps
+            // reserve working on those backends instead of hard-failing every upload. Surface
+            // this degraded mode once per process so operators know their backend can't fully
+            // guarantee collision safety under concurrent/retried creates for the same artifactId.
+            warnAboutConditionalWriteFallbackOnce();
+            const meta = await loadMeta(artifactId);
+            if (meta) {
+                throw Object.assign(new Error(`artifactId ${artifactId} already has an upload`), {
+                    statusCode: 409,
+                    status_code: 409,
+                });
+            }
+            await writeSidecar(artifactId, sidecar);
+        }
+        cacheSet(artifactId, { ext, ready: false, kind, relatedTo, checksum });
+        // @tus/s3-store uses this as the object key for the multipart upload, so
+        // the finished object lands at `<kind>/<artifactId><ext>`.
+        return artifactKey(artifactId, kind, ext);
+    };
+    const resolve = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        // Only serve ready uploads — an object that exists but is mid-upload or
+        // failed validation stays hidden.
+        if (!meta || !meta.ready)
+            return null;
+        const key = artifactKey(artifactId, meta.kind, meta.ext);
+        const url = await getSignedUrl(client, new GetObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            // Force the right Content-Type on the redirected download regardless
+            // of what was stored on the object.
+            ResponseContentType: extToContentType(meta.ext),
+        }), { expiresIn: presignTtl });
+        return { kind: 'redirect', url, statusCode: 302 };
+    };
+    const markReady = async (artifactId) => {
+        const sidecar = await readSidecar(artifactId);
+        if (!sidecar) {
+            throw new Error(`markReady: no sidecar for artifactId ${artifactId} (was reserveUpload called?)`);
+        }
+        const next = sidecarToCachedMeta(sidecar, true);
+        if (sidecar.status === 'ready') {
+            // Idempotent: already ready, just keep the cache consistent.
+            cacheSet(artifactId, next);
+            return;
+        }
+        await writeSidecar(artifactId, { ...sidecar, status: 'ready' });
+        cacheSet(artifactId, next);
+    };
+    const remove = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        // Evict before deleting so a racing `resolve` can't hand back a stale key.
+        metaCache.delete(artifactId);
+        if (!meta)
+            return false;
+        const key = artifactKey(artifactId, meta.kind, meta.ext);
+        // Abort any still-in-progress multipart upload (no-op / best-effort once
+        // the upload has completed) so we never orphan an open multipart session.
+        await Promise.allSettled([
+            datastore.remove?.(key),
+        ]);
+        // Delete the finalized object, the @tus/s3-store `.info` sidecar, and our
+        // metadata sidecar. DeleteObject is idempotent, so this is safe whether or
+        // not the multipart abort above already removed some of them.
+        await Promise.all([
+            client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key })),
+            client.send(new DeleteObjectCommand({ Bucket: bucket, Key: `${key}.info` })),
+            client.send(new DeleteObjectCommand({ Bucket: bucket, Key: sidecarKey(artifactId) })),
+        ]);
+        return true;
+    };
+    const readHeader = async (artifactId, n) => {
+        const meta = await loadMeta(artifactId);
+        if (!meta)
+            return null;
+        const key = artifactKey(artifactId, meta.kind, meta.ext);
+        try {
+            const res = await client.send(new GetObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Range: `bytes=0-${Math.max(0, n - 1)}`,
+            }));
+            return await bodyToBuffer(res.Body);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    };
+    const readAll = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        if (!meta)
+            return null;
+        const key = artifactKey(artifactId, meta.kind, meta.ext);
+        try {
+            const res = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+            return await bodyToBuffer(res.Body);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    };
+    const digestAll = async (artifactId, algorithm) => {
+        const meta = await loadMeta(artifactId);
+        if (!meta)
+            return null;
+        const key = artifactKey(artifactId, meta.kind, meta.ext);
+        try {
+            const res = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+            return await digestBody(res.Body, algorithm);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    };
+    const getKind = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta ? meta.kind : null;
+    };
+    const getRelatedTo = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta?.relatedTo ?? null;
+    };
+    const getChecksum = async (artifactId) => {
+        const meta = await loadMeta(artifactId);
+        return meta?.checksum ?? null;
+    };
+    const shutdown = async () => {
+        client.destroy();
+    };
+    return {
+        datastore,
+        bucket,
+        reserveUpload,
+        resolve,
+        markReady,
+        remove,
+        readHeader,
+        readAll,
+        digestAll,
+        getKind,
+        getRelatedTo,
+        getChecksum,
+        shutdown,
+    };
+}
+function hasTransformToByteArray(body) {
+    return (!!body &&
+        typeof body.transformToByteArray === 'function');
+}
+/** Collect an AWS SDK response body into a Buffer. */
+async function bodyToBuffer(body) {
+    if (hasTransformToByteArray(body)) {
+        return Buffer.from(await body.transformToByteArray());
+    }
+    const chunks = [];
+    for await (const chunk of body) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Stream an AWS SDK response body through a hash digest without buffering the
+ * whole thing into memory first — the streaming counterpart to
+ * `bodyToBuffer`, used by `digestAll`.
+ */
+async function digestBody(body, algorithm) {
+    const hash = createHash(algorithm);
+    if (hasTransformToByteArray(body)) {
+        hash.update(await body.transformToByteArray());
+        return hash.digest('hex');
+    }
+    for await (const chunk of body) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+/** Whether an AWS SDK error represents a missing key/object (404-ish). */
+function isNotFound(err) {
+    const e = err;
+    return (e?.name === 'NoSuchKey' ||
+        e?.name === 'NotFound' ||
+        e?.Code === 'NoSuchKey' ||
+        e?.Code === 'NotFound' ||
+        e?.$metadata?.httpStatusCode === 404);
+}
+/** Whether a conditional `PutObjectCommand` (`IfNoneMatch`) failed because the object already exists. */
+function isPreconditionFailed(err) {
+    const e = err;
+    return (e?.name === 'PreconditionFailed' ||
+        e?.Code === 'PreconditionFailed' ||
+        e?.$metadata?.httpStatusCode === 412);
+}
+/** Whether the backend rejected `IfNoneMatch` itself as unsupported, rather than the condition failing. */
+function isConditionalWriteUnsupported(err) {
+    const e = err;
+    return (e?.name === 'NotImplemented' ||
+        e?.Code === 'NotImplemented' ||
+        e?.$metadata?.httpStatusCode === 501);
+}
+let warnedAboutConditionalWriteFallback = false;
+/**
+ * One-time-per-process warning when `reserveUpload` falls back to
+ * check-then-write because the configured S3-compatible backend doesn't
+ * support `IfNoneMatch`. That fallback reopens a genuine TOCTOU window
+ * (two concurrent/retried `reserveUpload` calls for the same artifactId can
+ * both pass the check before either writes, silently clobbering one
+ * another's sidecar) — there's no way to close it without a real distributed
+ * lock, so the best this library can do is make the degraded mode visible.
+ */
+function warnAboutConditionalWriteFallbackOnce() {
+    if (warnedAboutConditionalWriteFallback)
+        return;
+    warnedAboutConditionalWriteFallback = true;
+    console.warn('[pulsevault] S3-compatible backend does not support conditional writes (IfNoneMatch); ' +
+        'falling back to check-then-write for reserveUpload. This reopens a collision race ' +
+        'between concurrent/retried creates for the same artifactId. If this matters for your ' +
+        'deployment, use a backend that supports IfNoneMatch, or serialize artifactId creation ' +
+        'in front of pulsevault (e.g. in your own /reserve endpoint).');
+}
+//# sourceMappingURL=s3.js.map

package/dist/storage/s3.js.map

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

package/dist/storage/types.d.ts

@@ -1,28 +1,72 @@
-import type { DataStore } from "@tus/server";
+import type { DataStore } from '@tus/server';
 /**
- * How the GET route should serve a resolved video. Stream means `@fastify/send`
- * reads directly from a local path; Redirect issues an HTTP 3xx to a URL the
- * adapter produced (e.g. a pre-signed object storage URL).
+ * How the GET route should serve a resolved artifact. Stream means
+ * `@fastify/send` reads directly from a local path; Redirect issues an HTTP
+ * 3xx to a URL the adapter produced (e.g. a pre-signed object storage URL).
  */
 export type PulseVaultResolution = {
-    kind: "stream";
+    kind: 'stream';
     /** Root directory `@fastify/send` should jail to. */
     root: string;
     /** Filename relative to `root`. */
     filename: string;
+    /**
+     * Explicit `Content-Type` to set on the response. When present the GET
+     * route overrides whatever `@fastify/send` infers from the extension.
+     * Populated by adapters for non-standard extensions (e.g. `.pulse`).
+     */
+    contentType?: string;
 } | {
-    kind: "redirect";
+    kind: 'redirect';
     url: string;
     /** Defaults to 302. */
     statusCode?: number;
 };
+/** Every artifact kind the server understands. Single source of truth for the union, the
+ * `/capabilities` `kinds` list, and `parseUploadKind`. Add a new kind here and every switch that
+ * routes on kind stays in lockstep. */
+export declare const UPLOAD_KINDS: readonly ["video", "project", "captions", "thumbnail"];
+export type UploadKind = (typeof UPLOAD_KINDS)[number];
+/**
+ * Coerce a raw metadata/sidecar `kind` string to a known `UploadKind`, defaulting to `"video"`
+ * (so pre-`kind` clients and older sidecars keep working). Use this everywhere a kind is parsed —
+ * do NOT hand-write per-kind ternaries, which drift out of sync when a kind is added.
+ */
+export declare function parseUploadKind(raw: string | null | undefined): UploadKind;
 export type ReserveUploadParams = {
-    /** UUID from `Upload-Metadata.videoid`. */
-    videoid: string;
+    /** UUID from `Upload-Metadata.artifactId` (or the `videoid`/`projectid` legacy aliases). */
+    artifactId: string;
     /** Raw filename from `Upload-Metadata.filename`. */
     filename: string;
     /** Lowercase extension including the leading dot, validated upstream. */
     ext: string;
+    /** Artifact kind derived from `Upload-Metadata.kind`. Defaults to `"video"`. */
+    kind: UploadKind;
+    /**
+     * Optional UUID of another artifact this one belongs to, from
+     * `Upload-Metadata.relatedTo`. Lets a single capability token scoped to one
+     * "session" artifact (e.g. a video) authorize related artifacts uploaded in
+     * the same session (a merged video's captions, beat manifest and thumbnail,
+     * or — under `uploadUnit: "segment"` — each clip plus the ordering manifest)
+     * without minting a token per artifact.
+     * The storage layer itself only stores and returns this value — it does not
+     * validate that the referenced artifact exists or was created by the same
+     * caller. The actual authorization check lives in `createCapabilityAuthorize`
+     * (`lib/capability-token.ts`), which treats a request's `relatedTo` as
+     * authorized whenever it matches the presented token's own signed
+     * `artifactId` claim. That's safe only because a token can't be forged or
+     * guessed (HMAC-signed) — do not read this field as "unauthenticated
+     * metadata with no security relevance."
+     */
+    relatedTo?: string;
+    /**
+     * Optional client-supplied integrity digest from `Upload-Metadata.checksum`
+     * (`<algorithm>:<hex>`), persisted so `createChecksumValidator` can read it
+     * at completion time even when completion happens on a different request
+     * than creation (chunked uploads, or even a single-PATCH upload sent as
+     * two separate HTTP requests).
+     */
+    checksum?: string;
 };
 /**
  * Storage backend contract. Keep the surface small: one write hook, one read
@@ -46,12 +90,12 @@ export interface PulseVaultStorage {
      */
     reserveUpload(params: ReserveUploadParams): Promise<string>;
     /**
-     * Called by the GET route. Returns how to serve the video, or `null` if
-     * the videoid is unknown *or* the upload is still in progress — adapters
+     * Called by the GET route. Returns how to serve the artifact, or `null` if
+     * the artifactId is unknown *or* the upload is still in progress — adapters
      * that implement `markReady` should only return non-null once the bytes
      * have been promoted to "ready."
      */
-    resolve(videoid: string): Promise<PulseVaultResolution | null>;
+    resolve(artifactId: string): Promise<PulseVaultResolution | null>;
     /**
      * Mark an upload as fully written and safe to serve. Called by the plugin
      * after the final byte lands and any `validatePayload` + `onUploadComplete`
@@ -60,13 +104,32 @@ export interface PulseVaultStorage {
      * may omit this method — `resolve` will be trusted to only return finished
      * uploads in that case.
      */
-    markReady?(videoid: string): Promise<void>;
+    markReady?(artifactId: string): Promise<void>;
+    /**
+     * Delete all storage associated with an artifactId. Returns `true` if
+     * something was removed, `false` if the artifactId was already absent.
+     * Called both from the `DELETE /artifacts/:artifactId` route and from the
+     * plugin's cleanup path when `validatePayload` rejects a completed upload.
+     */
+    remove?(artifactId: string): Promise<boolean>;
+    /**
+     * Return the artifact kind for a known artifactId, or `null` if the
+     * artifactId is not found. Used by the generic artifact route to resolve
+     * which kind to serve without it being encoded in the URL.
+     */
+    getKind?(artifactId: string): Promise<UploadKind | null>;
+    /**
+     * Return the `relatedTo` artifact id stored at `reserveUpload` time, or
+     * `null` if the artifactId is unknown or has no relation recorded. Used by
+     * `createCapabilityAuthorize` to authorize an artifact against a token
+     * scoped to the session it belongs to, not just its own id.
+     */
+    getRelatedTo?(artifactId: string): Promise<string | null>;
     /**
-     * Delete all storage associated with a videoid. Returns `true` if
-     * something was removed, `false` if the videoid was already absent.
-     * Called both from the `DELETE /:videoid` route and from the plugin's
-     * cleanup path when `validatePayload` rejects a completed upload.
+     * Return the `checksum` metadata stored at `reserveUpload` time, or `null`
+     * if the artifactId is unknown or no checksum was supplied. Used by
+     * `createChecksumValidator`/`createS3ChecksumValidator` at completion time.
      */
-    remove?(videoid: string): Promise<boolean>;
+    getChecksum?(artifactId: string): Promise<string | null>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,mBAAmB,GAAG;IAChC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B,sDAAsD;IACtD,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAE/D;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN;;uCAEuC;AACvC,eAAO,MAAM,YAAY,wDAAyD,CAAC;AAEnF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,UAAU,CAG1E;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B,sDAAsD;IACtD,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAElE;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,MAAM,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9C;;;;OAIG;IACH,OAAO,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEzD;;;;;OAKG;IACH,YAAY,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1D;;;;OAIG;IACH,WAAW,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D"}

package/dist/storage/types.js

@@ -1,2 +1,14 @@
-export {};
+/** Every artifact kind the server understands. Single source of truth for the union, the
+ * `/capabilities` `kinds` list, and `parseUploadKind`. Add a new kind here and every switch that
+ * routes on kind stays in lockstep. */
+export const UPLOAD_KINDS = ['video', 'project', 'captions', 'thumbnail'];
+/**
+ * Coerce a raw metadata/sidecar `kind` string to a known `UploadKind`, defaulting to `"video"`
+ * (so pre-`kind` clients and older sidecars keep working). Use this everywhere a kind is parsed —
+ * do NOT hand-write per-kind ternaries, which drift out of sync when a kind is added.
+ */
+export function parseUploadKind(raw) {
+    const lower = (raw ?? '').trim().toLowerCase();
+    return UPLOAD_KINDS.includes(lower) ? lower : 'video';
+}
 //# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AA4BA;;uCAEuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAU,CAAC;AAInF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/F,CAAC"}