@camox/api-contract 0.63.0 → 0.66.0

package/src/drafts.ts

@@ -25,6 +25,46 @@ export const PUBLISHING_DRAFT_HEADER = "x-camox-publishing-draft";
  */
 export 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 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 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 const LOOK_DOCUMENT_PATH = "/_camox/look";
+export const LOOK_PATH_PARAM = "path";
+export 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 const LOOK_BLOCK_DEFINITION_PARAM = "blockDefinition";
+export const LOOK_CONTENT_PARAM = "content";
+export 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 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"`.
@@ -87,19 +127,34 @@ export 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 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 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 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 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,
 } as const;
 
@@ -133,6 +188,7 @@ const BLOCK_WRITES: Record<keyof Router["blocks"], boolean> = {
   getUsageCounts: false,
   getPagesUsing: false,
   getSyncedContent: false,
+  getUnplaced: false,
   create: true,
   updateContent: true,
   updateSettings: true,
@@ -208,6 +264,14 @@ const LOCALE_WRITES: Record<keyof Router["locales"], boolean> = {
   addBack: true,
 };
 
+// Applying a finding's fix edits content as the member would; dismissing one is the project's,
+// never content (ADR 0034).
+const PATROL_WRITES: Record<keyof Router["patrol"], boolean> = {
+  get: false,
+  applyFix: true,
+  dismissFinding: false,
+};
+
 // `definitions` is absent: its sync is a release, never a studio content write.
 const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   blocks: BLOCK_WRITES,
@@ -215,6 +279,7 @@ const CONTENT_WRITES: Partial<Record<keyof Router, Record<string, boolean>>> = {
   collectionDefinitions: COLLECTION_WRITES,
   files: FILE_WRITES,
   pages: PAGE_WRITES,
+  patrol: PATROL_WRITES,
   repeatableItems: ITEM_WRITES,
 };
 

package/src/layout-routes.ts

@@ -0,0 +1,51 @@
+/** 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 function routeSegments(id: string) {
+  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.
+ */
+export function matchLayoutRoute<L>(
+  layouts: readonly L[],
+  pathname: string,
+  routeOf: (layout: L) => LayoutRoute,
+): { layout: L; params: Record<string, string> } | null {
+  const path = pathname.replace(/^\/|\/$/g, "").split("/");
+  const paramCount = (layout: L) =>
+    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: Record<string, string> = {};
+    let matches = true;
+    for (const [index, segment] of segments.entries()) {
+      let value: string;
+      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;
+}

package/src/patrol.ts

@@ -4,8 +4,11 @@
  * 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 const PATROLLER_IDS = ["translator", "seoManager", "linkChecker", "proofreader"] as const;
+
+/** 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
@@ -16,7 +19,10 @@ export type ReportVerb =
   | "mergedWithLive"
   | "wroteSeo"
   | "describedFile"
-  | "publishedCatchUp";
+  | "publishedCatchUp"
+  | "removedLink"
+  | "fixedLink"
+  | "fixedMistake";
 
 /** What a report can be about. */
 export type ReportEntity =
@@ -51,8 +57,11 @@ export const reportLocale = (
 /** 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
@@ -68,7 +77,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. */
@@ -80,6 +88,98 @@ 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;
+};
+
+/** What a finding is about, after where it is: "links to About, a page that no longer exists". */
+function aboutSentence(about: FindingAbout): string {
+  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".
+ */
+export function findingSentence(finding: Pick<FindingView, "about" | "subject">): string {
+  return `“${finding.about.text}” in ${finding.subject.name} ${aboutSentence(finding.about)}`;
+}
+
+/** 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; count: number };
 
@@ -96,18 +196,38 @@ 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[];
   /** How many more reports it has than `reports` shows, per locale, the most first. */
   more: { 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. */
-export type PatrolView = { patrollers: PatrollerView[] };
+/**
+ * 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 const REPORTS_SHOWN = 5;