@camox/api-contract 0.63.0 → 0.66.0

package/dist/analytics.d.ts

@@ -12,8 +12,8 @@ export declare const ga4MeasurementIdSchema: z.ZodString;
 export declare const posthogProjectApiKeySchema: z.ZodString;
 /** The PostHog Cloud region a project lives in. */
 export declare const posthogRegionSchema: z.ZodEnum<{
-  us: "us";
   eu: "eu";
+  us: "us";
 }>;
 export type PosthogRegion = z.output<typeof posthogRegionSchema>;
 //#endregion

package/dist/drafts.d.ts

@@ -20,6 +20,41 @@ export declare const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
  * `PUBLISHING_DRAFT_HEADER`.
  */
 export declare const PUBLISHING_DRAFT_VAR = "CAMOX_PUBLISHING_DRAFT";
+/**
+ * Request header carrying a look token (ADR 0032): a short-lived, read-only credential the API
+ * signs for the agent's `look` tool, naming one project and one draft. A request carrying a valid
+ * one reads that draft's content, named with `DRAFT_HEADER`, as a member would, without a session.
+ * It writes nothing, reads no other draft, and reads none of Live's private data.
+ */
+export declare const LOOK_TOKEN_HEADER = "x-camox-look-token";
+/**
+ * The cookie the browser `look` drives carries the look token in, set for the website's host
+ * only, so third-party requests never see it. The website forwards it as `LOOK_TOKEN_HEADER`.
+ */
+export declare const LOOK_TOKEN_COOKIE = "camox_look";
+/**
+ * The website's lightweight document the browser `look` drives loads (the SDK runtime's
+ * `RUNTIME_ROUTE_PATHS.look`): one page of the draft `DRAFT_SEARCH_PARAM` names, at the path
+ * `LOOK_PATH_PARAM` gives in the locale `LOOK_LOCALE_PARAM` names, its Default Locale without.
+ */
+export declare const LOOK_DOCUMENT_PATH = "/_camox/look";
+export declare const LOOK_PATH_PARAM = "path";
+export declare const LOOK_LOCALE_PARAM = "locale";
+/**
+ * The look document's Block Definition mode: instead of a page, the block of the Block Definition
+ * `LOOK_BLOCK_DEFINITION_PARAM` names, alone in the site's shell, with its default content and
+ * Block Settings and the overrides `LOOK_CONTENT_PARAM` and `LOOK_SETTINGS_PARAM` give as JSON, in
+ * the shape the content tools take.
+ */
+export declare const LOOK_BLOCK_DEFINITION_PARAM = "blockDefinition";
+export declare const LOOK_CONTENT_PARAM = "content";
+export declare const LOOK_SETTINGS_PARAM = "settings";
+/**
+ * The id of a block shown without being placed, as the look document's Block Definition mode
+ * shows it: never a stored block's, which are UUIDs. Its element is
+ * `[data-camox-viewport-block="unplaced"]`.
+ */
+export declare const UNPLACED_BLOCK_ID = "unplaced";
 /**
  * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
  * exist yet. Its value is `"1"`.
@@ -68,18 +103,31 @@ export type PublishAbortReason = (typeof PUBLISH_ABORT_REASONS)[number];
 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).
+ * locale goes live together, and there is no publishing anyway (ADR 0033).
  */
 export declare const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
+/**
+ * oRPC error code for a publish refused because the draft has open findings, each to fix or for a
+ * member to dismiss: there is no publishing past them (ADR 0033).
+ */
+export declare const FINDINGS_OPEN_ERROR = "FINDINGS_OPEN";
+/**
+ * oRPC error code for a publish refused because a patroller's check at publish hasn't read the
+ * draft's latest changes yet: publishing waits for it (ADR 0033).
+ */
+export declare const CHECKS_RUNNING_ERROR = "CHECKS_RUNNING";
 /**
  * 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,
- * translations are still running, or the draft's code changed since the preview.
+ * translations are still running, the draft has open findings, a check at publish is still
+ * running, or the draft's code changed since the preview.
  */
 export declare const NOT_PUBLISHED_CODES: {
   readonly conflictsChanged: "CONFLICTS_CHANGED";
   readonly blocked: "PUBLISH_BLOCKED";
   readonly translating: "TRANSLATIONS_PENDING";
+  readonly findings: "FINDINGS_OPEN";
+  readonly checking: "CHECKS_RUNNING";
   readonly revisionChanged: "REVISION_CHANGED";
 };
 export type NotPublishedReason = keyof typeof NOT_PUBLISHED_CODES;

package/dist/drafts.js

@@ -21,6 +21,41 @@ const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
 */
 const PUBLISHING_DRAFT_VAR = "CAMOX_PUBLISHING_DRAFT";
 /**
+* Request header carrying a look token (ADR 0032): a short-lived, read-only credential the API
+* signs for the agent's `look` tool, naming one project and one draft. A request carrying a valid
+* one reads that draft's content, named with `DRAFT_HEADER`, as a member would, without a session.
+* It writes nothing, reads no other draft, and reads none of Live's private data.
+*/
+const LOOK_TOKEN_HEADER = "x-camox-look-token";
+/**
+* The cookie the browser `look` drives carries the look token in, set for the website's host
+* only, so third-party requests never see it. The website forwards it as `LOOK_TOKEN_HEADER`.
+*/
+const LOOK_TOKEN_COOKIE = "camox_look";
+/**
+* The website's lightweight document the browser `look` drives loads (the SDK runtime's
+* `RUNTIME_ROUTE_PATHS.look`): one page of the draft `DRAFT_SEARCH_PARAM` names, at the path
+* `LOOK_PATH_PARAM` gives in the locale `LOOK_LOCALE_PARAM` names, its Default Locale without.
+*/
+const LOOK_DOCUMENT_PATH = "/_camox/look";
+const LOOK_PATH_PARAM = "path";
+const LOOK_LOCALE_PARAM = "locale";
+/**
+* The look document's Block Definition mode: instead of a page, the block of the Block Definition
+* `LOOK_BLOCK_DEFINITION_PARAM` names, alone in the site's shell, with its default content and
+* Block Settings and the overrides `LOOK_CONTENT_PARAM` and `LOOK_SETTINGS_PARAM` give as JSON, in
+* the shape the content tools take.
+*/
+const LOOK_BLOCK_DEFINITION_PARAM = "blockDefinition";
+const LOOK_CONTENT_PARAM = "content";
+const LOOK_SETTINGS_PARAM = "settings";
+/**
+* The id of a block shown without being placed, as the look document's Block Definition mode
+* shows it: never a stored block's, which are UUIDs. Its element is
+* `[data-camox-viewport-block="unplaced"]`.
+*/
+const UNPLACED_BLOCK_ID = "unplaced";
+/**
 * Request header asking the API to create the draft named by `DRAFT_HEADER` if it doesn't
 * exist yet. Its value is `"1"`.
 */
@@ -62,18 +97,31 @@ const PUBLISH_ABORT_REASONS = [
 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).
