@camox/api-contract 0.54.0 → 0.57.0

package/dist/drafts.d.ts

@@ -40,7 +40,7 @@ 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";
+export type DraftOutcome = "published" | "deleted";
 /** Who ended a draft, how and when, from its ended-drafts record (ADR 0009, ADR 0011). */
 export type EndedDraft = {
   draftId: string;
@@ -53,7 +53,7 @@ export type EndedDraft = {
 };
 /**
  * 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.
+ * so a page can render Live and say who published or deleted the draft.
  */
 export declare const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
 /**

package/dist/drafts.js

@@ -39,7 +39,7 @@ const NO_DEVELOPMENT_DRAFT_ERROR = "NO_DEVELOPMENT_DRAFT";
 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.
+* so a page can render Live and say who published or deleted the draft.
 */
 const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
 /**

package/dist/patrol.d.ts

@@ -0,0 +1,114 @@
+//#region src/patrol.d.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.
+ */
+/** A patroller's stable id. The registry in the API lists them all. */
+export type PatrollerId = "translator" | "seoManager";
+/**
+ * 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";
+/** 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. */
+export type ReportSubject = {
+  entity: ReportEntity;
+  id: string;
+  name: string;
+};
+/**
+ * What a report says: structured facts the studio turns into a sentence, in the studio's
+ * language, or text an AI wrote, shown as is. `locale` is a locale's tag.
+ */
+export type ReportSummary = {
+  kind: "structured";
+  verb: ReportVerb;
+  subject: ReportSubject | null;
+  locale: string | null;
+} | {
+  kind: "text";
+  text: string;
+};
+/** The locale a summary's work was in: a structured summary's, if any. A text summary has none. */
+export declare const reportLocale: (summary: {
+  kind: "structured";
+  locale: string | null;
+} | {
+  kind: "text";
+}) => 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 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.
+ */
+export type ReportPlace = {
+  kind: "page";
+  pageId: string;
+  blockId: string | null;
+  itemId: string | null;
+} | {
+  kind: "record";
+  collectionId: string;
+  recordId: string;
+} | {
+  kind: "file";
+  fileId: string;
+};
+export type ReportView = {
+  /** Unique among the patroller's reports in the view. */
+  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. */
+  live: boolean;
+  /**
+   * Where its subject shows, in the report's scope and locale. Null without a subject, or for one
+   * with no single place, such as a synced block's shared content or a layout's block.
+   */
+  place: ReportPlace | null;
+};
+/** How many subjects a patroller is on in one locale, a locale's tag. */
+export type LocaleCount = {
+  locale: string;
+  count: number;
+};
+/**
+ * What a patroller is on: the one subject when there's one, and how many subjects in each
+ * locale, the most first. A subject in several locales counts in each.
+ */
+export type PatrollerWorking = {
+  subject: ReportSubject | null;
+  locales: LocaleCount[];
+};
+export type PatrollerView = {
+  id: PatrollerId;
+  /** Its role, as editors know it: "Translator", "SEO manager". */
+  role: string;
+  /** 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. */
+  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;
+  }[];
+};
+/** Every patroller of the registry, the latest activity first; never-worked ones last. */
+export type PatrolView = {
+  patrollers: PatrollerView[];
+};
+/** How many reports the Patrol shows of each patroller; the rest are counted. */
+export declare const REPORTS_SHOWN = 5;
+//#endregion

package/dist/patrol.js

@@ -0,0 +1,8 @@
+//#region src/patrol.ts
+/** 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;
+/** How many reports the Patrol shows of each patroller; the rest are counted. */
+const REPORTS_SHOWN = 5;
+
+//#endregion
+export { REPORTS_SHOWN, reportLocale };

package/dist/query-keys.d.ts

@@ -40,6 +40,9 @@ export declare const queryKeys: {
     list: ["camox", string, string];
     get: ["camox", string, string];
   };
+  patrol: {
+    get: ["camox", 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";
@@ -61,7 +64,7 @@ export type InvalidationMessage = {
   draftId: string | null;
   targets: QueryKey[];
 };
-/** A draft was published or discarded: its viewers go back to Live. */
+/** A draft was published or deleted: its viewers go back to Live. */
 export type DraftEndedMessage = {
   type: "draftEnded";
 } & EndedDraft;

package/dist/query-keys.js

@@ -98,7 +98,8 @@ const queryKeys = {
 			"drafts",
 			"get"
 		]
-	}
+	},
+	patrol: { get: ["camox", "patrol"] }
 };
 /** The last segment of a query key: what the query reads, Live or a draft (ADR 0011). */
 const LIVE_KEY_SCOPE = "live";