@crombolo/delivery-client 0.0.0-stage → 0.22.0

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/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @crombolo/delivery-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for a [crombolo](https://github.com/kineco-au/crombolo-cms) site's
+Delivery API, for an app in the browser, Node or Bun. No dependencies.
+
+```sh
+npm install @crombolo/delivery-client
+# in the site: write its types into the app
+bunx crombolo generate --delivery --out ../app/src/cms-types.ts
+```
+
+```ts
+import { createDeliveryClient, isExpanded } from '@crombolo/delivery-client'
+import type { DeliveryTypes } from './cms-types'
+
+const cms = createDeliveryClient<DeliveryTypes>({ baseUrl: 'https://cms.example.com' })
+
+const page = await cms.item('/news/story', { expand: 'properties[related]' })
+if (page?.contentType === 'article') {
+  console.log(page.properties.title)
+  const related = page.properties.related
+  if (related && isExpanded(related)) console.log(related.properties)
+}
+
+const latest = await cms.content({ fetch: 'children:/news', sort: 'createDate:desc', take: 5 })
+const hits = await cms.search('harbour')
+```
+
+- `item`, `items`, `content`, `mediaItem`, `mediaItems`, `media` and `search`,
+  with the API's own `expand`, `fields`, `fetch`, `filter` and `sort` grammar.
+- `apiKey`, `culture`, `startItem` and `memberToken` options, each overridable
+  per request. Keep an API key out of code that runs in a browser.
+- An item that is not there is `undefined`; anything else refused throws a
+  `DeliveryError` with its `status` and `body`.
+- A browser app on another origin needs the site to allow it:
+  `deliveryApi.cors.allowedOrigins`.
+
+The site's docs describe the API and the generated types: `docs/delivery-api.md`.

package/dist/index.d.ts

@@ -0,0 +1,294 @@
+/**
+ * A typed client for a crombolo site's Delivery API (`/umbraco/delivery/api/v2`).
+ * The shapes are the JSON the API writes; `crombolo generate --delivery` writes
+ * a site's content types as a `DeliveryTypes` map to pass in as the generic.
+ * docs/delivery-api.md, "Typed apps".
+ *
+ * One file and no dependencies, because it is built to plain JavaScript for apps
+ * on any toolchain, unlike the rest of crombolo.
+ */
+/** Where a page lives: its path below its root, and the root itself. */
+export interface ApiRoute {
+    path: string;
+    queryString: string | null;
+    startItem: {
+        id: string;
+        path: string;
+    };
+}
+/** What a picker's target carries when it was not expanded. */
+export type NotExpanded = Record<string, never>;
+export interface ApiContent<Alias extends string = string, Properties = Record<string, unknown>> {
+    contentType: Alias;
+    name: string;
+    createDate: string;
+    updateDate: string;
+    route: ApiRoute;
+    id: string;
+    properties: Properties;
+}
+/** A page as a picker or a link holds it: its properties are there only when expanded. */
+export type ApiContentReference<Alias extends string = string, Properties = Record<string, unknown>> = ApiContent<Alias, Properties | NotExpanded>;
+/** A page as the item, items, query and search endpoints answer it. */
+export interface ApiContentResponse<Alias extends string = string, Properties = Record<string, unknown>> extends ApiContent<Alias, Properties> {
+    /** Its route in each culture; empty for a page that does not vary. */
+    cultures: Record<string, ApiRoute>;
+}
+/** A block or picked element: its properties are always there. */
+export interface ApiElement<Alias extends string = string, Properties = Record<string, unknown>> {
+    contentType: Alias;
+    id: string;
+    name: string;
+    properties: Properties;
+}
+export interface ApiFocalPoint {
+    left: number;
+    top: number;
+}
+export interface ApiCrop {
+    alias: string;
+    width: number;
+    height: number;
+    coordinates: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    } | null;
+}
+export interface ApiMedia<Alias extends string = string, Properties = Record<string, unknown>> {
+    id: string;
+    name: string;
+    mediaType: Alias;
+    url: string;
+    extension: string | null;
+    width: number | null;
+    height: number | null;
+    bytes: number | null;
+    properties: Properties;
+}
+/** Media as a picker holds it: its own properties are there only when expanded. */
+export type ApiMediaReference<Alias extends string = string, Properties = Record<string, unknown>> = ApiMedia<Alias, Properties | NotExpanded>;
+/** Media picked with the media picker: its crops and focal point, the pick's own first. */
+export type ApiMediaWithCrops<Alias extends string = string, Properties = Record<string, unknown>> = ApiMediaReference<Alias, Properties> & {
+    focalPoint: ApiFocalPoint | null;
+    crops: ApiCrop[];
+};
+/** Media as the media item and query endpoints answer it. */
+export type ApiMediaResponse<Alias extends string = string, Properties = Record<string, unknown>> = ApiMedia<Alias, Properties> & {
+    /** Names from the root down, lower case, with a trailing slash. */
+    path: string;
+    createDate: string;
+    updateDate: string;
+    focalPoint: ApiFocalPoint | null;
+    crops: ApiCrop[] | null;
+};
+export interface ApiLink {
+    url: string | null;
+    queryString: string | null;
+    title: string | null;
+    target: string | null;
+    destinationId: string | null;
+    destinationType: string | null;
+    route: ApiRoute | null;
+    linkType: 'Content' | 'Media' | 'External';
+    culture: string | null;
+}
+export interface ApiBlockListItem<Content = ApiElement, Settings = ApiElement> {
+    content: Content | null;
+    settings: Settings | null;
+}
+export interface ApiBlockList<Content = ApiElement, Settings = ApiElement> {
+    items: ApiBlockListItem<Content, Settings>[];
+}
+export interface ApiBlockGridArea<Content = ApiElement, Settings = ApiElement> {
+    alias: string;
+    rowSpan: number;
+    columnSpan: number;
+    items: ApiBlockGridItem<Content, Settings>[];
+}
+export interface ApiBlockGridItem<Content = ApiElement, Settings = ApiElement> extends ApiBlockListItem<Content, Settings> {
+    rowSpan: number;
+    columnSpan: number;
+    areaGridColumns: number;
+    areas: ApiBlockGridArea<Content, Settings>[];
+}
+export interface ApiBlockGrid<Content = ApiElement, Settings = ApiElement> {
+    gridColumns: number;
+    items: ApiBlockGridItem<Content, Settings>[];
+}
+/** Rich text: its markup, with links already this site's URLs. */
+export interface ApiRichText {
+    markup: string;
+    blocks: unknown[];
+}
+export interface ApiColor {
+    value: string;
+    label: string;
+}
+export interface ApiImageCropper {
+    url: string | null;
+    focalPoint: ApiFocalPoint | null;
+    crops: ApiCrop[];
+}
+/** A site's types, as `crombolo generate --delivery` writes them: each alias's properties. */
+export interface DeliverySchema {
+    content: object;
+    media: object;
+}
+type Aliases<Map> = Extract<keyof Map, string>;
+/** Any page the site serves, told apart by `contentType`. */
+export type ContentItem<Schema extends DeliverySchema = DeliverySchema> = DeliverySchema extends Schema ? ApiContentResponse : {
+    [Alias in Aliases<Schema['content']>]: ApiContentResponse<Alias, Schema['content'][Alias]>;
+}[Aliases<Schema['content']>];
+/** Any media item, told apart by `mediaType`. */
+export type MediaItem<Schema extends DeliverySchema = DeliverySchema> = DeliverySchema extends Schema ? ApiMediaResponse : {
+    [Alias in Aliases<Schema['media']>]: ApiMediaResponse<Alias, Schema['media'][Alias]>;
+}[Aliases<Schema['media']>];
+/** A search result: the page, how well it matched, and an excerpt with matches in `<mark>`. */
+export type SearchHit<Schema extends DeliverySchema = DeliverySchema> = ContentItem<Schema> & {
+    score: number;
+    /** HTML: everything escaped but the `<mark>` around each matching word. */
+    excerpt: string;
+};
+/** What the site answers at an address: a page, a redirect, or not found. */
+export type RouteAnswer<Schema extends DeliverySchema = DeliverySchema> = {
+    kind: 'page';
+    culture: string | null;
+    item: ContentItem<Schema>;
+} | {
+    kind: 'redirect';
+    location: string;
+    statusCode: number;
+    permanent: boolean;
+}
+/** With the site's not-found page, when it has one. */
+ | {
+    kind: 'notFound';
+    item: ContentItem<Schema> | null;
+};
+/** A menu's entry: a page, media item, address or label, with the entries below it. */
+export interface ApiMenuItem {
+    label: string;
+    kind: 'page' | 'media' | 'external' | 'label';
+    /** The page or media item it links to. */
+    id: string | null;
+    /** An address for media and external links; a page has its `route` instead. */
+    url: string | null;
+    route: ApiRoute | null;
+    target: string | null;
+    children: ApiMenuItem[];
+}
+export interface ApiMenu {
+    alias: string;
+    items: ApiMenuItem[];
+}
+export interface Paged<Item> {
+    total: number;
+    items: Item[];
+}
+/**
+ * Whether a picker's target came back expanded. An expanded target carries every
+ * property, empty ones as `null`; an unexpanded one carries none.
+ */
+export declare function isExpanded<Reference extends {
+    properties: object;
+}>(reference: Reference): reference is Reference & {
+    properties: Exclude<Reference['properties'], NotExpanded>;
+};
+/** `fields` narrows the properties a response carries, so any may be missing. */
+type Narrowed<Item> = Item extends {
+    properties: infer Properties;
+} ? Omit<Item, 'properties'> & {
+    properties: Partial<Properties>;
+} : Item;
+type Fielded<Item, Options> = Options extends {
+    fields: string;
+} ? Narrowed<Item> : Item;
+export interface RequestOptions {
+    /** A culture name, such as `en-US`; otherwise the client's, then the site's default. */
+    culture?: string;
+    /** A root's id or path, to resolve paths and queries under it. */
+    startItem?: string;
+    /** Which pickers to expand: `properties[$all]`, `properties[related[properties[$all]]]`. */
+    expand?: string;
+    /** Which properties to include: `properties[title,image]`. */
+    fields?: string;
+    signal?: AbortSignal;
+}
+export interface ContentQuery extends RequestOptions {
+    /** `children:<id or path>`, `descendants:…` or `ancestors:…`; everything when left out. */
+    fetch?: string;
+    /** `contentType:page`, `name:news`, `createDate>2026-01-01`; filters combine with AND. */
+    filter?: string | string[];
+    /** `name:asc`, `createDate:desc`, `sortOrder:asc`, `level:asc`, `updateDate:desc`. */
+    sort?: string | string[];
+    skip?: number;
+    take?: number;
+}
+export interface MediaQuery extends Omit<RequestOptions, 'culture' | 'startItem'> {
+    /** Required: `children:/` for the top level, or `children:<id or path>`. */
+    fetch: string;
+    filter?: string | string[];
+    sort?: string | string[];
+    skip?: number;
+    take?: number;
+}
+export interface SearchOptions {
+    culture?: string;
+    /** Keep to these page types. */
+    contentType?: string | string[];
+    skip?: number;
+    /** At most 100. */
+    take?: number;
+    signal?: AbortSignal;
+}
+export interface DeliveryClientOptions {
+    /** The site's address, such as `https://cms.example.com`. */
+    baseUrl: string;
+    /** Sent as `Api-Key`, for a site whose API is not public. Keep it out of browser code. */
+    apiKey?: string;
+    /** The culture every request asks for unless it names its own. */
+    culture?: string;
+    /** The root every request resolves under unless it names its own. */
+    startItem?: string;
+    /** A signed-in member's access token, for members-only pages. Asked for on every request. */
+    memberToken?: () => string | undefined | Promise<string | undefined>;
+    /** Headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Defaults to the global `fetch`. */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+}
+/** A refusal or failure from the API: its status, and its body when it had one. */
+export declare class DeliveryError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, url: string);
+}
+export interface DeliveryClient<Schema extends DeliverySchema = DeliverySchema> {
+    /** One page by id or path; undefined when there is none. */
+    item<Options extends RequestOptions>(idOrPath: string, options?: Options): Promise<Fielded<ContentItem<Schema>, Options> | undefined>;
+    /** Pages by id, in the order asked, leaving out any that do not exist. */
+    items<Options extends RequestOptions>(ids: readonly string[], options?: Options): Promise<Fielded<ContentItem<Schema>, Options>[]>;
+    /** A page of pages, filtered and sorted. */
+    content<Options extends ContentQuery>(query?: Options): Promise<Paged<Fielded<ContentItem<Schema>, Options>>>;
+    /** One media item by id or path; undefined when there is none. */
+    mediaItem<Options extends RequestOptions>(idOrPath: string, options?: Options): Promise<Fielded<MediaItem<Schema>, Options> | undefined>;
+    mediaItems<Options extends RequestOptions>(ids: readonly string[], options?: Options): Promise<Fielded<MediaItem<Schema>, Options>[]>;
+    /** A page of media below a folder. */
+    media<Options extends MediaQuery>(query: Options): Promise<Paged<Fielded<MediaItem<Schema>, Options>>>;
+    /** Published pages matching every word of the term, best first. */
+    search(term: string, options?: SearchOptions): Promise<Paged<SearchHit<Schema>>>;
+    /**
+     * What the site would answer at a visitor's address — the page, a redirect, or
+     * not found — for an app's router. `host` picks the root and culture as the
+     * site's domains do.
+     */
+    /** A menu by its alias, in the culture asked for; undefined when there is none. */
+    menu(alias: string, options?: Pick<RequestOptions, 'culture' | 'signal'>): Promise<ApiMenu | undefined>;
+    route(path: string, options?: Omit<RequestOptions, 'culture' | 'fields'> & {
+        host?: string;
+    }): Promise<RouteAnswer<Schema>>;
+}
+export declare function createDeliveryClient<Schema extends DeliverySchema = DeliverySchema>(options: DeliveryClientOptions): DeliveryClient<Schema>;
+export {};

