@shapio/cms 0.5.7 → 0.5.9

package/dist/config.d.ts

@@ -1,2 +1,2 @@
-import { A as ServiceFactoryContext, C as HookEvent, D as MediaUsage, E as MediaReferenceService, F as defineConfig, I as isHookError, M as ShapioServices, N as ThemeDefinition, O as ModelHooks, P as ThemeTokens, S as HookError, T as JobHandlerContext, _ as ExtensionRoute, a as BeforeHookContext, b as ExtensionSite, c as ContentReadOptions, d as EXTENSION_CONTRACT_VERSION, f as EnqueueOptions, g as ExtensionJobService, h as ExtensionJobHandler, i as BeforeHook, j as ShapioConfig, k as ServiceFactory, l as ContentReadService, m as ExtensionHostConfig, n as AfterHookContext, o as BeforeHookEvent, p as EntryData, r as AfterHookEvent, s as ContentReadEntry, t as AfterHook, u as CustomServices, v as ExtensionRouteOptions, w as HookModel, x as HookEntry, y as ExtensionServices } from "./public-COKbHR-N.js";
-export { AfterHook, AfterHookContext, AfterHookEvent, BeforeHook, BeforeHookContext, BeforeHookEvent, ContentReadEntry, ContentReadOptions, ContentReadService, CustomServices, EXTENSION_CONTRACT_VERSION, EnqueueOptions, EntryData, ExtensionHostConfig, ExtensionJobHandler, ExtensionJobService, ExtensionRoute, ExtensionRouteOptions, ExtensionServices, ExtensionSite, HookEntry, HookError, HookEvent, HookModel, JobHandlerContext, MediaReferenceService, MediaUsage, ModelHooks, ServiceFactory, ServiceFactoryContext, ShapioConfig, ShapioServices, ThemeDefinition, ThemeTokens, defineConfig, isHookError };
+import { A as ServiceFactoryContext, C as HookEvent, D as MediaUsage, E as MediaReferenceService, F as ThemeDefinition, I as ThemeTokens, L as defineConfig, M as ServiceModel, N as ShapioConfig, O as ModelHooks, P as ShapioServices, R as isHookError, S as HookError, T as JobHandlerContext, _ as ExtensionRoute, a as BeforeHookContext, b as ExtensionSite, c as ContentReadOptions, d as EXTENSION_CONTRACT_VERSION, f as EnqueueOptions, g as ExtensionJobService, h as ExtensionJobHandler, i as BeforeHook, j as ServiceField, k as ServiceFactory, l as ContentReadService, m as ExtensionHostConfig, n as AfterHookContext, o as BeforeHookEvent, p as EntryData, r as AfterHookEvent, s as ContentReadEntry, t as AfterHook, u as CustomServices, v as ExtensionRouteOptions, w as HookModel, x as HookEntry, y as ExtensionServices } from "./public-jttKsns_.js";
+export { AfterHook, AfterHookContext, AfterHookEvent, BeforeHook, BeforeHookContext, BeforeHookEvent, ContentReadEntry, ContentReadOptions, ContentReadService, CustomServices, EXTENSION_CONTRACT_VERSION, EnqueueOptions, EntryData, ExtensionHostConfig, ExtensionJobHandler, ExtensionJobService, ExtensionRoute, ExtensionRouteOptions, ExtensionServices, ExtensionSite, HookEntry, HookError, HookEvent, HookModel, JobHandlerContext, MediaReferenceService, MediaUsage, ModelHooks, ServiceFactory, ServiceFactoryContext, ServiceField, ServiceModel, ShapioConfig, ShapioServices, ThemeDefinition, ThemeTokens, defineConfig, isHookError };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as ServiceFactoryContext, B as Principal, C as HookEvent, D as MediaUsage, E as MediaReferenceService, F as defineConfig, G as ComponentDefinition, H as DB, I as isHookError, J as ModelDefinition, K as DataType, L as KnownVersions, M as ShapioServices, N as ThemeDefinition, O as ModelHooks, P as ThemeTokens, R as PermissionEvaluator, S as HookError, T as JobHandlerContext, U as OutboxEvents, V as Database, W as ContentData, Y as PlannedChange, _ as ExtensionRoute, a as BeforeHookContext, b as ExtensionSite, c as ContentReadOptions, d as EXTENSION_CONTRACT_VERSION, f as EnqueueOptions, g as ExtensionJobService, h as ExtensionJobHandler, i as BeforeHook, j as ShapioConfig, k as ServiceFactory, l as ContentReadService, m as ExtensionHostConfig, n as AfterHookContext, o as BeforeHookEvent, p as EntryData, q as JsonValue, r as AfterHookEvent, s as ContentReadEntry, t as AfterHook, u as CustomServices, v as ExtensionRouteOptions, w as HookModel, x as HookEntry, y as ExtensionServices, z as PermissionExecutor } from "./public-COKbHR-N.js";
+import { A as ServiceFactoryContext, B as PermissionEvaluator, C as HookEvent, D as MediaUsage, E as MediaReferenceService, F as ThemeDefinition, G as OutboxEvents, H as Principal, I as ThemeTokens, J as DataType, K as ContentData, L as defineConfig, M as ServiceModel, N as ShapioConfig, O as ModelHooks, P as ShapioServices, R as isHookError, S as HookError, T as JobHandlerContext, U as Database, V as PermissionExecutor, W as DB, X as PlannedChange, Y as JsonValue, Z as ResolvedModelDefinition, _ as ExtensionRoute, a as BeforeHookContext, b as ExtensionSite, c as ContentReadOptions, d as EXTENSION_CONTRACT_VERSION, f as EnqueueOptions, g as ExtensionJobService, h as ExtensionJobHandler, i as BeforeHook, j as ServiceField, k as ServiceFactory, l as ContentReadService, m as ExtensionHostConfig, n as AfterHookContext, o as BeforeHookEvent, p as EntryData, q as ComponentDefinition, r as AfterHookEvent, s as ContentReadEntry, t as AfterHook, u as CustomServices, v as ExtensionRouteOptions, w as HookModel, x as HookEntry, y as ExtensionServices, z as KnownVersions } from "./public-jttKsns_.js";
 import { FastifyBaseLogger, FastifyInstance } from "fastify";
 import { Kysely, Selectable, Transaction } from "kysely";
 import { Static, Type } from "typebox";