+* locale goes live together, and there is no publishing anyway (ADR 0033).
 */
 const TRANSLATIONS_PENDING_ERROR = "TRANSLATIONS_PENDING";
 /**
+* oRPC error code for a publish refused because the draft has open findings, each to fix or for a
+* member to dismiss: there is no publishing past them (ADR 0033).
+*/
+const FINDINGS_OPEN_ERROR = "FINDINGS_OPEN";
+/**
+* oRPC error code for a publish refused because a patroller's check at publish hasn't read the
+* draft's latest changes yet: publishing waits for it (ADR 0033).
+*/
+const CHECKS_RUNNING_ERROR = "CHECKS_RUNNING";
+/**
 * 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,
-* translations are still running, or the draft's code changed since the preview.
+* translations are still running, the draft has open findings, a check at publish is still
+* running, or the draft's code changed since the preview.
 */
 const NOT_PUBLISHED_CODES = {
 	conflictsChanged: CONFLICTS_CHANGED_ERROR,
 	blocked: PUBLISH_BLOCKED_ERROR,
 	translating: TRANSLATIONS_PENDING_ERROR,
+	findings: FINDINGS_OPEN_ERROR,
+	checking: CHECKS_RUNNING_ERROR,
 	revisionChanged: REVISION_CHANGED_ERROR
 };
 /**
@@ -96,6 +144,7 @@ const CONTENT_WRITES = {
 		getUsageCounts: false,
 		getPagesUsing: false,
 		getSyncedContent: false,
+		getUnplaced: false,
 		create: true,
 		updateContent: true,
 		updateSettings: true,
@@ -151,6 +200,11 @@ const CONTENT_WRITES = {
 		setLayout: true,
 		generateSeo: false
 	},
+	patrol: {
+		get: false,
+		applyFix: true,
+		dismissFinding: false
+	},
 	repeatableItems: {
 		get: false,
 		create: true,
@@ -169,4 +223,4 @@ function isContentWrite(path) {
 }
 
 //#endregion
-export { CAMOX_ACTOR, CAMOX_NAME, CONFLICTS_CHANGED_ERROR, DRAFT_CREATE_HEADER, DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, DRAFT_SEARCH_PARAM, LIVE_READ_ONLY_ERROR, LOCALE_HEADER, NOT_PUBLISHED_CODES, PUBLISHING_DRAFT_HEADER, PUBLISHING_DRAFT_VAR, PUBLISH_ABORT_REASONS, PUBLISH_BLOCKED_ERROR, REVISION_CHANGED_ERROR, TRANSLATIONS_PENDING_ERROR, isContentWrite };
+export { CAMOX_ACTOR, CAMOX_NAME, CHECKS_RUNNING_ERROR, CONFLICTS_CHANGED_ERROR, DRAFT_CREATE_HEADER, DRAFT_ENDED_ERROR_CODE, DRAFT_HEADER, DRAFT_SEARCH_PARAM, FINDINGS_OPEN_ERROR, LIVE_READ_ONLY_ERROR, LOCALE_HEADER, LOOK_BLOCK_DEFINITION_PARAM, LOOK_CONTENT_PARAM, LOOK_DOCUMENT_PATH, LOOK_LOCALE_PARAM, LOOK_PATH_PARAM, LOOK_SETTINGS_PARAM, LOOK_TOKEN_COOKIE, LOOK_TOKEN_HEADER, NOT_PUBLISHED_CODES, PUBLISHING_DRAFT_HEADER, PUBLISHING_DRAFT_VAR, PUBLISH_ABORT_REASONS, PUBLISH_BLOCKED_ERROR, REVISION_CHANGED_ERROR, TRANSLATIONS_PENDING_ERROR, UNPLACED_BLOCK_ID, isContentWrite };

package/dist/layout-routes.d.ts

@@ -0,0 +1,20 @@
+//#region src/layout-routes.d.ts
+/** How a layout's pages come about: authored by editors, derived from data, or one fixed page. */
+export type LayoutKind = "curated" | "derived" | "singleton";
+/** A layout as route matching reads it: its id, which is its file route, and its kind. */
+export type LayoutRoute = {
+  id: string;
+  kind: LayoutKind;
+};
+/** The segments of a layout's file route, such as `blog.$slug`: `$` segments are params. */
+export declare function routeSegments(id: string): string[];
+/**
+ * The singleton or derived layout whose route matches `pathname`, a path in its Locale, with its
+ * params, or null. The route with the fewest params wins, so a singleton's fixed route wins over
+ * a derived route that would match it too. The SDK renders pages and the API checks them with it.
+ */
+export declare function matchLayoutRoute<L>(layouts: readonly L[], pathname: string, routeOf: (layout: L) => LayoutRoute): {
+  layout: L;
+  params: Record<string, string>;
+} | null;
+//#endregion

package/dist/layout-routes.js

@@ -0,0 +1,43 @@
+//#region src/layout-routes.ts
+/** The segments of a layout's file route, such as `blog.$slug`: `$` segments are params. */
+function routeSegments(id) {
+	return id.split(".");
+}
+/**
+* The singleton or derived layout whose route matches `pathname`, a path in its Locale, with its
+* params, or null. The route with the fewest params wins, so a singleton's fixed route wins over
+* a derived route that would match it too. The SDK renders pages and the API checks them with it.
+*/
+function matchLayoutRoute(layouts, pathname, routeOf) {
+	const path = pathname.replace(/^\/|\/$/g, "").split("/");
+	const paramCount = (layout) => routeSegments(routeOf(layout).id).filter((s) => s.startsWith("$")).length;
+	const candidates = layouts.filter((layout) => routeOf(layout).kind !== "curated").sort((a, b) => paramCount(a) - paramCount(b));
+	for (const layout of candidates) {
+		const segments = routeSegments(routeOf(layout).id);
+		if (segments.length !== path.length) continue;
+		const params = {};
+		let matches = true;
+		for (const [index, segment] of segments.entries()) {
+			let value;
+			try {
+				value = decodeURIComponent(path[index]);
+			} catch {
+				matches = false;
+				break;
+			}
+			if (segment.startsWith("$") && value && !value.includes("/")) params[segment.slice(1)] = value;
+			else if (segment !== value) {
+				matches = false;
+				break;
+			}
+		}
+		if (matches) return {
+			layout,
+			params
+		};
+	}
+	return null;
+}
+
+//#endregion
+export { matchLayoutRoute, routeSegments };

package/dist/patrol.d.ts

