@crombolo/content 0.0.0-stage → 0.24.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@crombolo/content",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.24.1",
+  "description": "The rules every document write follows, whoever starts it: who may, approvals, and what it announces. No transport.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/content"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./rules": "./src/rules.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/core": "0.24.1",
+    "@crombolo/data": "0.24.1"
+  }
+}

package/src/actor.ts

@@ -0,0 +1,97 @@
+/**
+ * Who a document write is for (story 170). Every operation is handed one, so what
+ * it may do, whether approvals apply and whom the audit names never depend on how
+ * the write was started. Authentication stays with the transport that made it.
+ */
+import type { GroupGrant, StartNodes } from '@crombolo/core'
+
+/** A backoffice user, as far as a document write needs to know one. */
+export interface ContentPrincipal {
+  /** The user's key. */
+  id: string
+  name: string
+  isAdmin: boolean
+  /** Section manifest aliases, such as `Umb.Section.Content`. */
+  allowedSections: readonly string[]
+  hasAccessToAllLanguages: boolean
+  languages: readonly string[]
+  startNodes: { document: StartNodes }
+  groups: readonly GroupGrant[]
+}
+
+/** Where a write came from, for the audit log. */
+export interface ActorOrigin {
+  source: 'request' | 'cli' | 'job'
+  ipAddress?: string | null
+  forwardedFor?: string | null
+}
+
+export type Actor =
+  /** A signed-in user: their permissions, start nodes, languages and approvals. */
+  | { kind: 'user'; principal: ContentPrincipal; origin: ActorOrigin }
+  /**
+   * Someone at the command line on the box: no permission checks, since they hold
+   * the database, but approvals apply unless they say `skipApproval`, which the
+   * audit records.
+   */
+  | { kind: 'operator'; name: string; skipApproval?: boolean; origin: ActorOrigin }
+  /**
+   * The site acting on what was already decided — a schedule, an approved
+   * request, a form's workflow: no permission checks and no approval gate.
+   */
+  | {
+      kind: 'system'
+      name: string
+      origin: ActorOrigin
+      /** The person it acts for, when there is one: the approver of a request. */
+      user?: { id: string; name: string }
+      /** Said with what it did, in notifications and the audit: `approved through "Legal"`. */
+      note?: string
+    }
+
+export const userActor = (
+  principal: ContentPrincipal,
+  origin: Omit<ActorOrigin, 'source'> = {},
+): Actor => ({ kind: 'user', principal, origin: { source: 'request', ...origin } })
+
+export const operatorActor = (name: string, options: { skipApproval?: boolean } = {}): Actor => ({
+  kind: 'operator',
+  name,
+  skipApproval: options.skipApproval,
+  origin: { source: 'cli' },
+})
+
+export const systemActor = (
+  name: string,
+  options: {
+    source?: ActorOrigin['source']
+    user?: { id: string; name: string }
+    note?: string
+  } = {},
+): Actor => ({
+  kind: 'system',
+  name,
+  origin: { source: options.source ?? 'job' },
+  user: options.user,
+  note: options.note,
+})
+
+/** The name an audit entry or a notification gives the actor. */
+export const actorName = (actor: Actor): string =>
+  actor.kind === 'user'
+    ? actor.principal.name
+    : actor.kind === 'system'
+      ? (actor.user?.name ?? actor.name)
+      : actor.name
+
+/** The user's key, when the actor is one; versions record it as their author. */
+export const actorUserKey = (actor: Actor): string | null =>
+  actor.kind === 'user'
+    ? actor.principal.id
+    : actor.kind === 'system'
+      ? (actor.user?.id ?? null)
+      : null
+
+/** What the actor says alongside the change, if anything. */
+export const actorNote = (actor: Actor): string | undefined =>
+  actor.kind === 'system' ? actor.note : undefined

package/src/events.ts

@@ -0,0 +1,267 @@
+/**
+ * What a document write did, as the operation reports it (story 170). An
+ * operation reports to an `EventSink`; the server and the command line each wire
+ * one to the same database-backed steps — the audit log, webhooks, change
+ * notifications — and the server adds live backoffice refresh. The mappings here
+ * are pure, so every transport turns one event into the same entries.
+ */
+import type { Db } from '@crombolo/data'
+import { type Actor, actorName, actorNote, actorUserKey } from './actor.ts'
+
+export type DocumentEvent =
+  | { type: 'created'; key: string }
+  | { type: 'saved'; key: string }
+  | { type: 'createdAndPublished'; key: string; cultures: readonly string[] | null }
+  | { type: 'savedAndPublished'; key: string; cultures: readonly string[] | null }
+  | { type: 'published'; key: string; cultures: readonly string[] | null }
+  /** Only scheduled: nothing is published until the schedule fires. */
+  | { type: 'scheduled'; key: string }
+  /** A page and the pages below it: `published` names each one that went live. */
+  | { type: 'branchPublished'; key: string; published: readonly string[] }
+  | { type: 'unpublished'; key: string; cultures: readonly string[] | null }
+  | { type: 'trashed'; key: string }
+  /** `name` is read before it went, since it cannot be read after. */
+  | { type: 'deleted'; key: string; name: string | null }
+  | { type: 'restored'; key: string }
+  | { type: 'binEmptied' }
+  | { type: 'moved'; key: string }
+  | { type: 'copied'; key: string; copyKey: string }
+  /** `parentKey` null: the top level. */
+  | { type: 'sorted'; parentKey: string | null }
+  | { type: 'rolledBack'; key: string; versionId: string }
+  | { type: 'domainsAssigned'; key: string }
+  | { type: 'publicAccessChanged'; key: string; change: 'added' | 'set' | 'removed' }
+
+/**
+ * Where an operation reports what it did (story 171). `record` runs inside the
+ * change's own transaction, so what must not be lost — the audit entry, the
+ * announcement waiting to go out — commits with the change or not at all.
+ * `afterCommit` is for what only a running server does once it has.
+ */
+export interface EventSink {
+  record(tx: Db, event: DocumentEvent, actor: Actor): Promise<void>
+  afterCommit?(event: DocumentEvent, actor: Actor): void
+}
+
+/** A sink that hears nothing: for tests and tools that announce nothing. */
+export const SILENT: EventSink = { record: async () => {} }
+
+/** Several sinks heard in turn. */
+export const both = (...sinks: EventSink[]): EventSink => ({
+  async record(tx, event, actor) {
+    for (const sink of sinks) await sink.record(tx, event, actor)
+  },
+  afterCommit(event, actor) {
+    for (const sink of sinks) sink.afterCommit?.(event, actor)
+  },
+})
+
+/** The audit entry an event writes: the same whichever transport started it. Pure. */
+export function auditFor(event: DocumentEvent): {
+  category: 'content' | 'permission'
+  action: string
+  entityType: string
+  entityKey: string | null
+  detail?: string
+} {
+  const doc = (action: string, key: string | null) => ({
+    category: 'content' as const,
+    action,
+    entityType: 'Document',
+    entityKey: key,
+  })
+  switch (event.type) {
+    case 'created':
+      return doc('Create', event.key)
+    case 'saved':
+      return doc('Save', event.key)
+    case 'createdAndPublished':
+      return doc('CreateAndPublish', event.key)
+    case 'savedAndPublished':
+      return doc('SaveAndPublish', event.key)
+    case 'published':
+    case 'scheduled':
+      return doc('Publish', event.key)
+    case 'branchPublished':
+      return doc('PublishWithDescendants', event.key)
+    case 'unpublished':
+      return doc('Unpublish', event.key)
+    case 'trashed':
+      return doc('Trash', event.key)
+    case 'deleted':
+      return doc('Delete', event.key)
+    case 'restored':
+      return doc('Restore', event.key)
+    case 'binEmptied':
+      return doc('EmptyRecycleBin', null)
+    case 'moved':
+      return doc('Move', event.key)
+    case 'copied':
+      return doc('Copy', event.key)
+    case 'sorted':
+      return doc('Sort', event.parentKey)
+    case 'rolledBack':
+      return { ...doc('Rollback', event.versionId), entityType: 'DocumentVersion' }
+    case 'domainsAssigned':
+      return doc('AssignDomains', event.key)
+    case 'publicAccessChanged':
+      return {
+        ...doc(
+          event.change === 'added'
+            ? 'AddPublicAccess'
+            : event.change === 'set'
+              ? 'SetPublicAccess'
+              : 'RemovePublicAccess',
+          event.key,
+        ),
+        category: 'permission',
+      }
+  }
+}
+
+/** The webhook an event raises, by Umbraco's alias, and the page it names. Pure. */
+export function webhookFor(event: DocumentEvent): { alias: string; key: string } | undefined {
+  switch (event.type) {
+    case 'created':
+    case 'saved':
+      return { alias: 'Umbraco.ContentSaved', key: event.key }
+    case 'createdAndPublished':
+    case 'savedAndPublished':
+    case 'published':
+    case 'branchPublished':
+      return { alias: 'Umbraco.ContentPublish', key: event.key }
+    case 'unpublished':
+      return { alias: 'Umbraco.ContentUnpublish', key: event.key }
+    case 'deleted':
+      return { alias: 'Umbraco.ContentDelete', key: event.key }
+    case 'trashed':
+      return { alias: 'Umbraco.ContentMovedToRecycleBin', key: event.key }
+    // Out of the bin is a move, as Umbraco raises it.
+    case 'moved':
+    case 'restored':
+      return { alias: 'Umbraco.ContentMoved', key: event.key }
+    case 'copied':
+      return { alias: 'Umbraco.ContentCopied', key: event.copyKey }
+    case 'sorted':
+      return event.parentKey ? { alias: 'Umbraco.ContentSorted', key: event.parentKey } : undefined
+    case 'rolledBack':
+      return { alias: 'Umbraco.ContentRolledBack', key: event.key }
+    // A schedule publishes nothing yet: the job raises it when it fires.
+    case 'scheduled':
+    case 'binEmptied':
+    case 'domainsAssigned':
+    case 'publicAccessChanged':
+      return undefined
+  }
+}
+
+/** The change people subscribed to a page hear of (story 045), if any. Pure. */
+export function notificationFor(event: DocumentEvent):
+  | {
+      actions: string[]
+      key: string
+      keyKind: 'document' | 'version'
+      withDescendants?: boolean
+    }
+  | undefined {
+  const of = (actions: string[], key: string) => ({ actions, key, keyKind: 'document' as const })
+  switch (event.type) {
+    case 'created':
+      return of(['Umb.Document.Create'], event.key)
+    case 'saved':
+      return of(['Umb.Document.Update'], event.key)
+    case 'createdAndPublished':
+      return of(['Umb.Document.Create', 'Umb.Document.Publish'], event.key)
+    case 'savedAndPublished':
+      return of(['Umb.Document.Update', 'Umb.Document.Publish'], event.key)
+    case 'published':
+      return of(['Umb.Document.Publish'], event.key)
+    case 'branchPublished':
+      return { ...of(['Umb.Document.Publish'], event.key), withDescendants: true }
+    case 'trashed':
+      return of(['Umb.Document.Delete'], event.key)
+    case 'moved':
+      return of(['Umb.Document.Move'], event.key)
+    // Notified on the original, as Umbraco does.
+    case 'copied':
+      return of(['Umb.Document.Duplicate'], event.key)
+    // On the parent whose children were sorted; sorting the top level notifies nobody.
+    case 'sorted':
+      return event.parentKey ? of(['Umb.Document.Sort'], event.parentKey) : undefined
+    case 'rolledBack':
+      return { actions: ['Umb.Document.Rollback'], key: event.versionId, keyKind: 'version' }
+    case 'restored':
+      return of(['Umb.DocumentRecycleBin.Restore'], event.key)
+    case 'publicAccessChanged':
+      return of(['Umb.Document.PublicAccess'], event.key)
+    case 'scheduled':
+    case 'unpublished':
+    case 'deleted':
+    case 'binEmptied':
+    case 'domainsAssigned':
+      return undefined
+  }
+}
+
+/**
+ * The live events an open backoffice drops its cached copy on, by Umbraco's
+ * names: one per page the change touched. Pure.
+ */
+export function liveEventsFor(event: DocumentEvent): Array<{
+  eventSource: string
+  eventType: 'Created' | 'Updated' | 'Deleted' | 'Trashed'
+  key: string
+}> {
+  const source = 'Umbraco:CMS:Document'
+  const one = (eventType: 'Created' | 'Updated' | 'Deleted' | 'Trashed', key: string) => [
+    { eventSource: source, eventType, key },
+  ]
+  switch (event.type) {
+    case 'created':
+    case 'createdAndPublished':
+      return one('Created', event.key)
+    case 'copied':
+      return one('Created', event.copyKey)
+    case 'trashed':
+      return one('Trashed', event.key)
+    case 'deleted':
+      return one('Deleted', event.key)
+    case 'branchPublished':
+      return [...new Set([event.key, ...event.published])].map((key) => ({
+        eventSource: source,
+        eventType: 'Updated' as const,
+        key,
+      }))
+    case 'sorted':
+      return event.parentKey ? one('Updated', event.parentKey) : []
+    case 'binEmptied':
+      return []
+    default:
+      return one('Updated', event.key)
+  }
+}
+
+/**
+ * The whole audit entry an event writes, as every transport writes it: the
+ * entry, who acted and from where. An operator who skipped approval is said to
+ * have. The item's name is the transport's to look up. Pure.
+ */
+export function auditEntryFor(event: DocumentEvent, actor: Actor) {
+  const entry = auditFor(event)
+  const skipped = actor.kind === 'operator' && actor.skipApproval === true
+  return {
+    ...entry,
+    source: actor.origin.source,
+    userKey: actorUserKey(actor),
+    userName: actorName(actor),
+    ipAddress: actor.origin.ipAddress ?? null,
+    forwardedFor: actor.origin.forwardedFor ?? null,
+    detail: skipped
+      ? 'Approval skipped from the command line'
+      : (sentence(actorNote(actor)) ?? entry.detail ?? null),
+  }
+}
+
+/** A note as the audit log writes it: a capital first, as its entries read. */
+const sentence = (note: string | undefined) =>
+  note ? note.charAt(0).toUpperCase() + note.slice(1) : undefined

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './operations.ts'
+export * from './rules.ts'