@nonext/husk 0.2.3

package/dist/write-limits-Djmm6L3R.d.ts

@@ -0,0 +1,215 @@
+/**
+ * What the media library accepts, in one place.
+ *
+ * This file is the single definition of the allowed MIME types, their file extensions and
+ * their size ceilings. Three things read it and they must not drift apart:
+ *
+ * 1. The upload path in `firebase/media-upload.ts`, which refuses a bad file before it
+ *    spends a customer's bandwidth on it.
+ * 2. The admin's file input, which sets `accept` and says why a file was refused.
+ * 3. `storage.rules` and the `media/{mediaId}` block of `firestore.rules`, which are the
+ *    actual enforcement. A rule cannot import TypeScript, so the two are kept in step by
+ *    `media-constraints.test.ts`, which reads the rules files and fails when a type or a
+ *    limit is present here and absent there.
+ *
+ * It deliberately contains no Firebase import: the constraint is a product rule, not a
+ * storage detail, and the admin has to be able to state it without crossing the adapter
+ * boundary.
+ */
+type MediaCategory = "image" | "video" | "audio" | "document";
+interface MediaTypeRule {
+    /** The exact MIME type. No wildcards: see the note on `image/*` below. */
+    readonly type: string;
+    readonly category: MediaCategory;
+    readonly maxBytes: number;
+    /** Lowercase, with the dot. The first one is what a sanitized name is given. */
+    readonly extensions: readonly string[];
+}
+/**
+ * The hard ceiling, whatever the type. Large enough for a brochure or a short clip, small
+ * enough that one mistaken upload cannot fill a customer's bucket.
+ */
+declare const MAX_MEDIA_BYTES: number;
+/**
+ * Images are held to a lower ceiling than the rest.
+ *
+ * A 25 MB image is never what a website wants, and since Husk stores originals only (see
+ * .docs/decisions/2026-09-18-media-variants.md) the original is what a visitor's browser
+ * eventually fetches. The limit is the one place that fact is enforced rather than hoped
+ * for.
+ */
+declare const MAX_IMAGE_BYTES: number;
+/**
+ * The allowlist.
+ *
+ * Note what is missing, because each absence is a decision rather than an oversight:
+ *
+ * - `image/svg+xml`. An SVG is a script container. It is served from the Storage host, so
+ *   it cannot reach a customer's own origin, but it can still be handed to a visitor as an
+ *   executable document under the customer's brand. Nothing in the CMS needs it.
+ * - `image/tiff`, `image/bmp`, `video/quicktime`. No browser renders the first two and the
+ *   third is a phone-camera container that no `<video>` tag can be pointed at. A file that
+ *   cannot be displayed on the site it was uploaded for is a support ticket in waiting.
+ * - Everything else, including archives and office documents. Adding one is a line here,
+ *   a line in `storage.rules`, and a test; that friction is the point.
+ */
+declare const ALLOWED_MEDIA_TYPES: readonly MediaTypeRule[];
+/** Value for an `<input type="file">` accept attribute. The UI courtesy, not the rule. */
+declare const MEDIA_ACCEPT_ATTRIBUTE: string;
+/**
+ * The rule for a declared MIME type, or null when the type is not accepted.
+ *
+ * Parameters are stripped (`text/plain; charset=utf-8`) and the type is lowercased, because
+ * a browser is free to report either form and neither is the user's doing.
+ */
+declare function mediaTypeRule(type: string): MediaTypeRule | null;
+declare function normalizeMediaType(type: string): string;
+/** The extension including the dot, lowercased, or the empty string when there is none. */
+declare function fileExtension(name: string): string;
+type MediaRejectionCode = "type-not-allowed" | "too-large" | "empty" | "extension-mismatch";
+interface MediaRejection {
+    code: MediaRejectionCode;
+    /** Written for an editor to read, because it is what the upload row will show. */
+    message: string;
+}
+interface MediaFileFacts {
+    name: string;
+    type: string;
+    size: number;
+}
+/**
+ * Why this file may not be uploaded, or null when it may.
+ *
+ * Every check here is repeated in `storage.rules`. This one exists so a refusal is
+ * immediate and explains itself; the rule exists because this one runs on the client and a
+ * client can be replaced.
+ */
+declare function checkMediaFile(file: MediaFileFacts): MediaRejection | null;
+/**
+ * A file name safe to put in a Storage path.
+ *
+ * Lowercased, stripped of anything outside `[a-z0-9._-]`, with the extension preserved
+ * because the rules match on it. A name that sanitizes to nothing becomes `file`, so an
+ * upload never produces an object path ending in a bare dot.
+ */
+declare function safeFileName(name: string, type: string): string;
+
+/**
+ * What a single write may weigh, and how often one document may be written.
+ *
+ * Two layers, and they are not the same strength. Be exact about which is which:
+ *
+ * - **Enforced by firestore.rules.** The top-level field count of an incoming document,
+ *   and a minimum interval between two writes to the same document. A rule can see both,
+ *   so a client that skips the adapter is still refused. The numbers live here and are
+ *   repeated in firestore.rules, because a rules file cannot import.
+ * - **Enforced by the adapter only.** Estimated document size, nesting depth, array
+ *   length, and the burst limiter below. A Firestore rule cannot see the byte size of a
+ *   document and cannot count a caller's writes across documents, so these catch a
+ *   mistake and refuse it with a message a person can act on. They are not a guarantee
+ *   against a determined client holding a Firebase config: that client's real ceiling is
+ *   Firestore's own 1 MiB per document and the per-document floor in the rules.
+ *
+ * The two do not overlap, deliberately. The adapter does not repeat the per-document
+ * interval: the rules already refuse that write, repeating it here would only move the
+ * refusal earlier for callers who never needed it, and a legitimate script that creates an
+ * entry and immediately corrects it would be stopped by Husk before the database had a
+ * chance to say yes. Each guard lives at exactly one layer, and it is the layer that can
+ * see the thing it is guarding.
+ *
+ * Anything a customer can hit by accident should fail here, with a sentence naming the
+ * field, rather than at Firestore with `INVALID_ARGUMENT`.
+ */
+/** Firestore's own hard ceiling for one document. Nothing here may exceed it. */
+declare const FIRESTORE_DOCUMENT_BYTES = 1048576;
+/**
+ * Husk's ceiling, deliberately under Firestore's.
+ *
+ * The gap is headroom for the fields the adapter adds after the values are measured
+ * (`mediaRefs`, the audit stamps, the status) plus the difference between the estimate
+ * below and Firestore's own accounting, which counts field names and type tags.
+ */
+declare const MAX_WRITE_BYTES = 900000;
+/** Top-level fields on an entry document. Mirrored in firestore.rules. */
+declare const MAX_ENTRY_FIELDS = 200;
+/** Fields on one content type. Mirrored in firestore.rules on `schemas/{slug}`. */
+declare const MAX_CONTENT_TYPE_FIELDS = 100;
+/** Top-level keys of one settings document. Mirrored in firestore.rules. */
+declare const MAX_SETTINGS_FIELDS = 100;
+/** Firestore refuses deeper nesting than this, so refusing it here names the cause. */
+declare const MAX_NESTING_DEPTH = 20;
+/** Items in one stored array, which in practice is a repeater or a multi-relation. */
+declare const MAX_ARRAY_ITEMS = 1000;
+/**
+ * The floor between two writes to the same document. Mirrored in firestore.rules.
+ *
+ * Chosen so a human cannot reach it and a loop cannot ignore it: 200 ms throttles a
+ * runaway client to five writes a second on one document, while the fastest a person can
+ * meaningfully save the same entry twice is an order of magnitude slower.
+ */
+declare const MIN_WRITE_INTERVAL_MS = 200;
+/**
+ * The adapter-side burst window: at most this many writes in this many milliseconds.
+ *
+ * A loop detector, not a quota. It has to sit above everything the product does on
+ * purpose, and the product does bulk writes: a media replace rewrites the url on up to 500
+ * referencing entries, a field purge clears 250, a migration batch moves 50. Twenty writes
+ * a second is far past any of those and still nowhere near a runaway loop, which does
+ * thousands. Set it too low and the first thing it breaks is a legitimate operation.
+ */
+declare const WRITE_BURST_LIMIT = 200;
+declare const WRITE_BURST_WINDOW_MS = 10000;
+type WriteLimitCode = "too-many-fields" | "too-large" | "too-deep" | "too-many-items" | "too-fast";
+interface WriteLimitRejection {
+    code: WriteLimitCode;
+    /** Dotted path to the offending value, or "" when the document as a whole is at fault. */
+    path: string;
+    message: string;
+}
+/**
+ * A rough byte count for a value on its way to Firestore.
+ *
+ * Deliberately an estimate. Firestore's accounting adds the field name plus one byte per
+ * value and counts strings as UTF-8 plus one, and reproducing it exactly would be a second
+ * implementation to keep in step for no gain: the number is used against a ceiling that is
+ * already 148 KB below the real one. What it must not do is undercount badly, which is why
+ * strings are measured in UTF-8 bytes rather than in code units.
+ */
+declare function approximateBytes(value: unknown): number;
+interface PayloadLimits {
+    /** Top-level field cap. Defaults to the entry cap. */
+    maxFields?: number;
+    /** Byte ceiling. Defaults to MAX_WRITE_BYTES. */
+    maxBytes?: number;
+}
+/**
+ * Checks one document's worth of values. Returns the first problem, or null.
+ *
+ * First problem rather than all of them on purpose: these are not field validation errors
+ * a form routes to inputs, they are a refusal to write at all, and the caller shows one
+ * sentence. Field validation already ran; this is the guard behind it.
+ */
+declare function checkWritePayload(values: Record<string, unknown>, limits?: PayloadLimits): WriteLimitRejection | null;
+/** Reads a clock. Injected so a test does not have to sleep to cross a window. */
+type Clock = () => number;
+interface WriteRateLimiter {
+    /**
+     * Records an attempted write and says whether it is refused.
+     *
+     * One question only: is this process writing faster than anything but a loop would? The
+     * per-document interval is not asked here, because firestore.rules asks it of every
+     * write whether or not it came through this adapter.
+     */
+    check(): WriteLimitRejection | null;
+}
+/**
+ * The adapter's burst guard.
+ *
+ * Honest about what it is: one process's memory. A second tab has its own, and a script
+ * holding the customer's Firebase config has none at all. It exists to turn a runaway loop
+ * in the admin into one clear refusal instead of a few thousand writes and a bill, and the
+ * rules-side per-document floor is what covers the case this cannot see.
+ */
+declare function createWriteRateLimiter(clock?: Clock): WriteRateLimiter;
+
+export { ALLOWED_MEDIA_TYPES as A, type Clock as C, FIRESTORE_DOCUMENT_BYTES as F, MAX_ARRAY_ITEMS as M, type PayloadLimits as P, WRITE_BURST_LIMIT as W, MAX_CONTENT_TYPE_FIELDS as a, MAX_ENTRY_FIELDS as b, MAX_IMAGE_BYTES as c, MAX_MEDIA_BYTES as d, MAX_NESTING_DEPTH as e, MAX_SETTINGS_FIELDS as f, MAX_WRITE_BYTES as g, MEDIA_ACCEPT_ATTRIBUTE as h, MIN_WRITE_INTERVAL_MS as i, type MediaCategory as j, type MediaFileFacts as k, type MediaRejection as l, type MediaRejectionCode as m, type MediaTypeRule as n, WRITE_BURST_WINDOW_MS as o, type WriteLimitCode as p, type WriteLimitRejection as q, type WriteRateLimiter as r, approximateBytes as s, checkMediaFile as t, checkWritePayload as u, createWriteRateLimiter as v, fileExtension as w, mediaTypeRule as x, normalizeMediaType as y, safeFileName as z };

package/package.json

@@ -0,0 +1,136 @@
+{
+  "name": "@nonext/husk",
+  "version": "0.2.3",
+  "private": false,
+  "description": "Nonext CMS (Husk): schema-driven CMS for Next.js and Firebase",
+  "license": "PolyForm-Shield-1.0.0",
+  "author": "Nonext",
+  "homepage": "https://github.com/nonext-at/nonext-husk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nonext-at/nonext-husk.git",
+    "directory": "packages/cms"
+  },
+  "bugs": {
+    "url": "https://github.com/nonext-at/nonext-husk/issues"
+  },
+  "keywords": [
+    "cms",
+    "nextjs",
+    "firebase",
+    "firestore",
+    "headless-cms"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "bin": {
+    "nonext-husk": "./dist/cli/nonext-husk.js"
+  },
+  "files": [
+    "dist",
+    "api/public-api.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./admin/ui": {
+      "types": "./dist/admin/ui.d.ts",
+      "default": "./dist/admin/ui.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./permissions": {
+      "types": "./dist/permissions/index.d.ts",
+      "default": "./dist/permissions/index.js"
+    },
+    "./firebase": {
+      "types": "./dist/firebase/index.d.ts",
+      "default": "./dist/firebase/index.js"
+    },
+    "./richtext": {
+      "types": "./dist/richtext/index.d.ts",
+      "default": "./dist/richtext/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/types/index.js"
+    },
+    "./admin.css": "./dist/admin/admin.css"
+  },
+  "peerDependencies": {
+    "firebase": "^12.0.0",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "firebase": "^12.19.0",
+    "next": "^16.3.5",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.31.3",
+    "@tiptap/extension-blockquote": "^3.31.3",
+    "@tiptap/extension-bold": "^3.31.3",
+    "@tiptap/extension-document": "^3.31.3",
+    "@tiptap/extension-hard-break": "^3.31.3",
+    "@tiptap/extension-heading": "^3.31.3",
+    "@tiptap/extension-italic": "^3.31.3",
+    "@tiptap/extension-link": "^3.31.3",
+    "@tiptap/extension-list": "^3.31.3",
+    "@tiptap/extension-paragraph": "^3.31.3",
+    "@tiptap/extension-strike": "^3.31.3",
+    "@tiptap/extension-text": "^3.31.3",
+    "@tiptap/extensions": "^3.31.3",
+    "@tiptap/pm": "^3.31.3",
+    "@tiptap/react": "^3.31.3",
+    "@tiptap/static-renderer": "3.31.3",
+    "lucide": "1.47.0",
+    "lucide-react": "^1.47.0",
+    "morphicons": "^1.7.1"
+  },
+  "scripts": {
+    "build": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "typecheck": "tsc --noEmit",
+    "api": "node scripts/write-public-api.mjs"
+  }
+}