@mieweb/pulsevault 0.0.1

package/dist/routes/pulsevault.js

@@ -0,0 +1,315 @@
+import send from "@fastify/send";
+import { createPulsevaultTusServer, pulseVaultTusContext, } from "../lib/pulsevaultTus.js";
+import { pulseVaultError } from "../lib/errors.js";
+import { isUuid } from "../lib/uuid.js";
+/**
+ * Pull `videoid` out of a raw `Upload-Metadata` header. Format is a
+ * comma-separated list of `<key> <base64-value>` pairs (tus v1 creation
+ * extension). We only care about `videoid`; everything else is left to the
+ * tus server proper.
+ */
+function parseVideoidFromMetadata(header) {
+    for (const pair of header.split(",")) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const sep = trimmed.indexOf(" ");
+        if (sep < 0)
+            continue;
+        const key = trimmed.slice(0, sep);
+        if (key !== "videoid")
+            continue;
+        const value = trimmed.slice(sep + 1).trim();
+        if (!value)
+            return undefined;
+        try {
+            const decoded = Buffer.from(value, "base64").toString("utf8");
+            return isUuid(decoded) ? decoded : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Decode the last URL segment of a tus PATCH/HEAD/DELETE (base64url-encoded
+ * id) and extract the first path component, which the plugin always shapes as
+ * the videoid (see `pulseVaultTus.ts`).
+ */
+function videoidFromTusUrl(url) {
+    const match = url.match(/\/upload\/([^/?#]+)/);
+    if (!match?.[1])
+        return undefined;
+    let decoded;
+    try {
+        decoded = Buffer.from(match[1], "base64url").toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const first = decoded.split("/", 1)[0];
+    return isUuid(first) ? first : undefined;
+}
+function extractAuthzStatus(err) {
+    const e = err;
+    if (typeof e?.statusCode === "number")
+        return e.statusCode;
+    if (typeof e?.status_code === "number")
+        return e.status_code;
+    return 403;
+}
+function extractAuthzMessage(err) {
+    if (err instanceof Error && err.message)
+        return err.message;
+    return "Forbidden";
+}
+const pulseVaultErrorResponse = {
+    type: "object",
+    properties: {
+        ok: { type: "boolean" },
+        error: { type: "string" },
+    },
+    required: ["ok", "error"],
+};
+const tusRouteSchema = {
+    tags: ["pulsevault"],
+    summary: "TUS resumable upload endpoint",
+    description: "TUS v1 resumable upload protocol.\n\n" +
+        "- `POST` creates a new upload. The `Upload-Metadata` header must include a base64-encoded `videoid` pair.\n" +
+        "- `PATCH` appends a chunk at the offset given by `Upload-Offset`, with `Content-Type: application/offset+octet-stream`.\n" +
+        "- `HEAD` returns the current offset for a resumable upload.\n" +
+        "- `DELETE` cancels an in-flight upload.\n\n" +
+        "See https://tus.io/protocols/resumable-upload for the full protocol.",
+    response: {
+        400: { description: "Invalid request.", ...pulseVaultErrorResponse },
+        403: {
+            description: "Authorize hook rejected the request.",
+            ...pulseVaultErrorResponse,
+        },
+    },
+};
+const videoDeleteSchema = {
+    tags: ["pulsevault"],
+    summary: "Delete an uploaded video",
+    description: "Deletes all storage for a videoid (bytes + sidecar metadata). Runs the `authorize` hook with `phase: \"delete\"` before the adapter's `remove` is called. Returns 204 on success, 404 if the videoid was unknown, 501 if the adapter does not implement `remove`.",
+    params: {
+        type: "object",
+        properties: {
+            videoid: {
+                type: "string",
+                format: "uuid",
+                description: "UUID of the upload to delete.",
+            },
+        },
+        required: ["videoid"],
+    },
+    response: {
+        400: {
+            description: "`videoid` is not a valid UUID.",
+            ...pulseVaultErrorResponse,
+        },
+        403: {
+            description: "Authorize hook rejected the request.",
+            ...pulseVaultErrorResponse,
+        },
+        404: { description: "Video not found.", ...pulseVaultErrorResponse },
+        501: {
+            description: "Storage adapter does not implement delete.",
+            ...pulseVaultErrorResponse,
+        },
+    },
+};
+const videoGetSchema = {
+    tags: ["pulsevault"],
+    summary: "Serve a previously uploaded video",
+    description: "Resolves the `videoid` through the configured storage adapter and either streams the bytes or redirects (for CDN-backed adapters). Runs the `authorize` hook before resolve.",
+    params: {
+        type: "object",
+        properties: {
+            videoid: {
+                type: "string",
+                format: "uuid",
+                description: "UUID returned from the reserve/TUS-create flow.",
+            },
+        },
+        required: ["videoid"],
+    },
+    response: {
+        400: {
+            description: "`videoid` is not a valid UUID.",
+            ...pulseVaultErrorResponse,
+        },
+        403: {
+            description: "Authorize hook rejected the request.",
+            ...pulseVaultErrorResponse,
+        },
+        404: { description: "Video not found.", ...pulseVaultErrorResponse },
+    },
+};
+const pulseVaultRoutes = async (fastify, opts) => {
+    const { storage, maxUploadSize, allowedExtensions, cache, authorize, validatePayload, onUploadComplete, } = opts;
+    // `fastify.prefix` is `""` when the plugin is mounted at the root.
+    const tusPath = `${fastify.prefix}/upload`;
+    const tusServer = createPulsevaultTusServer({
+        storage,
+        tusPath,
+        maxSize: maxUploadSize,
+        allowedExtensions,
+        validatePayload,
+        onUploadComplete,
+    });
+    fastify.addContentTypeParser("application/offset+octet-stream", (_request, _payload, done) => {
+        done(null);
+    });
+    /**
+     * Run the consumer's `authorize` hook (if any) for a TUS request. Returns
+     * `true` iff the request may proceed; on rejection, this function already
+     * wrote the response.
+     */
+    const runAuthorize = async (request, reply, phase) => {
+        let videoid;
+        if (phase === "create") {
+            const meta = request.headers["upload-metadata"];
+            if (typeof meta === "string") {
+                videoid = parseVideoidFromMetadata(meta);
+            }
+        }
+        else {
+            videoid = videoidFromTusUrl(request.url);
+        }
+        if (videoid) {
+            request.pulseVault = { videoid };
+        }
+        if (!authorize) {
+            return { ok: true, videoid };
+        }
+        // If we can't extract a videoid, let tus produce its own 4xx for malformed
+        // input rather than synthesize a fake authorize failure.
+        if (!videoid) {
+            return { ok: true, videoid };
+        }
+        try {
+            await authorize(request, { phase, videoid });
+            return { ok: true, videoid };
+        }
+        catch (err) {
+            const statusCode = extractAuthzStatus(err);
+            const message = extractAuthzMessage(err);
+            request.log.info({ err, videoid, phase, statusCode }, "pulsevault authorize rejected");
+            await reply.code(statusCode).send(pulseVaultError(message));
+            return { ok: false };
+        }
+    };
+    const tusHandler = async (request, reply) => {
+        const phase = request.method === "POST" ? "create" : "patch";
+        const authz = await runAuthorize(request, reply, phase);
+        if (!authz.ok)
+            return;
+        // Once hijacked, Fastify will not write to this reply on our behalf, so we
+        // must translate any unexpected throw from `@tus/server` into a response
+        // ourselves — otherwise the socket stays open until the client times out.
+        reply.hijack();
+        try {
+            await pulseVaultTusContext.run({ request, videoid: authz.videoid }, () => tusServer.handle(request.raw, reply.raw));
+        }
+        catch (err) {
+            request.log.error({ err }, "pulsevault tus handler failed");
+            if (reply.raw.headersSent || reply.raw.writableEnded) {
+                reply.raw.destroy();
+                return;
+            }
+            reply.raw.statusCode = 500;
+            reply.raw.setHeader("content-type", "text/plain; charset=utf-8");
+            reply.raw.end("Internal Server Error");
+        }
+    };
+    const tusMethods = ["POST", "PATCH", "HEAD", "DELETE", "OPTIONS"];
+    fastify.route({
+        method: [...tusMethods],
+        url: "/upload",
+        schema: tusRouteSchema,
+        handler: tusHandler,
+    });
+    fastify.route({
+        method: [...tusMethods],
+        url: "/upload/*",
+        schema: tusRouteSchema,
+        handler: tusHandler,
+    });
+    fastify.delete("/:videoid", { schema: videoDeleteSchema }, async (request, reply) => {
+        const videoid = request.params?.videoid;
+        if (!isUuid(videoid)) {
+            return reply
+                .code(400)
+                .send(pulseVaultError("`videoid` must be a valid UUID"));
+        }
+        request.pulseVault = { videoid };
+        if (authorize) {
+            try {
+                await authorize(request, { phase: "delete", videoid });
+            }
+            catch (err) {
+                const statusCode = extractAuthzStatus(err);
+                const message = extractAuthzMessage(err);
+                request.log.info({ err, videoid, phase: "delete", statusCode }, "pulsevault authorize rejected");
+                return reply.code(statusCode).send(pulseVaultError(message));
+            }
+        }
+        if (typeof storage.remove !== "function") {
+            return reply
+                .code(501)
+                .send(pulseVaultError("Storage adapter does not support delete"));
+        }
+        const removed = await storage.remove(videoid);
+        if (!removed) {
+            return reply.code(404).send(pulseVaultError("Video not found"));
+        }
+        return reply.code(204).send();
+    });
+    fastify.get("/:videoid", { schema: videoGetSchema }, async (request, reply) => {
+        const videoid = request.params?.videoid;
+        if (!isUuid(videoid)) {
+            return reply
+                .code(400)
+                .send(pulseVaultError("`videoid` must be a valid UUID"));
+        }
+        request.pulseVault = { videoid };
+        // Run authorize *before* resolve so consumers can reject without the
+        // response leaking "this videoid exists but you don't own it" vs. "no such
+        // videoid".
+        if (authorize) {
+            try {
+                await authorize(request, { phase: "resolve", videoid });
+            }
+            catch (err) {
+                const statusCode = extractAuthzStatus(err);
+                const message = extractAuthzMessage(err);
+                request.log.info({ err, videoid, phase: "resolve", statusCode }, "pulsevault authorize rejected");
+                return reply.code(statusCode).send(pulseVaultError(message));
+            }
+        }
+        const resolved = await storage.resolve(videoid);
+        if (!resolved) {
+            return reply.code(404).send(pulseVaultError("Video not found"));
+        }
+        if (resolved.kind === "redirect") {
+            return reply.redirect(resolved.url, resolved.statusCode ?? 302);
+        }
+        const result = await send(request.raw, resolved.filename, {
+            root: resolved.root,
+            ...cache,
+        });
+        if (result.type === "error") {
+            return reply
+                .code(result.statusCode)
+                .send(pulseVaultError(result.metadata.error.message));
+        }
+        for (const [name, value] of Object.entries(result.headers)) {
+            reply.header(name, value);
+        }
+        return reply.code(result.statusCode).send(result.stream);
+    });
+};
+export default pulseVaultRoutes;
+//# sourceMappingURL=pulsevault.js.map

package/dist/routes/pulsevault.js.map

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

package/dist/storage/local.d.ts

@@ -0,0 +1,34 @@
+import type { PulseVaultStorage } from "./types.js";
+export type LocalStorageOptions = {
+    /** Directory where per-video subdirectories are stored. Resolved against CWD if relative. */
+    workspaceDir: string;
+};
+/**
+ * Local adapter storage. Layout contract (stable; downstream tools may rely
+ * on it):
+ *
+ * ```text
+ * <workspaceRoot>/<videoid>/
+ *   .pulsevault.json           # our sidecar: { version, ext, filename, status }
+ *   video/<videoid><ext>       # finalized upload bytes
+ *   video/<videoid><ext>.json  # @tus/file-store's offset/metadata sidecar
+ * ```
+ *
+ * `workspaceRoot` is exposed so consumers can layer post-processing (e.g.
+ * hydrate an ArtiPod with `video/`, `transcripts/`, `frames/` mounts) against
+ * the same on-disk tree from an `onUploadComplete` hook. `getLocalPath` is
+ * exposed for `validatePayload` helpers that need to sniff the bytes before
+ * the video is marked ready.
+ */
+export type LocalStorage = PulseVaultStorage & {
+    readonly workspaceRoot: string;
+    /**
+     * Return the absolute path to the upload bytes for `videoid`, regardless
+     * of ready state. Falls back to reading the sidecar if the in-memory cache
+     * is cold (so it works even after a server restart mid-upload). Returns
+     * `null` if the videoid is unknown.
+     */
+    getLocalPath(videoid: string): Promise<string | null>;
+};
+export declare function createLocalStorage(opts: LocalStorageOptions): LocalStorage;
+//# sourceMappingURL=local.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AA6BpB,MAAM,MAAM,mBAAmB,GAAG;IAChC,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAkL1E"}

package/dist/storage/local.js

@@ -0,0 +1,167 @@
+import { FileStore } from "@tus/file-store";
+import fs from "node:fs/promises";
+import path from "node:path";
+const SIDECAR_NAME = ".pulsevault.json";
+const SIDECAR_VERSION = 1;
+export function createLocalStorage(opts) {
+    const workspaceRoot = path.resolve(opts.workspaceDir);
+    const datastore = new FileStore({ directory: workspaceRoot });
+    // Metadata cache keyed by videoid. Populated eagerly on reserve and lazily
+    // from the sidecar on cache-miss — so we never do a workspace-wide scan at
+    // boot and never do a per-request readdir on the GET hot path.
+    const metaCache = new Map();
+    const videoDir = (videoid) => path.join(workspaceRoot, videoid);
+    const sidecarPath = (videoid) => path.join(videoDir(videoid), SIDECAR_NAME);
+    const videoRelPath = (videoid, ext) => `video/${videoid}${ext}`;
+    const writeSidecar = async (videoid, sidecar) => {
+        // Atomic tmp + rename so a crash mid-write can never leave a truncated
+        // JSON blob that `loadMeta` would then treat as corrupt.
+        const finalPath = sidecarPath(videoid);
+        const tmpPath = `${finalPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(sidecar), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    };
+    const readSidecar = async (videoid) => {
+        let raw;
+        try {
+            raw = await fs.readFile(sidecarPath(videoid), "utf8");
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.ext !== "string")
+                return null;
+            if (typeof parsed.filename !== "string")
+                return null;
+            // Older sidecars (pre-status) are treated as ready so an in-place
+            // upgrade doesn't hide finalized uploads. New uploads always write a
+            // `status` field explicitly.
+            const status = parsed.status === "uploading" ? "uploading" : "ready";
+            return {
+                version: SIDECAR_VERSION,
+                ext: parsed.ext,
+                filename: parsed.filename,
+                status,
+            };
+        }
+        catch {
+            // Malformed sidecar — treat as absent. `reserveUpload` will rewrite
+            // it on the next create.
+            return null;
+        }
+    };
+    const loadMeta = async (videoid) => {
+        const cached = metaCache.get(videoid);
+        if (cached)
+            return cached;
+        const sidecar = await readSidecar(videoid);
+        if (!sidecar)
+            return null;
+        const meta = {
+            ext: sidecar.ext,
+            ready: sidecar.status === "ready",
+        };
+        metaCache.set(videoid, meta);
+        return meta;
+    };
+    const initialize = async () => {
+        await fs.mkdir(workspaceRoot, { recursive: true });
+    };
+    const reserveUpload = async ({ videoid, filename, ext, }) => {
+        // Collision guard: if an upload (in-progress or ready) already exists
+        // for this videoid, refuse the new upload rather than letting
+        // @tus/file-store silently reset the metadata sidecar to offset 0 and
+        // overwrite the file chunk-by-chunk on subsequent PATCHes. Translates
+        // to HTTP 409 via @tus/server's error path.
+        const meta = await loadMeta(videoid);
+        if (meta) {
+            throw Object.assign(new Error(`videoid ${videoid} already has an upload`), { statusCode: 409, status_code: 409 });
+        }
+        const dir = videoDir(videoid);
+        await fs.mkdir(path.join(dir, "video"), { recursive: true });
+        await writeSidecar(videoid, {
+            version: SIDECAR_VERSION,
+            ext,
+            filename,
+            status: "uploading",
+        });
+        metaCache.set(videoid, { ext, ready: false });
+        // @tus/file-store joins this onto its configured `directory`, so the
+        // actual file lands at `<workspaceRoot>/<videoid>/video/<videoid><ext>`.
+        return `${videoid}/${videoRelPath(videoid, ext)}`;
+    };
+    const resolve = async (videoid) => {
+        const meta = await loadMeta(videoid);
+        // Only serve ready uploads. In-progress uploads stay hidden — a client
+        // GETting mid-upload would otherwise receive a truncated file.
+        if (!meta || !meta.ready)
+            return null;
+        const root = videoDir(videoid);
+        const relFile = videoRelPath(videoid, meta.ext);
+        try {
+            const stat = await fs.stat(path.join(root, relFile));
+            if (!stat.isFile())
+                return null;
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return { kind: "stream", root, filename: relFile };
+    };
+    const markReady = async (videoid) => {
+        const sidecar = await readSidecar(videoid);
+        if (!sidecar) {
+            // No sidecar means no `reserveUpload` happened for this videoid — this
+            // is a contract violation by the caller, not a recoverable state.
+            throw new Error(`markReady: no sidecar for videoid ${videoid} (was reserveUpload called?)`);
+        }
+        if (sidecar.status === "ready") {
+            // Idempotent: already ready is fine, keep the cache consistent.
+            metaCache.set(videoid, { ext: sidecar.ext, ready: true });
+            return;
+        }
+        await writeSidecar(videoid, { ...sidecar, status: "ready" });
+        metaCache.set(videoid, { ext: sidecar.ext, ready: true });
+    };
+    const remove = async (videoid) => {
+        const dir = videoDir(videoid);
+        // Drop from cache before the rm so a racing `resolve` that arrives after
+        // the rm but before the cache eviction can't hand back a stale path.
+        metaCache.delete(videoid);
+        try {
+            // Note: no `force: true` — we want ENOENT to surface so the caller
+            // (the DELETE route) can distinguish "removed something" from "nothing
+            // to remove" and return 204 vs 404 accordingly.
+            await fs.rm(dir, { recursive: true });
+            return true;
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    };
+    const getLocalPath = async (videoid) => {
+        const meta = await loadMeta(videoid);
+        if (!meta)
+            return null;
+        return path.join(workspaceRoot, videoid, "video", `${videoid}${meta.ext}`);
+    };
+    return {
+        datastore,
+        workspaceRoot,
+        initialize,
+        reserveUpload,
+        resolve,
+        markReady,
+        remove,
+        getLocalPath,
+    };
+}
+//# sourceMappingURL=local.js.map

package/dist/storage/local.js.map

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

package/dist/storage/types.d.ts

@@ -0,0 +1,72 @@
+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).
+ */
+export type PulseVaultResolution = {
+    kind: "stream";
+    /** Root directory `@fastify/send` should jail to. */
+    root: string;
+    /** Filename relative to `root`. */
+    filename: string;
+} | {
+    kind: "redirect";
+    url: string;
+    /** Defaults to 302. */
+    statusCode?: number;
+};
+export type ReserveUploadParams = {
+    /** UUID from `Upload-Metadata.videoid`. */
+    videoid: string;
+    /** Raw filename from `Upload-Metadata.filename`. */
+    filename: string;
+    /** Lowercase extension including the leading dot, validated upstream. */
+    ext: string;
+};
+/**
+ * Storage backend contract. Keep the surface small: one write hook, one read
+ * hook, plus optional one-time init. Adapters own their own configuration.
+ */
+export interface PulseVaultStorage {
+    /** TUS datastore used for resumable uploads. */
+    readonly datastore: DataStore;
+    /** One-time setup. Called once during plugin boot. */
+    initialize?(): Promise<void>;
+    /**
+     * One-time teardown. Called from Fastify's `onClose` hook so adapters can
+     * flush state, close connections, etc. The local adapter has nothing to
+     * release, so it omits this method.
+     */
+    shutdown?(): Promise<void>;
+    /**
+     * Called by TUS's `namingFunction` after core validation. Returns the file
+     * id (the string the datastore will use as its key/path). Adapters may also
+     * perform per-upload bookkeeping here (e.g. creating local mount dirs).
+     */
+    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
+     * that implement `markReady` should only return non-null once the bytes
+     * have been promoted to "ready."
+     */
+    resolve(videoid: 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`
+     * hooks succeed. Adapters that do not distinguish uploading from ready
+     * (e.g. S3 multipart, which only materializes on CompleteMultipartUpload)
+     * may omit this method — `resolve` will be trusted to only return finished
+     * uploads in that case.
+     */
+    markReady?(videoid: string): Promise<void>;
+    /**
+     * 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.
+     */
+    remove?(videoid: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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"}

package/dist/storage/types.js

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

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":""}