@basaltkit/files 1.0.0 → 1.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/files
 
 **Upload** pipeline for Basalt, built on top of [`@basaltkit/storage`](https://www.npmjs.com/package/@basaltkit/storage): validates (type/size), enforces **per-tenant quota**, stores the bytes, records metadata, and fires **hooks** (antivirus, thumbnails). You need this module when users upload files — attachments, avatars, documents — and you want to do it safely and with tenant isolation.

package/dist/files.d.ts

@@ -0,0 +1,83 @@
+import { BasaltError, type DurationInput, type HookBus } from '@basaltkit/core';
+import type { Disk } from '@basaltkit/storage';
+import { type FileRecord, type FileStore } from './store.js';
+export declare class FileTooLargeError extends BasaltError {
+    readonly status = 413;
+    constructor(size: number, max: number);
+}
+export declare class FileTypeNotAllowedError extends BasaltError {
+    readonly status = 415;
+    constructor(contentType: string);
+}
+/** The tenant's storage allowance is exhausted. */
+export declare class StorageQuotaExceededError extends BasaltError {
+    readonly status = 402;
+    constructor();
+}
+export declare class FileNotFoundError extends BasaltError {
+    readonly status = 404;
+    constructor();
+}
+export declare class FileTenantRequiredError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+export interface FileValidation {
+    /** Max size in bytes. */
+    maxSize?: number;
+    /** Allowed content types; supports `image/*` wildcards. */
+    allowedTypes?: string[];
+}
+export interface FilesOptions {
+    disk: Disk;
+    store?: FileStore;
+    hooks?: HookBus;
+    validate?: FileValidation;
+    /** Max total bytes per tenant (a built-in quota). */
+    maxTotalBytes?: number;
+    /** Custom quota check — throw to reject (e.g. wire @basaltkit/subscriptions). */
+    checkQuota?: (tenantId: string, size: number) => Promise<void> | void;
+    now?: () => number;
+}
+export interface UploadInput {
+    name: string;
+    contentType: string;
+    tenantId?: string;
+    uploadedBy?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
+ * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
+ * operation is tenant-scoped; storage access runs in the resolved tenant's
+ * context so files are isolated whether called from a request or a job.
+ */
+export declare class Files {
+    private readonly disk;
+    private readonly store;
+    private readonly hooks;
+    private readonly validation;
+    private readonly maxTotalBytes;
+    private readonly checkQuota;
+    private readonly now;
+    constructor(options: FilesOptions);
+    upload(content: Buffer, input: UploadInput): Promise<FileRecord>;
+    get(id: string, tenantId?: string): Promise<FileRecord | null>;
+    list(tenantId?: string): Promise<FileRecord[]>;
+    download(id: string, tenantId?: string): Promise<{
+        record: FileRecord;
+        content: Buffer;
+    }>;
+    temporaryUrl(id: string, expiresIn: DurationInput, tenantId?: string): Promise<string>;
+    delete(id: string, tenantId?: string): Promise<void>;
+    /** Records the result of an out-of-band scan (antivirus, moderation, …). */
+    markScanned(id: string, result: {
+        clean: boolean;
+        detail?: string;
+    }, tenantId?: string): Promise<FileRecord>;
+    private validate;
+    private enforceQuota;
+    private tenant;
+    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    private inTenant;
+}

package/dist/files.js

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { BasaltError, runWithContext, tryCtx } from '@basaltkit/core';
+import { MemoryFileStore } from './store.js';
+export class FileTooLargeError extends BasaltError {
+    status = 413;
+    constructor(size, max) {
+        super('FILE_TOO_LARGE', `File is ${size} bytes; the limit is ${max}.`);
+    }
+}
+export class FileTypeNotAllowedError extends BasaltError {
+    status = 415;
+    constructor(contentType) {
+        super('FILE_TYPE_NOT_ALLOWED', `Content type "${contentType}" is not allowed.`);
+    }
+}
+/** The tenant's storage allowance is exhausted. */
+export class StorageQuotaExceededError extends BasaltError {
+    status = 402;
+    constructor() {
+        super('FILE_QUOTA_EXCEEDED', 'Storage quota exceeded for this tenant.');
+    }
+}
+export class FileNotFoundError extends BasaltError {
+    status = 404;
+    constructor() {
+        super('FILE_NOT_FOUND', 'File not found.');
+    }
+}
+export class FileTenantRequiredError extends BasaltError {
+    status = 400;
+    constructor() {
+        super('FILE_TENANT_REQUIRED', 'A tenant is required — pass tenantId or run inside a tenant context.');
+    }
+}
+const matchesType = (contentType, allowed) => allowed.some((a) => a === contentType || (a.endsWith('/*') && contentType.startsWith(a.slice(0, -1))));
+const storagePath = (id) => `files/${id}`;
+/**
+ * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
+ * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
+ * operation is tenant-scoped; storage access runs in the resolved tenant's
+ * context so files are isolated whether called from a request or a job.
+ */
+export class Files {
+    disk;
+    store;
+    hooks;
+    validation;
+    maxTotalBytes;
+    checkQuota;
+    now;
+    constructor(options) {
+        this.disk = options.disk;
+        this.store = options.store ?? new MemoryFileStore();
+        this.hooks = options.hooks;
+        this.validation = options.validate ?? {};
+        this.maxTotalBytes = options.maxTotalBytes;
+        this.checkQuota = options.checkQuota;
+        this.now = options.now ?? Date.now;
+    }
+    async upload(content, input) {
+        const tenantId = this.tenant(input.tenantId);
+        const size = content.length;
+        this.validate(input.contentType, size);
+        await this.enforceQuota(tenantId, size);
+        const id = randomUUID();
+        const path = storagePath(id);
+        const checksum = createHash('sha256').update(content).digest('hex');
+        await this.inTenant(tenantId, () => this.disk.put(path, content, { contentType: input.contentType }));
+        const record = {
+            id,
+            tenantId,
+            name: input.name,
+            contentType: input.contentType,
+            size,
+            path,
+            checksum,
+            createdAt: this.now(),
+            ...(input.uploadedBy !== undefined ? { uploadedBy: input.uploadedBy } : {}),
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        };
+        await this.store.create(record);
+        await this.hooks?.emit('file:uploaded', { file: record });
+        return record;
+    }
+    async get(id, tenantId) {
+        return this.store.find(this.tenant(tenantId), id);
+    }
+    async list(tenantId) {
+        return this.store.list(this.tenant(tenantId));
+    }
+    async download(id, tenantId) {
+        const resolved = this.tenant(tenantId);
+        const record = await this.store.find(resolved, id);
+        if (!record)
+            throw new FileNotFoundError();
+        const content = await this.inTenant(resolved, () => this.disk.get(record.path));
+        return { record, content };
+    }
+    async temporaryUrl(id, expiresIn, tenantId) {
+        const resolved = this.tenant(tenantId);
+        const record = await this.store.find(resolved, id);
+        if (!record)
+            throw new FileNotFoundError();
+        return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn));
+    }
+    async delete(id, tenantId) {
+        const resolved = this.tenant(tenantId);
+        const record = await this.store.find(resolved, id);
+        if (!record)
+            return;
+        await this.inTenant(resolved, () => this.disk.delete(record.path));
+        await this.store.delete(resolved, id);
+        await this.hooks?.emit('file:deleted', { tenantId: resolved, id });
+    }
+    /** Records the result of an out-of-band scan (antivirus, moderation, …). */
+    async markScanned(id, result, tenantId) {
+        const resolved = this.tenant(tenantId);
+        const record = await this.store.find(resolved, id);
+        if (!record)
+            throw new FileNotFoundError();
+        const patch = { scanned: true, metadata: { ...record.metadata, scan: result } };
+        const updated = (await this.store.update(resolved, id, patch)) ?? record;
+        await this.hooks?.emit('file:scanned', { file: updated });
+        return updated;
+    }
+    validate(contentType, size) {
+        if (this.validation.maxSize !== undefined && size > this.validation.maxSize) {
+            throw new FileTooLargeError(size, this.validation.maxSize);
+        }
+        if (this.validation.allowedTypes && !matchesType(contentType, this.validation.allowedTypes)) {
+            throw new FileTypeNotAllowedError(contentType);
+        }
+    }
+    async enforceQuota(tenantId, size) {
+        if (this.maxTotalBytes !== undefined) {
+            const total = await this.store.totalSize(tenantId);
+            if (total + size > this.maxTotalBytes)
+                throw new StorageQuotaExceededError();
+        }
+        await this.checkQuota?.(tenantId, size);
+    }
+    tenant(explicit) {
+        const id = explicit ?? tryCtx()?.['tenant']?.id;
+        if (!id)
+            throw new FileTenantRequiredError();
+        return id;
+    }
+    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
+    inTenant(tenantId, fn) {
+        return runWithContext({ tenant: { id: tenantId } }, fn);
+    }
+}

package/dist/index.d.ts

@@ -1,159 +1,3 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { HookBus, DurationInput, BasaltError } from '@basaltkit/core';
-import { Disk } from '@basaltkit/storage';
-import { BasaltRoute } from '@basaltkit/fastify';
-
-/** Metadata for one uploaded file. The bytes live in storage; this is the record. */
-interface FileRecord {
-    id: string;
-    tenantId: string;
-    /** Original filename. */
-    name: string;
-    contentType: string;
-    /** Size in bytes. */
-    size: number;
-    /** Path within the storage disk. */
-    path: string;
-    /** SHA-256 of the content. */
-    checksum: string;
-    uploadedBy?: string;
-    metadata?: Record<string, unknown>;
-    /** Set by a scanning step (antivirus, etc.) via `markScanned`. */
-    scanned?: boolean;
-    createdAt: number;
-}
-type FilePatch = Partial<Pick<FileRecord, 'scanned' | 'metadata'>>;
-/** Where file metadata lives — the app's database in production. */
-interface FileStore {
-    create(record: FileRecord): Promise<void>;
-    find(tenantId: string, id: string): Promise<FileRecord | null>;
-    list(tenantId: string): Promise<FileRecord[]>;
-    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
-    delete(tenantId: string, id: string): Promise<void>;
-    /** Total bytes stored by a tenant — used for quota checks. */
-    totalSize(tenantId: string): Promise<number>;
-}
-declare class MemoryFileStore implements FileStore {
-    private readonly records;
-    private key;
-    create(record: FileRecord): Promise<void>;
-    find(tenantId: string, id: string): Promise<FileRecord | null>;
-    list(tenantId: string): Promise<FileRecord[]>;
-    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
-    delete(tenantId: string, id: string): Promise<void>;
-    totalSize(tenantId: string): Promise<number>;
-}
-
-declare class FileTooLargeError extends BasaltError {
-    readonly status = 413;
-    constructor(size: number, max: number);
-}
-declare class FileTypeNotAllowedError extends BasaltError {
-    readonly status = 415;
-    constructor(contentType: string);
-}
-/** The tenant's storage allowance is exhausted. */
-declare class StorageQuotaExceededError extends BasaltError {
-    readonly status = 402;
-    constructor();
-}
-declare class FileNotFoundError extends BasaltError {
-    readonly status = 404;
-    constructor();
-}
-declare class FileTenantRequiredError extends BasaltError {
-    readonly status = 400;
-    constructor();
-}
-interface FileValidation {
-    /** Max size in bytes. */
-    maxSize?: number;
-    /** Allowed content types; supports `image/*` wildcards. */
-    allowedTypes?: string[];
-}
-interface FilesOptions {
-    disk: Disk;
-    store?: FileStore;
-    hooks?: HookBus;
-    validate?: FileValidation;
-    /** Max total bytes per tenant (a built-in quota). */
-    maxTotalBytes?: number;
-    /** Custom quota check — throw to reject (e.g. wire @basaltkit/subscriptions). */
-    checkQuota?: (tenantId: string, size: number) => Promise<void> | void;
-    now?: () => number;
-}
-interface UploadInput {
-    name: string;
-    contentType: string;
-    tenantId?: string;
-    uploadedBy?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Upload pipeline over a storage {@link Disk}: validates size/type, enforces a
- * per-tenant quota, writes the bytes, records metadata, and emits hooks. Every
- * operation is tenant-scoped; storage access runs in the resolved tenant's
- * context so files are isolated whether called from a request or a job.
- */
-declare class Files {
-    private readonly disk;
-    private readonly store;
-    private readonly hooks;
-    private readonly validation;
-    private readonly maxTotalBytes;
-    private readonly checkQuota;
-    private readonly now;
-    constructor(options: FilesOptions);
-    upload(content: Buffer, input: UploadInput): Promise<FileRecord>;
-    get(id: string, tenantId?: string): Promise<FileRecord | null>;
-    list(tenantId?: string): Promise<FileRecord[]>;
-    download(id: string, tenantId?: string): Promise<{
-        record: FileRecord;
-        content: Buffer;
-    }>;
-    temporaryUrl(id: string, expiresIn: DurationInput, tenantId?: string): Promise<string>;
-    delete(id: string, tenantId?: string): Promise<void>;
-    /** Records the result of an out-of-band scan (antivirus, moderation, …). */
-    markScanned(id: string, result: {
-        clean: boolean;
-        detail?: string;
-    }, tenantId?: string): Promise<FileRecord>;
-    private validate;
-    private enforceQuota;
-    private tenant;
-    /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
-    private inTenant;
-}
-
-declare module '@basaltkit/core' {
-    interface BasaltHooks {
-        'file:uploaded': {
-            file: FileRecord;
-        };
-        'file:deleted': {
-            tenantId: string;
-            id: string;
-        };
-        'file:scanned': {
-            file: FileRecord;
-        };
-    }
-}
-declare const FILES: _basaltkit_core.Token<Files>;
-interface FilesPluginOptions {
-    /** A `Disk` instance or the name of a disk configured in `@basaltkit/storage`. */
-    disk: Disk | string;
-    store?: FileStore;
-    validate?: FileValidation;
-    maxTotalBytes?: number;
-    checkQuota?: FilesOptions['checkQuota'];
-}
-declare function filesPlugin(options: FilesPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-/**
- * Read/manage routes for the current tenant's files: list, metadata, a signed
- * URL, and delete. Uploading is transport-specific (multipart) — call
- * `FILES.upload(buffer, input)` from your own upload handler.
- */
-declare function fileRoutes(): BasaltRoute[];
-
-export { FILES, FileNotFoundError, type FilePatch, type FileRecord, type FileStore, FileTenantRequiredError, FileTooLargeError, FileTypeNotAllowedError, type FileValidation, Files, type FilesOptions, type FilesPluginOptions, MemoryFileStore, StorageQuotaExceededError, type UploadInput, fileRoutes, filesPlugin };
+export { Files, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, type FilesOptions, type FileValidation, type UploadInput, } from './files.js';
+export { MemoryFileStore, type FileRecord, type FileStore, type FilePatch, } from './store.js';
+export { filesPlugin, fileRoutes, FILES, type FilesPluginOptions } from './plugin.js';

package/dist/index.js

@@ -1,254 +1,3 @@
-// src/files.ts
-import { createHash, randomUUID } from "crypto";
-import { BasaltError, runWithContext, tryCtx } from "@basaltkit/core";
-
-// src/store.ts
-var MemoryFileStore = class {
-  records = /* @__PURE__ */ new Map();
-  key(tenantId, id) {
-    return `${tenantId} ${id}`;
-  }
-  async create(record) {
-    this.records.set(this.key(record.tenantId, record.id), record);
-  }
-  async find(tenantId, id) {
-    return this.records.get(this.key(tenantId, id)) ?? null;
-  }
-  async list(tenantId) {
-    const out = [];
-    for (const record of this.records.values()) if (record.tenantId === tenantId) out.push(record);
-    return out;
-  }
-  async update(tenantId, id, patch) {
-    const record = this.records.get(this.key(tenantId, id));
-    if (!record) return null;
-    Object.assign(record, patch);
-    return record;
-  }
-  async delete(tenantId, id) {
-    this.records.delete(this.key(tenantId, id));
-  }
-  async totalSize(tenantId) {
-    let total = 0;
-    for (const record of this.records.values()) if (record.tenantId === tenantId) total += record.size;
-    return total;
-  }
-};
-
-// src/files.ts
-var FileTooLargeError = class extends BasaltError {
-  status = 413;
-  constructor(size, max) {
-    super("FILE_TOO_LARGE", `File is ${size} bytes; the limit is ${max}.`);
-  }
-};
-var FileTypeNotAllowedError = class extends BasaltError {
-  status = 415;
-  constructor(contentType) {
-    super("FILE_TYPE_NOT_ALLOWED", `Content type "${contentType}" is not allowed.`);
-  }
-};
-var StorageQuotaExceededError = class extends BasaltError {
-  status = 402;
-  constructor() {
-    super("FILE_QUOTA_EXCEEDED", "Storage quota exceeded for this tenant.");
-  }
-};
-var FileNotFoundError = class extends BasaltError {
-  status = 404;
-  constructor() {
-    super("FILE_NOT_FOUND", "File not found.");
-  }
-};
-var FileTenantRequiredError = class extends BasaltError {
-  status = 400;
-  constructor() {
-    super("FILE_TENANT_REQUIRED", "A tenant is required \u2014 pass tenantId or run inside a tenant context.");
-  }
-};
-var matchesType = (contentType, allowed) => allowed.some((a) => a === contentType || a.endsWith("/*") && contentType.startsWith(a.slice(0, -1)));
-var storagePath = (id) => `files/${id}`;
-var Files = class {
-  disk;
-  store;
-  hooks;
-  validation;
-  maxTotalBytes;
-  checkQuota;
-  now;
-  constructor(options) {
-    this.disk = options.disk;
-    this.store = options.store ?? new MemoryFileStore();
-    this.hooks = options.hooks;
-    this.validation = options.validate ?? {};
-    this.maxTotalBytes = options.maxTotalBytes;
-    this.checkQuota = options.checkQuota;
-    this.now = options.now ?? Date.now;
-  }
-  async upload(content, input) {
-    const tenantId = this.tenant(input.tenantId);
-    const size = content.length;
-    this.validate(input.contentType, size);
-    await this.enforceQuota(tenantId, size);
-    const id = randomUUID();
-    const path = storagePath(id);
-    const checksum = createHash("sha256").update(content).digest("hex");
-    await this.inTenant(tenantId, () => this.disk.put(path, content, { contentType: input.contentType }));
-    const record = {
-      id,
-      tenantId,
-      name: input.name,
-      contentType: input.contentType,
-      size,
-      path,
-      checksum,
-      createdAt: this.now(),
-      ...input.uploadedBy !== void 0 ? { uploadedBy: input.uploadedBy } : {},
-      ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
-    };
-    await this.store.create(record);
-    await this.hooks?.emit("file:uploaded", { file: record });
-    return record;
-  }
-  async get(id, tenantId) {
-    return this.store.find(this.tenant(tenantId), id);
-  }
-  async list(tenantId) {
-    return this.store.list(this.tenant(tenantId));
-  }
-  async download(id, tenantId) {
-    const resolved = this.tenant(tenantId);
-    const record = await this.store.find(resolved, id);
-    if (!record) throw new FileNotFoundError();
-    const content = await this.inTenant(resolved, () => this.disk.get(record.path));
-    return { record, content };
-  }
-  async temporaryUrl(id, expiresIn, tenantId) {
-    const resolved = this.tenant(tenantId);
-    const record = await this.store.find(resolved, id);
-    if (!record) throw new FileNotFoundError();
-    return this.inTenant(resolved, () => this.disk.temporaryUrl(record.path, expiresIn));
-  }
-  async delete(id, tenantId) {
-    const resolved = this.tenant(tenantId);
-    const record = await this.store.find(resolved, id);
-    if (!record) return;
-    await this.inTenant(resolved, () => this.disk.delete(record.path));
-    await this.store.delete(resolved, id);
-    await this.hooks?.emit("file:deleted", { tenantId: resolved, id });
-  }
-  /** Records the result of an out-of-band scan (antivirus, moderation, …). */
-  async markScanned(id, result, tenantId) {
-    const resolved = this.tenant(tenantId);
-    const record = await this.store.find(resolved, id);
-    if (!record) throw new FileNotFoundError();
-    const patch = { scanned: true, metadata: { ...record.metadata, scan: result } };
-    const updated = await this.store.update(resolved, id, patch) ?? record;
-    await this.hooks?.emit("file:scanned", { file: updated });
-    return updated;
-  }
-  validate(contentType, size) {
-    if (this.validation.maxSize !== void 0 && size > this.validation.maxSize) {
-      throw new FileTooLargeError(size, this.validation.maxSize);
-    }
-    if (this.validation.allowedTypes && !matchesType(contentType, this.validation.allowedTypes)) {
-      throw new FileTypeNotAllowedError(contentType);
-    }
-  }
-  async enforceQuota(tenantId, size) {
-    if (this.maxTotalBytes !== void 0) {
-      const total = await this.store.totalSize(tenantId);
-      if (total + size > this.maxTotalBytes) throw new StorageQuotaExceededError();
-    }
-    await this.checkQuota?.(tenantId, size);
-  }
-  tenant(explicit) {
-    const id = explicit ?? tryCtx()?.["tenant"]?.id;
-    if (!id) throw new FileTenantRequiredError();
-    return id;
-  }
-  /** Runs a storage op in the resolved tenant's context so the disk scopes correctly. */
-  inTenant(tenantId, fn) {
-    return runWithContext({ tenant: { id: tenantId } }, fn);
-  }
-};
-
-// src/plugin.ts
-import { createToken, ctx, definePlugin } from "@basaltkit/core";
-import { STORAGE } from "@basaltkit/storage";
-import { route } from "@basaltkit/fastify";
-import { z } from "zod";
-var FILES = createToken("files");
-function filesPlugin(options) {
-  return definePlugin({
-    name: "basalt:files",
-    register({ container, hooks }) {
-      container.singleton(FILES, () => {
-        const disk = typeof options.disk === "string" ? container.get(STORAGE).disk(options.disk) : options.disk;
-        return new Files({
-          disk,
-          hooks,
-          ...options.store ? { store: options.store } : {},
-          ...options.validate ? { validate: options.validate } : {},
-          ...options.maxTotalBytes !== void 0 ? { maxTotalBytes: options.maxTotalBytes } : {},
-          ...options.checkQuota ? { checkQuota: options.checkQuota } : {}
-        });
-      });
-    }
-  });
-}
-var files = () => ctx().container.get(FILES);
-function fileRoutes() {
-  return [
-    route({
-      method: "GET",
-      url: "/files",
-      meta: { auth: true },
-      async handler() {
-        return files().list();
-      }
-    }),
-    route({
-      method: "GET",
-      url: "/files/:id",
-      meta: { auth: true },
-      params: z.object({ id: z.string() }),
-      async handler({ params, reply }) {
-        const record = await files().get(params.id);
-        return record ?? reply.code(404).send({ error: { code: "FILE_NOT_FOUND", message: "File not found." } });
-      }
-    }),
-    route({
-      method: "POST",
-      url: "/files/:id/url",
-      meta: { auth: true },
-      params: z.object({ id: z.string() }),
-      body: z.object({ expiresIn: z.string().optional() }).optional(),
-      async handler({ params, body }) {
-        return { url: await files().temporaryUrl(params.id, body?.expiresIn ?? "15m") };
-      }
-    }),
-    route({
-      method: "DELETE",
-      url: "/files/:id",
-      meta: { auth: true },
-      params: z.object({ id: z.string() }),
-      async handler({ params, reply }) {
-        await files().delete(params.id);
-        return reply.code(204).send();
-      }
-    })
-  ];
-}
-export {
-  FILES,
-  FileNotFoundError,
-  FileTenantRequiredError,
-  FileTooLargeError,
-  FileTypeNotAllowedError,
-  Files,
-  MemoryFileStore,
-  StorageQuotaExceededError,
-  fileRoutes,
-  filesPlugin
-};
+export { Files, FileTooLargeError, FileTypeNotAllowedError, StorageQuotaExceededError, FileNotFoundError, FileTenantRequiredError, } from './files.js';
+export { MemoryFileStore, } from './store.js';
+export { filesPlugin, fileRoutes, FILES } from './plugin.js';

package/dist/plugin.d.ts

@@ -0,0 +1,34 @@
+import { type Disk } from '@basaltkit/storage';
+import { type BasaltRoute } from '@basaltkit/fastify';
+import { Files, type FileValidation, type FilesOptions } from './files.js';
+import type { FileRecord, FileStore } from './store.js';
+declare module '@basaltkit/core' {
+    interface BasaltHooks {
+        'file:uploaded': {
+            file: FileRecord;
+        };
+        'file:deleted': {
+            tenantId: string;
+            id: string;
+        };
+        'file:scanned': {
+            file: FileRecord;
+        };
+    }
+}
+export declare const FILES: import("@basaltkit/core").Token<Files>;
+export interface FilesPluginOptions {
+    /** A `Disk` instance or the name of a disk configured in `@basaltkit/storage`. */
+    disk: Disk | string;
+    store?: FileStore;
+    validate?: FileValidation;
+    maxTotalBytes?: number;
+    checkQuota?: FilesOptions['checkQuota'];
+}
+export declare function filesPlugin(options: FilesPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;
+/**
+ * Read/manage routes for the current tenant's files: list, metadata, a signed
+ * URL, and delete. Uploading is transport-specific (multipart) — call
+ * `FILES.upload(buffer, input)` from your own upload handler.
+ */
+export declare function fileRoutes(): BasaltRoute[];

package/dist/plugin.js

@@ -0,0 +1,72 @@
+import { createToken, ctx, definePlugin } from '@basaltkit/core';
+import { STORAGE } from '@basaltkit/storage';
+import { route } from '@basaltkit/fastify';
+import { z } from 'zod';
+import { Files } from './files.js';
+export const FILES = createToken('files');
+export function filesPlugin(options) {
+    return definePlugin({
+        name: 'basalt:files',
+        register({ container, hooks }) {
+            container.singleton(FILES, () => {
+                const disk = typeof options.disk === 'string' ? container.get(STORAGE).disk(options.disk) : options.disk;
+                return new Files({
+                    disk,
+                    hooks,
+                    ...(options.store ? { store: options.store } : {}),
+                    ...(options.validate ? { validate: options.validate } : {}),
+                    ...(options.maxTotalBytes !== undefined ? { maxTotalBytes: options.maxTotalBytes } : {}),
+                    ...(options.checkQuota ? { checkQuota: options.checkQuota } : {}),
+                });
+            });
+        },
+    });
+}
+const files = () => ctx().container.get(FILES);
+/**
+ * Read/manage routes for the current tenant's files: list, metadata, a signed
+ * URL, and delete. Uploading is transport-specific (multipart) — call
+ * `FILES.upload(buffer, input)` from your own upload handler.
+ */
+export function fileRoutes() {
+    return [
+        route({
+            method: 'GET',
+            url: '/files',
+            meta: { auth: true },
+            async handler() {
+                return files().list();
+            },
+        }),
+        route({
+            method: 'GET',
+            url: '/files/:id',
+            meta: { auth: true },
+            params: z.object({ id: z.string() }),
+            async handler({ params, reply }) {
+                const record = await files().get(params.id);
+                return record ?? reply.code(404).send({ error: { code: 'FILE_NOT_FOUND', message: 'File not found.' } });
+            },
+        }),
+        route({
+            method: 'POST',
+            url: '/files/:id/url',
+            meta: { auth: true },
+            params: z.object({ id: z.string() }),
+            body: z.object({ expiresIn: z.string().optional() }).optional(),
+            async handler({ params, body }) {
+                return { url: await files().temporaryUrl(params.id, body?.expiresIn ?? '15m') };
+            },
+        }),
+        route({
+            method: 'DELETE',
+            url: '/files/:id',
+            meta: { auth: true },
+            params: z.object({ id: z.string() }),
+            async handler({ params, reply }) {
+                await files().delete(params.id);
+                return reply.code(204).send();
+            },
+        }),
+    ];
+}

package/dist/store.d.ts

@@ -0,0 +1,40 @@
+/** Metadata for one uploaded file. The bytes live in storage; this is the record. */
+export interface FileRecord {
+    id: string;
+    tenantId: string;
+    /** Original filename. */
+    name: string;
+    contentType: string;
+    /** Size in bytes. */
+    size: number;
+    /** Path within the storage disk. */
+    path: string;
+    /** SHA-256 of the content. */
+    checksum: string;
+    uploadedBy?: string;
+    metadata?: Record<string, unknown>;
+    /** Set by a scanning step (antivirus, etc.) via `markScanned`. */
+    scanned?: boolean;
+    createdAt: number;
+}
+export type FilePatch = Partial<Pick<FileRecord, 'scanned' | 'metadata'>>;
+/** Where file metadata lives — the app's database in production. */
+export interface FileStore {
+    create(record: FileRecord): Promise<void>;
+    find(tenantId: string, id: string): Promise<FileRecord | null>;
+    list(tenantId: string): Promise<FileRecord[]>;
+    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+    /** Total bytes stored by a tenant — used for quota checks. */
+    totalSize(tenantId: string): Promise<number>;
+}
+export declare class MemoryFileStore implements FileStore {
+    private readonly records;
+    private key;
+    create(record: FileRecord): Promise<void>;
+    find(tenantId: string, id: string): Promise<FileRecord | null>;
+    list(tenantId: string): Promise<FileRecord[]>;
+    update(tenantId: string, id: string, patch: FilePatch): Promise<FileRecord | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+    totalSize(tenantId: string): Promise<number>;
+}

package/dist/store.js

@@ -0,0 +1,36 @@
+export class MemoryFileStore {
+    records = new Map();
+    key(tenantId, id) {
+        return `${tenantId} ${id}`;
+    }
+    async create(record) {
+        this.records.set(this.key(record.tenantId, record.id), record);
+    }
+    async find(tenantId, id) {
+        return this.records.get(this.key(tenantId, id)) ?? null;
+    }
+    async list(tenantId) {
+        const out = [];
+        for (const record of this.records.values())
+            if (record.tenantId === tenantId)
+                out.push(record);
+        return out;
+    }
+    async update(tenantId, id, patch) {
+        const record = this.records.get(this.key(tenantId, id));
+        if (!record)
+            return null;
+        Object.assign(record, patch);
+        return record;
+    }
+    async delete(tenantId, id) {
+        this.records.delete(this.key(tenantId, id));
+    }
+    async totalSize(tenantId) {
+        let total = 0;
+        for (const record of this.records.values())
+            if (record.tenantId === tenantId)
+                total += record.size;
+        return total;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/files",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "File uploads for Basalt: validation (type/size), per-tenant storage quota, metadata records, signed URLs, and hooks (antivirus/thumbnails) over @basaltkit/storage.",
   "license": "MIT",
   "type": "module",
@@ -14,19 +14,18 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0",
-    "@basaltkit/storage": "^1.0.0",
-    "@basaltkit/fastify": "^1.0.0"
+    "@basaltkit/core": "^1.1.2",
+    "@basaltkit/storage": "^1.2.1",
+    "@basaltkit/fastify": "^1.6.1"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "zod": "^3.24.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^3.24.0 || ^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -34,11 +33,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/files"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/files#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/files#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -48,7 +47,7 @@
     "storage"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }