@sonordev/contracts 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.6.0
+
+A minor release: one new entry, `@sonordev/contracts/knowledge`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/knowledge`**: which Sonor records Signal reads into a project's knowledge, where each one's knowledge is stored, and how big a page sync may be, so the API that announces a change and Signal, which indexes it, agree.
+  - `KNOWLEDGE_RECORD_KINDS` lists the record kinds (`portfolio`, `proof`, `faq`, `review`, `article`, `offering`), and `isKnowledgeRecordKind(value)` checks one.
+  - `knowledgeRecordSourceUrl(kind, id, anchor?)` builds a record's address (`faq://<id>`, `article://<id>#pricing`) and `knowledgeRecordPrefix(kind)` the `<kind>://` all of a kind's addresses start with.
+  - `knowledgeRecordKindOf(url)` tells a record's row from a page passage by its scheme, and `knowledgeRecordRefOf(url)` returns the `{ kind, id }` an address names, the legacy `commerce://offering/<id>` (`legacyOfferingSourceUrl`) included.
+  - `KNOWLEDGE_SYNC_MAX_PAGES` (500), `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) and `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253) are the limits of one page sync, and `KnowledgePageChange` is the shape of each page in it. Signal applies every removal in a call and reads the changed pages in the order given, so a sender puts removals first.
+
 ## 2.5.0
 
 A minor release: one new entry, `@sonordev/contracts/sentences`, and a cache tag for commerce. Every other entry is unchanged.

package/README.md

@@ -27,6 +27,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/error-page` | Whether stored text is a rendered error page rather than a page's content, and whether generated copy says the page itself is missing | anything that stores page text or writes page copy from it: the Sonor API's page-view and sitemap writers, Signal's metadata generators |
 | `@sonordev/contracts/schema-placeholders` | Whether stored JSON-LD carries a template's unfilled slots (`example.com` URLs, an `Organization` named "Example", a placeholder phone, `[Resident Name]`, `{plan.name}`), and the value without them | site-kit's schema output, the Sonor API's schema reads and writes |
 | `@sonordev/contracts/sentences` | Where prose splits into sentences, without dropping a word or ending one at "p.m." (`splitSentences`) | anything that cuts an excerpt, a social slide or a summary out of an article: the Sonor API's carousels, Signal's article pipeline |
+| `@sonordev/contracts/knowledge` | Which Sonor records Signal reads into a project's knowledge, the address each one's knowledge is stored under (`portfolio://<id>`), and the limits of the call that tells Signal a site's pages changed | the Sonor API sends those calls and Signal answers them |
 
 ## Schema placeholders
 
