@camox/api-contract 0.44.0 → 0.45.0

package/dist/index.js

@@ -1,102 +1,70 @@
-// src/icons.ts
-import { getIconData, iconToSVG } from "@iconify/utils";
-var ICON_CATALOG_VERSION = "2.2.532";
-var 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;
-  }
+import { n as scopeIconSvgIds, r as validateIconValue, t as ICON_CATALOG_VERSION } from "./icons-Bk4igP2j.js";
+import { PAGE_TEXT_LINK_PREFIX, generateUuidv7, projectIdSchema, uuidv7JsonSchema, uuidv7Schema } from "./ids.js";
+
+//#region src/artifact.ts
+/**
+* Artifact titles, shared by the SDK (frame titles, studio sidebar) and the API (Markdown
+* Representation, write warnings), so every surface names an artifact the same way.
+*/
+const UNTITLED_ARTIFACT = "Untitled artifact";
+const entities = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " "
+};
+function decodeEntities(text) {
+	return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity) => {
+		if (entity[0] !== "#") return entities[entity.toLowerCase()] ?? match;
+		const code = entity[1] === "x" || entity[1] === "X" ? Number.parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+		return Number.isNaN(code) ? match : String.fromCodePoint(code);
+	});
 }
-function iconCollectionIds(data) {
-  return [...Object.keys(data.icons), ...Object.keys(data.aliases ?? {})].filter((name) => getIconData(data, name) !== null).sort().map((name) => `${data.prefix}:${name}`);
+/** The non-empty `<title>` of an artifact source, if it has one. */
+function artifactSourceTitle(source) {
+	const match = /<title\b[^>]*>([\s\S]*?)<\/title\s*>/i.exec(source);
+	return (match ? decodeEntities(match[1]).replace(/\s+/g, " ").trim() : "") || void 0;
 }
-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
-  };
+/** The artifact's name: its source's `<title>`, or "Untitled artifact". */
+function artifactTitle(source) {
+	return artifactSourceTitle(source) ?? "Untitled artifact";
 }
-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}`
-  );
+
+//#endregion
+//#region src/reference-query.ts
+/**
+* Rules for query-backed reference lists, shared by the SDK (builders) and the API (definition
+* sync), so both accept and reject the same queries.
+*/
+/** The most records a query-backed list resolves to, and its default `limit`. */
+const QUERY_LIMIT_CAP = 100;
+const SYSTEM_ORDER_KEYS = ["createdAt", "publishedAt"];
+function isSystemOrderKey(key) {
+	return SYSTEM_ORDER_KEYS.includes(key);
 }
-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)}`);
-  }
+/** Whether a reference list field is query-backed: code defines its records, nothing is stored. */
+function isQueryBacked(field) {
+	return !!field && field.query !== void 0;
+}
+/**
+* Why a query is invalid, if it is. `fieldTypeOf` gives the collection field type an ordering
+* key names; keys must name a `String` field or system metadata.
+*/
+function referenceQueryProblem(query, fieldTypeOf) {
+	if (!query || typeof query !== "object" || Array.isArray(query)) return "query must be an object";
+	const { orderBy, limit, ...rest } = query;
+	if (Object.keys(rest).length) return "query only supports orderBy and limit";
+	if (limit !== void 0 && !(typeof limit === "number" && Number.isInteger(limit) && limit >= 1 && limit <= 100)) return `limit must be an integer from 1 to ${100}`;
+	if (orderBy === void 0) return;
+	const entries = orderBy && typeof orderBy === "object" && !Array.isArray(orderBy) ? Object.entries(orderBy) : [];
+	if (entries.length !== 1) return "orderBy takes a single key";
+	const [[key, direction]] = entries;
+	if (direction !== "asc" && direction !== "desc") return "order must be \"asc\" or \"desc\"";
+	if (isSystemOrderKey(key)) return;
+	if (fieldTypeOf(key) !== "String") return `cannot order by "${key}"`;
 }
 
