@mieweb/pulsevault 0.0.1

package/LICENSE

@@ -0,0 +1,45 @@
+@mieweb/pulsevault - Source Available License
+
+Copyright (c) 2026 Medical Informatics Engineering, LLC. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of Medical Informatics Engineering, LLC. ("MIE").
+
+OPEN SOURCE / NON-COMMERCIAL USE
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of this Software, to use, copy, modify, merge, and distribute
+the Software for non-commercial purposes, subject to the following conditions:
+
+1. Attribution Required: The above copyright notice, this permission notice,
+   and clear attribution to Medical Informatics Engineering, LLC. shall be
+   included in all copies or substantial portions of the Software.
+
+2. Open Source Requirement: If you distribute the Software or any derivative
+   works, you must do so under an open source license approved by the Open
+   Source Initiative (OSI) and make the source code publicly available.
+
+3. Non-Commercial Use Only: This license does not grant permission to use the
+   Software for commercial purposes. "Commercial purposes" means any use
+   intended for or directed toward commercial advantage or monetary
+   compensation.
+
+COMMERCIAL USE
+
+For commercial use, including but not limited to:
+- Use in proprietary/closed-source products
+- Use in products or services sold for profit
+- Use by for-profit organizations for internal business operations
+
+You must obtain a separate commercial license from Medical Informatics
+Engineering, LLC. Contact: https://www.mieweb.com or helpdesk@mieweb.com
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+MEDICAL INFORMATICS ENGINEERING, LLC. OR ITS AFFILIATES BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# @mieweb/pulsevault
+
+Fastify plugin for resumable video uploads via the [TUS protocol](https://tus.io/), with filesystem-first local storage and deep link helpers for the [Pulse](https://github.com/mieweb/pulse) mobile app.
+
+```text
+    Pulse app                   Your Fastify app
+    ─────────                   ────────────────
+
+   ┌───────────┐    pair +    ┌──────────────────────┐
+   │ iOS / web │ ─── TUS ───► │  Pulsevault plugin   │
+   └───────────┘              │  POST  /upload       │
+                              │  PATCH /upload/:id   │
+                              │  GET   /:videoid     │
+                              └──────────┬───────────┘
+                                         │
+                                         ▼
+                              ┌──────────────────────┐
+                              │  Your hooks          │
+                              │  • authorize         │
+                              │  • validatePayload   │
+                              │  • onUploadComplete  │
+                              └──┬─────────────────┬─┘
+                                 │                 │
+                                 ▼                 ▼
+                          ┌──────────────┐  ┌──────────────┐
+                          │   Storage    │  │ Your systems │
+                          │   adapter    │  │  DB · SSO ·  │
+                          │ local / S3 / │  │  audit logs  │
+                          │ GCS / custom │  │  pipelines   │
+                          └──────────────┘  └──────────────┘
+```
+
+Self-hosted video capture for places that can't ship recordings to a vendor. Pulse records the walkthrough on the phone; Pulsevault receives it inside the Fastify app you already run, behind your auth, on your storage. Pair a device by QR code and upload over TUS so two-minute captures from the floor survive signal drops and device restarts.
+
+Hook in at `authorize`, `validatePayload`, or `onUploadComplete` to bolt on whatever your institution already runs — SSO, audit logs, transcoding queues, AI pipelines. The plugin mounts three routes; the rest stays yours.
+
+The local storage adapter writes to a stable on-disk layout (see [Local storage](#local-storage)) so you can layer post-processing — transcription, thumbnails, AI analysis — directly against the files from an `onUploadComplete` hook.
+
+## Requirements
+
+- Fastify `^5.x`
+- Node.js `>=18`
+
+## Installation
+
+```sh
+npm install @mieweb/pulsevault
+```
+
+## Quick start
+
+```ts
+import Fastify from "fastify";
+import { randomUUID } from "node:crypto";
+import pulseVault, { createLocalStorage } from "@mieweb/pulsevault";
+
+const app = Fastify();
+
+await app.register(pulseVault, {
+  prefix: "",
+  storage: createLocalStorage({ workspaceDir: "./data" }),
+  maxUploadSize: 5 * 1024 * 1024 * 1024, // 5 GiB
+});
+
+// Your server owns videoid creation — attach auth, DB records, quotas here.
+app.post("/reserve", async (_req, reply) => {
+  return reply.send({ videoid: randomUUID() });
+});
+
+await app.listen({ port: 3030 });
+```
+
+## Routes
+
+The plugin mounts the following routes under `prefix`:
+
+| Method                         | Path          | Description                                      |
+| ------------------------------ | ------------- | ------------------------------------------------ |
+| `POST`                         | `/upload`     | Create a TUS upload session                      |
+| `PATCH` / `HEAD` / `DELETE` \* | `/upload/:id` | Upload chunks, probe offset, cancel upload (TUS) |
+| `GET`                          | `/:videoid`   | Stream or redirect to the uploaded video         |
+| `DELETE`                       | `/:videoid`   | Delete a finalized upload (bytes + sidecar)      |
+
+\* `DELETE /upload/:id` is TUS's own "cancel in-flight upload" — distinct from `DELETE /:videoid`, which removes a finalized video.
+
+> `POST /reserve` is **not** part of the plugin. Your server implements it so you control auth, ownership, and any business logic tied to video creation.
+
+`GET /:videoid` only serves uploads whose adapter has been told to mark them ready. With the built-in local adapter, that means the final PATCH has landed _and_ `validatePayload` (if configured) accepted the bytes. In-progress uploads return 404.
+
+## Plugin options
+
+```ts
+type PulseVaultPluginOptions = {
+  storage: PulseVaultStorage;
+  prefix: string;
+  maxUploadSize: number;
+  decoratorName?: string; // default: "pulseVault"
+  allowedExtensions?: string[]; // default: [".mp4"]
+  cache?: PulseVaultCacheOptions;
+  authorize?: PulseVaultAuthorize;
+  validatePayload?: PulseVaultValidatePayload;
+  onUploadComplete?: PulseVaultOnUploadComplete;
+};
+```
+
+### `storage`
+
+A `PulseVaultStorage` adapter. Use the built-in `createLocalStorage` for filesystem-backed deployments (the blessed default) or implement the interface for custom backends (S3, GCS, etc.).
+
+### `prefix`
+
+URL prefix for all plugin routes. Use `""` to mount at the root or `"/pulsevault"` to namespace. Must start with `/` (no trailing slash) or be `""`.
+
+> Because the plugin uses `fastify-plugin` to escape encapsulation, Fastify's native `register(..., { prefix })` is a no-op — always pass `prefix` through this option.
+
+### `maxUploadSize`
+
+Maximum upload size in bytes. Use `Infinity` for no cap.
+
+### `decoratorName`
+
+Name of the Fastify decorator that exposes the storage adapter on the instance. Defaults to `"pulseVault"`. Override when registering the plugin more than once in the same process.
+
+For TypeScript access to the default decorator, add a side-effect import once in your app:
+
+```ts
+import "@mieweb/pulsevault/augment";
+```
+
+### `allowedExtensions`
+
+File extensions accepted in `Upload-Metadata.filename`. Must include the leading dot. Defaults to `[".mp4"]`.
+
+### `cache`
+
+Cache-control options for the `GET /:videoid` route, forwarded to `@fastify/send`:
+
+```ts
+type PulseVaultCacheOptions = {
+  cacheControl?: boolean; // default: true
+  maxAge?: string | number; // ms or ms-style string e.g. "1y". default: 0
+  immutable?: boolean; // requires maxAge > 0. default: false
+};
+```
+
+Upload filenames are keyed by UUID, so `immutable: true` is safe when `maxAge` is non-zero.
+
+### `authorize`
+
+Optional async hook called before TUS create/patch, before GET resolve, and before DELETE. Throw to reject — a `statusCode` or `status_code` number on the thrown error is used as the HTTP status (default `403`).
+
+```ts
+type PulseVaultAuthorize = (
+  request: FastifyRequest,
+  ctx: {
+    phase: "create" | "patch" | "resolve" | "delete";
+    videoid: string;
+  },
+) => void | Promise<void>;
+```
+
+```ts
+await app.register(pulseVault, {
+  // ...
+  authorize: async (request, { phase, videoid }) => {
+    const token = request.headers.authorization?.replace("Bearer ", "");
+    if (!isValid(token, videoid)) {
+      throw Object.assign(new Error("Forbidden"), { statusCode: 403 });
+    }
+  },
+});
+```
+
+### `validatePayload`
+
+Optional async hook that runs _after_ TUS writes the final byte but _before_ the upload is marked ready or `onUploadComplete` fires. Throw to reject — the plugin calls `storage.remove` to free the bytes and returns a 4xx (default 422) to the client. The sidecar never flips to `"ready"`, so the video is never served.
+
+```ts
+type PulseVaultValidatePayload = (
+  request: FastifyRequest,
+  ctx: {
+    videoid: string;
+    size: number;
+    uploadId: string;
+    /** Absolute path to finalized bytes for adapters that expose `getLocalPath`. */
+    localPath: string | null;
+  },
+) => void | Promise<void>;
+```
+
+Use for magic-byte sniffing, virus scanning, size re-checks — anything that needs the final bytes. A ready-made helper ships with the package:
+
+```ts
+import pulseVault, {
+  createLocalStorage,
+  createMp4Sniffer,
+} from "@mieweb/pulsevault";
+
+const storage = createLocalStorage({ workspaceDir: "./data" });
+
+await app.register(pulseVault, {
+  // ...
+  storage,
+  validatePayload: createMp4Sniffer(storage),
+});
+```
+
+`createMp4Sniffer` reads the first 12 bytes and verifies the ISOBMFF `ftyp` header (MP4, MOV, M4V, 3GP). Uploads that pass the extension check but contain non-video bytes are rejected with 422 and the disk is cleaned up.
+
+The lower-level `sniffMp4(path)` is also exported if you want to drive your own validator.
+
+### `onUploadComplete`
+
+Optional async hook fired once the final byte is written, `validatePayload` has passed, and the sidecar has been marked ready. Use it to update a database row, enqueue a job, or write an audit log. Throwing returns a `500` to the client. The video is ready at this point — if you want all-or-nothing semantics, call `storage.remove` before throwing.
+
+```ts
+type PulseVaultOnUploadComplete = (
+  request: FastifyRequest,
+  ctx: { videoid: string; size: number; uploadId: string },
+) => void | Promise<void>;
+```
+
+### Upload-complete sequencing
+
+When the final PATCH lands, the plugin runs the following in order. Any step failing short-circuits the rest.
+
+1. **`validatePayload`** (optional) — throws → `storage.remove(videoid)`, HTTP 4xx (default 422).
+2. **`storage.markReady(videoid)`** — flips the sidecar so `resolve()` will serve the bytes.
+3. **`onUploadComplete`** (optional) — throws → HTTP 500; bytes remain on disk and ready unless the consumer explicitly removes them.
+
+## Local storage
+
+```ts
+import { createLocalStorage } from "@mieweb/pulsevault";
+
+const storage = createLocalStorage({
+  workspaceDir: "./data", // directory for uploads; created if absent
+});
+```
+
+### Filesystem layout (stable contract)
+
+The local adapter writes each upload into a self-describing per-video directory. Downstream tools may rely on this layout across minor versions:
+
+```text
+<workspaceRoot>/<videoid>/
+  .pulsevault.json           # sidecar: { version, ext, filename, status }
+  video/<videoid><ext>       # upload bytes (partial during upload, full when ready)
+  video/<videoid><ext>.json  # @tus/file-store's offset/metadata sidecar
+```
+
+`status` is `"uploading"` between `reserveUpload` and the successful final PATCH; `"ready"` thereafter. `GET /:videoid` only serves `"ready"` uploads.
+
+The adapter exposes `storage.workspaceRoot` (absolute, resolved from `workspaceDir`) so consumers can compute per-video paths without re-implementing the layout.
+
+### Post-processing (transcription, thumbnails, AI)
+
+The filesystem layout is the integration surface. Use the `onUploadComplete` hook as your trigger. For example, to hydrate an [ArtiPod](https://github.com/mieweb/artipod) with the video plus sibling artifact directories:
+
+```ts
+import path from "node:path";
+import { ArtiPod, ArtiMount } from "@mieweb/artipod";
+import pulseVault, { createLocalStorage } from "@mieweb/pulsevault";
+
+const storage = createLocalStorage({ workspaceDir: "./data" });
+
+await app.register(pulseVault, {
+  prefix: "",
+  storage,
+  maxUploadSize: 5 * 1024 * 1024 * 1024,
+  onUploadComplete: async (_req, { videoid }) => {
+    const root = path.join(storage.workspaceRoot, videoid);
+    const pod = new ArtiPod({ id: videoid, useMainMount: false });
+    pod.addMount(new ArtiMount("video", path.join(root, "video")));
+    // Create these lazily as your pipeline produces artifacts:
+    // pod.addMount(new ArtiMount("transcripts", path.join(root, "transcripts")));
+    // pod.addMount(new ArtiMount("frames", path.join(root, "frames")));
+    await pod.initialize();
+    // Run a containerized transcription step, build an LLM prompt from
+    // collected artifacts, etc. See the @mieweb/artipod docs for details.
+  },
+});
+```
+
+`@mieweb/artipod` is **not** a dependency of this plugin — install it in your app only if you want it. Any filesystem-native pipeline (ffmpeg, whisper, rsync) works equally well.
+
+## Custom storage adapter
+
+Implement `PulseVaultStorage` to back uploads with any system (S3, GCS, database, etc.):
+
+```ts
+import type {
+  PulseVaultStorage,
+  PulseVaultResolution,
+} from "@mieweb/pulsevault";
+
+const storage: PulseVaultStorage = {
+  datastore, // @tus/server DataStore instance
+  async initialize() {
+    /* optional setup */
+  },
+  async shutdown() {
+    /* optional teardown */
+  },
+  async reserveUpload({ videoid, filename, ext }) {
+    // Called by the TUS naming function. Return the file id for the datastore.
+    await db.createVideo({ videoid, filename, status: "uploading" });
+    return `${videoid}${ext}`;
+  },
+  async resolve(videoid): Promise<PulseVaultResolution | null> {
+    const video = await db.findVideo(videoid);
+    if (!video || video.status !== "ready") return null;
+    // Stream from local disk:
+    return { kind: "stream", root: "/uploads", filename: video.filename };
+    // Or redirect to a CDN / presigned URL:
+    // return { kind: "redirect", url: video.signedUrl, statusCode: 302 };
+  },
+  async markReady(videoid) {
+    // Called after `validatePayload` (if any) accepts the bytes. Flip your
+    // state so `resolve` starts returning non-null. Omit this method if
+    // your backend can't distinguish in-progress from finalized uploads.
+    await db.updateVideo(videoid, { status: "ready" });
+  },
+  async remove(videoid) {
+    // Called from DELETE /:videoid and from the plugin's cleanup path when
+    // `validatePayload` rejects an upload. Return false if the videoid was
+    // already absent.
+    const result = await db.deleteVideo(videoid);
+    return result.deleted;
+  },
+};
+```
+
+## Deep link helpers
+
+Use these to generate `pulsecam://` deep links for pairing the Pulse mobile app with your server. Typically encoded as QR codes on a pairing page.
+
+```ts
+import {
+  buildConfigureDestinationLink,
+  buildUploadLink,
+} from "@mieweb/pulsevault";
+import { randomUUID } from "node:crypto";
+
+// Adds this server as a saved destination in the Pulse app.
+const configureLink = buildConfigureDestinationLink({
+  server: "https://example.com",
+  name: "My Server", // optional — shown in the app's destination list
+  token: "secret", // optional — forwarded to your authorize hook
+});
+
+// Opens the app directly on the upload screen for a specific video.
+const uploadLink = buildUploadLink({
+  server: "https://example.com",
+  videoid: randomUUID(), // generate server-side; skip POST /reserve on the app
+  token: "secret", // optional
+});
+```
+
+## Tests
+
+```sh
+npm test
+```
+
+Runs a Node `--test` suite against the built plugin: TUS create/HEAD/PATCH resume, collision handling, extension rejection, range GETs, the ready-gate (`GET` returns 404 while uploading), `DELETE /:videoid`, `authorize` rejection on every phase, `validatePayload` + `createMp4Sniffer`, `onUploadComplete` dispatch, and sidecar corruption recovery.
+
+## Accessing storage outside the plugin routes
+
+The storage adapter is exposed as a Fastify decorator, so you can use it in your own routes:
+
+```ts
+import "@mieweb/pulsevault/augment"; // once, for TypeScript types
+
+app.get("/admin/video/:id", async (req, reply) => {
+  const resolved = await app.pulseVault.resolve(req.params.id);
+  if (!resolved) return reply.code(404).send();
+  // custom logic...
+});
+```
+
+## License
+
+Source Available — free for non-commercial use under the terms in [LICENSE](LICENSE), which also requires that redistributions be published under an OSI-approved open source license. Commercial use requires a separate license from Medical Informatics Engineering, LLC — contact [helpdesk@mieweb.com](mailto:helpdesk@mieweb.com) or [mieweb.com](https://www.mieweb.com).
+
+Copyright © 2026 Medical Informatics Engineering, LLC. All rights reserved.

package/dist/app.d.ts

@@ -0,0 +1,114 @@
+import type { FastifyPluginAsync } from "fastify";
+import { type PulseVaultAuthorize } from "./routes/pulsevault.js";
+import type { PulseVaultOnUploadComplete } from "./lib/pulsevaultTus.js";
+import type { PulseVaultValidatePayload } from "./lib/magic.js";
+import type { PulseVaultStorage } from "./storage/types.js";
+/**
+ * Subset of `@fastify/send`'s cache-related options forwarded to the GET
+ * route. All upload filenames are content-addressable (keyed by the upload
+ * UUID), so `immutable: true` is safe whenever you also set a non-zero
+ * `maxAge`.
+ */
+export type PulseVaultCacheOptions = {
+    /** Enable the `Cache-Control` response header. Defaults to `true`. */
+    cacheControl?: boolean;
+    /**
+     * `max-age` for the `Cache-Control` header. Accepts a number of
+     * milliseconds or an `ms`-style string such as `"1y"`. Defaults to `0`.
+     */
+    maxAge?: string | number;
+    /**
+     * Add the `immutable` directive to `Cache-Control`. Requires `maxAge > 0`
+     * to take effect. Defaults to `false`.
+     */
+    immutable?: boolean;
+};
+export type PulseVaultPluginOptions = {
+    /** Storage adapter. Use `createLocalStorage(...)` for filesystem-backed deployments. */
+    storage: PulseVaultStorage;
+    /**
+     * URL prefix where the plugin's routes are mounted, e.g. `"/pulsevault"`.
+     * Must be set explicitly: because this plugin is wrapped with
+     * `fastify-plugin` (so its decorator escapes encapsulation), Fastify's own
+     * `register(..., { prefix })` is a no-op and must be routed through this
+     * option instead. Use `""` to mount at the root.
+     */
+    prefix: string;
+    /**
+     * Max TUS upload size in bytes. Required — consumers must choose an
+     * explicit cap for their deployment. Use `Infinity` for no cap.
+     */
+    maxUploadSize: number;
+    /**
+     * Fastify instance decorator name under which the storage adapter is
+     * exposed. Defaults to `"pulseVault"`. Override when registering this
+     * plugin more than once in the same process so the decorators don't
+     * collide.
+     *
+     * For typed access to the default decorator, add a single side-effect
+     * import somewhere in your app: `import "@mieweb/pulsevault/augment"`.
+     * Consumers using a custom name must skip that import and write their own
+     * `declare module "fastify"` augmentation — see `./augment.ts` for the
+     * template.
+     */
+    decoratorName?: string;
+    /**
+     * File extensions allowed in the upload `filename` metadata. Must include
+     * the leading dot; matched case-insensitively. Defaults to `[".mp4"]`.
+     */
+    allowedExtensions?: readonly string[];
+    /**
+     * Cache-control options forwarded to `@fastify/send` for the GET route.
+     * When omitted, `@fastify/send`'s defaults apply (`Cache-Control: public,
+     * max-age=0`).
+     */
+    cache?: PulseVaultCacheOptions;
+    /**
+     * Optional authorization hook. Runs before the TUS create/PATCH lifecycle
+     * and before `resolve` on GET. Throw to reject the request; a thrown
+     * `statusCode`/`status_code` number on the error is honored (default 403).
+     *
+     * The hook is called with the `FastifyRequest`, so consumers can look up
+     * sessions, API keys, JWTs, etc. using whatever auth system they have
+     * registered higher up in the Fastify tree.
+     *
+     * When omitted, the plugin performs no authorization. For production
+     * deployments you almost certainly want to set this — register your auth
+     * plugin on the parent scope and let the hook verify ownership of the
+     * `videoid` before any bytes are written.
+     */
+    authorize?: PulseVaultAuthorize;
+    /**
+     * Optional payload-validation hook. Runs *after* TUS writes the final byte
+     * but *before* the upload is marked ready or `onUploadComplete` fires.
+     * Throw to reject — the plugin will call `storage.remove` to free the
+     * bytes and return a 4xx (default 422) to the client. The sidecar never
+     * flips to `"ready"`, so the video is never served.
+     *
+     * Use this for magic-byte sniffing, virus scanning, or any check that
+     * needs the final bytes. Ship-ready helpers are exported from this
+     * package — see `createMp4Sniffer`.
+     */
+    validatePayload?: PulseVaultValidatePayload;
+    /**
+     * Optional post-upload hook. Fires once TUS writes the final byte *and*
+     * any `validatePayload` has passed, and after the adapter's `markReady`
+     * has run. Use this to flip consumer state (DB row, queue job, audit
+     * log). Throwing turns the upload into a 500 response; the video is
+     * marked ready at this point, so consumers that want all-or-nothing
+     * semantics should `storage.remove` before throwing.
+     */
+    onUploadComplete?: PulseVaultOnUploadComplete;
+};
+declare const _default: FastifyPluginAsync<PulseVaultPluginOptions>;
+export default _default;
+export { createLocalStorage } from "./storage/local.js";
+export type { LocalStorage, LocalStorageOptions } from "./storage/local.js";
+export type { PulseVaultResolution, PulseVaultStorage, ReserveUploadParams, } from "./storage/types.js";
+export type { PulseVaultAuthorize, PulseVaultAuthorizeContext, PulseVaultAuthorizePhase, } from "./routes/pulsevault.js";
+export type { PulseVaultOnUploadComplete } from "./lib/pulsevaultTus.js";
+export { sniffMp4, createMp4Sniffer } from "./lib/magic.js";
+export type { PulseVaultValidatePayload } from "./lib/magic.js";
+export { buildConfigureDestinationLink, buildUploadLink, } from "./lib/deeplinks.js";
+export type { ConfigureDestinationLinkOptions, UploadLinkOptions, } from "./lib/deeplinks.js";
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,OAAyB,EACvB,KAAK,mBAAmB,EAGzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,wFAAwF;IACxF,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C,CAAC;;AAgEF,wBAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EACL,6BAA6B,EAC7B,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,+BAA+B,EAC/B,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/dist/app.js

@@ -0,0 +1,54 @@
+import fp from "fastify-plugin";
+import pulseVaultRoutes, {} from "./routes/pulsevault.js";
+const DEFAULT_DECORATOR_NAME = "pulseVault";
+const DEFAULT_ALLOWED_EXTENSIONS = [".mp4"];
+const EXTENSION_REGEX = /^\.[^.\s/\\]+$/;
+function validateOptions(opts) {
+    if (opts.prefix !== "" && (!opts.prefix.startsWith("/") || opts.prefix.endsWith("/"))) {
+        throw new TypeError("`prefix` must be '' or start with '/' with no trailing slash (e.g. '/pulsevault')");
+    }
+    if (!(opts.maxUploadSize > 0)) {
+        throw new TypeError("`maxUploadSize` must be a positive number (use Infinity for no cap)");
+    }
+    if (opts.allowedExtensions) {
+        if (opts.allowedExtensions.length === 0) {
+            throw new TypeError("`allowedExtensions` must not be empty");
+        }
+        for (const ext of opts.allowedExtensions) {
+            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')`);
+            }
+        }
+    }
+}
+const app = async (fastify, opts) => {
+    validateOptions(opts);
+    // Register the shutdown hook *before* awaiting initialize() so any partial
+    // state the adapter allocates mid-init still gets cleaned up if Fastify
+    // later tears the plugin down.
+    fastify.addHook("onClose", async () => {
+        await opts.storage.shutdown?.();
+    });
+    await opts.storage.initialize?.();
+    const decoratorName = opts.decoratorName ?? DEFAULT_DECORATOR_NAME;
+    const allowedExtensions = (opts.allowedExtensions ?? DEFAULT_ALLOWED_EXTENSIONS).map((e) => e.toLowerCase());
+    fastify.decorate(decoratorName, opts.storage);
+    await fastify.register(pulseVaultRoutes, {
+        prefix: opts.prefix,
+        storage: opts.storage,
+        maxUploadSize: opts.maxUploadSize,
+        allowedExtensions,
+        cache: opts.cache,
+        authorize: opts.authorize,
+        validatePayload: opts.validatePayload,
+        onUploadComplete: opts.onUploadComplete,
+    });
+};
+export default fp(app, {
+    name: "pulsevault",
+    fastify: "5.x",
+});
+export { createLocalStorage } from "./storage/local.js";
+export { sniffMp4, createMp4Sniffer } from "./lib/magic.js";
+export { buildConfigureDestinationLink, buildUploadLink, } from "./lib/deeplinks.js";
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChC,OAAO,gBAAgB,EAAE,EAIxB,MAAM,wBAAwB,CAAC;AAwGhC,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAC5C,MAAM,0BAA0B,GAAsB,CAAC,MAAM,CAAC,CAAC;AAC/D,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEzC,SAAS,eAAe,CAAC,IAA6B;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,SAAS,CACjB,mFAAmF,CACpF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CACjB,qEAAqE,CACtE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;QAC/D,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,SAAS,CACjB,+BAA+B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,uFAAuF,CAC1I,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,GAAG,GAAgD,KAAK,EAC5D,OAAO,EACP,IAAI,EACJ,EAAE;IACF,eAAe,CAAC,IAAI,CAAC,CAAC;IAEtB,2EAA2E;IAC3E,wEAAwE;IACxE,+BAA+B;IAC/B,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;IAElC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACnE,MAAM,iBAAiB,GAAG,CACxB,IAAI,CAAC,iBAAiB,IAAI,0BAA0B,CACrD,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9C,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACvC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,iBAAiB;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;KACxC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,eAAe,EAAE,CAAC,GAAG,EAAE;IACrB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,KAAK;CACf,CAAC,CAAC;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAaxD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EACL,6BAA6B,EAC7B,eAAe,GAChB,MAAM,oBAAoB,CAAC"}

package/dist/augment.d.ts

@@ -0,0 +1,45 @@
+import type { PulseVaultStorage } from "./storage/types.js";
+/**
+ * Opt-in TypeScript augmentation for the default `pulseVault` decorator and
+ * the per-request `request.pulseVault` context that the plugin sets when it
+ * recognizes a videoid on the incoming request. Import for side effects in
+ * one place in your app when you register the plugin with the default
+ * `decoratorName`:
+ *
+ * ```ts
+ * import "@mieweb/pulsevault/augment";
+ * ```
+ *
+ * If you pass a custom `decoratorName`, skip this import and write your own
+ * augmentation:
+ *
+ * ```ts
+ * declare module "fastify" {
+ *   interface FastifyInstance {
+ *     myCustomName: PulseVaultStorage;
+ *   }
+ *   interface FastifyRequest {
+ *     pulseVault?: { videoid: string };
+ *   }
+ * }
+ * ```
+ */
+declare module "fastify" {
+    interface FastifyInstance {
+        pulseVault: PulseVaultStorage;
+    }
+    interface FastifyRequest {
+        /**
+         * Populated by the plugin when it can extract a videoid from the
+         * incoming request (from `Upload-Metadata` on POST, the URL id on
+         * PATCH/HEAD/DELETE, or the route param on GET). Present on every
+         * request the plugin routes serve that refer to a valid UUID — use it
+         * from your own `preHandler` / auth hooks to avoid re-parsing.
+         */
+        pulseVault?: {
+            videoid: string;
+        };
+    }
+}
+export {};
+//# sourceMappingURL=augment.d.ts.map

package/dist/augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.d.ts","sourceRoot":"","sources":["../src/augment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,UAAU,EAAE,iBAAiB,CAAC;KAC/B;IACD,UAAU,cAAc;QACtB;;;;;;WAMG;QACH,UAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAClC;CACF;AAED,OAAO,EAAE,CAAC"}

package/dist/augment.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=augment.js.map

package/dist/augment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.js","sourceRoot":"","sources":["../src/augment.ts"],"names":[],"mappings":"AA2CA,OAAO,EAAE,CAAC"}