@camox/api-contract 0.44.0 → 0.45.0

package/dist/analytics.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+//#region src/analytics.d.ts
+/**
+ * A GA4 measurement ID: `G-` followed by uppercase letters and digits. Shared so the dashboard
+ * checks an ID by the API's own rule before saving it.
+ */
+export declare const ga4MeasurementIdSchema: z.ZodString;
+/**
+ * A PostHog project API key: `phc_` followed by letters and digits. The prefix tells it apart from
+ * a personal API key, which is secret and must never reach a public page.
+ */
+export declare const posthogProjectApiKeySchema: z.ZodString;
+/** The PostHog Cloud region a project lives in. */
+export declare const posthogRegionSchema: z.ZodEnum<{
+  us: "us";
+  eu: "eu";
+}>;
+export type PosthogRegion = z.output<typeof posthogRegionSchema>;
+//#endregion

package/dist/analytics.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+//#region src/analytics.ts
+/**
+* A GA4 measurement ID: `G-` followed by uppercase letters and digits. Shared so the dashboard
+* checks an ID by the API's own rule before saving it.
+*/
+const ga4MeasurementIdSchema = /* @__PURE__ */ z.string().regex(/^G-[A-Z0-9]+$/, "Not a GA4 measurement ID");
+/**
+* A PostHog project API key: `phc_` followed by letters and digits. The prefix tells it apart from
+* a personal API key, which is secret and must never reach a public page.
+*/
+const posthogProjectApiKeySchema = /* @__PURE__ */ z.string().regex(/^phc_[A-Za-z0-9]+$/, "Not a PostHog project API key");
+/** The PostHog Cloud region a project lives in. */
+const posthogRegionSchema = /* @__PURE__ */ z.enum(["us", "eu"]);
+
+//#endregion
+export { ga4MeasurementIdSchema, posthogProjectApiKeySchema, posthogRegionSchema };

package/dist/drafts.d.ts

@@ -0,0 +1,82 @@
+//#region src/drafts.d.ts
+/** Request header naming the draft a request reads and writes (ADR 0011). Absent means Live. */
+export declare const DRAFT_HEADER = "x-camox-draft";
+/**
+ * Request header naming, by its tag, the locale a request reads and writes content in (ADR
+ * 0015). Absent means the project's default locale.
+ */
+export declare const LOCALE_HEADER = "x-camox-locale";
+/**
+ * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
+ * exist yet. Its value is `"1"`.
+ */
+export declare const DRAFT_CREATE_HEADER = "x-camox-draft-create";
+/**
+ * The `x-camox-draft` value naming the caller's own development draft in the project a request
+ * acts on (ADR 0006, ADR 0011). Dev mode and the CLI always send it.
+ */
+export declare const DEVELOPMENT_DRAFT = "development";
+/**
+ * oRPC error code for a request naming the development draft before dev mode created it: the
+ * first dev-mode sync after login does, so the site has to run locally once first.
+ */
+export declare const NO_DEVELOPMENT_DRAFT_ERROR = "NO_DEVELOPMENT_DRAFT";
+/** URL search param carrying the current draft's id in the studio and the rendered site. */
+export declare const DRAFT_SEARCH_PARAM = "camox-draft";
+/** A regular draft is a named set of edits; a development draft backs a dev server. */
+export type DraftKind = "regular" | "development";
+/** How a regular draft ended. */
+export type DraftOutcome = "published" | "discarded";
+/** Who ended a draft, how and when, from its ended-drafts record (ADR 0009, ADR 0011). */
+export type EndedDraft = {
+  draftId: string;
+  outcome: DraftOutcome;
+  endedBy: {
+    id: string;
+    name: string;
+  };
+  endedAt: number;
+};
+/**
+ * The oRPC error code a request naming an ended draft fails with. Its `data` is an `EndedDraft`,
+ * so a page can render Live and say who published or discarded the draft.
+ */
+export declare const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
+/**
+ * oRPC error code for a publish whose token no longer matches Live: Live changed since the
+ * preview, so nothing was applied and the caller reviews the new preview.
+ */
+export declare const CONFLICTS_CHANGED_ERROR = "CONFLICTS_CHANGED";
+/** oRPC error code for a publish refused because the draft still has blockers. */
+export declare const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
+/**
+ * oRPC error code for a publish refused because the draft still has pending translations: every
+ * locale goes live together, unless the caller publishes anyway (ADR 0017).
+ */
+export declare const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
+/**
+ * Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
+ * review again, by the error code of each: Live changed since the preview, the draft has blockers,
+ * or translations are still running.
+ */
+export declare const NOT_PUBLISHED_CODES: {
+  readonly conflictsChanged: "CONFLICTS_CHANGED";
+  readonly blocked: "PUBLISH_BLOCKED";
+  readonly translating: "TRANSLATIONS_PENDING";
+};
+export type NotPublishedReason = keyof typeof NOT_PUBLISHED_CODES;
+/**
+ * Who Camox's own work is by: the creator of the drafts it opens to catch translations up, their
+ * publisher on Live, and who ended them. Shown as "Camox".
+ */
+export declare const CAMOX_ACTOR = "camox";
+/** The name Camox's own work shows under. */
+export declare const CAMOX_NAME = "Camox";
+/**
+ * oRPC error code for a content write that names no draft. Live is read-only (ADR 0003): content
+ * changes reach it only by publishing a draft, or through a release.
+ */
+export declare const LIVE_READ_ONLY_ERROR = "LIVE_READ_ONLY";
+/** Whether the procedure at `path` (`[router, procedure]`) writes content. */
+export declare function isContentWrite(path: readonly string[]): boolean;
+//#endregion

package/dist/drafts.js

@@ -0,0 +1,145 @@
+//#region src/drafts.ts
+/** Request header naming the draft a request reads and writes (ADR 0011). Absent means Live. */
+const DRAFT_HEADER = "x-camox-draft";
+/**
+* Request header naming, by its tag, the locale a request reads and writes content in (ADR
+* 0015). Absent means the project's default locale.
+*/
+const LOCALE_HEADER = "x-camox-locale";
+/**
+* Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
+* exist yet. Its value is `"1"`.
+*/
+const DRAFT_CREATE_HEADER = "x-camox-draft-create";
+/**
+* The `x-camox-draft` value naming the caller's own development draft in the project a request
+* acts on (ADR 0006, ADR 0011). Dev mode and the CLI always send it.
+*/
+const DEVELOPMENT_DRAFT = "development";
+/**
+* oRPC error code for a request naming the development draft before dev mode created it: the
+* first dev-mode sync after login does, so the site has to run locally once first.
+*/
+const NO_DEVELOPMENT_DRAFT_ERROR = "NO_DEVELOPMENT_DRAFT";
+/** URL search param carrying the current draft's id in the studio and the rendered site. */
+const DRAFT_SEARCH_PARAM = "camox-draft";
+/**
+* The oRPC error code a request naming an ended draft fails with. Its `data` is an `EndedDraft`,
+* so a page can render Live and say who published or discarded the draft.
+*/
+const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
+/**
+* oRPC error code for a publish whose token no longer matches Live: Live changed since the
+* preview, so nothing was applied and the caller reviews the new preview.
+*/
+const CONFLICTS_CHANGED_ERROR = "CONFLICTS_CHANGED";
+/** oRPC error code for a publish refused because the draft still has blockers. */
+const PUBLISH_BLOCKED_ERROR = "PUBLISH_BLOCKED";
+/**
+* oRPC error code for a publish refused because the draft still has pending translations: every
+* locale goes live together, unless the caller publishes anyway (ADR 0017).
+*/
+const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
+/**
+* Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
+* review again, by the error code of each: Live changed since the preview, the draft has blockers,
+* or translations are still running.
+*/
+const NOT_PUBLISHED_CODES = {
+	conflictsChanged: CONFLICTS_CHANGED_ERROR,
+	blocked: PUBLISH_BLOCKED_ERROR,
+	translating: TRANSLATIONS_PENDING_ERROR
+};
+/**
+* Who Camox's own work is by: the creator of the drafts it opens to catch translations up, their
+* publisher on Live, and who ended them. Shown as "Camox".
+*/
+const CAMOX_ACTOR = "camox";
+/** The name Camox's own work shows under. */
+const CAMOX_NAME = "Camox";
+/**
+* oRPC error code for a content write that names no draft. Live is read-only (ADR 0003): content
+* changes reach it only by publishing a draft, or through a release.
+*/
+const LIVE_READ_ONLY_ERROR = "LIVE_READ_ONLY";
+const CONTENT_WRITES = {
+	blocks: {
+		get: false,
+		getPageMarkdown: false,
+		getLayoutMarkdown: false,
+		getUsageCounts: false,
+		getPagesUsing: false,
+		getSyncedContent: false,
+		create: true,
+		updateContent: true,
+		updateSettings: true,
+		updatePosition: true,
+		delete: true,
+		deleteMany: true,
+		generateSummary: false,
+		duplicate: true
+	},
+	locales: {
+		list: false,
+		add: true,
+		remove: true,
+		setDefaultTag: false,
+		listMissing: false,
+		addBack: true
+	},
+	collectionDefinitions: {
+		list: false,
+		get: false,
+		listRecords: false,
+		getRecord: false,
+		getRecordUsageCount: false,
+		findRecordsByField: false,
+		listRecordPageValues: false,
+		recordMarkdown: false,
+		createRecord: true,
+		editRecord: true,
+		deleteRecord: true
+	},
+	files: {
+		list: false,
+		get: false,
+		getUsageCount: false,
+		setAlt: true,
+		setFilename: true,
+		delete: true,
+		deleteMany: true,
+		setAiMetadata: true,
+		generateMetadata: false
+	},
+	pages: {
+		getByPath: false,
+		getStructure: false,
+		list: false,
+		listBySlug: false,
+		get: false,
+		create: true,
+		update: true,
+		delete: true,
+		setSeo: true,
+		setLayout: true,
+		generateSeo: false
+	},
+	repeatableItems: {
+		get: false,
+		create: true,
+		updateContent: true,
+		updateSettings: true,
+		updatePosition: true,
+		duplicate: true,
+		generateSummary: false,
+		delete: true
+	}
+};
+/** Whether the procedure at `path` (`[router, procedure]`) writes content. */
+function isContentWrite(path) {
+	if (path.length !== 2) return false;
+	return CONTENT_WRITES[path[0]]?.[path[1]] === true;
+}
+
+//#endregion
+export { CAMOX_ACTOR, CAMOX_NAME, CONFLICTS_CHANGED_ERROR, DEVELOPMENT_DRAFT, DRAFT_CREATE_HEADER, DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, DRAFT_SEARCH_PARAM, LIVE_READ_ONLY_ERROR, LOCALE_HEADER, NOT_PUBLISHED_CODES, NO_DEVELOPMENT_DRAFT_ERROR, PUBLISH_BLOCKED_ERROR, TRANSLATIONS_PENDING_ERROR, isContentWrite };

package/dist/icon-catalog.d.ts

@@ -0,0 +1,7 @@
+import { n as IconSvgData } from "./icons-BAxwOBBX.js";
+import { IconifyJSON } from "@iconify/types";
+//#region src/icon-catalog.d.ts
+export declare function loadIconCollection(prefix: string): Promise<IconifyJSON>;
+export declare function iconCollectionIds(data: IconifyJSON): string[];
+export declare function resolveIconSvg(data: IconifyJSON, id: string): IconSvgData;
+//#endregion

package/dist/icon-catalog.js

@@ -0,0 +1,48 @@
+import { t as ICON_CATALOG_VERSION } from "./icons-Bk4igP2j.js";
+import { getIconData, iconToSVG } from "@iconify/utils";
+
+//#region src/icon-catalog.ts
+const collections = /* @__PURE__ */ new Map();
+async function loadIconCollection(prefix) {
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(prefix)) throw new Error("Invalid icon collection");
+	const existing = collections.get(prefix);
+	if (existing) return existing;
+	const pending = (async () => {
+		const response = await fetch(`https://unpkg.com/@iconify/json@${ICON_CATALOG_VERSION}/json/${prefix}.json`, { signal: AbortSignal.timeout(3e4) });
+		if (!response.ok) throw new Error(`Unable to load icon collection ${prefix}`);
+		const data = await response.json();
+		if (data.prefix !== prefix || !data.icons || !data.info?.license) throw new Error("Invalid icon catalog or missing license");
+		return data;
+	})();
+	collections.set(prefix, pending);
+	if (collections.size > 8) collections.delete(collections.keys().next().value);
+	try {
+		return await pending;
+	} catch (error) {
+		collections.delete(prefix);
+		throw error;
+	}
+}
+function iconCollectionIds(data) {
+	return [...Object.keys(data.icons), ...Object.keys(data.aliases ?? {})].filter((name) => getIconData(data, name) !== null).sort().map((name) => `${data.prefix}:${name}`);
+}
+function resolveIconSvg(data, id) {
+	const [prefix, name, extra] = id.split(":");
+	if (prefix !== data.prefix || !name || extra !== void 0) throw new Error("Invalid icon ID");
+	const icon = getIconData(data, name);
+	if (!icon) throw new Error(`Unknown icon: ${id}`);
+	const svg = iconToSVG(icon);
+	return {
+		body: svg.body,
+		attributes: svg.attributes,
+		attribution: data.info ? {
+			collection: data.info.name,
+			author: data.info.author.name,
+			license: data.info.license.title,
+			url: data.info.license.url
+		} : void 0
+	};
+}
+
+//#endregion
+export { iconCollectionIds, loadIconCollection, resolveIconSvg };

