@crombolo/delivery-client 0.36.2 → 0.37.0

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>> {
@@ -205,6 +207,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 +272,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 +321,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 +369,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

@@ -2,6 +2,48 @@
 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 +76,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 +117,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 +143,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 +155,8 @@ function createDeliveryClient(options) {
 export {
   DELIVERY_API_PATH,
   DeliveryError,
+  contentKeysIn,
   createDeliveryClient,
-  isExpanded
+  isExpanded,
+  memoryConditionalStore
 };

package/package.json

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