-// src/comments.ts
-import { z } from "zod";
-var COMMENT_MESSAGE_MAX_LENGTH = 1e4;
-var objectId = z.number().int().positive();
-var fieldName = z.string().min(1).max(200);
-var commentTargetSchema = z.discriminatedUnion("kind", [
-  z.strictObject({ kind: z.literal("page") }),
-  z.strictObject({ kind: z.literal("block"), blockId: objectId }),
-  z.strictObject({ kind: z.literal("item"), blockId: objectId, itemId: objectId }),
-  z.strictObject({ kind: z.literal("block-field"), blockId: objectId, fieldName }),
-  z.strictObject({
-    kind: z.literal("item-field"),
-    blockId: objectId,
-    itemId: objectId,
-    fieldName
-  })
-]);
-var commentSchema = z.object({
-  id: z.uuid(),
-  pageId: objectId,
-  environmentId: objectId,
-  message: z.string(),
-  resolved: z.boolean(),
-  target: commentTargetSchema.nullable(),
-  author: z.object({ name: z.string(), image: z.string().nullable() }),
-  createdAt: z.number()
-});
-export {
-  COMMENT_MESSAGE_MAX_LENGTH,
-  ICON_CATALOG_VERSION,
-  commentSchema,
-  commentTargetSchema,
-  iconCollectionIds,
-  loadIconCollection,
-  resolveIconSvg,
-  scopeIconSvgIds,
-  validateIconValue
-};
+//#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 };

package/dist/projects.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/projects.d.ts
+/**
+ * Project Slugs Camox keeps for its own hosts and pages, so no project's `<slug>.camox.site`
+ * looks like one of them.
+ */
+export declare const RESERVED_PROJECT_SLUGS: ReadonlySet<string>;
+/**
+ * A Project Slug: one lowercase DNS label, the only depth Universal SSL covers on `camox.site`,
+ * made of letters, digits and inner hyphens.
+ */
+export declare const projectSlugSchema: z.ZodString;
+/** Why a slug can't be given to a new project. */
+export type UnavailableSlugReason = "invalid" | "reserved" | "taken";
+/** What a member is told when a slug can't be used, by reason. */
+export declare const UNAVAILABLE_SLUG_MESSAGES: Record<UnavailableSlugReason, string>;
+/**
+ * Where a project is in its life: `settingUp` from its creation until its first release
+ * succeeds, then `live`. `setupFailed` when its setup gave up: Camox is told and fixes it.
+ */
+export type ProjectStatus = "settingUp" | "live" | "setupFailed";
+/**
+ * The steps a project's setup goes through before it's live, as its page lists them: copying the
+ * Template into its repo, then its first release building it and serving it from its Worker.
+ */
+export type ProjectSetupStep = "copyTemplate" | "build" | "serve";
+export declare const PROJECT_SETUP_STEPS: readonly ProjectSetupStep[];
+//#endregion

package/dist/projects.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+//#region src/projects.ts
+/**
+* Project Slugs Camox keeps for its own hosts and pages, so no project's `<slug>.camox.site`
+* looks like one of them.
+*/
+const RESERVED_PROJECT_SLUGS = /* @__PURE__ */ new Set([
+	"www",
+	"api",
+	"app",
+	"dashboard",
+	"studio",
+	"sites",
+	"site",
+	"docs",
+	"blog",
+	"help",
+	"support",
+	"status",
+	"admin",
+	"auth",
+	"login",
+	"mail",
+	"email",
+	"cdn",
+	"static",
+	"assets",
+	"files",
+	"camox"
+]);
+/**
+* A Project Slug: one lowercase DNS label, the only depth Universal SSL covers on `camox.site`,
+* made of letters, digits and inner hyphens.
+*/
+const projectSlugSchema = /* @__PURE__ */ z.string().min(1, "Enter a slug").max(63, "Use at most 63 characters").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, digits and hyphens, without a hyphen at either end");
+/** What a member is told when a slug can't be used, by reason. */
+const UNAVAILABLE_SLUG_MESSAGES = {
+	invalid: "Use lowercase letters, digits and hyphens, without a hyphen at either end.",
+	reserved: "This slug is reserved by Camox. Choose another.",
+	taken: "This slug is already taken. Choose another."
+};
+const PROJECT_SETUP_STEPS = [
+	"copyTemplate",
+	"build",
+	"serve"
+];
+
+//#endregion
+export { PROJECT_SETUP_STEPS, RESERVED_PROJECT_SLUGS, UNAVAILABLE_SLUG_MESSAGES, projectSlugSchema };

package/dist/query-keys.d.ts

