@prenta/core 8.9.2 → 8.11.0

package/dist/ai/batch-links.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The batch AI `links` operation ("Add internal links"). For each document it
+ * ranks candidate pages with link embeddings, asks the text model to copy an
+ * anchor phrase for the closest ones from the document's body, and wraps the
+ * first fitting occurrence of each phrase in a link. CONFLICTS.md §4 (P-16,
+ * `links`) has the decisions.
+ *
+ * Links only go into rich text: top-level `richText` fields and the `richText`
+ * slots of visible sections, the HTML sinks that write-time sanitizing covers.
+ * A plain text field would show the markup as text, so it's never touched.
+ */
+import type { PrentaDB } from '../db/client-types.js';
+import { type BatchAiChange, type BatchAiItem, type BatchAiOptions, type BatchAiUsage } from './batch-list.js';
+/** The contract's name for the field a link changes: the kit's "Body links". */
+export declare const LINKS_FIELD = "body";
+/** About this many tokens per document: one embeddings call over the pool, one short text call. */
+export declare const LINK_TOKENS_PER_DOCUMENT = 2700;
+/** A page a document can link to. */
+export interface LinkTarget {
+    id: string;
+    title: string;
+    /** Public path, such as `/services/seo-audit`. */
+    path: string;
+    focusKeyword: string | null;
+    description: string;
+    /** Title, description and the start of the body, as plain text, for embedding. */
+    text: string;
+    updatedAt?: string | Date;
+}
+/** A link to put in a document's body: the first fitting `anchor` becomes a link to `href`. */
+interface BodyLink {
+    href: string;
+    anchor: string;
+}
+type LinkInsert = {
+    data: Record<string, unknown>;
+    patch: Record<string, unknown>;
+    /** The href put in: the page's path in the site's canonical form. */
+    href: string;
+    html: string;
+    index: number;
+    match: string;
+} | {
+    reason: 'already-linked' | 'not-found';
+};
+/** The `links` preset: a document with body text and fewer than 2 internal links in it. */
+export declare function needsBodyLinks(collection: string, data: unknown): boolean;
+/**
+ * Put one link in a document's rich text, as it is now. It's refused when the
+ * document already links to the page anywhere, in any spelling, or when the
+ * phrase has no occurrence outside a tag, an entity, a link, a heading, code, a
+ * button or a caption. With `before` (a review item's line), only the
+ * occurrence in that line will do, so the link lands where the item showed it.
+ * The href is written in the site's canonical form, the form the save keeps, so
+ * undo finds the same markup.
+ */
+export declare function insertBodyLink(collection: string, data: Record<string, unknown>, link: BodyLink, before?: string): LinkInsert;
+/**
+ * Take out a link this operation put in, keeping its text. The markup has to be
+ * as it was put in, an href to the same page in any spelling, around the same
+ * words. Null when it isn't there any more, because the link was edited or removed.
+ */
+export declare function removeBodyLink(collection: string, data: Record<string, unknown>, link: BodyLink): Record<string, unknown> | null;
+/** The link a review item suggests, read back from its `after`. */
+export declare function linkFromAfter(after: string): BodyLink | null;
+/**
+ * The link targets for a database, loaded at most once every
+ * {@link LINK_TARGETS_TTL_MS} and shared by worker ticks and previews, so a
+ * tick's first slice doesn't reload every page. A failed load is tried again.
+ * A page that goes away in between is caught when its link is applied.
+ */
+export declare function linkTargetLoader(db: PrentaDB): () => Promise<LinkTarget[]>;
+/**
+ * Whether a link's address is still a published page that search engines may
+ * index, so a link approved or applied later doesn't point at a page that was
+ * deleted, unpublished, hidden from search or moved since it was suggested.
+ */
+export declare function linkTargetLive(db: PrentaDB, href: string): Promise<boolean>;
+/**
+ * Suggest up to 3 internal links for one document without writing them, one
+ * change per link. Candidate pages leave out the document itself, pages it
+ * already links to, and pages a job suggested for it before. The closest ones
+ * by link embeddings go to the text model for anchors; its phrase is tried
+ * first, then the page's focus keyword, then its title.
+ */
+export declare function suggestBodyLinks(db: PrentaDB, item: BatchAiItem, options?: BatchAiOptions): Promise<{
+    changes: BatchAiChange[];
+    usage?: BatchAiUsage;
+}>;
+/**
+ * Suggest a document's links and write them in one save, so one revision.
+ * Each link is put in again, in its line, on the document as it is just before
+ * the save; one that no longer fits, or whose page isn't live at that address,
+ * is left out. The save is conditional on that read. If the document changed
+ * in between, it's read and the links are put in once more, so another save is
+ * never overwritten.
+ */
+export declare function applyBodyLinks(db: PrentaDB, item: BatchAiItem, options?: BatchAiOptions & {
+    write?: (patch: Record<string, unknown>, expectedUpdatedAt?: Date) => Promise<void>;
+}): Promise<{
+    updated: boolean;
+    usage?: BatchAiUsage;
+}>;
+export {};
+//# sourceMappingURL=batch-links.d.ts.map

package/dist/ai/batch-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-links.d.ts","sourceRoot":"","sources":["../../src/ai/batch-links.ts"],"names":[],"mappings":"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"}