@@ -350,6 +351,69 @@ short forms (a period after one it doesn't know ends a sentence, so "Sra.
 García" splits after "Sra."), and the next sentence has to start with `A` to
 `Z` or a digit.
 
+## The knowledge contract
+
+Signal answers questions about a business from what it has read: the
+passages of the site's live pages, and the business's own records in Sonor.
+The Sonor API tells Signal when either changes, and Signal indexes it. Both
+have to agree on which records count, how a stored row says which record it
+came from, and how big a page sync may be. If they don't, a record the API
+announces is refused, or a row Signal wrote reads as a page. Anything that
+shows what Signal has read, like the dashboard's view of it, reads stored
+addresses by the same rules.
+
+- **Record kinds.** `KNOWLEDGE_RECORD_KINDS` is `portfolio` (case studies),
+  `proof` (proof records), `faq` (managed FAQs), `review`, `article` and
+  `offering` (commerce offerings), in the order the dashboard lists them.
+  `isKnowledgeRecordKind(value)` is true only for one of them, spelled exactly.
+- **Addresses.** A record's knowledge is stored under `<kind>://<id>`, and
+  any further chunk under `<kind>://<id>#<anchor>` (an article indexed in full
+  is split by heading). `knowledgeRecordSourceUrl(kind, id, anchor?)` builds
+  one and `knowledgeRecordPrefix(kind)` gives the `<kind>://` every address of
+  that kind starts with. The id is the record's UUID, and the caller checks
+  it: one holding `#`, `?`, `/` or whitespace can't be read back. A page's
+  passages are stored under the page's https URL instead, so the scheme alone
+  tells a record's rows apart. The content type can't: an article's record
+  has the same type as the page passages beside it, because a live article is
+  a page on the site.
+- **Reading an address.** `knowledgeRecordKindOf(url)` is the kind by scheme
+  alone, or `null` for a page passage, an older page summary or a note. It's
+  the test for whether a row belongs to a record. `knowledgeRecordRefOf(url)`
+  is `{ kind, id }` for the record an address names, or `null` when it names
+  none; the id runs to the first `#`, `?`, `/` or whitespace. Both ignore the
+  scheme's case and surrounding whitespace.
+- **The legacy offering address.** Offerings were once stored under
+  `commerce://offering/<id>` (`legacyOfferingSourceUrl(id)`). Nothing writes
+  it now, and Signal switches each such row off the next time its offering
+  syncs. Until then `knowledgeRecordRefOf` names the offering, while
+  `knowledgeRecordKindOf` doesn't count the row as a record's.
+- **A page sync.** One call names at most `KNOWLEDGE_SYNC_MAX_PAGES` (500)
+  pages, each a `KnowledgePageChange` (`{ site?, path, removed? }`) with a
+  path of at most `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) characters and a
+  host of at most `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253). Signal refuses a
+  longer list, path or host outright, so a sender keeps within them before it
+  calls. Signal applies every removal in the call, then reads the changed
+  pages in the order given, as many as it reads in one call; the rest wait for
+  its nightly sweep. So put removals first, then the pages that matter most,
+  and cut the list after ordering it.
+
+```ts
+import {
+  KNOWLEDGE_SYNC_MAX_PAGES,
+  knowledgeRecordRefOf,
+  knowledgeRecordSourceUrl,
+} from '@sonordev/contracts/knowledge'
+
+knowledgeRecordSourceUrl('faq', id)
+// 'faq://<id>'
+
+knowledgeRecordRefOf('article://<id>#part-2')
+// { kind: 'article', id: '<id>' }
+
+const batch = [...removed, ...changed].slice(0, KNOWLEDGE_SYNC_MAX_PAGES)
+// removals first, so the cut drops changed pages before any removal
+```
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/knowledge.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Knowledge contract: which Sonor records Signal reads into a project's
+ * knowledge, the address each record's knowledge is stored under, and the
+ * limits of the call that tells Signal a site's pages changed. The Sonor API
+ * makes those calls and Signal answers them, so both import this as
+ * `@sonordev/contracts/knowledge` instead of keeping lists that drift apart.
+ * The dashboard, which shows the owner what Signal read, reads stored
+ * addresses by the same rules.
+ *
+ * A record's knowledge is stored under a URI built from its kind and id:
+ * `<kind>://<id>` for its first chunk and `<kind>://<id>#<anchor>` for any
+ * more (an article indexed in full, split by heading). The scheme is what
+ * tells a record's rows apart from a page's passages, which are stored under
+ * the page's https URL. The content type can't: an article's record has the
+ * same content type as the page passages beside it, because a live article is
+ * a page on the site.
+ */
+/**
+ * The kinds of Sonor record Signal indexes, in the order the dashboard lists
+ * them: case studies, proof records, managed FAQs, reviews, articles and
+ * commerce offerings. Each kind is also its URI scheme.
+ */
+export declare const KNOWLEDGE_RECORD_KINDS: readonly ["portfolio", "proof", "faq", "review", "article", "offering"];
+export type KnowledgeRecordKind = (typeof KNOWLEDGE_RECORD_KINDS)[number];
+/** True for one of KNOWLEDGE_RECORD_KINDS, spelled exactly (lowercase). */
+export declare function isKnowledgeRecordKind(value: unknown): value is KnowledgeRecordKind;
+/** `<kind>://`, the start every address of that kind shares, for prefix queries. */
+export declare function knowledgeRecordPrefix(kind: KnowledgeRecordKind): string;
+/**
+ * Where a record's knowledge is stored: `<kind>://<id>` for its first chunk,
+ * `<kind>://<id>#<anchor>` for a further one. `id` is the record's UUID, and
+ * checking it is the caller's job: an empty id, or one holding `#`, `?`, `/`
+ * or whitespace, builds an address knowledgeRecordRefOf can't read back.
+ */
+export declare function knowledgeRecordSourceUrl(kind: KnowledgeRecordKind, id: string, anchor?: string | null): string;
+/**
+ * The address an offering had before offerings were records of their own:
+ * `commerce://offering/<id>`. Nothing writes it any more. Signal switches the
+ * row off the next time that offering syncs, and a reader counts it as the
+ * offering until then (knowledgeRecordRefOf).
+ */
+export declare function legacyOfferingSourceUrl(id: string): string;
+/**
+ * The kind of record a stored address belongs to, by its scheme
+ * (`article://<id>#part-2` is 'article'), or null for anything else: a page
+ * passage, an older page summary, a note. Case doesn't matter and surrounding
+ * whitespace is ignored. This is the test for "is this row a record's": it
+ * reads only the scheme, so it doesn't need an id, and an offering's legacy
+ * address isn't a record row by it.
+ */
+export declare function knowledgeRecordKindOf(sourceUrl: string | null | undefined): KnowledgeRecordKind | null;
+/** The record a stored address names. */
+export interface KnowledgeRecordRef {
+    kind: KnowledgeRecordKind;
+    id: string;
+}
+/**
+ * The record a stored address names (`portfolio://<id>#part-2` is
+ * `{ kind: 'portfolio', id }`), or null when it names none. An offering's
+ * legacy address (`commerce://offering/<id>`) names that offering. Case
+ * doesn't matter in the scheme, surrounding whitespace is ignored, and the id
+ * keeps its own case.
+ */
+export declare function knowledgeRecordRefOf(sourceUrl: string | null | undefined): KnowledgeRecordRef | null;
+/**
+ * One page of a site in a page sync: it changed (Signal reads it live) or
+ * left the site (`removed`: Signal switches its passages off). Signal applies
+ * every removal in a call, then reads the changed pages in the order given,
+ * as many as it reads in one call; the rest wait for its nightly sweep. So a
+ * sender puts removals first, then the pages that matter most.
+ */
+export interface KnowledgePageChange {
+    /** The host as the project's pages store it; null or absent is the project's primary domain. */
+    site?: string | null;
+    /** The page's path, from "/". */
+    path: string;
+    removed?: boolean;
+}
+/** The most pages one page sync may name. Signal refuses a longer list outright, so cut the list after ordering it. */
+export declare const KNOWLEDGE_SYNC_MAX_PAGES = 500;
+/** The longest path a page sync may name, in characters. */
+export declare const KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+/** The longest host a page sync may name, in characters (a DNS name's limit). */
+export declare const KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;

package/dist/knowledge.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+exports.KNOWLEDGE_RECORD_KINDS = KNOWLEDGE_RECORD_KINDS;
+exports.KNOWLEDGE_SYNC_MAX_PAGES = KNOWLEDGE_SYNC_MAX_PAGES;
+exports.KNOWLEDGE_SYNC_PATH_MAX_LENGTH = KNOWLEDGE_SYNC_PATH_MAX_LENGTH;
+exports.KNOWLEDGE_SYNC_SITE_MAX_LENGTH = KNOWLEDGE_SYNC_SITE_MAX_LENGTH;
+exports.isKnowledgeRecordKind = isKnowledgeRecordKind;
+exports.knowledgeRecordKindOf = knowledgeRecordKindOf;
+exports.knowledgeRecordPrefix = knowledgeRecordPrefix;
+exports.knowledgeRecordRefOf = knowledgeRecordRefOf;
+exports.knowledgeRecordSourceUrl = knowledgeRecordSourceUrl;
+exports.legacyOfferingSourceUrl = legacyOfferingSourceUrl;

package/dist/knowledge.mjs

@@ -0,0 +1,37 @@
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+export { KNOWLEDGE_RECORD_KINDS, KNOWLEDGE_SYNC_MAX_PAGES, KNOWLEDGE_SYNC_PATH_MAX_LENGTH, KNOWLEDGE_SYNC_SITE_MAX_LENGTH, isKnowledgeRecordKind, knowledgeRecordKindOf, knowledgeRecordPrefix, knowledgeRecordRefOf, knowledgeRecordSourceUrl, legacyOfferingSourceUrl };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.5.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, and where prose splits into sentences. Pure functions, no dependencies.",
+  "version": "2.6.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, and which Sonor records Signal reads into a project's knowledge and the address each one is stored under. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -105,6 +105,11 @@
       "import": "./dist/sentences.mjs",
       "require": "./dist/sentences.js"
     },
+    "./knowledge": {
+      "types": "./dist/knowledge.d.ts",
+      "import": "./dist/knowledge.mjs",
+      "require": "./dist/knowledge.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {