@basaltkit/files 1.1.0 → 1.1.1

package/README.md

@@ -81,17 +81,30 @@ await files.markScanned(id, { clean: true }, tenantId) // emits file:scanned
 
 ## API reference
 
-### `filesPlugin(options)`
+### Options reference
 
-| Option | Type | Description |
-|---|---|---|
-| `disk` | `Disk \| string` | A `Disk` instance or the name of a `@basaltkit/storage` disk. |
-| `validate` | `{ maxSize?, allowedTypes? }` | Size limit and allowed types (`image/*` accepts wildcards). |
-| `maxTotalBytes` | `number` | Total quota per tenant. |
-| `checkQuota` | `(tenantId, size) => void` | Custom quota check (e.g. hook into `@basaltkit/subscriptions`). Throw to reject. |
-| `store` | `FileStore` | Metadata persistence. Default: in-memory. |
+`filesPlugin(options)` — registers a `Files` singleton under the `FILES` token:
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `disk` | `Disk \| string` | — (required) | A `Disk` instance, or the name of a disk declared in `storagePlugin`. A string is resolved from the `STORAGE` token at first use. |
+| `validate` | `FileValidation` | `{ maxSize: DEFAULT_MAX_FILE_SIZE }` | Size limit and content-type allowlist. See below — the size cap applies **even if you pass nothing**. |
+| `maxTotalBytes` | `number` | — (no quota) | Built-in per-tenant quota: rejects an upload when the tenant's stored bytes plus this file would exceed it. Costs one `store.totalSize()` read per upload. |
+| `checkQuota` | `(tenantId, size) => Promise<void> \| void` | — | Custom quota check, run after the built-in one. Throw to reject — this is where you wire `@basaltkit/subscriptions` plan limits. |
+| `store` | `FileStore` | `MemoryFileStore` | Where file metadata lives. In-memory means records vanish on restart while the bytes stay in storage — implement `FileStore` over your database in production. |
+
+`FileValidation`:
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `maxSize` | `number` | `DEFAULT_MAX_FILE_SIZE` = **25 MiB** (`26214400`) | Per-file byte cap. Secure by default: uploads are capped even when you configure nothing. Raise it, or pass `Infinity` to disable. |
+| `allowedTypes` | `string[]` | — (anything) | Content-type allowlist. Supports trailing wildcards: `'image/*'` matches `image/png`. |
 
-Registers the `FILES` token.
+`DEFAULT_MAX_FILE_SIZE` is exported, so you can express a limit relative to it.
+
+> The cap applies to the buffer you hand to `upload()`. Your HTTP adapter's own
+> body limit still applies first, and `@basaltkit/storage` itself caps nothing
+> unless you pass `maxBytes` per `put()`.
 
 ### `class Files`
 
@@ -99,14 +112,46 @@ Registers the `FILES` token.
 |---|---|
 | `upload(content, input)` | Validates, enforces quota, stores, records metadata, emits `file:uploaded`. |
 | `download(id, tenantId?)` | `{ record, content }`. |
-| `temporaryUrl(id, expiresIn, tenantId?)` | Signed URL. |
+| `temporaryUrl(id, expiresIn, tenantId?, options?)` | Signed URL. Served `Content-Disposition: attachment` by default; pass `{ disposition: 'inline' }` only when top-level rendering is deliberate — an uploaded HTML/SVG file served inline is stored XSS on the storage origin. Embedded `<img>`/`<video>` uses render regardless. |
 | `get(id, tenantId?)` · `list(tenantId?)` | Metadata. |
 | `delete(id, tenantId?)` | Deletes bytes + metadata; emits `file:deleted`. |
 | `markScanned(id, result, tenantId?)` | Marks as scanned; emits `file:scanned`. |
 
 Without an explicit `tenantId`, it uses `ctx().tenant.id`; without a tenant, it throws `FileTenantRequiredError`. Storage access runs in the resolved tenant's context, so files stay isolated even from a background job.
 
-Errors: `FileTooLargeError` (413), `FileTypeNotAllowedError` (415), `StorageQuotaExceededError` (402), `FileNotFoundError` (404).
+### Failure modes
+
+| Error | Code | HTTP | When |
+|---|---|---|---|
+| `FileTooLargeError` | `FILE_TOO_LARGE` | 413 | The buffer exceeds `validate.maxSize` — 25 MiB when you configured nothing. |
+| `FileTypeNotAllowedError` | `FILE_TYPE_NOT_ALLOWED` | 415 | `contentType` doesn't match `validate.allowedTypes`. |
+| `StorageQuotaExceededError` | `FILE_QUOTA_EXCEEDED` | 402 | The tenant's total stored bytes plus this upload would pass `maxTotalBytes`. |
+| `FileNotFoundError` | `FILE_NOT_FOUND` | 404 | `download` / `temporaryUrl` / `markScanned` for an id absent from this tenant's metadata store. |
+| `FileTenantRequiredError` | `FILE_TENANT_REQUIRED` | 400 | No `tenantId` argument and no `ctx().tenant` — every operation is tenant-scoped and fails closed rather than querying unscoped. |
+
+All extend `BasaltError` and declare a `status`, so the adapters map them to the
+HTTP code above with the real error `code` in the body. Errors thrown by the
+underlying disk (`STORAGE_*`) do **not** — they surface as 500 `INTERNAL_ERROR`.
+
+- **`FILE_NOT_FOUND` for a file that exists in the bucket** — the metadata
+  record is gone, not the bytes. `MemoryFileStore` loses everything on restart;
+  wire a durable `FileStore`.
+- **`FILE_TOO_LARGE` at exactly 25 MiB** — that's the default, not your adapter.
+  Set `validate: { maxSize: … }`.
+- **`FILE_TENANT_REQUIRED` inside a queue job** — jobs don't inherit the request
+  context. Pass `tenantId` explicitly, or run the job body inside
+  `tenancy.run(tenantId, …)`.
+
+### Hooks & events
+
+| Hook | Payload | When |
+|---|---|---|
+| `file:uploaded` | `{ file: FileRecord }` | After the bytes are written and the metadata recorded. |
+| `file:deleted` | `{ tenantId: string; id: string }` | After the bytes and the record are removed. |
+| `file:scanned` | `{ file: FileRecord }` | After `markScanned()` records an out-of-band scan result. |
+
+They are declared on `BasaltHooks`, so `hooks.on('file:uploaded', …)` is fully
+typed.
 
 ## How it connects to other modules
 
@@ -114,3 +159,5 @@ Errors: `FileTooLargeError` (413), `FileTypeNotAllowedError` (415), `StorageQuot
 - **`@basaltkit/subscriptions`** — hook `checkQuota` into `features(tenant).consume(...)` for plan-based quotas.
 - **`@basaltkit/queue`** — processes `file:uploaded` outside the request (antivirus, thumbnails).
 - **`@basaltkit/tenancy`** — supplies the tenant from the context.
+
+Guides: [Files & uploads](/guide/files) · [Storage](/guide/storage) · [Queues](/guide/queues).

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/files",
-  "version": "1.1.0",
+  "version": "1.1.1",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "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",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,9 +18,9 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.3.0",
-    "@basaltkit/http": "^1.10.0",
-    "@basaltkit/storage": "^1.3.0"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/http": "^1.14.0",
+    "@basaltkit/storage": "^1.3.1"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"
@@ -26,7 +30,7 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "zod": "^3.24.0 || ^4.0.0",
-    "@basaltkit/fastify": "^1.7.0",
+    "@basaltkit/fastify": "^1.8.1",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {