@crombolo/api-delivery 0.0.0-stage → 0.13.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/api-delivery",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.1",
+  "description": "Umbraco's Content Delivery API for crombolo: published content and media as JSON, served from the published cache.",
+  "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/api-delivery"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/core": "0.13.1",
+    "@crombolo/contracts": "0.13.1",
+    "@crombolo/render": "0.13.1"
+  }
+}

package/src/coverage.ts

@@ -0,0 +1,27 @@
+/**
+ * How much of the Delivery API contract is served, found by asking: each
+ * operation is sent to the handler with placeholder parameters, and counts
+ * when the handler answers it at all rather than passing it on.
+ */
+import { listOperations, loadDeliverySpec, type OperationInfo } from '@crombolo/contracts'
+import type { DeliveryApi } from './handler.ts'
+
+/** A request for an operation, its path parameters filled with placeholders. Pure. */
+export function probeFor(op: OperationInfo, origin = 'http://localhost'): Request {
+  const path = op.path
+    .replace('{id}', '00000000-0000-4000-8000-000000000001')
+    .replace('{path}', 'probe')
+  return new Request(`${origin}${path}`, { method: op.method.toUpperCase() })
+}
+
+export async function deliveryCoverage(
+  api: DeliveryApi,
+): Promise<{ operations: OperationInfo[]; served: Set<string> }> {
+  const operations = listOperations(loadDeliverySpec())
+  const served = new Set<string>()
+  for (const op of operations) {
+    const response = await api.handle(probeFor(op))
+    if (response && response.status !== 501) served.add(op.operationId)
+  }
+  return { operations, served }
+}

package/src/expansion.ts

@@ -0,0 +1,81 @@
+/**
+ * `expand` and `fields` (v2): which pickers are expanded, and which properties
+ * are kept, as Umbraco's `ElementOnlyOutputExpansionStrategy` reads them.
+ * `properties[a,b[properties[c]]]` is a tree; `$all` matches every alias.
+ */
+
+export interface ExpansionNode {
+  key: string
+  children: ExpansionNode[]
+}
+
+export class ExpansionSyntaxError extends Error {}
+
+/** `properties[a,b[properties[c]]]` as a tree under an unnamed root. Pure. */
+export function parseExpansion(value: string): ExpansionNode {
+  const root: ExpansionNode = { key: '', children: [] }
+  const text = value.trim()
+  if (!text) return root
+  const opens = [...text].filter((c) => c === '[').length
+  const closes = [...text].filter((c) => c === ']').length
+  if (opens !== closes)
+    throw new ExpansionSyntaxError(
+      'Value did not contain an equal number of start and end brackets',
+    )
+  if (text.startsWith('[')) throw new ExpansionSyntaxError('Value cannot start with a bracket')
+  if (text.includes('[]')) throw new ExpansionSyntaxError('Value cannot contain empty brackets')
+
+  const stack: ExpansionNode[] = [root]
+  let current: ExpansionNode | undefined
+  let name = ''
+  const flush = () => {
+    if (name.trim() && !current) {
+      current = { key: name.trim(), children: [] }
+      ;(stack[stack.length - 1] as ExpansionNode).children.push(current)
+    } else if (name.trim() && current) current.key += name.trim()
+    name = ''
+  }
+  for (const c of text) {
+    if (c === '[') {
+      flush()
+      if (!current) throw new ExpansionSyntaxError('Value cannot contain empty brackets')
+      stack.push(current)
+      current = undefined
+    } else if (c === ']') {
+      flush()
+      current = stack.pop()
+    } else if (c === ',') {
+      flush()
+      current = undefined
+    } else name += c
+  }
+  flush()
+  return root
+}
+
+const child = (node: ExpansionNode | undefined, key: string) =>
+  node?.children.find((c) => c.key === key)
+
+/**
+ * The node governing a property at this level: `$all` here, else
+ * `properties[$all]` or `properties[<alias>]`. Pure.
+ */
+export function nextNode(
+  node: ExpansionNode | undefined,
+  alias: string,
+): ExpansionNode | undefined {
+  if (!node) return undefined
+  const all = child(node, '$all')
+  if (all) return all
+  const properties = child(node, 'properties')
+  return child(properties, '$all') ?? child(properties, alias)
+}
+
+/** Whether `fields` keeps a property: a node with no children keeps everything beneath it. Pure. */
+export function keeps(include: ExpansionNode | undefined, alias: string): boolean {
+  if (!include || include.children.length === 0) return true
+  return nextNode(include, alias) !== undefined
+}
+
+/** The default for an absent `fields`: everything. */
+export const ALL_FIELDS: ExpansionNode = { key: '', children: [{ key: '$all', children: [] }] }