@mieweb/pulsevault 0.0.2 → 0.1.1

package/dist/lib/magic.js

@@ -1,4 +1,4 @@
-import fs from "node:fs/promises";
+import fs from 'node:fs/promises';
 /**
  * Check whether a file's first bytes match the ISO base media file format
  * (`ftyp` box at offset 4), which covers MP4, MOV, M4V, 3GP, and related
@@ -12,7 +12,7 @@ import fs from "node:fs/promises";
 export async function sniffMp4(filePath) {
     let fd;
     try {
-        fd = await fs.open(filePath, "r");
+        fd = await fs.open(filePath, 'r');
     }
     catch {
         return false;
@@ -22,19 +22,23 @@ export async function sniffMp4(filePath) {
         const { bytesRead } = await fd.read(buf, 0, 12, 0);
         if (bytesRead < 12)
             return false;
-        // Bytes 4..7 must spell "ftyp" (ASCII 0x66 0x74 0x79 0x70). The first
-        // four bytes are the box size and the remaining four after "ftyp" are
-        // the brand (e.g. "isom", "mp42", "qt  ") — brand validation is left
-        // to downstream tools.
-        return (buf[4] === 0x66 &&
-            buf[5] === 0x74 &&
-            buf[6] === 0x79 &&
-            buf[7] === 0x70);
+        return hasFtypBox(buf);
     }
     finally {
         await fd.close();
     }
 }
+/**
+ * Whether a buffer's first 12 bytes carry an ISO base media `ftyp` box.
+ * Bytes 4..7 must spell "ftyp" (ASCII 0x66 0x74 0x79 0x70). The first four
+ * bytes are the box size and the four after "ftyp" are the brand (e.g.
+ * "isom", "mp42", "qt  ") — brand validation is left to downstream tools.
+ */
+function hasFtypBox(buf) {
+    if (buf.length < 12)
+        return false;
+    return buf[4] === 0x66 && buf[5] === 0x74 && buf[6] === 0x79 && buf[7] === 0x70;
+}
 /**
  * Build a `validatePayload` hook that enforces every uploaded file is a
  * valid MP4-family container. Only works with `LocalStorage` (or any
@@ -52,14 +56,47 @@ export async function sniffMp4(filePath) {
  * ```
  */
 export function createMp4Sniffer(storage) {
-    return async (_request, { videoid }) => {
-        const localPath = await storage.getLocalPath(videoid);
+    return async (_request, { artifactId }) => {
+        const localPath = await storage.getLocalPath(artifactId);
         if (!localPath) {
-            throw Object.assign(new Error(`Cannot validate upload ${videoid}: no local path available`), { statusCode: 500 });
+            throw Object.assign(new Error(`Cannot validate upload ${artifactId}: no local path available`), { statusCode: 500 });
         }
         const ok = await sniffMp4(localPath);
         if (!ok) {
-            throw Object.assign(new Error("Uploaded bytes are not a valid MP4 (missing ftyp header)"), { statusCode: 422 });
+            throw Object.assign(new Error('Uploaded bytes are not a valid MP4 (missing ftyp header)'), {
+                statusCode: 422,
+            });
+        }
+    };
+}
+/**
+ * `createMp4Sniffer` for the S3 / R2 backend. Instead of opening a local file,
+ * it asks the adapter for the first 12 bytes of the finalized object via a
+ * small ranged GET (`S3Storage.readHeader`) and applies the same `ftyp` check.
+ * Runs in the same lifecycle slot — after `@tus/s3-store` completes the
+ * multipart upload (so the object is readable) but before `markReady` — so a
+ * non-MP4 upload is removed and never served.
+ *
+ * Usage:
+ * ```ts
+ * const storage = await createS3Storage({ ... });
+ * await app.register(pulseVault, {
+ *   storage,
+ *   validatePayload: createS3Mp4Sniffer(storage),
+ *   // ...
+ * });
+ * ```
+ */
+export function createS3Mp4Sniffer(storage) {
+    return async (_request, { artifactId }) => {
+        const header = await storage.readHeader(artifactId, 12);
+        if (!header) {
+            throw Object.assign(new Error(`Cannot validate upload ${artifactId}: no object bytes available`), { statusCode: 500 });
+        }
+        if (!hasFtypBox(header)) {
+            throw Object.assign(new Error('Uploaded bytes are not a valid MP4 (missing ftyp header)'), {
+                statusCode: 422,
+            });
         }
     };
 }

package/dist/lib/magic.js.map

@@ -1 +1 @@
-{"version":3,"file":"magic.js","sourceRoot":"","sources":["../../src/lib/magic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AA2BlC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,EAAiB,CAAC;IACtB,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACnD,IAAI,SAAS,GAAG,EAAE;YAAE,OAAO,KAAK,CAAC;QACjC,sEAAsE;QACtE,sEAAsE;QACtE,qEAAqE;QACrE,uBAAuB;QACvB,OAAO,CACL,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;YACf,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAChB,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAqB;IAErB,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACrC,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CACP,0BAA0B,OAAO,2BAA2B,CAC7D,EACD,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CAAC,0DAA0D,CAAC,EACrE,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"magic.js","sourceRoot":"","sources":["../../src/lib/magic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAiClC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,EAAiB,CAAC;IACtB,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACnD,IAAI,SAAS,GAAG,EAAE;YAAE,OAAO,KAAK,CAAC;QACjC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;QACxC,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QACzD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CAAC,0BAA0B,UAAU,2BAA2B,CAAC,EAC1E,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,0DAA0D,CAAC,EAAE;gBACzF,UAAU,EAAE,GAAG;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAkB;IACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CAAC,0BAA0B,UAAU,6BAA6B,CAAC,EAC5E,EAAE,UAAU,EAAE,GAAG,EAAE,CACpB,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,0DAA0D,CAAC,EAAE;gBACzF,UAAU,EAAE,GAAG;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/options.d.ts

@@ -0,0 +1,41 @@
+import type { PulseVaultValidatePayload } from './magic.js';
+import type { PulseVaultOnUploadComplete } from './pulsevaultTus.js';
+/** Per-kind form of `PulseVaultAllowedExtensionsInput`, named once so it isn't re-declared at every use site. */
+type AllowedExtensionsByKind = {
+    video?: readonly string[];
+    project?: readonly string[];
+    captions?: readonly string[];
+    thumbnail?: readonly string[];
+};
+export type PulseVaultAllowedExtensionsInput = readonly string[] | AllowedExtensionsByKind;
+export type PulseVaultAllowedExtensions = {
+    video: readonly string[];
+    project: readonly string[];
+    captions: readonly string[];
+    thumbnail: readonly string[];
+};
+/**
+ * Normalize the consumer's `allowedExtensions` option (legacy array or per-kind
+ * object) into the canonical `{ video, project, captions }` shape both
+ * adapters pass down to the tus layer.
+ */
+export declare function normalizeAllowedExtensions(raw: PulseVaultAllowedExtensionsInput | undefined): PulseVaultAllowedExtensions;
+/** Shared by the Fastify plugin's `prefix` and the core's `basePath` — same shape, different option name. */
+export declare function validateBasePath(basePath: string, optionName: string): void;
+export declare function validateMaxUploadSize(maxUploadSize: number): void;
+export declare function validateUploadUnit(uploadUnit: 'segment' | 'merged' | undefined): void;
+export declare function validateAllowedExtensions(allowedExtensions: PulseVaultAllowedExtensionsInput | undefined): void;
+/**
+ * One-time (not per-request) warning for the now-deprecated per-kind project
+ * hooks, so consumers notice the migration need instead of it being silently
+ * aliased away until a future major version removes it outright.
+ */
+export declare function warnIfUsingDeprecatedProjectHooks(opts: {
+    validateProjectPayload?: unknown;
+    onProjectUploadComplete?: unknown;
+}): void;
+/** Compose the legacy per-kind hook (if any) with the generic hook, mapped onto the `"project"` kind only. */
+export declare function composeValidatePayload(generic: PulseVaultValidatePayload | undefined, legacyProject: PulseVaultValidatePayload | undefined): PulseVaultValidatePayload | undefined;
+export declare function composeOnUploadComplete(generic: PulseVaultOnUploadComplete | undefined, legacyProject: PulseVaultOnUploadComplete | undefined): PulseVaultOnUploadComplete | undefined;
+export {};
+//# sourceMappingURL=options.d.ts.map

package/dist/lib/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/lib/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAErE,iHAAiH;AACjH,KAAK,uBAAuB,GAAG;IAC7B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG,SAAS,MAAM,EAAE,GAAG,uBAAuB,CAAC;AAE3F,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAWF;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,gCAAgC,GAAG,SAAS,GAChD,2BAA2B,CAyB7B;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAIjE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAIrF;AAED,wBAAgB,yBAAyB,CACvC,iBAAiB,EAAE,gCAAgC,GAAG,SAAS,GAC9D,IAAI,CAiBN;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC,GAAG,IAAI,CAaP;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,GAAG,SAAS,EAC9C,aAAa,EAAE,yBAAyB,GAAG,SAAS,GACnD,yBAAyB,GAAG,SAAS,CASvC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,aAAa,EAAE,0BAA0B,GAAG,SAAS,GACpD,0BAA0B,GAAG,SAAS,CASxC"}

package/dist/lib/options.js

@@ -0,0 +1,111 @@
+const DEFAULT_VIDEO_EXTENSIONS = ['.mp4'];
+const DEFAULT_PROJECT_EXTENSIONS = ['.pulse', '.zip'];
+// WebVTT only — it's what the Pulse app uploads, and it carries word-level
+// inline cue timestamps (`<00:00:01.500>word`) for karaoke rendering.
+const DEFAULT_CAPTIONS_EXTENSIONS = ['.vtt'];
+// The merged-mode poster frame (the draft's first-clip thumbnail).
+const DEFAULT_THUMBNAIL_EXTENSIONS = ['.jpg', '.jpeg', '.png'];
+const EXTENSION_REGEX = /^\.[^.\s/\\]+$/;
+/**
+ * Normalize the consumer's `allowedExtensions` option (legacy array or per-kind
+ * object) into the canonical `{ video, project, captions }` shape both
+ * adapters pass down to the tus layer.
+ */
+export function normalizeAllowedExtensions(raw) {
+    if (!raw) {
+        return {
+            video: DEFAULT_VIDEO_EXTENSIONS,
+            project: DEFAULT_PROJECT_EXTENSIONS,
+            captions: DEFAULT_CAPTIONS_EXTENSIONS,
+            thumbnail: DEFAULT_THUMBNAIL_EXTENSIONS,
+        };
+    }
+    if (Array.isArray(raw)) {
+        // Legacy flat array: treat as video-only, project/captions/thumbnail keep their defaults.
+        return {
+            video: raw.map((ext) => ext.toLowerCase()),
+            project: DEFAULT_PROJECT_EXTENSIONS,
+            captions: DEFAULT_CAPTIONS_EXTENSIONS,
+            thumbnail: DEFAULT_THUMBNAIL_EXTENSIONS,
+        };
+    }
+    const byKind = raw;
+    return {
+        video: (byKind.video ?? DEFAULT_VIDEO_EXTENSIONS).map((ext) => ext.toLowerCase()),
+        project: (byKind.project ?? DEFAULT_PROJECT_EXTENSIONS).map((ext) => ext.toLowerCase()),
+        captions: (byKind.captions ?? DEFAULT_CAPTIONS_EXTENSIONS).map((ext) => ext.toLowerCase()),
+        thumbnail: (byKind.thumbnail ?? DEFAULT_THUMBNAIL_EXTENSIONS).map((ext) => ext.toLowerCase()),
+    };
+}
+/** Shared by the Fastify plugin's `prefix` and the core's `basePath` — same shape, different option name. */
+export function validateBasePath(basePath, optionName) {
+    if (basePath !== '' && (!basePath.startsWith('/') || basePath.endsWith('/'))) {
+        throw new TypeError(`\`${optionName}\` must be '' or start with '/' with no trailing slash (e.g. '/pulsevault')`);
+    }
+}
+export function validateMaxUploadSize(maxUploadSize) {
+    if (!(maxUploadSize > 0)) {
+        throw new TypeError('`maxUploadSize` must be a positive number (use Infinity for no cap)');
+    }
+}
+export function validateUploadUnit(uploadUnit) {
+    if (uploadUnit && uploadUnit !== 'segment' && uploadUnit !== 'merged') {
+        throw new TypeError('`uploadUnit` must be "segment" or "merged"');
+    }
+}
+export function validateAllowedExtensions(allowedExtensions) {
+    if (!allowedExtensions)
+        return;
+    const exts = Array.isArray(allowedExtensions)
+        ? allowedExtensions
+        : [
+            ...(allowedExtensions.video ?? []),
+            ...(allowedExtensions.project ?? []),
+            ...(allowedExtensions.captions ?? []),
+            ...(allowedExtensions.thumbnail ?? []),
+        ];
+    for (const ext of exts) {
+        if (!EXTENSION_REGEX.test(ext)) {
+            throw new TypeError(`\`allowedExtensions\` entry ${JSON.stringify(ext)} must start with '.' and contain no nested dots, slashes, or whitespace (e.g. '.mp4')`);
+        }
+    }
+}
+/**
+ * One-time (not per-request) warning for the now-deprecated per-kind project
+ * hooks, so consumers notice the migration need instead of it being silently
+ * aliased away until a future major version removes it outright.
+ */
+export function warnIfUsingDeprecatedProjectHooks(opts) {
+    if (opts.validateProjectPayload) {
+        process.emitWarning('pulsevault: `validateProjectPayload` is deprecated — use `validatePayload` and branch on `ctx.kind === "project"` instead. Still honored this release.', 'DeprecationWarning');
+    }
+    if (opts.onProjectUploadComplete) {
+        process.emitWarning('pulsevault: `onProjectUploadComplete` is deprecated — use `onUploadComplete` and branch on `ctx.kind === "project"` instead. Still honored this release.', 'DeprecationWarning');
+    }
+}
+/** Compose the legacy per-kind hook (if any) with the generic hook, mapped onto the `"project"` kind only. */
+export function composeValidatePayload(generic, legacyProject) {
+    if (!legacyProject)
+        return generic;
+    return async (request, ctx) => {
+        if (ctx.kind === 'project') {
+            await legacyProject(request, ctx);
+            return;
+        }
+        if (generic)
+            await generic(request, ctx);
+    };
+}
+export function composeOnUploadComplete(generic, legacyProject) {
+    if (!legacyProject)
+        return generic;
+    return async (request, ctx) => {
+        if (ctx.kind === 'project') {
+            await legacyProject(request, ctx);
+            return;
+        }
+        if (generic)
+            await generic(request, ctx);
+    };
+}
+//# sourceMappingURL=options.js.map

package/dist/lib/options.js.map

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

package/dist/lib/pulsevaultTus.d.ts

@@ -1,23 +1,45 @@
-import { Server } from "@tus/server";
-import type { FastifyRequest } from "fastify";
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { PulseVaultValidatePayload } from "./magic.js";
-import type { PulseVaultStorage } from "../storage/types.js";
+import { Server } from '@tus/server';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { PulseVaultValidatePayload } from './magic.js';
+import { type PulseVaultRequest, type PulseVaultLogger } from './request.js';
+import type { PulseVaultStorage } from '../storage/types.js';
+import type { UploadKind } from '../storage/types.js';
 /**
- * Context the plugin stashes on each incoming Fastify request for the lifetime
- * of a TUS call. Shared with the tus hooks via `AsyncLocalStorage` because
- * `@tus/server` v2 hooks receive a web `Request`, not the FastifyRequest.
+ * Context the plugin stashes on each incoming request for the lifetime of a
+ * TUS call. Shared with the tus hooks via `AsyncLocalStorage` because
+ * `@tus/server` v2 hooks receive a raw `req`/`res`, not the host's request
+ * wrapper (Fastify's `FastifyRequest`, Express's `req`, etc.).
  */
 export type PulseVaultTusContext = {
-    request: FastifyRequest;
-    videoid?: string;
+    request: PulseVaultRequest;
+    artifactId?: string;
+    /** Kind resolved during TUS create; available on the same request only. */
+    kind?: UploadKind;
+    /** `relatedTo` resolved during TUS create; available on the same request only. */
+    relatedTo?: string;
+    /** Raw `checksum` metadata value (`<algorithm>:<hex>`), if the client sent one. */
+    checksum?: string;
 };
 export declare const pulseVaultTusContext: AsyncLocalStorage<PulseVaultTusContext>;
-export type PulseVaultOnUploadComplete = (request: FastifyRequest, ctx: {
-    videoid: string;
+export type PulseVaultOnUploadComplete = (request: PulseVaultRequest, ctx: {
+    artifactId: string;
+    kind: UploadKind;
     size: number;
     uploadId: string;
 }) => void | Promise<void>;
+/**
+ * Fired at low-frequency, audit-worthy moments — never per chunk — so an
+ * operator can wire one hook to get both ops metrics and a compliance audit
+ * trail without hand-rolling both from the lower-level hooks.
+ */
+export type PulseVaultArtifactEvent = {
+    phase: 'authorize' | 'complete' | 'reject';
+    artifactId: string;
+    kind: UploadKind;
+    size?: number;
+    reason?: string;
+};
+export type PulseVaultOnArtifactEvent = (event: PulseVaultArtifactEvent) => void | Promise<void>;
 export type PulsevaultTusOptions = {
     storage: PulseVaultStorage;
     /** Absolute URL path where TUS is mounted, e.g. `/pulsevault/upload`. */
@@ -25,25 +47,28 @@ export type PulsevaultTusOptions = {
     /** Max total upload size in bytes. Use `Infinity` for no cap. */
     maxSize: number;
     /**
-     * File extensions allowed in the upload `filename` metadata. Must be
-     * pre-normalized to lowercase and include the leading dot.
+     * Allowed extensions per kind. Must be pre-normalized to lowercase and
+     * include the leading dot.
      */
-    allowedExtensions: readonly string[];
+    allowedExtensions: {
+        video: readonly string[];
+        project: readonly string[];
+        captions: readonly string[];
+        thumbnail: readonly string[];
+    };
     /**
-     * Optional payload-validation hook. Runs after TUS writes the final byte
-     * but before `markReady` and `onUploadComplete`. Throwing from this hook
-     * causes the plugin to `storage.remove?.(videoid)` and return a 4xx
-     * (default 422) to the client. Use for magic-byte sniffing, virus
-     * scanning, size re-checks — anything that needs the final bytes.
+     * Optional payload-validation hook, called for every kind with `ctx.kind`
+     * set accordingly. Runs after TUS writes the final byte but before
+     * `markReady` and `onUploadComplete`. Throwing causes
+     * `storage.remove?.(artifactId)` and a 4xx (default 422).
      */
     validatePayload?: PulseVaultValidatePayload;
-    /**
-     * Fired once the final byte of an upload has been written *and* any
-     * `validatePayload` has passed. Use this to flip consumer state (DB row,
-     * queue job, audit log). Throwing here returns a 500 — bytes are on disk
-     * and marked ready, but consumer-side work failed.
-     */
+    /** Fired once the final byte has been written and any `validatePayload` has passed, for every kind. */
     onUploadComplete?: PulseVaultOnUploadComplete;
+    /** See `PulseVaultOnArtifactEvent`. */
+    onArtifactEvent?: PulseVaultOnArtifactEvent;
+    /** Logger for internal diagnostics (cleanup failures, etc). Defaults to `console`. */
+    logger?: PulseVaultLogger;
 };
 /**
  * Shape `@tus/server` recognizes for sending an error response. We tag both
@@ -52,5 +77,7 @@ export type PulsevaultTusOptions = {
  * right HTTP status.
  */
 export declare function tusError(status: number, body: string): Error;
+/** Parse the artifactId UUID from a tus upload id of the form `<kind>/<artifactId><ext>`. */
+export declare function artifactIdFromUploadId(id: string): string | undefined;
 export declare function createPulsevaultTusServer(options: PulsevaultTusOptions): Server;
 //# sourceMappingURL=pulsevaultTus.d.ts.map

package/dist/lib/pulsevaultTus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pulsevaultTus.d.ts","sourceRoot":"","sources":["../../src/lib/pulsevaultTus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAElF,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KACrD,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAM5D;AAmBD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,UAyHtE"}
+{"version":3,"file":"pulsevaultTus.d.ts","sourceRoot":"","sources":["../../src/lib/pulsevaultTus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAiB,MAAM,cAAc,CAAC;AAC5F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,oBAAoB,yCAAgD,CAAC;AAElF,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KAC1E,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjG,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,EAAE;QACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;KAC9B,CAAC;IACF;;;;;OAKG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;IAC9C,uCAAuC;IACvC,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,sFAAsF;IACtF,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAM5D;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrE;AAoCD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,UA8JtE"}