@@ -4,13 +4,15 @@
  * studio shows it at the top of the Agent Sidebar. The API reads it for one scope, a draft or
  * Live, and names each report's subject, so the studio needs no entity loaded to show it.
  */
-/** A patroller's stable id. The registry in the API lists them all. */
-export type PatrollerId = "translator" | "seoManager";
+/** Every patroller's stable id. The registry in the API lists them all. */
+export declare const PATROLLER_IDS: readonly ["translator", "seoManager", "linkChecker", "proofreader"];
+/** A patroller's stable id. */
+export type PatrollerId = (typeof PATROLLER_IDS)[number];
 /**
  * What a structured report says was done. Each has a failed form, by the report's outcome. A
  * merge with Live's localization reads as a translation.
  */
-export type ReportVerb = "translated" | "mergedWithLive" | "wroteSeo" | "describedFile" | "publishedCatchUp";
+export type ReportVerb = "translated" | "mergedWithLive" | "wroteSeo" | "describedFile" | "publishedCatchUp" | "removedLink" | "fixedLink" | "fixedMistake";
 /** What a report can be about. */
 export type ReportEntity = "page" | "block" | "sharedContent" | "repeatableItem" | "record" | "file";
 /** A report's subject, named as the Canvas names it, read when the Patrol is. */
@@ -41,8 +43,11 @@ export declare const reportLocale: (summary: {
 }) => string | null;
 /** Whether the work was done, or failed. A failure shows in its report only. */
 export type ReportOutcome = "done" | "failed";
-/** Whether a report needs a human. Nothing raises one yet. */
-export type AttentionLevel = "none" | "needed";
+/**
+ * Where a patroller is on duty, in drafts or on Live: it works as you go, checks when you
+ * publish, or is off there (ADR 0034).
+ */
+export type PatrollerDuty = "asYouGo" | "atPublish" | "off";
 /**
  * Where the studio shows a report's subject: a page on the Canvas, with the block and repeatable
  * item to select on it, a collection record, or a file.
@@ -65,7 +70,6 @@ export type ReportView = {
   id: string;
   summary: ReportSummary;
   outcome: ReportOutcome;
-  attention: AttentionLevel;
   /** When the work last settled, in milliseconds since the epoch. */
   at: number;
   /** Whether the report is Live's, seen from a draft or from Live. */
@@ -76,6 +80,89 @@ export type ReportView = {
    */
   place: ReportPlace | null;
 };
