@camox/api-contract 0.47.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.47.0",
+  "version": "0.51.0",
   "license": "MIT",
   "files": [
     "src",
@@ -39,6 +39,14 @@
     "./projects": {
       "types": "./dist/projects.d.ts",
       "default": "./dist/projects.js"
+    },
+    "./locales": {
+      "types": "./dist/locales.d.ts",
+      "default": "./dist/locales.js"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "default": "./dist/router.js"
     }
   },
   "dependencies": {

package/src/drafts.ts

@@ -1,4 +1,4 @@
-import type { Router } from "./index.ts";
+import type { Router } from "./router.ts";
 
 /** Request header naming the draft a request reads and writes (ADR 0011). Absent means Live. */
 export const DRAFT_HEADER = "x-camox-draft";
@@ -147,6 +147,7 @@ const FILE_WRITES: Record<keyof Router["files"], boolean> = {
 const PAGE_WRITES: Record<keyof Router["pages"], boolean> = {
   getByPath: false,
   getStructure: false,
+  getMarkdown: false,
   list: false,
   listBySlug: false,
   get: false,

package/src/index.ts

@@ -1,7 +1,6 @@
 export * from "./artifact.ts";
 export * from "./icons.ts";
 export * from "./ids.ts";
+export * from "./record-templates.ts";
 export * from "./reference-query.ts";
-export type { Router } from "../../../apps/api/src/router";
-export type { PublishPreview } from "../../../apps/api/src/domains/drafts/publish";
-export type { EntityKind } from "../../../apps/api/src/domains/drafts/overlay";
+export * from "./structured-data.ts";

package/src/locales.ts

@@ -0,0 +1,34 @@
+/**
+ * The URL names the locale (ADR 0015): a non-default locale's paths sit under its prefix
+ * (`/de/preise`), the default locale's have none. Pure, so the API, the runtime and the browser
+ * read a path the same way.
+ */
+
+/** A locale of a project, as `locales.list` returns it. */
+export type LocaleView = { tag: string; isDefault: boolean };
+
+/** A runtime path split into the locale it names and the locale-relative path after its prefix. */
+export type LocalePath = { locale: LocaleView; path: string };
+
+/** A locale's URL prefix: its tag in lowercase. The default locale has none. */
+export function localePrefix(locale: LocaleView): string {
+  return locale.isDefault ? "" : `/${locale.tag.toLowerCase()}`;
+}
+
+/**
+ * The locale a runtime path names, and the path after its prefix, without search or hash. A first
+ * segment that isn't a non-default locale's prefix leaves the path the default locale's. A
+ * locale's home is `/de`; `/de/` names it too.
+ */
+export function parseLocalePath(pathname: string, locales: readonly LocaleView[]): LocalePath {
+  const path = pathname.replace(/[?#].*$/s, "") || "/";
+  const end = path.indexOf("/", 1);
+  const segment = end === -1 ? path.slice(1) : path.slice(1, end);
+  const named = locales.find(
+    (locale) => !locale.isDefault && localePrefix(locale) === `/${segment}`,
+  );
+  if (named) return { locale: named, path: end === -1 ? "/" : path.slice(end) };
+  const fallback = locales.find((locale) => locale.isDefault);
+  if (!fallback) throw new Error("A project's locales include its default locale.");
+  return { locale: fallback, path };
+}

package/src/projects.ts

@@ -42,6 +42,9 @@ export const projectSlugSchema = /* @__PURE__ */ z
     "Use lowercase letters, digits and hyphens, without a hyphen at either end",
   );
 
+/** The address a project's website is served at: its Project Slug's `camox.site` subdomain. */
+export const projectWebsiteUrl = (slug: string) => `https://${slug}.camox.site`;
+
 /** Why a slug can't be given to a new project. */
 export type UnavailableSlugReason = "invalid" | "reserved" | "taken";
 
@@ -65,3 +68,21 @@ export type ProjectStatus = "settingUp" | "live" | "setupFailed";
 export type ProjectSetupStep = "copyTemplate" | "build" | "serve";
 
 export const PROJECT_SETUP_STEPS: readonly ProjectSetupStep[] = ["copyTemplate", "build", "serve"];
+
+/**
+ * A social profile's address: an absolute `https` URL. Shared so the studio checks a profile by
+ * the API's own rule before saving it.
+ */
+export const socialProfileUrlSchema = /* @__PURE__ */ z
+  .string()
+  .max(2048, "Use a shorter URL")
+  .refine(isHttpsUrl, "Enter a URL starting with https://");
+
+function isHttpsUrl(value: string) {
+  if (!value.startsWith("https://")) return false;
+  try {
+    return new URL(value).hostname !== "";
+  } catch {
+    return false;
+  }
+}

package/src/record-templates.ts

@@ -0,0 +1,44 @@
+/**
+ * A collection's `toTitle` and `toDescription` are record templates: text with `{{field}}` tokens
+ * naming the record's String fields, which the SDK writes and the API fills with each record's
+ * plain text. Both sides read them the same way through these helpers.
+ */
+
+const TOKEN = /\{\{([^}]*)\}\}/g;
+
+/** The fields a record template's tokens name, in order, such as `firstName` and `lastName`. */
+export function templateFields(template: string): string[] {
+  return [...template.matchAll(TOKEN)].map(([, name]) => name!);
+}
+
+/**
+ * The fields a record template names that aren't String fields of the content schema's
+ * properties: templates read fields as plain text, so they name no other field.
+ */
+export function nonStringTemplateFields(
+  template: string,
+  properties: Readonly<Record<string, object | undefined>>,
+): string[] {
+  const isString = (field: object | undefined) =>
+    field !== undefined && "fieldType" in field && field.fieldType === "String";
+  return templateFields(template).filter((name) => !isString(properties[name]));
+}
+
+/** How a record names itself: its title, and its description, or null when it has none. */
+export type RecordText = { title: string; description: string | null };
+
+/**
+ * A record's title and description: its collection's templates filled with the plain text
+ * `textOf` reads from each field they name.
+ */
+export function recordText(
+  templates: { toTitle: string; toDescription?: string | null },
+  textOf: (field: string) => string,
+): RecordText {
+  const fill = (template: string) =>
+    template.replace(TOKEN, (_token, name: string) => textOf(name)).trim();
+  return {
+    title: fill(templates.toTitle),
+    description: (templates.toDescription && fill(templates.toDescription)) || null,
+  };
+}

package/src/router.ts

@@ -0,0 +1,5 @@
+// The API's router and server-side types. Kept off the main entry so a site importing
+// `camox` doesn't load the whole API's types (and packages it can't resolve).
+export type { Router } from "../../../apps/api/src/router";
+export type { PublishPreview } from "../../../apps/api/src/domains/drafts/publish";
+export type { EntityKind } from "../../../apps/api/src/domains/drafts/overlay";

package/src/structured-data.ts

@@ -0,0 +1,104 @@
+/**
+ * Structured Data the API evaluates from block and repeatable item templates, for the runtime to
+ * put in a page's graph. Only the runtime knows the website's address, so where a node needs an
+ * absolute URL to a page of the website, the API leaves a marker the runtime resolves.
+ */
+
+/** A JSON value of a node the API evaluated, which may hold markers. */
+export type StructuredDataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | StructuredDataValue[]
+  | { [key: string]: StructuredDataValue };
+
+/** A node the API evaluated from a template, before the runtime resolves its markers. */
+export type EvaluatedNode = { [key: string]: StructuredDataValue };
+
+/**
+ * A page of the website, by its path in a locale, whose absolute URL the runtime fills in. The
+ * path is locale-relative, as pages store it; without `locale`, it's the default locale's.
+ */
+export type PageUrlMarker = { "@camox": "pageUrl"; path: string; locale?: string };
+
+/**
+ * A link to a collection record's node, as templates and record pages' layouts leave it. Only the
+ * runtime knows the website's address, which a record's `@id` is built from, so the link names
+ * the record by its id, and the runtime gives it the record's `@id` in the page's locale.
+ */
+export type RecordLink = { "@id": `camox:record:${string}` };
+
+const RECORD_LINK_PREFIX = "camox:record:";
+
+/** A link to the node of the record with id `id`. */
+export function recordLink(id: string): RecordLink {
+  return { "@id": `${RECORD_LINK_PREFIX}${id}` };
+}
+
+/** The id of the record a value links, when it is a record link. */
+export function linkedRecordId(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  // A link holds nothing else: a node with a record's `@id` is the record's node.
+  if (Object.keys(value).length !== 1) return undefined;
+  const id = (value as { "@id"?: unknown })["@id"];
+  if (typeof id !== "string" || !id.startsWith(RECORD_LINK_PREFIX)) return undefined;
+  return id.slice(RECORD_LINK_PREFIX.length);
+}
+
+/**
+ * The nodes of the records a read's content references, from their collections' templates, and
+ * of the records those link in turn. Their `@id`s and links are record links.
+ */
+export type RecordStructuredData = {
+  /** Each record's node, by record id. */
+  nodes: Record<string, EvaluatedNode>;
+  /**
+   * The records with nodes that the content references itself, in the order found: the page's
+   * `mentions`, unless a node places them.
+   */
+  referenced: string[];
+};
+
+/** The Article types, whose name is their `headline`. */
+export const ARTICLE_TYPES = [
+  "Article",
+  "BlogPosting",
+  "NewsArticle",
+  "TechArticle",
+  "ScholarlyArticle",
+  "Report",
+  "SocialMediaPosting",
+] as const;
+
+/** Whether a value is a marker for a page's URL. */
+export function isPageUrlMarker(value: unknown): value is PageUrlMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { "@camox"?: unknown })["@camox"] === "pageUrl" &&
+    typeof (value as { path?: unknown }).path === "string"
+  );
+}
+
+/**
+ * A part of a block's or repeatable item's template shown only while one of its settings holds:
+ * a Boolean setting is on, or an Enum setting `equals` a value. The API evaluates `show` when it
+ * does and leaves the part out otherwise; a list in a list adds its entries.
+ */
+export type SettingCondition = {
+  "@camox": "if";
+  setting: `settings.${string}` | `itemSettings.${string}`;
+  equals?: string;
+  show: unknown;
+};
+
+/** Whether a template's value is shown only under a setting. */
+export function isSettingCondition(value: unknown): value is SettingCondition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { "@camox"?: unknown })["@camox"] === "if" &&
+    typeof (value as { setting?: unknown }).setting === "string"
+  );
+}