@@ -1,3 +1,5 @@
+import { EndedDraft } from "./drafts.js";
+//#region src/query-keys.d.ts
 /**
  * Use TypeScript to enforce 'camox' as the first query key to ensure they're all namespaced.
  * This is because the Tanstack Query client on the frontend may be shared with the user's routes,
@@ -5,50 +7,64 @@
  */
 export type QueryKey = [first: "camox", ...rest: Array<string | number>];
 /**
- * Source axis on read query keys. `'live'` reads the page's live published
- * checkpoint snapshot; `'draft'` reads the live editor rows. The two render
- * through the same component — only the cache slot differs, so toggling the
- * source select is instant once both have been seeded.
- *
- * Block / page-read query keys include the source as the trailing key segment.
- * Omitting it on `invalidateQueries` is a prefix invalidation that hits every
- * source — used for navigation events and other source-agnostic invalidations.
- * Edit-time invalidations (which only touch draft data) pass `'draft'`
- * explicitly so the `'live'` cache stays untouched.
+ * The key prefixes the API's realtime invalidations name (ADR 0011). The studio caches each read
+ * under one of them, with the scope appended, so an invalidation reaches every read it should;
+ * the studio's own keys live with its reads, in the SDK.
  */
-export type ReadSource = "draft" | "live";
 export declare const queryKeys: {
-    comments: {
-        all: ["camox", string];
-        list: (pageId: number) => ["camox", string, string, number];
-    };
-    pages: {
-        list: ["camox", string, string];
-        getByPath: (path: string, source?: ReadSource) => ["camox", string, string, string] | ["camox", string, string, string, ReadSource];
-        getByPathAll: ["camox", string, string];
-        getById: (id: number) => ["camox", string, string, number];
-    };
-    files: {
-        list: ["camox", string, string];
-        get: (id: number) => ["camox", string, string, number];
-    };
-    blocks: {
-        get: (id: number, source?: ReadSource) => ["camox", string, string, number] | ["camox", string, string, number, ReadSource];
-        getUsageCounts: ["camox", string, string];
-        getPageMarkdown: (pageId: number) => ["camox", string, string, number];
-    };
-    repeatableItems: {
-        get: (id: number) => ["camox", string, string, number];
-    };
-    layouts: {
-        all: ["camox", string];
-    };
-    environments: {
-        all: ["camox", string];
-        checkCompatibility: ["camox", string, string];
-    };
+  collections: {
+    record: (projectUuid: string, collectionId: string, id: string) => ["camox", string, string, string, string, string];
+    records: (projectUuid: string, collectionId: string) => ["camox", string, string, string, string];
+  };
+  pages: {
+    list: ["camox", string, string];
+    getByPath: (path: string) => ["camox", string, string, string];
+    getByPathAll: ["camox", string, string];
+    getById: (id: string) => ["camox", string, string, string];
+  };
+  files: {
+    list: ["camox", string, string];
+    get: (id: string) => ["camox", string, string, string];
+  };
+  blocks: {
+    get: (id: string) => ["camox", string, string, string];
+    getUsageCounts: ["camox", string, string];
+    getSyncedContent: (type: string) => ["camox", string, string, string, string];
+    getPageMarkdown: (pageId: string) => ["camox", string, string, string];
+  };
+  layouts: {
+    all: ["camox", string];
+  };
+  drafts: {
+    all: ["camox", string];
+    list: ["camox", string, string];
+    get: ["camox", string, string];
+  };
 };
+/** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
+export declare const LIVE_KEY_SCOPE = "live";
+/**
+ * A query key read from Live (`draftId` null) or from a draft. The keys above are prefixes naming
+ * what a query reads; the cache holds them with the scope appended, so each draft's queries are
+ * kept and invalidated apart.
+ */
+export declare function inScope(key: QueryKey, draftId: string | null): QueryKey;
+/** The scope a scoped query key ends in: `"live"` or a draft's id. */
+export declare function scopeOfKey(key: readonly unknown[]): unknown;
+/**
+ * Refetch the queries under these prefixes. `draftId` names the draft the change came from, so
+ * only that draft's queries refetch; a Live change (`null`) refetches every draft's too, since
+ * drafts read Live wherever they change nothing.
+ */
 export type InvalidationMessage = {
-    type: "invalidate";
-    targets: QueryKey[];
+  type: "invalidate";
+  draftId: string | null;
+  targets: QueryKey[];
 };