+/**
+ * What a finding is about (ADR 0034), by its kind:
+ * - `missingPage`: a link to a page that doesn't exist, the page's name as it was last known.
+ * - `brokenLink`: an external link that failed, and how.
+ * - `misspelling`, `grammar`: the flagged text, in the sentence it's in.
+ * A link's `url` is as content stores it: a page link's is `camox:page:<id>`, and `text` is what
+ * the link reads.
+ */
+export type FindingAbout = {
+  kind: "missingPage";
+  url: string;
+  text: string;
+  page: string | null;
+} | {
+  kind: "brokenLink";
+  url: string;
+  text: string;
+  failure: LinkFailure;
+} | {
+  kind: "misspelling" | "grammar";
+  text: string;
+  sentence: string;
+};
+/** How a link failed: an HTTP error status, no connection (DNS included), or no answer in time. */
+export type LinkFailure = {
+  kind: "status";
+  status: number;
+} | {
+  kind: "unreachable";
+} | {
+  kind: "timeout";
+};
+export type FindingKind = FindingAbout["kind"];
+/**
+ * The fix a finding suggests, which applying makes: removing the link, keeping its text, or
+ * replacing the flagged text with `replacement` in its sentence, keeping its formatting.
+ */
+export type FindingFix = {
+  kind: "removeLink";
+} | {
+  kind: "replaceText";
+  replacement: string;
+};
+/** A finding, open, in the scope viewed. */
+export type FindingView = {
+  /** What applying or dismissing it names. */
+  id: number;
+  about: FindingAbout;
+  /** The fix it suggests, if any. */
+  fix: FindingFix | null;
+  /** The content it's in, named in its locale. */
+  subject: ReportSubject;
+  /** The locale of the content it's in, by its tag. */
+  locale: string;
+  /** The content field it's in, by name. */
+  field: string;
+  /** When it was first raised, in milliseconds since the epoch. */
+  raisedAt: number;
+  /** Whether it's Live's. Live's are fixed in the Patrol Draft. */
+  live: boolean;
+  /** Where its content shows, as for reports. */
+  place: ReportPlace | null;
+};
+/**
+ * A finding as one sentence, as the studio, emails, Briefs and refusals word it: "“About us” in
+ * Footer links to About, a page that no longer exists".
+ */
+export declare function findingSentence(finding: Pick<FindingView, "about" | "subject">): string;
+/** A member's dismissal of what a finding was about: no finding like it is raised again. */
+export type DismissalView = {
+  id: number;
+  about: FindingAbout;
+  by: {
+    id: string;
+    name: string;
+  };
+  /** When it was dismissed, in milliseconds since the epoch. */
+  at: number;
+};
+/** What applying a finding's fix did: applied it, or found its content changed and rechecked. */
+export type ApplyResult = {
+  applied: boolean;
+};
 /** How many subjects a patroller is on in one locale, a locale's tag. */
 export type LocaleCount = {
   locale: string;
@@ -93,9 +180,19 @@ export type PatrollerView = {
   id: PatrollerId;
   /** Its role, as editors know it: "Translator", "SEO manager". */
   role: string;
+  /** Its duty in the scope viewed. Off there, it still has its reports. */
+  duty: PatrollerDuty;
   /** Null when it isn't working in the scope. */
   working: PatrollerWorking | null;
-  /** Its latest activity in the scope, or null when it never worked there. */
+  /**
+   * When it last finished a check in the scope, whether it found anything or not, or null when it
+   * never checked there.
+   */
+  lastCheckedAt: number | null;
+  /**
+   * Its latest activity in the scope: its last check, its newest report or when its pending work
+   * started, whichever is later. Null when it never worked there.
+   */
   lastActivityAt: number | null;
   /** Its newest reports, newest first. */
   reports: ReportView[];
@@ -104,10 +201,21 @@ export type PatrollerView = {
     locale: string | null;
     count: number;
   }[];
+  /** Its open findings in the scope viewed, the oldest first. Their count is the row's badge. */
+  findings: FindingView[];
+  /** The project's dismissals of its findings, the newest first. */
+  dismissals: DismissalView[];
 };
-/** Every patroller of the registry, the latest activity first; never-worked ones last. */
+/**
+ * Every patroller of the registry, the latest activity first; never-worked ones last. With the
+ * project's open Patrol Draft, where Live's findings are fixed, if any.
+ */
 export type PatrolView = {
   patrollers: PatrollerView[];
+  patrolDraft: {
+    id: string;
+    name: string | null;
+  } | null;
 };
 /** How many reports the Patrol shows of each patroller; the rest are counted. */
 export declare const REPORTS_SHOWN = 5;

package/dist/patrol.js

@@ -1,8 +1,40 @@
 //#region src/patrol.ts
+/**
+* The Patrol (ADR 0024): every patroller of a project, the work each did as reports, as the
+* studio shows it at the top of the Agent Sidebar. The API reads it for one scope, a draft or
+* Live, and names each report's subject, so the studio needs no entity loaded to show it.
+*/
+/** Every patroller's stable id. The registry in the API lists them all. */
+const PATROLLER_IDS = [
+	"translator",
+	"seoManager",
+	"linkChecker",
+	"proofreader"
+];
 /** The locale a summary's work was in: a structured summary's, if any. A text summary has none. */
 const reportLocale = (summary) => summary.kind === "structured" ? summary.locale : null;
+/** What a finding is about, after where it is: "links to About, a page that no longer exists". */
+function aboutSentence(about) {
+	switch (about.kind) {
+		case "missingPage": return about.page === null ? "links to a page that no longer exists" : `links to ${about.page}, a page that no longer exists`;
+		case "brokenLink": {
+			const { failure } = about;
+			const how = failure.kind === "status" ? `answers with an error (${failure.status})` : failure.kind === "timeout" ? "doesn't answer in time" : "can't be reached";
+			return `links to ${about.url}, which ${how}`;
+		}
+		case "misspelling": return "may be misspelled";
+		case "grammar": return "may be a grammar mistake";
+	}
+}
+/**
+* A finding as one sentence, as the studio, emails, Briefs and refusals word it: "“About us” in
+* Footer links to About, a page that no longer exists".
+*/
+function findingSentence(finding) {
+	return `“${finding.about.text}” in ${finding.subject.name} ${aboutSentence(finding.about)}`;
+}
 /** How many reports the Patrol shows of each patroller; the rest are counted. */
 const REPORTS_SHOWN = 5;
 
 //#endregion
-export { REPORTS_SHOWN, reportLocale };
+export { PATROLLER_IDS, REPORTS_SHOWN, findingSentence, reportLocale };