Initial Commit

packages/api-stack/api/api-plugin-file-upload/src/schemas/options.md

@@ -0,0 +1,51 @@
+# `options.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the Zod schema validating caller-supplied `FileUploadPluginOptions`. Invalid input — wrong type, malformed `basePath`, non-positive limits, non-conforming `storage`/`sessionStore` shapes — throws `FileUploadError(UPLOAD.INVALID_INPUT)` at the `createFileUploadPlugin` boundary so misconfiguration fails fast at boot rather than at first request.
+
+## Features
+
+- `basePath` regex matches Hono's mount rules: starts with `/`, never ends with `/` except the root.
+- Default `singleShotLimitBytes` of 10 MiB, `maxFileSizeBytes` of 1 GiB, `defaultChunkSize` of 5 MiB, `sessionTtlMs` of 24 h.
+- Default MIME denylist covers common native-executable formats so a default-configured deployment refuses obvious malware delivery vectors.
+- `storage`, `sessionStore`, and `logger` validated structurally via `z.custom` (they are runtime objects).
+- Exports both the input shape (what callers pass) and the resolved shape (what the descriptor stores).
+
+## Usage: Basic
+
+```ts
+import { FileUploadPluginOptionsSchema } from "@suaveplan/api-plugin-file-upload/schemas/options";
+
+const config = FileUploadPluginOptionsSchema.parse({ basePath: "/files" });
+```
+
+## Usage: Advanced
+
+```ts
+import { FileUploadPluginOptionsSchema } from "@suaveplan/api-plugin-file-upload";
+import { MemoryUploadStorage } from "@suaveplan/api-plugin-file-upload/storage/memory";
+
+const config = FileUploadPluginOptionsSchema.parse({
+    basePath: "/api/v1/uploads",
+    singleShotLimitBytes: 5 * 1024 * 1024,
+    allowedMimeTypes: ["image/png", "image/jpeg", "application/pdf"],
+    storage: new MemoryUploadStorage(),
+});
+```
+
+## API Reference
+
+- `FileUploadPluginOptionsSchema` — Zod object schema.
+- `FileUploadPluginOptionsInput` — `z.input` type, what callers may pass.
+- `FileUploadPluginOptionsResolved` — `z.output` type, post-default shape.
+
+## Implementation Notes
+
+- The schema applies defaults rather than rejecting missing fields — calling `createFileUploadPlugin({})` is a valid (development) configuration. The defaults match the hardening baseline (executable denylist on, generous size caps, 24 h TTL).
+- `allowedMimeTypes` empty defaults to "no allow-list" (everything except the denylist). Setting any value flips to "exclusive allow" semantics — the validator rejects anything not in the array.
+- The `z.custom` structural checks for `storage`/`sessionStore`/`logger` accept any object exposing the expected duck-typed methods; full interface conformance is enforced at the consumer call site by TypeScript when the package's exported types are imported.