+/** A draft was published or discarded: its viewers go back to Live. */
+export type DraftEndedMessage = {
+  type: "draftEnded";
+} & EndedDraft;
+/** Everything the project room broadcasts. */
+export type ProjectRoomMessage = InvalidationMessage | DraftEndedMessage;
+//#endregion

package/dist/query-keys.js

@@ -1,33 +1,119 @@
-export const queryKeys = {
-    comments: {
-        all: ["camox", "comments"],
-        list: (pageId) => ["camox", "comments", "list", pageId],
-    },
-    pages: {
-        list: ["camox", "pages", "list"],
-        getByPath: (path, source) => source
-            ? ["camox", "pages", "getByPath", path, source]
-            : ["camox", "pages", "getByPath", path],
-        getByPathAll: ["camox", "pages", "getByPath"],
-        getById: (id) => ["camox", "pages", "getById", id],
-    },
-    files: {
-        list: ["camox", "files", "list"],
-        get: (id) => ["camox", "files", "get", id],
-    },
-    blocks: {
-        get: (id, source) => source ? ["camox", "blocks", "get", id, source] : ["camox", "blocks", "get", id],
-        getUsageCounts: ["camox", "blocks", "getUsageCounts"],
-        getPageMarkdown: (pageId) => ["camox", "blocks", "getPageMarkdown", pageId],
-    },
-    repeatableItems: {
-        get: (id) => ["camox", "repeatableItems", "get", id],
-    },
-    layouts: {
-        all: ["camox", "layouts"],
-    },
-    environments: {
-        all: ["camox", "environments"],
-        checkCompatibility: ["camox", "environments", "checkCompatibility"],
-    },
+//#region src/query-keys.ts
+/**
+* The key prefixes the API's realtime invalidations name (ADR 0011). The studio caches each read
+* under one of them, with the scope appended, so an invalidation reaches every read it should;
+* the studio's own keys live with its reads, in the SDK.
+*/
+const queryKeys = {
+	collections: {
+		record: (projectUuid, collectionId, id) => [
+			"camox",
+			"collections",
+			"record",
+			projectUuid,
+			collectionId,
+			id
+		],
+		records: (projectUuid, collectionId) => [
+			"camox",
+			"collections",
+			"records",
+			projectUuid,
+			collectionId
+		]
+	},
+	pages: {
+		list: [
+			"camox",
+			"pages",
+			"list"
+		],
+		getByPath: (path) => [
+			"camox",
+			"pages",
+			"getByPath",
+			path
+		],
+		getByPathAll: [
+			"camox",
+			"pages",
+			"getByPath"
+		],
+		getById: (id) => [
+			"camox",
+			"pages",
+			"getById",
+			id
+		]
+	},
+	files: {
+		list: [
+			"camox",
+			"files",
+			"list"
+		],
+		get: (id) => [
+			"camox",
+			"files",
+			"get",
+			id
+		]
+	},
+	blocks: {
+		get: (id) => [
+			"camox",
+			"blocks",
+			"get",
+			id
+		],
+		getUsageCounts: [
+			"camox",
+			"blocks",
+			"getUsageCounts"
+		],
+		getSyncedContent: (type) => [
+			"camox",
+			"blocks",
+			"getUsageCounts",
+			"synced",
+			type
+		],
+		getPageMarkdown: (pageId) => [
+			"camox",
+			"blocks",
+			"getPageMarkdown",
+			pageId
+		]
+	},
+	layouts: { all: ["camox", "layouts"] },
+	drafts: {
+		all: ["camox", "drafts"],
+		list: [
+			"camox",
+			"drafts",
+			"list"
+		],
+		get: [
+			"camox",
+			"drafts",
+			"get"
+		]
+	}
 };
+/** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
+const LIVE_KEY_SCOPE = "live";
+/**
+* A query key read from Live (`draftId` null) or from a draft. The keys above are prefixes naming
+* what a query reads; the cache holds them with the scope appended, so each draft's queries are
+* kept and invalidated apart.
+*/
+function inScope(key, draftId) {
+	return [...key, draftId ?? "live"];
+}
+/** The scope a scoped query key ends in: `"live"` or a draft's id. */
+function scopeOfKey(key) {
+	return key[key.length - 1];
+}
+
+//#endregion
+export { LIVE_KEY_SCOPE, inScope, queryKeys, scopeOfKey };