package/dist/index.js

@@ -0,0 +1,86 @@
+// packages/delivery-client/src/index.ts
+function isExpanded(reference) {
+  return Object.keys(reference.properties).length > 0;
+}
+
+class DeliveryError extends Error {
+  status;
+  body;
+  constructor(status, body, url) {
+    super(`The Delivery API answered ${status} for ${url}`);
+    this.name = "DeliveryError";
+    this.status = status;
+    this.body = body;
+  }
+}
+var API_PATH = "/umbraco/delivery/api/v2";
+var list = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+var itemPath = (idOrPath) => idOrPath.replace(/^\/+/, "").split("/").map((segment) => encodeURIComponent(segment)).join("/");
+function createDeliveryClient(options) {
+  const base = `${options.baseUrl.replace(/\/+$/, "")}${API_PATH}`;
+  const send = options.fetch ?? ((input, init) => fetch(input, init));
+  async function get(path, params, request, missing) {
+    const query = new URLSearchParams(params).toString();
+    const url = `${base}/${path}${query ? `?${query}` : ""}`;
+    const headers = { accept: "application/json", ...options.headers };
+    if (options.apiKey)
+      headers["api-key"] = options.apiKey;
+    const culture = request.culture ?? options.culture;
+    if (culture)
+      headers["accept-language"] = culture;
+    const startItem = request.startItem ?? options.startItem;
+    if (startItem)
+      headers["start-item"] = startItem;
+    const token = await options.memberToken?.();
+    if (token)
+      headers.authorization = `Bearer ${token}`;
+    const response = await send(url, { headers, signal: request.signal });
+    if (response.status === 404 && missing === "undefined")
+      return;
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : null;
+    if (response.status === 404 && missing === "body")
+      return body;
+    if (!response.ok)
+      throw new DeliveryError(response.status, body, url);
+    return body;
+  }
+  const shaping = (request) => [
+    ...request.expand ? [["expand", request.expand]] : [],
+    ...request.fields ? [["fields", request.fields]] : []
+  ];
+  const paging = (query) => [
+    ...list(query.filter).map((filter) => ["filter", filter]),
+    ...list(query.sort).map((sort) => ["sort", sort]),
+    ...query.skip !== undefined ? [["skip", String(query.skip)]] : [],
+    ...query.take !== undefined ? [["take", String(query.take)]] : []
+  ];
+  const ids = (keys) => keys.map((id) => ["id", id]);
+  return {
+    item: (idOrPath, request) => get(`content/item/${itemPath(idOrPath)}`, shaping(request ?? {}), request ?? {}, "undefined"),
+    items: (keys, request) => get("content/items", [...ids(keys), ...shaping(request ?? {})], request ?? {}, "throw"),
+    content: (query) => {
+      const q = query ?? {};
+      return get("content", [...q.fetch ? [["fetch", q.fetch]] : [], ...paging(q), ...shaping(q)], q, "throw");
+    },
+    mediaItem: (idOrPath, request) => get(`media/item/${itemPath(idOrPath)}`, shaping(request ?? {}), request ?? {}, "undefined"),
+    mediaItems: (keys, request) => get("media/items", [...ids(keys), ...shaping(request ?? {})], request ?? {}, "throw"),
+    media: (query) => get("media", [["fetch", query.fetch], ...paging(query), ...shaping(query)], query, "throw"),
+    menu: (alias, request = {}) => get(`menus/${encodeURIComponent(alias)}`, [], request, "undefined"),
+    route: (path, request = {}) => get("route", [
+      ["path", path],
+      ...request.host ? [["host", request.host]] : [],
+      ...shaping(request)
+    ], request, "body"),
+    search: (term, search = {}) => get("search", [
+      ["term", term],
+      ...list(search.contentType).map((type) => ["contentType", type]),
+      ...paging(search)
+    ], search, "throw")
+  };
+}
+export {
+  DeliveryError,
+  createDeliveryClient,
+  isExpanded
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@crombolo/delivery-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.22.0",
+  "description": "A typed client for a crombolo site's Delivery API, for apps in the browser, Node or Bun. No dependencies.",
+  "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/delivery-client"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "keywords": [
+    "crombolo",
+    "headless",
+    "delivery-api"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}