package/dist/icons-BAxwOBBX.d.ts

@@ -0,0 +1,19 @@
+//#region src/icons.d.ts
+declare const ICON_CATALOG_VERSION = "2.2.532";
+type IconSvgData = {
+  body: string;
+  attributes: Record<string, string>;
+  attribution?: {
+    collection: string;
+    author: string;
+    license: string;
+    url?: string;
+  };
+};
+declare function scopeIconSvgIds(body: string, prefix: string): string;
+declare function validateIconValue(value: unknown, schema: {
+  fieldType?: string;
+  enum?: unknown;
+}): void;
+//#endregion
+export { validateIconValue as i, IconSvgData as n, scopeIconSvgIds as r, ICON_CATALOG_VERSION as t };

package/dist/icons-Bk4igP2j.js

@@ -0,0 +1,15 @@
+//#region src/icons.ts
+const ICON_CATALOG_VERSION = "2.2.532";
+function scopeIconSvgIds(body, prefix) {
+	const ids = [...body.matchAll(/\sid="([^\s"]+)"/g)].map((match) => match[1]);
+	if (!ids.length) return body;
+	const pattern = ids.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+	return body.replace(new RegExp(`([#;"])(${pattern})([")]|\\.[a-z])`, "g"), (_match, before, id, after) => `${before}${prefix}${id}${after}`);
+}
+function validateIconValue(value, schema) {
+	if (schema.fieldType !== "Icon") return;
+	if (typeof value !== "string" || !Array.isArray(schema.enum) || !schema.enum.includes(value)) throw new Error(`Invalid icon ID: ${String(value)}`);
+}
+
+//#endregion
+export { scopeIconSvgIds as n, validateIconValue as r, ICON_CATALOG_VERSION as t };

package/dist/ids.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+//#region src/ids.d.ts
+/** The id of a content entity: one UUIDv7, kept in Live and every draft (ADR 0004). */
+export declare const uuidv7Schema: z.ZodUUID;
+/**
+ * A Project ID: a UUIDv7 in lowercase only, the form the project's Worker is named by, so an
+ * uppercase one fails here rather than silently naming no project.
+ */
+export declare const projectIdSchema: z.ZodUUID;
+/**
+ * `uuidv7Schema` as JSON Schema, for content schemas. Written out rather than derived, so site
+ * bundles, which need only this, leave zod out.
+ */
+export declare const uuidv7JsonSchema: {
+  type: string;
+  format: string;
+  pattern: string;
+};
+/** A text link to a page: this prefix, then the page's UUIDv7. */
+export declare const PAGE_TEXT_LINK_PREFIX = "camox:page:";
+/**
+ * Mints a UUIDv7 (RFC 9562): a 48-bit millisecond timestamp, then random bits.
+ * The server mints ids; clients mint one only for optimistic inserts.
+ */
+export declare function generateUuidv7(): string;
+//#endregion

package/dist/ids.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+//#region src/ids.ts
+/** The id of a content entity: one UUIDv7, kept in Live and every draft (ADR 0004). */
+const uuidv7Schema = /* @__PURE__ */ z.uuidv7();
+/**
+* A Project ID: a UUIDv7 in lowercase only, the form the project's Worker is named by, so an
+* uppercase one fails here rather than silently naming no project.
+*/
+const projectIdSchema = /* @__PURE__ */ z.uuidv7().regex(/^[0-9a-f-]+$/, "A Project ID is a UUIDv7 in lowercase");
+/**
+* `uuidv7Schema` as JSON Schema, for content schemas. Written out rather than derived, so site
+* bundles, which need only this, leave zod out.
+*/
+const uuidv7JsonSchema = {
+	type: "string",
+	format: "uuid",
+	pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"
+};
+/** A text link to a page: this prefix, then the page's UUIDv7. */
+const PAGE_TEXT_LINK_PREFIX = "camox:page:";
+/**
+* Mints a UUIDv7 (RFC 9562): a 48-bit millisecond timestamp, then random bits.
+* The server mints ids; clients mint one only for optimistic inserts.
+*/
+function generateUuidv7() {
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	let timestamp = Date.now();
+	for (let index = 5; index >= 0; index--) {
+		bytes[index] = timestamp % 256;
+		timestamp = Math.floor(timestamp / 256);
+	}
+	bytes[6] = bytes[6] & 15 | 112;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+//#endregion
+export { PAGE_TEXT_LINK_PREFIX, generateUuidv7, projectIdSchema, uuidv7JsonSchema, uuidv7Schema };