@@ -432,15 +432,33 @@ type SiteRef = {
 //#region src/content/model.d.ts
 /** A collection or singleton resolved from a pinned snapshot, with what writes need to know about it. */
 type ContentModel = {
-  definition: ModelDefinition;
+  /** The effective definition: inherited fields first (`inheritedFrom` set), then the model's own. */
+  definition: ResolvedModelDefinition;
   /** Per-model version at the pinned snapshot (re-checked at commit). */
   version: number;
   revisionId: string;
-  /** Components reachable from the model (directly or through other components), with their versions. */
+  /**
+   * The models this one extends, by ID, at the pinned snapshot: a parent change changes this model's shape
+   * without changing its own version, so writes re-check these too and validators are cached by them.
+   */
+  ancestors: ReadonlyMap<string, {
+    version: number;
+    revisionId: string;
+  }>;
+  /** Components reachable from the model's effective fields (directly or through other components). */
   components: ReadonlyMap<string, {
     definition: ComponentDefinition;
     version: number;
   }>;
+  /**
+   * Where the model is served (plan polymorphic-types): its route key (`products/digital`) and its ancestors'
+   * API IDs, root first. Set by the resolvers here; absent on models built by hand.
+   */
+  route?: ModelRoute;
+};
+type ModelRoute = {
+  key: string;
+  ancestors: readonly string[];
 };
 //#endregion
 //#region src/content/hooks.d.ts
@@ -575,6 +593,11 @@ type FieldVisibilityLookup = {
    * definition is granted by roles held on that site (plan site-schema, rule 4).
    */
   getModelSite: (modelId: string, executor?: PermissionExecutor, versions?: KnownVersions) => Promise<string | null>;
+  /**
+   * The models a model extends, root first ([] for a root or an unknown model), at the request's schema
+   * version: a grant on an ancestor applies to its descendants (plan polymorphic-types D8).
+   */
+  getAncestors: (modelId: string, executor?: PermissionExecutor, versions?: KnownVersions) => Promise<readonly string[]>;
 };
 //#endregion
 //#region src/publishing/outbound/ssrf.d.ts
@@ -611,7 +634,8 @@ type SeqAllocator = {
 /**
  * Where a definition's values live inside entries: for a model, its own heads at the root; for a
  * component, every model that embeds it, with the field-ID path from the entry root down to the component
- * or dynamic-zone field that holds it.
+ * or dynamic-zone field that holds it. A change to a model that others extend has one location per family
+ * member holding the field (plan polymorphic-types), all at the root.
  */
 type ValueLocation = {
   modelId: string;
@@ -623,6 +647,8 @@ type ContentStep = {
   ownerId: string;
   fieldId: string;
   locations: ValueLocation[];
+  /** The field's API ID, to name it when the check fails. Absent in older plans. */
+  fieldApiKey?: string;
 } | {
   kind: 'backfill';
   ownerId: string;
@@ -637,8 +663,14 @@ type ContentStep = {
   locations: ValueLocation[];
 } | {
   kind: 'checkUnique';
+  /** The model whose entries are checked: one step per family member holding the field. */
   modelId: string;
   fieldId: string;
+  /**
+   * The definition the change is for (the model a family's steps come from), when it is not `modelId`;
+   * the content ports load the proposed schema through it. Absent in plans made before inheritance.
+   */
+  ownerId?: string;
   /**
    * The field is already unique under the active schema (its type changes): its live registry rows stay in
    * force until activation, so the dry run stages its claims under a separate registry key and the
@@ -667,6 +699,11 @@ type FollowUpStep = IndexStep | {
 } | {
   kind: 'releaseUnique';
   fieldId: string;
+  /**
+   * The models whose registry rows go: the family members that lose the field (a parent keeps its own
+   * when a child moves away). Absent in plans made before inheritance: every model's.
+   */
+  modelIds?: string[];
 } |
 /**
  * Deletes a removed locale's heads, revisions and unique-registry rows, and moves non-localized entries stored
@@ -861,5 +898,5 @@ export declare const startDedicatedWorker: (config: AppConfig) => Promise<Worker
 //#region src/constants/version.d.ts
 export declare const SHAPIO_VERSION: string;
 //#endregion
-export { AfterHook, AfterHookContext, AfterHookEvent, type AppConfig, type AppDependencies, BeforeHook, BeforeHookContext, BeforeHookEvent, ContentReadEntry, ContentReadOptions, ContentReadService, CustomServices, EXTENSION_CONTRACT_VERSION, EnqueueOptions, EntryData, ExtensionHostConfig, ExtensionJobHandler, ExtensionJobService, ExtensionRoute, ExtensionRouteOptions, ExtensionServices, ExtensionSite, HookEntry, HookError, HookEvent, HookModel, JobHandlerContext, MediaReferenceService, MediaUsage, ModelHooks, type RunningServer, ServiceFactory, ServiceFactoryContext, ShapioConfig, ShapioServices, ThemeDefinition, ThemeTokens, defineConfig, isHookError };
+export { AfterHook, AfterHookContext, AfterHookEvent, type AppConfig, type AppDependencies, BeforeHook, BeforeHookContext, BeforeHookEvent, ContentReadEntry, ContentReadOptions, ContentReadService, CustomServices, EXTENSION_CONTRACT_VERSION, EnqueueOptions, EntryData, ExtensionHostConfig, ExtensionJobHandler, ExtensionJobService, ExtensionRoute, ExtensionRouteOptions, ExtensionServices, ExtensionSite, HookEntry, HookError, HookEvent, HookModel, JobHandlerContext, MediaReferenceService, MediaUsage, ModelHooks, type RunningServer, ServiceFactory, ServiceFactoryContext, ServiceField, ServiceModel, ShapioConfig, ShapioServices, ThemeDefinition, ThemeTokens, defineConfig, isHookError };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as loadConfig, n as startServer, s as buildApp, t as startDedicatedWorker, u as SHAPIO_VERSION } from "./worker-jspgh10V.js";
+import { a as loadConfig, n as startServer, s as buildApp, t as startDedicatedWorker, u as SHAPIO_VERSION } from "./worker-6ru1tYBs.js";
 import { i as isHookError, n as HookError, r as defineConfig, t as EXTENSION_CONTRACT_VERSION } from "./public-B57h4F7Y.js";
 export { EXTENSION_CONTRACT_VERSION, HookError, SHAPIO_VERSION, buildApp, defineConfig, isHookError, loadConfig, startDedicatedWorker, startServer };

package/dist/public-B57h4F7Y.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-B57h4F7Y.js","names":[],"sources":["../src/extensions/public.ts"],"sourcesContent":["import type { ThemeToken } from '@shapio/schema';\nimport type { FastifyBaseLogger, FastifyPluginAsync, preHandlerAsyncHookHandler } from 'fastify';\nimport type { Kysely, Transaction } from 'kysely';\nimport type { DB } from '../db/types.js';\nimport type { PermissionEvaluator, Principal } from '../permissions/types.js';\nimport type { RouteAuditConfig } from '../plugins/auditDeclaration.js';\n\n// What Shapio adds to Fastify, repeated here so custom route code is typed without the server's internals.\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    /** Who is calling. Anonymous unless a session cookie or API token resolved. Never null after onRequest. */\n    principal: Principal;\n    /**\n     * The request's site on a site route (custom routes are site routes): the credential's site, else the\n     * `Shapio-Site` header or `?site=`, else the primary site. Undefined on a route declaring\n     * `config.site = 'network'`.\n     */\n    site: { id: string; key: string } | undefined;\n  }\n  interface FastifyContextConfig {\n    /** Required on every mutating route: the audit action recorded on success, or `{ exempt: '<why>' }`. */\n    audit?: RouteAuditConfig;\n    /** `'network'` for a custom route that is about the whole instance rather than one site. */\n    site?: 'site' | 'network';\n  }\n}\n\n/**\n * The project extension contract (ADR 0009), imported by project authors from `@shapio/cms/config`:\n *\n * ```ts\n * import { defineConfig } from '@shapio/cms/config';\n * export const config = defineConfig({ hooks: { article: { beforePublish: (ctx) => { ... } } } });\n * ```\n *\n * Extensions are code: changing them needs a restart of Shapio (never a rebuild). Content models are never\n * configured here; they change live in the admin. This file has no runtime imports from the server, so a\n * config that imports it stays cheap to load.\n *\n * Stability: everything exported here follows semver with `EXTENSION_CONTRACT_VERSION`; Shapio's database\n * tables (reachable through `trx`) are internal and may change in any release.\n */\nexport const EXTENSION_CONTRACT_VERSION = 1;\n\nexport type BeforeHookEvent = 'beforeCreate' | 'beforeUpdate' | 'beforePublish' | 'beforeDelete';\nexport type AfterHookEvent = 'afterCreate' | 'afterUpdate' | 'afterPublish' | 'afterDelete';\nexport type HookEvent = BeforeHookEvent | AfterHookEvent;\n\n/** A site of a multi-site instance: its stable ID and its key (sites share the schema, not content). */\nexport type ExtensionSite = { id: string; key: string };\n\n/** Entry data keyed by field API key (the admin API's shape; media and relations are IDs). */\nexport type EntryData = Readonly<Record<string, unknown>>;\n\nexport type HookModel = {\n  /** Stable model ID (never changes). */\n  id: string;\n  apiKey: string;\n  label: string;\n  kind: 'collection' | 'singleton';\n  localized: boolean;\n  draftAndPublish: boolean;\n};\n\nexport type HookEntry = {\n  id: string;\n  locale: string | null;\n  /** Which head the change is about: the draft (create/update), the live version (publish), or a delete. */\n  state: 'draft' | 'published' | 'deleted';\n};\n\nexport type ContentReadOptions = {\n  locale?: string;\n  /** Read as this principal (its permissions apply). Default: Shapio itself (everything). */\n  principal?: Principal;\n};\n\nexport type ContentReadEntry = {\n  id: string;\n  locale: string;\n  status: string;\n  data: Record<string, unknown>;\n};\n\n/** Read-only access to content (drafts, as the admin API shows them). Reads committed data. */\nexport type ContentReadService = {\n  get: (modelKey: string, id: string, options?: ContentReadOptions) => Promise<ContentReadEntry>;\n  /** `query` is a delivery-style querystring, e.g. `filters[title][$contains]=a&pageSize=10`. */\n  list: (\n    modelKey: string,\n    query?: string,\n    options?: Omit<ContentReadOptions, 'locale'>,\n  ) => Promise<{ items: ContentReadEntry[]; total: number }>;\n  /** Number of (non-deleted) entries of a model. */\n  count: (modelKey: string) => Promise<number>;\n  /** The active content models (collections and singletons) of this site: shared ones and its own. */\n  models: () => Promise<HookModel[]>;\n};\n\nexport type MediaUsage = {\n  entryId: string;\n  modelId: string;\n  fieldId: string;\n  locale: string;\n  state: string;\n};\n\nexport type MediaReferenceService = {\n  /** Where an asset is used (up to 100 references, plus the total). */\n  usages: (assetId: string) => Promise<{ items: MediaUsage[]; total: number }>;\n};\n\nexport type EnqueueOptions = {\n  runAt?: Date;\n  /** Enqueueing the same key twice creates one job. */\n  idempotencyKey?: string;\n  maxAttempts?: number;\n};\n\nexport type ExtensionJobService = {\n  /** Enqueues one of the project's own jobs (`jobs` in the config), by its name without the `ext.` prefix. */\n  enqueue: (\n    name: string,\n    payload?: Record<string, unknown>,\n    options?: EnqueueOptions,\n  ) => Promise<{ id: string; created: boolean }>;\n};\n\n/**\n * What Shapio offers extensions. Deliberately small; everything else goes through `trx` or HTTP.\n *\n * Content and media are per site. The services handed to a hook read the hook's site; the services given to\n * routes, jobs and service factories read the primary site. Use `forSite` for another one (in a custom\n * route: `services.forSite(request.site)`).\n */\nexport type ShapioServices = {\n  /** The site `content` and `media` read. */\n  site: ExtensionSite;\n  /** The same services reading another site. */\n  forSite: (site: ExtensionSite) => ShapioServices;\n  content: ContentReadService;\n  media: MediaReferenceService;\n  jobs: ExtensionJobService;\n  logger: FastifyBaseLogger;\n};\n\n/**\n * Your own services, by name. Augment it for typed access everywhere services appear:\n *\n * ```ts\n * declare module '@shapio/cms/config' {\n *   interface CustomServices { stats: StatsService }\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmented by projects\nexport interface CustomServices {}\n\nexport type ExtensionServices = ShapioServices & CustomServices;\n\ntype HookContextBase = {\n  /** The site the entry belongs to; `services` read this site. */\n  site: ExtensionSite;\n  model: HookModel;\n  entry: HookEntry;\n  locale: string | null;\n  /** The document after the change (absent for deletes). */\n  data: EntryData | undefined;\n  /** The document before the change: the previous draft (update) or the live version (publish). */\n  before: EntryData | undefined;\n  /** Who made the change (an admin, an API token, an app user, or Shapio itself for scheduled work). */\n  principal: Principal;\n  services: ExtensionServices;\n  logger: FastifyBaseLogger;\n  /** Aborted when Shapio shuts down. */\n  signal: AbortSignal;\n};\n\n/**\n * `before*` hooks run INSIDE the write's transaction, before it commits. Throw `HookError` (or call\n * `reject`) to abort the write with 422 `HOOK_REJECTED`; nothing of the write is kept. Other errors abort it\n * too, as a 500. Database work through `trx` commits or rolls back with the write.\n */\nexport type BeforeHookContext = HookContextBase & {\n  event: BeforeHookEvent;\n  trx: Transaction<DB>;\n  reject: (message: string, details?: Record<string, unknown>) => never;\n};\n\n/**\n * `after*` hooks run AFTER the write committed, as a job (retried with backoff on error, never rolling the\n * write back). Database work through `trx` is exactly once: it commits together with the record that the\n * hook ran. Other side effects (HTTP calls) are at least once: make them idempotent with `idempotencyKey`.\n */\nexport type AfterHookContext = HookContextBase & {\n  event: AfterHookEvent;\n  trx: Transaction<DB>;\n  /** The outbox event the hook runs for. */\n  eventId: string;\n  /** `<eventId>:<hook name>`: stable across retries. */\n  idempotencyKey: string;\n  attempt: number;\n};\n\nexport type BeforeHook = (context: BeforeHookContext) => Promise<void> | void;\nexport type AfterHook = (context: AfterHookContext) => Promise<void> | void;\n\nexport type ModelHooks = { [E in BeforeHookEvent]?: BeforeHook } & { [E in AfterHookEvent]?: AfterHook };\n\nexport type ServiceFactoryContext = {\n  /** Kysely on Shapio's database. Shapio's own tables are internal and may change between releases. */\n  db: Kysely<DB>;\n  config: ExtensionHostConfig;\n  logger: FastifyBaseLogger;\n  /** Shapio's services plus the custom services declared before this one. */\n  services: ExtensionServices;\n};\n\nexport type ExtensionHostConfig = {\n  nodeEnv: 'development' | 'production' | 'test';\n  /** PUBLIC_URL origin, without a trailing slash. */\n  publicUrl: string;\n  basePath: string;\n  /** The directory holding shapio.config and extensions/. */\n  projectDir: string;\n};\n\nexport type ServiceFactory = (context: ServiceFactoryContext) => unknown;\n\n/** Options every custom route plugin receives (also available as `app.ext`). */\nexport type ExtensionRouteOptions = {\n  services: ExtensionServices;\n  /** Shapio's permission evaluator: `permissions.evaluate(request.principal, { action, modelId })`. */\n  permissions: PermissionEvaluator;\n  logger: FastifyBaseLogger;\n  /** preHandler: 401/403 unless the caller is an admin user or an admin API token. */\n  requireAdmin: preHandlerAsyncHookHandler;\n};\n\nexport type ExtensionRoute = {\n  /** Mounted at `/api/ext/<prefix>` (under BASE_PATH). Lower-case letters, digits and dashes. */\n  prefix: string;\n  plugin: FastifyPluginAsync<ExtensionRouteOptions>;\n};\n\nexport type JobHandlerContext = {\n  jobId: string;\n  payload: Record<string, unknown>;\n  attempt: number;\n  maxAttempts: number;\n  idempotencyKey: string | null;\n  services: ExtensionServices;\n  logger: FastifyBaseLogger;\n  signal: AbortSignal;\n};\n\n/** Throw to retry with backoff; the return value (JSON) is stored as the job result. */\nexport type ExtensionJobHandler = (context: JobHandlerContext) => Promise<unknown>;\n\n/**\n * A colour theme for the admin: token values for a light variant, a dark variant, or both. Every UI token is\n * required in a variant; the `brand-*` tokens may be left out (Shapio's are used). Values are `#rrggbb`\n * (contrast is checked by `shapio extensions check`), `#rgb`, `#rrggbbaa`, or `rgb()`, `hsl()`, `oklch()`,\n * `oklab()` with plain arguments.\n */\nexport type ThemeTokens = Partial<Record<ThemeToken, string>>;\n\nexport type ThemeDefinition = {\n  /** Lower-case letters, digits and dashes; not a built-in theme's key. Saved in each browser's setting. */\n  key: string;\n  /** Shown in the theme menu (not translated). */\n  name: string;\n  description?: string;\n  light?: ThemeTokens;\n  dark?: ThemeTokens;\n};\n\nexport type ShapioConfig = {\n  /** Lifecycle hooks by model API ID (or stable model UUID); `*` runs for every model. */\n  hooks?: Record<string, ModelHooks>;\n  routes?: ExtensionRoute[];\n  /** Constructed once at startup, in order, and shared by hooks, routes and jobs. */\n  services?: Record<string, ServiceFactory>;\n  /** Custom field editor modules: file names inside `extensions/editors/` (built ES modules). */\n  editors?: string[];\n  /** Job handlers by name; registered as `ext.<name>`. */\n  jobs?: Record<string, ExtensionJobHandler>;\n  /** Admin colour themes, listed after the built-in ones in the theme menu. */\n  themes?: ThemeDefinition[];\n};\n\n/** Identity helper for completion and type checking in `shapio.config.ts`. */\nexport const defineConfig = (config: ShapioConfig): ShapioConfig => config;\n\nconst HOOK_ERROR_BRAND = Symbol.for('shapio.HookError');\n\n/**\n * Thrown by a `before*` hook to reject a write: the API answers 422 with code `HOOK_REJECTED`, this message\n * and the details. Recognised by a brand, not `instanceof`, so a copy of this class loaded from another\n * path (a project's own `node_modules`) works the same.\n */\nexport class HookError extends Error {\n  readonly details: Record<string, unknown> | undefined;\n  readonly [HOOK_ERROR_BRAND] = true;\n\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message);\n    this.name = 'HookError';\n    this.details = details;\n  }\n}\n\nexport const isHookError = (error: unknown): error is HookError =>\n  typeof error === 'object' &&\n  error !== null &&\n  (error as Record<symbol, unknown>)[HOOK_ERROR_BRAND] === true;\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,MAAa,6BAA6B;;AA0P1C,MAAa,gBAAgB,WAAuC;AAEpE,MAAM,mBAAmB,OAAO,IAAI,kBAAkB;;;;;;AAOtD,IAAa,YAAb,cAA+B,MAAM;CACnC;CACA,CAAU,oBAAoB;CAE9B,YAAY,SAAiB,SAAmC;EAC9D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,UAAU;CACjB;AACF;AAEA,MAAa,eAAe,UAC1B,OAAO,UAAU,YACjB,UAAU,QACT,MAAkC,sBAAsB"}
+{"version":3,"file":"public-B57h4F7Y.js","names":[],"sources":["../src/extensions/public.ts"],"sourcesContent":["import type { ThemeToken } from '@shapio/schema';\nimport type { FastifyBaseLogger, FastifyPluginAsync, preHandlerAsyncHookHandler } from 'fastify';\nimport type { Kysely, Transaction } from 'kysely';\nimport type { DB } from '../db/types.js';\nimport type { PermissionEvaluator, Principal } from '../permissions/types.js';\nimport type { RouteAuditConfig } from '../plugins/auditDeclaration.js';\n\n// What Shapio adds to Fastify, repeated here so custom route code is typed without the server's internals.\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    /** Who is calling. Anonymous unless a session cookie or API token resolved. Never null after onRequest. */\n    principal: Principal;\n    /**\n     * The request's site on a site route (custom routes are site routes): the credential's site, else the\n     * `Shapio-Site` header or `?site=`, else the primary site. Undefined on a route declaring\n     * `config.site = 'network'`.\n     */\n    site: { id: string; key: string } | undefined;\n  }\n  interface FastifyContextConfig {\n    /** Required on every mutating route: the audit action recorded on success, or `{ exempt: '<why>' }`. */\n    audit?: RouteAuditConfig;\n    /** `'network'` for a custom route that is about the whole instance rather than one site. */\n    site?: 'site' | 'network';\n  }\n}\n\n/**\n * The project extension contract (ADR 0009), imported by project authors from `@shapio/cms/config`:\n *\n * ```ts\n * import { defineConfig } from '@shapio/cms/config';\n * export const config = defineConfig({ hooks: { article: { beforePublish: (ctx) => { ... } } } });\n * ```\n *\n * Extensions are code: changing them needs a restart of Shapio (never a rebuild). Content models are never\n * configured here; they change live in the admin. This file has no runtime imports from the server, so a\n * config that imports it stays cheap to load.\n *\n * Stability: everything exported here follows semver with `EXTENSION_CONTRACT_VERSION`; Shapio's database\n * tables (reachable through `trx`) are internal and may change in any release.\n */\nexport const EXTENSION_CONTRACT_VERSION = 1;\n\nexport type BeforeHookEvent = 'beforeCreate' | 'beforeUpdate' | 'beforePublish' | 'beforeDelete';\nexport type AfterHookEvent = 'afterCreate' | 'afterUpdate' | 'afterPublish' | 'afterDelete';\nexport type HookEvent = BeforeHookEvent | AfterHookEvent;\n\n/** A site of a multi-site instance: its stable ID and its key (sites share the schema, not content). */\nexport type ExtensionSite = { id: string; key: string };\n\n/** Entry data keyed by field API key (the admin API's shape; media and relations are IDs). */\nexport type EntryData = Readonly<Record<string, unknown>>;\n\nexport type HookModel = {\n  /** Stable model ID (never changes). */\n  id: string;\n  apiKey: string;\n  label: string;\n  kind: 'collection' | 'singleton';\n  localized: boolean;\n  draftAndPublish: boolean;\n  /** The API ID of the model this one extends; absent for a model that extends nothing. */\n  extends?: string;\n};\n\n/** A field of a model as `content.models()` describes it (its effective fields, inherited ones first). */\nexport type ServiceField = {\n  /** Stable field ID (never changes; an inherited field keeps the declaring model's ID). */\n  id: string;\n  apiKey: string;\n  label: string;\n  type: string;\n  required: boolean;\n  localized: boolean;\n  /** The API ID of the model that declares the field, when it is inherited; absent for the model's own. */\n  inheritedFrom?: string;\n};\n\n/** A content model with its effective fields and where the delivery API serves it. */\nexport type ServiceModel = HookModel & {\n  /** The delivery route key: the plural API ID, nested under the models it extends (`posts/guides`). */\n  routeKey: string;\n  fields: ServiceField[];\n};\n\nexport type HookEntry = {\n  id: string;\n  locale: string | null;\n  /** Which head the change is about: the draft (create/update), the live version (publish), or a delete. */\n  state: 'draft' | 'published' | 'deleted';\n};\n\nexport type ContentReadOptions = {\n  locale?: string;\n  /** Read as this principal (its permissions apply). Default: Shapio itself (everything). */\n  principal?: Principal;\n};\n\nexport type ContentReadEntry = {\n  id: string;\n  locale: string;\n  status: string;\n  data: Record<string, unknown>;\n};\n\n/** Read-only access to content (drafts, as the admin API shows them). Reads committed data. */\nexport type ContentReadService = {\n  get: (modelKey: string, id: string, options?: ContentReadOptions) => Promise<ContentReadEntry>;\n  /** `query` is a delivery-style querystring, e.g. `filters[title][$contains]=a&pageSize=10`. */\n  list: (\n    modelKey: string,\n    query?: string,\n    options?: Omit<ContentReadOptions, 'locale'>,\n  ) => Promise<{ items: ContentReadEntry[]; total: number }>;\n  /** Number of (non-deleted) entries of a model. */\n  count: (modelKey: string) => Promise<number>;\n  /**\n   * The active content models (collections and singletons) of this site: shared ones and its own, each with\n   * its effective fields (a model that extends another lists the inherited fields first) and route key.\n   */\n  models: () => Promise<ServiceModel[]>;\n};\n\nexport type MediaUsage = {\n  entryId: string;\n  modelId: string;\n  fieldId: string;\n  locale: string;\n  state: string;\n};\n\nexport type MediaReferenceService = {\n  /** Where an asset is used (up to 100 references, plus the total). */\n  usages: (assetId: string) => Promise<{ items: MediaUsage[]; total: number }>;\n};\n\nexport type EnqueueOptions = {\n  runAt?: Date;\n  /** Enqueueing the same key twice creates one job. */\n  idempotencyKey?: string;\n  maxAttempts?: number;\n};\n\nexport type ExtensionJobService = {\n  /** Enqueues one of the project's own jobs (`jobs` in the config), by its name without the `ext.` prefix. */\n  enqueue: (\n    name: string,\n    payload?: Record<string, unknown>,\n    options?: EnqueueOptions,\n  ) => Promise<{ id: string; created: boolean }>;\n};\n\n/**\n * What Shapio offers extensions. Deliberately small; everything else goes through `trx` or HTTP.\n *\n * Content and media are per site. The services handed to a hook read the hook's site; the services given to\n * routes, jobs and service factories read the primary site. Use `forSite` for another one (in a custom\n * route: `services.forSite(request.site)`).\n */\nexport type ShapioServices = {\n  /** The site `content` and `media` read. */\n  site: ExtensionSite;\n  /** The same services reading another site. */\n  forSite: (site: ExtensionSite) => ShapioServices;\n  content: ContentReadService;\n  media: MediaReferenceService;\n  jobs: ExtensionJobService;\n  logger: FastifyBaseLogger;\n};\n\n/**\n * Your own services, by name. Augment it for typed access everywhere services appear:\n *\n * ```ts\n * declare module '@shapio/cms/config' {\n *   interface CustomServices { stats: StatsService }\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmented by projects\nexport interface CustomServices {}\n\nexport type ExtensionServices = ShapioServices & CustomServices;\n\ntype HookContextBase = {\n  /** The site the entry belongs to; `services` read this site. */\n  site: ExtensionSite;\n  model: HookModel;\n  entry: HookEntry;\n  locale: string | null;\n  /** The document after the change (absent for deletes). */\n  data: EntryData | undefined;\n  /** The document before the change: the previous draft (update) or the live version (publish). */\n  before: EntryData | undefined;\n  /** Who made the change (an admin, an API token, an app user, or Shapio itself for scheduled work). */\n  principal: Principal;\n  services: ExtensionServices;\n  logger: FastifyBaseLogger;\n  /** Aborted when Shapio shuts down. */\n  signal: AbortSignal;\n};\n\n/**\n * `before*` hooks run INSIDE the write's transaction, before it commits. Throw `HookError` (or call\n * `reject`) to abort the write with 422 `HOOK_REJECTED`; nothing of the write is kept. Other errors abort it\n * too, as a 500. Database work through `trx` commits or rolls back with the write.\n */\nexport type BeforeHookContext = HookContextBase & {\n  event: BeforeHookEvent;\n  trx: Transaction<DB>;\n  reject: (message: string, details?: Record<string, unknown>) => never;\n};\n\n/**\n * `after*` hooks run AFTER the write committed, as a job (retried with backoff on error, never rolling the\n * write back). Database work through `trx` is exactly once: it commits together with the record that the\n * hook ran. Other side effects (HTTP calls) are at least once: make them idempotent with `idempotencyKey`.\n */\nexport type AfterHookContext = HookContextBase & {\n  event: AfterHookEvent;\n  trx: Transaction<DB>;\n  /** The outbox event the hook runs for. */\n  eventId: string;\n  /** `<eventId>:<hook name>`: stable across retries. */\n  idempotencyKey: string;\n  attempt: number;\n};\n\nexport type BeforeHook = (context: BeforeHookContext) => Promise<void> | void;\nexport type AfterHook = (context: AfterHookContext) => Promise<void> | void;\n\nexport type ModelHooks = { [E in BeforeHookEvent]?: BeforeHook } & { [E in AfterHookEvent]?: AfterHook };\n\nexport type ServiceFactoryContext = {\n  /** Kysely on Shapio's database. Shapio's own tables are internal and may change between releases. */\n  db: Kysely<DB>;\n  config: ExtensionHostConfig;\n  logger: FastifyBaseLogger;\n  /** Shapio's services plus the custom services declared before this one. */\n  services: ExtensionServices;\n};\n\nexport type ExtensionHostConfig = {\n  nodeEnv: 'development' | 'production' | 'test';\n  /** PUBLIC_URL origin, without a trailing slash. */\n  publicUrl: string;\n  basePath: string;\n  /** The directory holding shapio.config and extensions/. */\n  projectDir: string;\n};\n\nexport type ServiceFactory = (context: ServiceFactoryContext) => unknown;\n\n/** Options every custom route plugin receives (also available as `app.ext`). */\nexport type ExtensionRouteOptions = {\n  services: ExtensionServices;\n  /** Shapio's permission evaluator: `permissions.evaluate(request.principal, { action, modelId })`. */\n  permissions: PermissionEvaluator;\n  logger: FastifyBaseLogger;\n  /** preHandler: 401/403 unless the caller is an admin user or an admin API token. */\n  requireAdmin: preHandlerAsyncHookHandler;\n};\n\nexport type ExtensionRoute = {\n  /** Mounted at `/api/ext/<prefix>` (under BASE_PATH). Lower-case letters, digits and dashes. */\n  prefix: string;\n  plugin: FastifyPluginAsync<ExtensionRouteOptions>;\n};\n\nexport type JobHandlerContext = {\n  jobId: string;\n  payload: Record<string, unknown>;\n  attempt: number;\n  maxAttempts: number;\n  idempotencyKey: string | null;\n  services: ExtensionServices;\n  logger: FastifyBaseLogger;\n  signal: AbortSignal;\n};\n\n/** Throw to retry with backoff; the return value (JSON) is stored as the job result. */\nexport type ExtensionJobHandler = (context: JobHandlerContext) => Promise<unknown>;\n\n/**\n * A colour theme for the admin: token values for a light variant, a dark variant, or both. Every UI token is\n * required in a variant; the `brand-*` tokens may be left out (Shapio's are used). Values are `#rrggbb`\n * (contrast is checked by `shapio extensions check`), `#rgb`, `#rrggbbaa`, or `rgb()`, `hsl()`, `oklch()`,\n * `oklab()` with plain arguments.\n */\nexport type ThemeTokens = Partial<Record<ThemeToken, string>>;\n\nexport type ThemeDefinition = {\n  /** Lower-case letters, digits and dashes; not a built-in theme's key. Saved in each browser's setting. */\n  key: string;\n  /** Shown in the theme menu (not translated). */\n  name: string;\n  description?: string;\n  light?: ThemeTokens;\n  dark?: ThemeTokens;\n};\n\nexport type ShapioConfig = {\n  /** Lifecycle hooks by model API ID (or stable model UUID); `*` runs for every model. */\n  hooks?: Record<string, ModelHooks>;\n  routes?: ExtensionRoute[];\n  /** Constructed once at startup, in order, and shared by hooks, routes and jobs. */\n  services?: Record<string, ServiceFactory>;\n  /** Custom field editor modules: file names inside `extensions/editors/` (built ES modules). */\n  editors?: string[];\n  /** Job handlers by name; registered as `ext.<name>`. */\n  jobs?: Record<string, ExtensionJobHandler>;\n  /** Admin colour themes, listed after the built-in ones in the theme menu. */\n  themes?: ThemeDefinition[];\n};\n\n/** Identity helper for completion and type checking in `shapio.config.ts`. */\nexport const defineConfig = (config: ShapioConfig): ShapioConfig => config;\n\nconst HOOK_ERROR_BRAND = Symbol.for('shapio.HookError');\n\n/**\n * Thrown by a `before*` hook to reject a write: the API answers 422 with code `HOOK_REJECTED`, this message\n * and the details. Recognised by a brand, not `instanceof`, so a copy of this class loaded from another\n * path (a project's own `node_modules`) works the same.\n */\nexport class HookError extends Error {\n  readonly details: Record<string, unknown> | undefined;\n  readonly [HOOK_ERROR_BRAND] = true;\n\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message);\n    this.name = 'HookError';\n    this.details = details;\n  }\n}\n\nexport const isHookError = (error: unknown): error is HookError =>\n  typeof error === 'object' &&\n  error !== null &&\n  (error as Record<symbol, unknown>)[HOOK_ERROR_BRAND] === true;\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,MAAa,6BAA6B;;AAmR1C,MAAa,gBAAgB,WAAuC;AAEpE,MAAM,mBAAmB,OAAO,IAAI,kBAAkB;;;;;;AAOtD,IAAa,YAAb,cAA+B,MAAM;CACnC;CACA,CAAU,oBAAoB;CAE9B,YAAY,SAAiB,SAAmC;EAC9D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,UAAU;CACjB;AACF;AAEA,MAAa,eAAe,UAC1B,OAAO,UAAU,YACjB,UAAU,QACT,MAAkC,sBAAsB"}

package/dist/{public-COKbHR-N.d.ts → public-jttKsns_.d.ts}

@@ -215,9 +215,28 @@ type ModelDefinition = {
   description?: string;
   localized: boolean;
   draftAndPublish: boolean;
+  /**
+   * The stable ID of the collection this one extends. The stored definition holds its own fields only;
+   * `resolveModelDefinition` adds the inherited ones (ancestors' first).
+   */
+  extends?: string;
   fields: FieldDefinition[];
   display: ModelDisplay;
 };
+/** A field as a model sees it after inheritance: `inheritedFrom` names the declaring ancestor's ID. */
+type ResolvedField = FieldDefinition & {
+  inheritedFrom?: string;
+};
+/**
+ * A model with its effective fields: every ancestor's fields (root first), then its own, and its display
+ * merged with its ancestors' (`resolveModelDefinition`). `ancestorIds` is required so code that needs
+ * effective fields can demand this type; a stored definition does not satisfy it.
+ */
+type ResolvedModelDefinition = Omit<ModelDefinition, 'fields'> & {
+  fields: ResolvedField[];
+  /** Ancestors' stable IDs, root first; empty for a model that extends nothing. */
+  ancestorIds: readonly string[];
+};
 type ComponentDefinition = {
   id: string;
   kind: 'component';
@@ -231,7 +250,7 @@ type ComponentDefinition = {
 };
 //#endregion
 //#region src/diff/types.d.ts
-declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
+declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "model.extends", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
 type ChangeKind = (typeof CHANGE_KINDS)[number];
 /**
  * One difference between two versions of a definition. `property` names the changed property for
@@ -1312,6 +1331,26 @@ type HookModel = {
   kind: 'collection' | 'singleton';
   localized: boolean;
   draftAndPublish: boolean;
+  /** The API ID of the model this one extends; absent for a model that extends nothing. */
+  extends?: string;
+};
+/** A field of a model as `content.models()` describes it (its effective fields, inherited ones first). */
+type ServiceField = {
+  /** Stable field ID (never changes; an inherited field keeps the declaring model's ID). */
+  id: string;
+  apiKey: string;
+  label: string;
+  type: string;
+  required: boolean;
+  localized: boolean;
+  /** The API ID of the model that declares the field, when it is inherited; absent for the model's own. */
+  inheritedFrom?: string;
+};
+/** A content model with its effective fields and where the delivery API serves it. */
+type ServiceModel = HookModel & {
+  /** The delivery route key: the plural API ID, nested under the models it extends (`posts/guides`). */
+  routeKey: string;
+  fields: ServiceField[];
 };
 type HookEntry = {
   id: string;
@@ -1340,8 +1379,11 @@ type ContentReadService = {
   }>;
   /** Number of (non-deleted) entries of a model. */
   count: (modelKey: string) => Promise<number>;
-  /** The active content models (collections and singletons) of this site: shared ones and its own. */
-  models: () => Promise<HookModel[]>;
+  /**
+   * The active content models (collections and singletons) of this site: shared ones and its own, each with
+   * its effective fields (a model that extends another lists the inherited fields first) and route key.
+   */
+  models: () => Promise<ServiceModel[]>;
 };
 type MediaUsage = {
   entryId: string;
@@ -1529,5 +1571,5 @@ declare class HookError extends Error {
 }
 declare const isHookError: (error: unknown) => error is HookError;
 //#endregion
-export { ServiceFactoryContext as A, Principal as B, HookEvent as C, MediaUsage as D, MediaReferenceService as E, defineConfig as F, ComponentDefinition as G, DB as H, isHookError as I, ModelDefinition as J, DataType as K, KnownVersions as L, ShapioServices as M, ThemeDefinition as N, ModelHooks as O, ThemeTokens as P, PermissionEvaluator as R, HookError as S, JobHandlerContext as T, OutboxEvents as U, Database as V, ContentData as W, PlannedChange as Y, ExtensionRoute as _, BeforeHookContext as a, ExtensionSite as b, ContentReadOptions as c, EXTENSION_CONTRACT_VERSION as d, EnqueueOptions as f, ExtensionJobService as g, ExtensionJobHandler as h, BeforeHook as i, ShapioConfig as j, ServiceFactory as k, ContentReadService as l, ExtensionHostConfig as m, AfterHookContext as n, BeforeHookEvent as o, EntryData as p, JsonValue$1 as q, AfterHookEvent as r, ContentReadEntry as s, AfterHook as t, CustomServices as u, ExtensionRouteOptions as v, HookModel as w, HookEntry as x, ExtensionServices as y, PermissionExecutor as z };
-//# sourceMappingURL=public-COKbHR-N.d.ts.map
+export { ServiceFactoryContext as A, PermissionEvaluator as B, HookEvent as C, MediaUsage as D, MediaReferenceService as E, ThemeDefinition as F, OutboxEvents as G, Principal as H, ThemeTokens as I, DataType as J, ContentData as K, defineConfig as L, ServiceModel as M, ShapioConfig as N, ModelHooks as O, ShapioServices as P, isHookError as R, HookError as S, JobHandlerContext as T, Database as U, PermissionExecutor as V, DB as W, PlannedChange as X, JsonValue$1 as Y, ResolvedModelDefinition as Z, ExtensionRoute as _, BeforeHookContext as a, ExtensionSite as b, ContentReadOptions as c, EXTENSION_CONTRACT_VERSION as d, EnqueueOptions as f, ExtensionJobService as g, ExtensionJobHandler as h, BeforeHook as i, ServiceField as j, ServiceFactory as k, ContentReadService as l, ExtensionHostConfig as m, AfterHookContext as n, BeforeHookEvent as o, EntryData as p, ComponentDefinition as q, AfterHookEvent as r, ContentReadEntry as s, AfterHook as t, CustomServices as u, ExtensionRouteOptions as v, HookModel as w, HookEntry as x, ExtensionServices as y, KnownVersions as z };
+//# sourceMappingURL=public-jttKsns_.d.ts.map