@camox/api-contract 0.47.0 → 0.48.0

package/dist/index.js

@@ -32,6 +32,38 @@ function artifactTitle(source) {
 	return artifactSourceTitle(source) ?? "Untitled artifact";
 }
 
+//#endregion
+//#region src/record-templates.ts
+/**
+* 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`. */
+function templateFields(template) {
+	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.
+*/
+function nonStringTemplateFields(template, properties) {
+	const isString = (field) => field !== void 0 && "fieldType" in field && field.fieldType === "String";
+	return templateFields(template).filter((name) => !isString(properties[name]));
+}
+/**
+* A record's title and description: its collection's templates filled with the plain text
+* `textOf` reads from each field they name.
+*/
+function recordText(templates, textOf) {
+	const fill = (template) => template.replace(TOKEN, (_token, name) => textOf(name)).trim();
+	return {
+		title: fill(templates.toTitle),
+		description: templates.toDescription && fill(templates.toDescription) || null
+	};
+}
+
 //#endregion
 //#region src/reference-query.ts
 /**
@@ -67,4 +99,38 @@ function referenceQueryProblem(query, fieldTypeOf) {
 }
 
 //#endregion
-export { ICON_CATALOG_VERSION, PAGE_TEXT_LINK_PREFIX, QUERY_LIMIT_CAP, SYSTEM_ORDER_KEYS, UNTITLED_ARTIFACT, artifactSourceTitle, artifactTitle, generateUuidv7, isQueryBacked, isSystemOrderKey, projectIdSchema, referenceQueryProblem, scopeIconSvgIds, uuidv7JsonSchema, uuidv7Schema, validateIconValue };
+//#region src/structured-data.ts
+const RECORD_LINK_PREFIX = "camox:record:";
+/** A link to the node of the record with id `id`. */
+function recordLink(id) {
+	return { "@id": `${RECORD_LINK_PREFIX}${id}` };
+}
+/** The id of the record a value links, when it is a record link. */
+function linkedRecordId(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	if (Object.keys(value).length !== 1) return void 0;
+	const id = value["@id"];
+	if (typeof id !== "string" || !id.startsWith(RECORD_LINK_PREFIX)) return void 0;
+	return id.slice(13);
+}
+/** The Article types, whose name is their `headline`. */
+const ARTICLE_TYPES = [
+	"Article",
+	"BlogPosting",
+	"NewsArticle",
+	"TechArticle",
+	"ScholarlyArticle",
+	"Report",
+	"SocialMediaPosting"
+];
+/** Whether a value is a marker for a page's URL. */
+function isPageUrlMarker(value) {
+	return typeof value === "object" && value !== null && value["@camox"] === "pageUrl" && typeof value.path === "string";
+}
+/** Whether a template's value is shown only under a setting. */
+function isSettingCondition(value) {
+	return typeof value === "object" && value !== null && value["@camox"] === "if" && typeof value.setting === "string";
+}
+
+//#endregion
+export { ARTICLE_TYPES, ICON_CATALOG_VERSION, PAGE_TEXT_LINK_PREFIX, QUERY_LIMIT_CAP, SYSTEM_ORDER_KEYS, UNTITLED_ARTIFACT, artifactSourceTitle, artifactTitle, generateUuidv7, isPageUrlMarker, isQueryBacked, isSettingCondition, isSystemOrderKey, linkedRecordId, nonStringTemplateFields, projectIdSchema, recordLink, recordText, referenceQueryProblem, scopeIconSvgIds, templateFields, uuidv7JsonSchema, uuidv7Schema, validateIconValue };

package/dist/projects.d.ts

@@ -25,4 +25,9 @@ export type ProjectStatus = "settingUp" | "live" | "setupFailed";
  */
 export type ProjectSetupStep = "copyTemplate" | "build" | "serve";
 export declare const PROJECT_SETUP_STEPS: readonly ProjectSetupStep[];
+/**
+ * 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 declare const socialProfileUrlSchema: z.ZodString;
 //#endregion

package/dist/projects.js

@@ -45,6 +45,19 @@ const PROJECT_SETUP_STEPS = [
 	"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.
+*/
+const socialProfileUrlSchema = /* @__PURE__ */ z.string().max(2048, "Use a shorter URL").refine(isHttpsUrl, "Enter a URL starting with https://");
+function isHttpsUrl(value) {
+	if (!value.startsWith("https://")) return false;
+	try {
+		return new URL(value).hostname !== "";
+	} catch {
+		return false;
+	}
+}
 
 //#endregion
-export { PROJECT_SETUP_STEPS, RESERVED_PROJECT_SLUGS, UNAVAILABLE_SLUG_MESSAGES, projectSlugSchema };
+export { PROJECT_SETUP_STEPS, RESERVED_PROJECT_SLUGS, UNAVAILABLE_SLUG_MESSAGES, projectSlugSchema, socialProfileUrlSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "license": "MIT",
   "files": [
     "src",

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from "./artifact.ts";
 export * from "./icons.ts";
 export * from "./ids.ts";
+export * from "./record-templates.ts";
 export * from "./reference-query.ts";
+export * from "./structured-data.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";

package/src/projects.ts

@@ -65,3 +65,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/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"
+  );
+}