@crombolo/delivery-client 0.36.2 → 0.38.1

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export type ApiContentReference<Alias extends string = string, Properties = Reco
 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>;
+    /** Search and sharing details, when asked for with `seo: true`. */
+    seo?: ApiSeo;
 }
 /** A block or picked element: its properties are always there. */
 export interface ApiElement<Alias extends string = string, Properties = Record<string, unknown>> {
@@ -117,11 +119,87 @@ 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[];
+/** Text in a rich-text tree. */
+export interface RichTextTextElement {
+    $type: 'RichTextTextElement';
+    tag: '#text';
+    text: string;
 }
+/** A tag in a rich-text tree, its `data-*` attributes without their prefix. */
+export interface RichTextGenericElement<Tag extends string = string, Attributes = RichTextAttributes> {
+    $type: 'RichTextGenericElement';
+    tag: Tag;
+    attributes: Attributes;
+    elements: RichTextElement[];
+}
+export type RichTextAttributes = Record<string, unknown>;
+/**
+ * A link: to a page, with its `route` and no `href`; to media, with `href` its
+ * URL; or anywhere else, with `href` as written. A local link to nothing has
+ * neither.
+ */
+export interface RichTextLinkAttributes extends RichTextAttributes {
+    href?: string;
+    target?: string;
+    title?: string;
+    destinationId?: string;
+    destinationType?: string;
+    linkType?: 'Content' | 'Media';
+    route?: ApiRoute;
+}
+/** An image; from the media library, `src` is its URL with the crop query kept. */
+export interface RichTextImageAttributes extends RichTextAttributes {
+    src?: string;
+    alt?: string;
+    width?: string;
+    height?: string;
+}
+/** Where a block sits: `content-id` names its entry in the value's `blocks`. */
+export interface RichTextBlockAttributes extends RichTextAttributes {
+    'content-id': string;
+}
+/** The tags whose attributes are known. */
+export interface RichTextTags {
+    a: RichTextGenericElement<'a', RichTextLinkAttributes>;
+    img: RichTextGenericElement<'img', RichTextImageAttributes>;
+    'umb-rte-block': RichTextGenericElement<'umb-rte-block', RichTextBlockAttributes>;
+    'umb-rte-block-inline': RichTextGenericElement<'umb-rte-block-inline', RichTextBlockAttributes>;
+}
+export type RichTextBlockElement = RichTextTags['umb-rte-block' | 'umb-rte-block-inline'];
+/** Any element below the root. */
+export type RichTextElement = RichTextGenericElement | RichTextTextElement;
+/**
+ * A rich-text value: Umbraco's `RichTextOutputAsJson` tree, the only form the
+ * Delivery API answers rich text in (story 216).
+ */
+export interface RichTextValue<Content = ApiElement, Settings = ApiElement> {
+    tag: '#root';
+    attributes: RichTextAttributes;
+    elements: RichTextElement[];
+    blocks: ApiBlockListItem<Content, Settings>[];
+}
+/**
+ * What `walkRichText` makes of each node, given what it made of the node's
+ * children. A tag with no visitor of its own goes to `element`; a block to
+ * `block` when there is one, with its entry in `blocks`.
+ */
+export interface RichTextVisitors<Result, Content = ApiElement, Settings = ApiElement> {
+    text(node: RichTextTextElement): Result;
+    element(node: RichTextGenericElement, children: Result[]): Result;
+    block?(item: ApiBlockListItem<Content, Settings> | undefined, node: RichTextBlockElement): Result;
+    tags?: {
+        [Tag in keyof RichTextTags]?: (node: RichTextTags[Tag], children: Result[]) => Result;
+    } & {
+        [tag: string]: ((node: never, children: Result[]) => Result) | undefined;
+    };
+}
+/**
+ * Text or an attribute from a rich-text tree as characters: the tree keeps
+ * entities as the CMS stored them, as Umbraco's does. Unknown names are left.
+ */
+export declare function decodeEntities(text: string): string;
+/** A rich-text tree folded through `visitors`, children first: what each top-level node made. */
+export declare function walkRichText<Result, Content = ApiElement, Settings = ApiElement>(tree: RichTextValue<Content, Settings>, visitors: RichTextVisitors<Result, Content, Settings>): Result[];
 export interface ApiColor {
     value: string;
     label: string;
@@ -205,6 +283,62 @@ type Narrowed<Item> = Item extends {
 type Fielded<Item, Options> = Options extends {
     fields: string;
 } ? Narrowed<Item> : Item;
+/** A page's search and sharing details, with `seo: true` (story 055). */
+export interface ApiSeo {
+    title: string;
+    description: string | null;
+    image: {
+        url: string;
+        width: number | null;
+        height: number | null;
+    } | null;
+    canonical: string | null;
+    robots: string | null;
+    alternates: Array<{
+        culture: string;
+        url: string;
+    }>;
+    xDefault: string | null;
+    siteName: string;
+}
+/** One page `sitemap(host)` lists. */
+export interface ApiSitemapItem {
+    id: string;
+    url: string;
+    lastmod: string;
+    alternates: Array<{
+        culture: string;
+        url: string;
+    }>;
+}
+/** What a request learned, for a cache that tags what it keeps. */
+export interface DeliveryAnswer {
+    url: string;
+    status: number;
+    /** Every page and media key the answer holds, lower case. */
+    keys: string[];
+    /** The purge tags the site sent, when it sends them. */
+    tags: string[];
+    etag: string | null;
+    cacheControl: string | null;
+    /** The answer came from a kept copy after a `304`. */
+    revalidated: boolean;
+}
+/** Copies kept for `If-None-Match`, by address. */
+export interface ConditionalStore {
+    get(url: string): {
+        etag: string;
+        body: string;
+    } | undefined;
+    set(url: string, copy: {
+        etag: string;
+        body: string;
+    }): void;
+}
+/** A store of the most recent `limit` copies, in memory. */
+export declare function memoryConditionalStore(limit?: number): ConditionalStore;
+/** Every page and media key in an answer, lower case: items, pickers, links, list entries. */
+export declare function contentKeysIn(body: unknown): string[];
 export interface RequestOptions {
     /** A culture name, such as `en-US`; otherwise the client's, then the site's default. */
     culture?: string;
@@ -214,6 +348,8 @@ export interface RequestOptions {
     expand?: string;
     /** Which properties to include: `properties[title,image]`. */
     fields?: string;
+    /** Adds each page's search and sharing details as `seo`. */
+    seo?: boolean;
     signal?: AbortSignal;
 }
 export interface ContentQuery extends RequestOptions {
@@ -261,6 +397,21 @@ export interface DeliveryClientOptions {
     memberToken?: () => string | undefined | Promise<string | undefined>;
     /** Headers sent with every request. */
     headers?: Record<string, string>;
+    /**
+     * Drafts instead of what is published (story 053): `Preview: true`, with the
+     * editor's preview token when there is one. Asked for on every request.
+     */
+    preview?: () => boolean | {
+        token?: string;
+    } | undefined | Promise<boolean | {
+        token?: string;
+    } | undefined>;
+    /** Told about every answer: its keys and tags, for a cache to tag what it keeps. */
+    onAnswer?: (answer: DeliveryAnswer) => void;
+    /** Keeps copies and revalidates them with `If-None-Match`; a `304` reuses the copy. */
+    conditional?: ConditionalStore;
+    /** Where the site sends purge tags; `Surrogate-Key` and `Cache-Tag` are read when unset. */
+    tagHeader?: string;
     /** Defaults to the global `fetch`. */
     fetch?: (input: string, init: RequestInit) => Promise<Response>;
 }
@@ -294,6 +445,10 @@ export interface DeliveryClient<Schema extends DeliverySchema = DeliverySchema>
     route(path: string, options?: Omit<RequestOptions, 'culture' | 'fields'> & {
         host?: string;
     }): Promise<RouteAnswer<Schema>>;
+    /** The pages `/sitemap.xml` lists for a hostname; undefined when the site serves none. */
+    sitemap(host?: string, options?: Pick<RequestOptions, 'signal'>): Promise<Paged<ApiSitemapItem> | undefined>;
+    /** A form to draw, by key or alias (story 056); undefined when there is none. */
+    form(keyOrAlias: string, options?: Pick<RequestOptions, 'culture' | 'signal'>): Promise<Record<string, unknown> | undefined>;
 }
 /** Where a crombolo site serves it; Umbraco's own path, `/umbraco/delivery/api/v2`, answers too. */
 export declare const DELIVERY_API_PATH = "/crombolo/delivery/api/v2";

package/dist/index.js

@@ -1,7 +1,108 @@
 // packages/delivery-client/src/index.ts
+var ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  shy: "­",
+  copy: "©",
+  reg: "®",
+  trade: "™",
+  hellip: "…",
+  mdash: "—",
+  ndash: "–",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
+  laquo: "«",
+  raquo: "»",
+  bull: "•",
+  middot: "·",
+  deg: "°",
+  times: "×",
+  divide: "÷",
+  euro: "€",
+  pound: "£"
+};
+function decodeEntities(text) {
+  if (!text.includes("&"))
+    return text;
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);/gi, (whole, name) => {
+    if (name[0] !== "#")
+      return ENTITIES[name] ?? ENTITIES[name.toLowerCase()] ?? whole;
+    const code = name[1] === "x" || name[1] === "X" ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1));
+    return code > 0 && code <= 1114111 ? String.fromCodePoint(code) : whole;
+  });
+}
+var BLOCK_TAGS = new Set(["umb-rte-block", "umb-rte-block-inline"]);
+function walkRichText(tree, visitors) {
+  const blocks = new Map(tree.blocks.flatMap((item) => {
+    const id = item.content?.id;
+    return typeof id === "string" ? [[id.toLowerCase(), item]] : [];
+  }));
+  const visit = (node) => {
+    if (node.tag === "#text")
+      return visitors.text(node);
+    const element = node;
+    if (visitors.block && BLOCK_TAGS.has(element.tag)) {
+      const block = element;
+      const id = String(block.attributes["content-id"] ?? "").toLowerCase();
+      return visitors.block(blocks.get(id), block);
+    }
+    const children = element.elements.map(visit);
+    const own = visitors.tags?.[element.tag];
+    return own ? own(element, children) : visitors.element(element, children);
+  };
+  return tree.elements.map(visit);
+}
 function isExpanded(reference) {
   return Object.keys(reference.properties).length > 0;
 }
