@pramen/cms 0.0.61 → 0.0.63

package/README.md

@@ -126,6 +126,34 @@ entry, so doing it there made the returned array stop matching the `as const` li
   the tenant's `media/` prefix); the client PUTs the bytes, then `createMedia({ ref, alt? })`
   confirms the blob is in R2 and persists a `cms_media` row. `listMedia`/`getMedia`/`deleteMedia`
   (deleteMedia also removes the R2 blob) round it out. Editor-gated.
+- **Browsing:** `listMedia({ limit, offset, q?, sort?, kind?, term? })`. `q` matches the filename **or**
+  the alt text (case-insensitive; a `%` or `_` in the needle is a literal), `sort` is one of
+  `newest`/`oldest`/`name`/`name_desc`/`largest`/`smallest`, and `kind` narrows to
+  `image`/`video`/`audio`/`document`/`other`. All three are applied in SQL rather than to the
+  page that arrived, so they mean what they say on a library larger than one page. `sort` and
+  `kind` are closed vocabularies — a caller never names a column — and an unrecognised value
+  falls back to the default instead of erroring.
+
+  This is what `cms_media.filename`/`contentType`/`size` are for: `file` is a `fileRef` (JSON in
+  a TEXT cell), which `orderBy` and `where` cannot see into, so the three fields the library
+  queries by are projected onto indexed columns when a row is created. **Spread `cmsMigrations`
+  into `app.migrations`** to backfill rows written before those columns existed — without it
+  they keep NULL, sort together under a name sort, and answer only the `other` filter.
+- **Tagging:** files carry taxonomy terms from the same `cms_taxonomies`/`cms_terms` tables pages
+  use, through a `cms_media_terms` junction — one vocabulary, edited in one place, applied to
+  whichever of the two it declares. A vocabulary carries **`appliesTo`** — `["page"]`,
+  `["media"]`, both, or `null` for everything (which is what an un-narrowed one, and every row
+  written before the column existed, means). `listTaxonomies({ target })` narrows to it, and
+  `setPageTerms`/`setMediaTerms` REFUSE a term from a vocabulary that does not apply, so it is a
+  rule rather than a UI hint. Narrowing a vocabulary away from something it is still assigned to
+  is refused too — those assignments would stay stored and stop being reachable from the panel
+  that could remove them. `listMediaTerms({ mediaId })` reads a file's terms and `setMediaTerms({ mediaId, termIds })`
+  replaces them wholesale (set semantics, like `setPageTerms`); `listMedia({ term })` filters by
+  one, ANDed with `kind` and `q`. The filter is a relation traversal compiled to a subquery, so
+  it narrows in SQL like every other option here. Deleting a term takes its assignments with it
+  (a real `ON DELETE CASCADE`), and trashing a file does NOT — only `purgeMedia` does, so a
+  restored file keeps its tags. Declared to the editor as
+  `listCmsCapabilities().mediaTerms`.
 - **Reference from a block:** a `"media"` field stores a `cms_media` id. At assemble/publish time
   the id is resolved (recursively, through group/repeater nesting) to a `ResolvedMedia`
   `{ id, key, url, alt, contentType, filename }` in the snapshot — so the content API returns a
@@ -195,6 +223,12 @@ authorization. Spread `cmsRoutes()` into `app.routes` to serve `GET /cms/preview
 verifies the token in the Worker before any read and returns the live draft with
 `isPreview: true` and `Cache-Control: private, no-store`.
 
+That route answers with **JSON** — this CMS is headless, so it has the draft and no idea what
+it should look like. Your site renders it: redeem the same token with `client.getPreview(token)`
+(`@pramen/cms-astro`) from a route of your own, through the same components the published page
+uses, and point the editor's Preview link button at it with `admin.previewUrl`. A working one
+is `example/site/src/pages/preview.astro`.
+
 If you pass custom roles to `createCmsHandlers`, hand `cmsRoutes` the **same options
 object** — it derives the route's identity from them, so the two cannot drift:
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue, SchemaDef } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, DataMigration, JsonValue, SchemaDef } from "@pramen/server";
 import type { EnvBag } from "@pramen/server";
 /** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
  * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
@@ -887,6 +887,9 @@ export declare const cmsSchema: {
         } & {
             readonly default: false;
         };
+        appliesTo: {
+            readonly type: "json";
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -953,6 +956,11 @@ export declare const cmsSchema: {
             readonly target: "cms_page_terms";
             readonly column: string;
         };
+        media: {
+            readonly kind: "hasMany";
+            readonly target: "cms_media_terms";
+            readonly column: string;
+        };
     }>;
     cms_page_terms: import("@pramen/server").EntityDef<{
         id: {
@@ -991,6 +999,43 @@ export declare const cmsSchema: {
             readonly onDelete: import("@pramen/server").OnDelete | undefined;
         };
     }>;
+    cms_media_terms: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        mediaId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        termId: {
+            readonly type: "uuid";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+    }, {
+        media: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_media";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+        term: {
+            readonly kind: "belongsTo";
+            readonly target: "cms_terms";
+            readonly column: string;
+            readonly onDelete: import("@pramen/server").OnDelete | undefined;
+        };
+    }>;
     cms_widget_areas: import("@pramen/server").EntityDef<{
         id: {
             readonly type: "uuid";
@@ -1046,6 +1091,19 @@ export declare const cmsSchema: {
         file: {
             readonly type: "fileRef";
         };
+        filename: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
+        contentType: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
+        size: {
+            readonly type: "integer";
+        };
         alt: {
             readonly type: "text";
         };
@@ -1059,8 +1117,36 @@ export declare const cmsSchema: {
         } & {
             readonly defaultExpr: string;
         };
-    }, Record<string, never>>;
+    }, {
+        terms: {
+            readonly kind: "manyToMany";
+            readonly target: "cms_terms";
+            readonly through: string;
+            readonly sourceColumn: string;
+            readonly targetColumn: string;
+        };
+    }>;
 };
+/** How a media list may be ordered. */
+export type MediaSort = "newest" | "oldest" | "name" | "name_desc" | "largest" | "smallest";
+/** The coarse type buckets the library filters by — the first segment of a MIME type, which
+ * is the distinction someone browsing a library actually makes ("show me the images"). */
+export declare const MEDIA_KINDS: readonly ["image", "video", "audio", "document", "other"];
+export type MediaKind = (typeof MEDIA_KINDS)[number];
+/** The object types a vocabulary can be applied to. A CLOSED vocabulary, like `MEDIA_KINDS`:
+ * it decides which panels offer a taxonomy AND which assignments are accepted, so an unknown
+ * value must not be storable. */
+export declare const TAXONOMY_TARGETS: readonly ["page", "media"];
+export type TaxonomyTarget = (typeof TAXONOMY_TARGETS)[number];
+/** Whether a vocabulary applies to `target`.
+ *
+ * The permissive readings all collapse to TRUE, deliberately: NULL (never narrowed, or written
+ * before the column existed), a non-array, an array of things that are not targets. A stored
+ * value nobody can interpret must not silently stop a vocabulary from working — the failure
+ * would be a taxonomy that has quietly vanished from every panel, with the row still there. */
+export declare function taxonomyApplies(row: {
+    appliesTo?: unknown;
+}, target: TaxonomyTarget): boolean;
 /** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
  * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
 export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
@@ -1478,28 +1564,48 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     }, {
         ok: true;
     }>;
-    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
-     * is a URL segment) and a front end routes on it. */
-    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Every vocabulary, or just the ones that classify `target`. PUBLIC — like content
+     * types, a taxonomy's slug is structural (it is a URL segment) and a front end routes on
+     * it.
+     *
+     * Narrowed HERE rather than in each caller, so the page panel, the media panel and the
+     * write-side guard cannot disagree about what a vocabulary applies to. In memory, because
+     * `appliesTo` is a `t.json()` column that `where` cannot see into — which costs nothing:
+     * this handler already reads every taxonomy, and nothing pages by them.
+     *
+     * No `target` means EVERY vocabulary, which is what the Taxonomies screen needs: the one
+     * place that edits `appliesTo` must be able to see a vocabulary it has narrowed away. */
+    listTaxonomies: import("@pramen/server").Handler<{
+        target?: TaxonomyTarget;
+    }, Record<string, unknown>[]>;
     createTaxonomy: import("@pramen/server").Handler<{
         slug: string;
         label: string;
         pluralLabel?: string;
         description?: string;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown>>;
     /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
      * is not mutable — the same rule content types and block types already follow.
      *
      * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
      * would leave a stored hierarchy that no reader renders and no writer can clear, and
-     * flattening the terms silently is a destructive edit behind a checkbox. */
+     * flattening the terms silently is a destructive edit behind a checkbox.
+     *
+     * NARROWING `appliesTo` is refused on exactly the same grounds, and it is the same bug:
+     * dropping a target this vocabulary is already used for would strand those assignments —
+     * still stored, still returned by `listPageTerms`/`listMediaTerms`, but invisible in the
+     * panel that could remove them, because the panel only renders vocabularies that apply.
+     * Unassign them first; then the narrowing is a settings change rather than a silent
+     * orphaning. WIDENING is always fine — it strands nothing. */
     updateTaxonomy: import("@pramen/server").Handler<{
         id: string;
         label?: string;
         pluralLabel?: string | null;
         description?: string | null;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown> | undefined>;
     /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
      * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
@@ -1617,6 +1723,10 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     listMedia: import("@pramen/server").Handler<{
         limit?: number;
         offset?: number;
+        sort?: MediaSort;
+        kind?: MediaKind;
+        q?: string;
+        term?: string;
     }, Record<string, unknown>[]>;
     getMedia: import("@pramen/server").Handler<{
         id: string;
@@ -1626,6 +1736,25 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
+    /** A media asset's assigned terms.
+     *
+     * The media row is read FIRST, through `ctx.db`, so the caller's own scope decides
+     * whether this answers — the junction and `cms_terms` are granted unscoped, so without
+     * it anyone holding an id could read a TRASHED file's tags and the non-empty answer
+     * would confirm the file exists. Same rule as `listPageTerms`, for the same reason. */
+    listMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+    }, Term[]>;
+    /** Replace a media asset's term assignments wholesale — set semantics, like
+     * `setPageTerms`, and for the same reason: the panel holds the whole selection, and two
+     * calls each patching one end of it race into a state neither asked for. */
+    setMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
     /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
      * `restoreMedia` a lie, and a block still referencing the id would render a dead url
      * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
@@ -1787,6 +1916,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         pagesByType: true;
         siteFurniture: true;
         codeDefinedTypes: true;
+        mediaTerms: true;
         canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
@@ -2077,28 +2207,48 @@ export declare const cmsHandlers: {
     }, {
         ok: true;
     }>;
-    /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
-     * is a URL segment) and a front end routes on it. */
-    listTaxonomies: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Every vocabulary, or just the ones that classify `target`. PUBLIC — like content
+     * types, a taxonomy's slug is structural (it is a URL segment) and a front end routes on
+     * it.
+     *
+     * Narrowed HERE rather than in each caller, so the page panel, the media panel and the
+     * write-side guard cannot disagree about what a vocabulary applies to. In memory, because
+     * `appliesTo` is a `t.json()` column that `where` cannot see into — which costs nothing:
+     * this handler already reads every taxonomy, and nothing pages by them.
+     *
+     * No `target` means EVERY vocabulary, which is what the Taxonomies screen needs: the one
+     * place that edits `appliesTo` must be able to see a vocabulary it has narrowed away. */
+    listTaxonomies: import("@pramen/server").Handler<{
+        target?: TaxonomyTarget;
+    }, Record<string, unknown>[]>;
     createTaxonomy: import("@pramen/server").Handler<{
         slug: string;
         label: string;
         pluralLabel?: string;
         description?: string;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown>>;
     /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
      * is not mutable — the same rule content types and block types already follow.
      *
      * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
      * would leave a stored hierarchy that no reader renders and no writer can clear, and
-     * flattening the terms silently is a destructive edit behind a checkbox. */
+     * flattening the terms silently is a destructive edit behind a checkbox.
+     *
+     * NARROWING `appliesTo` is refused on exactly the same grounds, and it is the same bug:
+     * dropping a target this vocabulary is already used for would strand those assignments —
+     * still stored, still returned by `listPageTerms`/`listMediaTerms`, but invisible in the
+     * panel that could remove them, because the panel only renders vocabularies that apply.
+     * Unassign them first; then the narrowing is a settings change rather than a silent
+     * orphaning. WIDENING is always fine — it strands nothing. */
     updateTaxonomy: import("@pramen/server").Handler<{
         id: string;
         label?: string;
         pluralLabel?: string | null;
         description?: string | null;
         hierarchical?: boolean;
+        appliesTo?: TaxonomyTarget[] | null;
     }, Record<string, unknown> | undefined>;
     /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
      * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
@@ -2216,6 +2366,10 @@ export declare const cmsHandlers: {
     listMedia: import("@pramen/server").Handler<{
         limit?: number;
         offset?: number;
+        sort?: MediaSort;
+        kind?: MediaKind;
+        q?: string;
+        term?: string;
     }, Record<string, unknown>[]>;
     getMedia: import("@pramen/server").Handler<{
         id: string;
@@ -2225,6 +2379,25 @@ export declare const cmsHandlers: {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
+    /** A media asset's assigned terms.
+     *
+     * The media row is read FIRST, through `ctx.db`, so the caller's own scope decides
+     * whether this answers — the junction and `cms_terms` are granted unscoped, so without
+     * it anyone holding an id could read a TRASHED file's tags and the non-empty answer
+     * would confirm the file exists. Same rule as `listPageTerms`, for the same reason. */
+    listMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+    }, Term[]>;
+    /** Replace a media asset's term assignments wholesale — set semantics, like
+     * `setPageTerms`, and for the same reason: the panel holds the whole selection, and two
+     * calls each patching one end of it race into a state neither asked for. */
+    setMediaTerms: import("@pramen/server").Handler<{
+        mediaId: string;
+        termIds: string[];
+    }, {
+        ok: true;
+        count: number;
+    }>;
     /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
      * `restoreMedia` a lie, and a block still referencing the id would render a dead url
      * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
@@ -2386,6 +2559,7 @@ export declare const cmsHandlers: {
         pagesByType: true;
         siteFurniture: true;
         codeDefinedTypes: true;
+        mediaTerms: true;
         canEdit: boolean;
     }>;
     /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
@@ -2916,6 +3090,18 @@ export declare function createCollectionTasks(collections: readonly CollectionDe
  * between the revision insert and the page update leaves the page unpublished with an orphan
  * revision until the next at-least-once redelivery re-runs (the token still matches, so it
  * completes). Acceptable for a scheduled job; the interactive path is atomic. */
+/**
+ * The CMS's own data migrations — spread into `app.migrations`.
+ *
+ *     migrations: [...cmsMigrations]
+ *
+ * Opt-in like every other fragment this package ships (`cmsHandlers`, `cmsPolicies`,
+ * `cmsTasks`), and with the same consequence for forgetting it: nothing breaks loudly. Media
+ * rows written before the projection columns existed keep NULL `filename`/`contentType`, so
+ * they sort together under a name sort and answer only the `other` type filter. New uploads
+ * are unaffected — `createMedia` writes the columns itself.
+ */
+export declare const cmsMigrations: readonly DataMigration[];
 export declare const cmsTasks: {
     "cms:publish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
     "cms:unpublish": (ctx: HandlerContext, payload: unknown) => Promise<void>;