@nakedcreativity/cee-ms-node 2.0.0-beta.0 → 2.0.0-beta.10

package/lib/interfaces.d.ts

@@ -3,6 +3,7 @@ import type express from 'express';
 import type { Context, FilterImplOptions } from 'liquidjs';
 export declare enum CacheSource {
     Local = 0,
+    /** The bucket, read with the host's own AWS credentials (`cacheBucket`, `cacheRegion`). */
     S3 = 1
 }
 export interface CeemsConfig {
@@ -17,6 +18,13 @@ export interface CeemsConfig {
     /** Region of `cacheBucket`. Defaults to the `AWS_REGION` environment variable. */
     cacheRegion?: string;
     cacheFolder?: string;
+    /**
+     * The environment this renderer serves: published files are read from `<environment>/` in the bucket or
+     * folder. Defaults to the `CEEMS_ENVIRONMENT` environment variable, then `development`.
+     */
+    environment?: string;
+    /** Where published files are read from in the bucket or folder: `<environment>/` unless set. */
+    cachePrefix?: string;
     whitelistedCookies?: Array<string>;
     tags?: Array<LiquidTag>;
     filters?: Array<LiquidFilter>;
@@ -26,21 +34,25 @@ export interface CeemsConfig {
      * `ceems.engine.options.globals.metadata` (which still works).
      */
     globals?: Record<string, unknown>;
-    /** Draft previews for the Cee.ms editor. Drafts are disabled unless `secret` and `apiUrl` are set. */
+    /** Draft previews for the Cee.ms editor. Drafts are disabled unless the preview secret is set. */
     preview?: PreviewConfig;
 }
+/**
+ * Only the secret is needed: each preview token names the API that serves its draft and the editor that frames
+ * it, and the bridge loads from that editor (`<editor>/bridge.js`). The rest are fallbacks and overrides.
+ */
 export interface PreviewConfig {
     /** Per-site secret that signs preview tokens. Defaults to `CEEMS_PREVIEW_SECRET`. */
     secret?: string;
-    /** Base URL of the Cee.ms API, for example `https://api.cee.ms`. Defaults to `CEEMS_API_URL`. */
+    /** The Cee.ms API, for tokens that don't name one. Defaults to `CEEMS_API_URL`. */
     apiUrl?: string;
-    /** Origin of the Cee.ms editor, the only page allowed to frame drafts. Defaults to `CEEMS_EDITOR_ORIGIN`. */
+    /** The editor's origin, for tokens that don't name one. Defaults to `CEEMS_EDITOR_ORIGIN`. */
     editorOrigin?: string;
-    /** The editor bridge script injected into drafts. Defaults to `CEEMS_BRIDGE_SRC` / `CEEMS_BRIDGE_INTEGRITY`. */
-    bridge?: {
-        src: string;
-        integrity?: string;
-    };
+    /**
+     * Loads the bridge from here instead of the editor, for testing a local build. Defaults to
+     * `CEEMS_BRIDGE_SRC`.
+     */
+    bridgeSrc?: string;
 }
 /** Matches liquidjs's tag options, which liquidjs 10 no longer exports from its entry point. */
 export interface TagImplOptions {
@@ -60,8 +72,247 @@ export interface CeemsSite {
     navigation: any;
     blogs: any;
     pages: any;
-    site: any;
+    site: CeemsSiteInfo;
+    /**
+     * Site settings by field key (from Cee.ms 2), as published; drafts carry them as edited. Templates
+     * read them as `settings`, e.g. `{{ settings.phone }}`. Stored links read as their address.
+     */
+    settings?: Record<string, any>;
     collections?: any;
+    /**
+     * Every published page by id (absent for sites last published before it): page links read their address from here when the page
+     * renders, so a renamed or moved page is right everywhere once it is published. A link to a page that
+     * isn't here is broken.
+     */
+    pageIndex?: Record<string, CeemsPageIndexEntry>;
+    /** The documents published content uses, by id, read by document links and values as the page renders. */
+    documents?: Record<string, CeemsPublishedDocument>;
+    /** The site's People by row id, for bylines, profile pages and row fields. */
+    people?: Record<string, CeemsPerson>;
+}
+/** A person from the site's People, in `site.json` `people`. Sites may add columns of their own. */
+export interface CeemsPerson {
+    name: string;
+    jobTitle?: string;
+    photo?: CeemsImage;
+    /** Rich text. */
+    bio?: string;
+    links?: {
+        url: string;
+    }[];
+    /** `links` as addresses, for structured data. */
+    sameAs: string[];
+    email?: string;
+    telephone?: string;
+    /** Their profile page, if they have one. */
+    profile?: {
+        kind: 'page';
+        pageId: string;
+        url: string;
+    };
+    [column: string]: unknown;
+}
+/** A byline author, as published: a person from People, someone typed in, or the organisation. */
+export type CeemsBylineAuthor = {
+    kind: 'person';
+    collectionId: string;
+    rowId: string;
+} | {
+    kind: 'guest';
+    name: string;
+    url?: string;
+    jobTitle?: string;
+} | {
+    kind: 'organisation';
+};
+/** A published page, in `site.json` `pageIndex`. */
+export interface CeemsPageIndexEntry {
+    /** Its address, e.g. `/about/team`, or `/` for the home page. */
+    path: string;
+    name: string;
+}
+export interface CeemsDocumentInfo {
+    numpages?: number;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+}
+/** A library document, in `site.json` `documents`. */
+export interface CeemsPublishedDocument {
+    url: string;
+    thumbnail?: string;
+    info?: CeemsDocumentInfo;
+}
+/** A published `data/<id>.json`. */
+export interface CeemsDataFile {
+    _id: string;
+    name: string;
+    slug: string;
+    columns: any[];
+    /** Each row's values, in order: as Cee.ms 1 published them. */
+    data: Record<string, any>[];
+    /** The same rows with their ids, for row references. Absent for data last published before it. */
+    rows?: ({
+        _id: string;
+    } & Record<string, any>)[];
+}
+/** The published `site.json` `site`. */
+export interface CeemsSiteInfo {
+    name: string;
+    cdn: string;
+    url: string;
+    /** The site's organisation, for templates (`{{ site.organisation.telephone }}`) and structured data. */
+    organisation?: CeemsOrganisation;
+    structuredData?: {
+        defaults?: StructuredDataDefaults;
+        /** For module types holding questions and answers: where they are, by module config type. */
+        faqModules?: Record<string, FaqModuleMapping>;
+        /** For module types holding reviews, which attach to a product or event page. */
+        reviewModules?: Record<string, ReviewsModuleMapping>;
+        /** For module types featuring people: their row field to People, by module config type. */
+        peopleModules?: Record<string, {
+            field: string;
+        }>;
+    };
+    [key: string]: any;
+}
+/** A schema.org type a page or the site's defaults can switch on for `{% structureddata %}`. */
+export type StructuredDataType = 'WEBSITE' | 'WEBPAGE' | 'BREADCRUMB' | 'ORGANISATION' | 'ARTICLE' | 'FAQ';
+/**
+ * What a page is about. Products, events, people and services output their own node when they have the data;
+ * `HOME` is the site's front page, which by default carries the site and organisation. Templates and modules
+ * can read it, e.g. `{% if page.entity == 'PRODUCT' %}`.
+ */
+export type PageEntity = 'HOME' | 'PAGE' | 'ARTICLE' | 'PRODUCT' | 'EVENT' | 'PERSON' | 'SERVICE';
+/** The types each kind of page outputs unless it chooses its own. */
+export interface StructuredDataDefaults {
+    home: StructuredDataType[];
+    page: StructuredDataType[];
+    blog: StructuredDataType[];
+    article: StructuredDataType[];
+}
+/** `itemsField` is a contributor field of the module; the others are fields of its items. */
+export interface FaqModuleMapping {
+    itemsField: string;
+    questionField: string;
+    answerField: string;
+}
+/** `itemsField` is a contributor field of the module; the others are fields of its items. */
+export interface ReviewsModuleMapping {
+    itemsField: string;
+    authorField: string;
+    /** A select of numbers, or text holding one. */
+    ratingField: string;
+    bodyField?: string;
+    dateField?: string;
+    bestRating: number;
+    worstRating: number;
+}
+/** An image value as published. */
+export interface CeemsImage {
+    src: string;
+    variants?: Record<string, string>;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+export interface CeemsPostalAddress {
+    street?: string;
+    locality?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+}
+export interface CeemsOrganisation {
+    /** The schema.org type, from Cee.ms's business types: `Organization`, or one such as `RealEstateAgent`. */
+    type: string;
+    name: string;
+    legalName?: string;
+    logo?: CeemsImage;
+    url?: string;
+    email?: string;
+    telephone?: string;
+    address?: CeemsPostalAddress;
+    /** Its profiles by platform, e.g. `{{ site.organisation.socialProfiles.instagram }}`. */
+    socialProfiles?: CeemsSocialProfiles;
+    /** Every profile URL in `socialProfiles`, as structured data lists them. */
+    sameAs?: string[];
+    openingHours?: {
+        days: string[];
+        opens: string;
+        closes: string;
+    }[];
+    priceRange?: string;
+}
+/** Profile URLs on the platforms most sites link to, and any others by name. */
+export interface CeemsSocialProfiles {
+    instagram?: string;
+    facebook?: string;
+    linkedin?: string;
+    x?: string;
+    youtube?: string;
+    tiktok?: string;
+    bluesky?: string;
+    /** A `wa.me` link. */
+    whatsapp?: string;
+    custom: {
+        name: string;
+        url: string;
+    }[];
+}
+export type CeemsAvailability = 'IN_STOCK' | 'OUT_OF_STOCK' | 'PRE_ORDER' | 'SOLD_OUT' | 'DISCONTINUED';
+export interface CeemsOffer {
+    price: number;
+    currency: string;
+    url?: string;
+    availability?: CeemsAvailability;
+}
+/** A page's structured data choices, and the details of its entity. */
+export interface CeemsPageStructuredData {
+    /** Absent: the site's defaults for the page's kind. */
+    types?: StructuredDataType[];
+    event?: {
+        name?: string;
+        description?: string;
+        startDate: string;
+        endDate?: string;
+        attendance?: 'OFFLINE' | 'ONLINE' | 'MIXED';
+        status?: 'SCHEDULED' | 'CANCELLED' | 'POSTPONED' | 'RESCHEDULED' | 'MOVED_ONLINE';
+        location?: {
+            name?: string;
+            address?: CeemsPostalAddress;
+            url?: string;
+        };
+        image?: CeemsImage;
+        offers?: CeemsOffer;
+    };
+    product?: {
+        name?: string;
+        description?: string;
+        brand?: string;
+        sku?: string;
+        image?: CeemsImage;
+        /** With `currency`; a product needs a price or reviews. */
+        price?: number;
+        currency?: string;
+        availability?: CeemsAvailability;
+    };
+    person?: {
+        name: string;
+        jobTitle?: string;
+        url?: string;
+        image?: CeemsImage;
+        sameAs?: string[];
+    };
+    service?: {
+        name?: string;
+        description?: string;
+        serviceType?: string;
+        areaServed?: string;
+        image?: CeemsImage;
+        offers?: CeemsOffer;
+    };
 }
 export interface CeemsRequest extends express.Request {
     page: CeemsPage;
@@ -80,11 +331,43 @@ export interface CeemsPage {
     modules: Record<string, CeemsModule | string>;
     template: string;
     path: Array<string>;
-    redirect: string;
+    /** A stored link (read as its address), or a path on sites from before links; a published page redirects */
+    redirect?: string | {
+        url: string;
+        toString(): string;
+    } | null;
     _id: string;
     pagination: number;
     fullpath: string;
     handle: string;
+    /** The page's own name, for menus. */
+    name?: string;
+    /** SEO title. */
+    title?: string;
+    /** SEO description. */
+    description?: string;
+    /** Social sharing image. */
+    social?: CeemsImage;
+    type?: 'blog' | 'article';
+    /** Published from Cee.ms with the default resolved: `HOME` for the home page, else `PAGE`. */
+    entity?: PageEntity;
+    /** The site's own page type, such as `property`, by key. Its `entity` is the type's base. */
+    pageType?: string;
+    tags?: string[];
+    /** An article's date. */
+    date?: string;
+    publishedAt?: string;
+    updatedAt?: string;
+    structuredData?: CeemsPageStructuredData;
+    /** An article's byline, as published. Templates read `page.authors`. */
+    byline?: {
+        authors: CeemsBylineAuthor[];
+        reviewedBy?: unknown;
+    };
+    /** For entity `PERSON`: the person whose profile page it is, as a `RowDrop` once loaded. */
+    person?: unknown;
+    /** The byline, resolved (see `bylineAuthors`): people, guests and the organisation, in order. */
+    authors?: Record<string, unknown>[];
     [key: string]: any;
 }
 export interface CeemsRegion {
@@ -106,6 +389,8 @@ export interface RenderState {
     page: CeemsPage;
     /** A verified editor draft: adds module markers and the editor bridge. */
     edit: boolean;
+    /** In a draft, the editor framing it, which the bridge talks to. */
+    editorOrigin?: string;
 }
 export interface CeemsModuleContextGlobal {
     site: Array<any>;

package/lib/interfaces.js

@@ -4,6 +4,7 @@ exports.CacheSource = void 0;
 var CacheSource;
 (function (CacheSource) {
     CacheSource[CacheSource["Local"] = 0] = "Local";
+    /** The bucket, read with the host's own AWS credentials (`cacheBucket`, `cacheRegion`). */
     CacheSource[CacheSource["S3"] = 1] = "S3";
 })(CacheSource || (exports.CacheSource = CacheSource = {}));
 //# sourceMappingURL=interfaces.js.map

package/lib/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";;;AAIA,IAAY,WAGX;AAHD,WAAY,WAAW;IACnB,+CAAK,CAAA;IACL,yCAAE,CAAA;AACN,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB"}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":";;;AAIA,IAAY,WAIX;AAJD,WAAY,WAAW;IACnB,+CAAK,CAAA;IACL,2FAA2F;IAC3F,yCAAE,CAAA;AACN,CAAC,EAJW,WAAW,2BAAX,WAAW,QAItB"}

package/lib/links.d.ts

@@ -0,0 +1,90 @@
+import { Drop } from 'liquidjs';
+import type { CeemsDataFile, CeemsDocumentInfo, CeemsPageIndexEntry, CeemsPublishedDocument, CeemsSite } from './interfaces';
+/**
+ * What references resolve against when a page renders: the published pages and documents from `site.json`,
+ * and the rows of the data collections the page points at. Each is published once, so a renamed page or an
+ * edited row is right everywhere as soon as that one change is published. A site published before Cee.ms
+ * sent these has none of them, and links read their stored address as before.
+ */
+export interface LinkContext {
+    pageIndex?: Record<string, CeemsPageIndexEntry>;
+    documents?: Record<string, CeemsPublishedDocument>;
+    /** A row by collection and row id, or undefined if it isn't published (or was deleted). */
+    row?: (collectionId: string, rowId: string) => Record<string, unknown> | undefined;
+}
+/**
+ * A stored link value in templates. It reads as its address, so a field that held a URL string and became a
+ * link field still works where templates print it (`{{ item.url }}`), filter it (`| escape`, `| append`),
+ * compare it (`== '/about'`, `!= blank`) or measure it (`| size`); and its parts are there too
+ * (`{{ item.url.kind }}`, `.pageId`, `.anchor`). `| json` shows the whole link.
+ *
+ * A page link whose page isn't published reads as `''`, with `broken` true, so `{% if link %}` leaves it out.
+ */
+export declare class LinkDrop extends Drop {
+    kind: string;
+    url: string;
+    pageId?: string;
+    documentId?: string;
+    anchor?: string;
+    email?: string;
+    broken?: boolean;
+    constructor(link: Record<string, unknown>);
+    valueOf(): string;
+    toString(): string;
+    /** For `| size`, which reads `.length`. */
+    get length(): number;
+    /** For `{{ item.url.size }}`. */
+    get size(): number;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * A document value (`{ documentId, url, thumbnail, info }`) in templates, read from the published documents
+ * so a replaced file is right everywhere. It prints as its address, so `{{ download }}` and
+ * `{{ download.url }}` both work.
+ */
+export declare class DocumentDrop extends Drop {
+    documentId?: string;
+    url: string;
+    thumbnail?: string;
+    info?: CeemsDocumentInfo;
+    constructor(value: Record<string, unknown>);
+    valueOf(): string;
+    toString(): string;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * A row of a data collection, from a `row` field: its columns by key (`{{ author.name }}`,
+ * `{% image person.photo 'square' %}`), plus `_id`. It prints as its `name`, else its first text value.
+ */
+export declare class RowDrop extends Drop {
+    _id: string;
+    [column: string]: unknown;
+    constructor(row: Record<string, unknown>);
+    toString(): string;
+    valueOf(): string;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Rich text links carry the page they point at (`data-page-id`); their `href` comes from the published page,
+ * keeping any `#anchor`, and is dropped when that page isn't published. Documents' come from `documents`.
+ */
+export declare function resolveRichText(html: string, context: LinkContext): string;
+/**
+ * Wraps every stored link in a published page, data file or draft in a `LinkDrop`, every document value in a
+ * `DocumentDrop` and every row reference in a `RowDrop`, in place, resolving each against `context`. A row
+ * that isn't published reads as nothing, and is left out of lists.
+ */
+export declare function wrapLinks<T>(value: T, context?: LinkContext, depth?: number): T;
+/** The rows a page's row references and byline authors point at, by collection id. */
+export declare function referencedRows(value: unknown, found?: Map<string, Set<string>>): Map<string, Set<string>>;
+/**
+ * The context for a site and the data files its page points at. People come from `site.json` `people` (with
+ * `sameAs`), so a person reads the same wherever they are referenced.
+ */
+export declare function linkContextFor(site: CeemsSite | undefined, files?: Iterable<CeemsDataFile | null>): LinkContext;
+/**
+ * An article's byline as templates and structured data read it, in order: `page.authors`. A person is their
+ * People row (`{{ author.name }}`, `{{ author.profile }}`); a guest is what was typed; the organisation is the
+ * site's. Each has `kind`, `name` and `url` (a person's profile page, else their first profile link).
+ */
+export declare function bylineAuthors(page: Record<string, any>, site: CeemsSite | undefined, context: LinkContext): Record<string, unknown>[];