+function memoryConditionalStore(limit = 500) {
+  const copies = new Map;
+  return {
+    get(url) {
+      const copy = copies.get(url);
+      if (copy) {
+        copies.delete(url);
+        copies.set(url, copy);
+      }
+      return copy;
+    },
+    set(url, copy) {
+      copies.delete(url);
+      copies.set(url, copy);
+      while (copies.size > limit)
+        copies.delete(copies.keys().next().value);
+    }
+  };
+}
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function contentKeysIn(body) {
+  const keys = new Set;
+  const walk = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        walk(item);
+      return;
+    }
+    if (!value || typeof value !== "object")
+      return;
+    const record = value;
+    const id = record.id;
+    if (typeof id === "string" && UUID.test(id) && (("contentType" in record) || ("mediaType" in record)))
+      keys.add(id.toLowerCase());
+    if (typeof record.destinationId === "string" && UUID.test(record.destinationId))
+      keys.add(record.destinationId.toLowerCase());
+    for (const child of Object.values(record))
+      walk(child);
+  };
+  walk(body);
+  return [...keys];
+}
 
 class DeliveryError extends Error {
   status;
@@ -34,11 +135,39 @@ function createDeliveryClient(options) {
     const token = await options.memberToken?.();
     if (token)
       headers.authorization = `Bearer ${token}`;
+    const preview = await options.preview?.();
+    if (preview) {
+      headers.preview = "true";
+      if (typeof preview === "object" && preview.token)
+        headers["preview-token"] = preview.token;
+    }
+    const keeps = options.conditional && !token && !preview ? options.conditional : undefined;
+    const kept = keeps?.get(url);
+    if (kept)
+      headers["if-none-match"] = kept.etag;
     const response = await send(url, { headers, signal: request.signal });
     if (response.status === 404 && missing === "undefined")
       return;
-    const text = await response.text();
+    const revalidated = response.status === 304 && kept !== undefined;
+    const text = revalidated ? kept.body : await response.text();
     const body = text ? JSON.parse(text) : null;
+    const etag = revalidated ? kept.etag : response.headers.get("etag");
+    if (keeps && etag && response.ok && !revalidated)
+      keeps.set(url, { etag, body: text });
+    if (options.onAnswer) {
+      const tagged = response.headers.get(options.tagHeader ?? "surrogate-key") ?? (options.tagHeader ? null : response.headers.get("cache-tag"));
+      options.onAnswer({
+        url,
+        status: revalidated ? 200 : response.status,
+        keys: contentKeysIn(body),
+        tags: tagged ? tagged.split(/[\s,]+/).filter(Boolean) : [],
+        etag,
+        cacheControl: response.headers.get("cache-control"),
+        revalidated
+      });
+    }
+    if (revalidated)
+      return body;
     if (response.status === 404 && missing === "body")
       return body;
     if (!response.ok)
@@ -47,7 +176,8 @@ function createDeliveryClient(options) {
   }
   const shaping = (request) => [
     ...request.expand ? [["expand", request.expand]] : [],
-    ...request.fields ? [["fields", request.fields]] : []
+    ...request.fields ? [["fields", request.fields]] : [],
+    ...request.seo ? [["seo", "true"]] : []
   ];
   const paging = (query) => [
     ...list(query.filter).map((filter) => ["filter", filter]),
@@ -72,6 +202,8 @@ function createDeliveryClient(options) {
       ...request.host ? [["host", request.host]] : [],
       ...shaping(request)
     ], request, "body"),
+    sitemap: (host, request = {}) => get("sitemap", host ? [["host", host]] : [], request, "undefined"),
+    form: (keyOrAlias, request = {}) => get(`forms/${encodeURIComponent(keyOrAlias)}`, [], request, "undefined"),
     search: (term, search = {}) => get("search", [
       ["term", term],
       ...list(search.contentType).map((type) => ["contentType", type]),
@@ -82,6 +214,10 @@ function createDeliveryClient(options) {
 export {
   DELIVERY_API_PATH,
   DeliveryError,
+  contentKeysIn,
   createDeliveryClient,
-  isExpanded
+  decodeEntities,
+  isExpanded,
+  memoryConditionalStore,
+  walkRichText
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/delivery-client",
-  "version": "0.36.2",
+  "version": "0.38.1",
   "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",