@hollware/server 0.4.0 → 0.5.0

package/dist/{ceremonies-V_1BbmZQ.mjs → ceremonies-BM9G03lZ.mjs}

@@ -1,4 +1,4 @@
-import { a as findInvitation, c as invitationById, d as redeemInvitation, f as saveChallenge, h as userHandle, i as createUser, m as touchPasskey, o as findPasskey, p as takeChallenge, r as createSession, t as addPasskey, u as passkeysOf } from "./store-CsuER6J7.mjs";
+import { a as findInvitation, c as invitationById, d as redeemInvitation, f as saveChallenge, h as userHandle, i as createUser, m as touchPasskey, o as findPasskey, p as takeChallenge, r as createSession, t as addPasskey, u as passkeysOf } from "./store-DiS8UFI2.mjs";
 import { HollwareError, newId } from "@hollware/core";
 import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
 import { isoBase64URL } from "@simplewebauthn/server/helpers";

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries } from "@hollware/core";
+import { AcknowledgedWarning, EntryDocument, EntryLookup, EntryRef, HollwareConfig, OperationByName, OperationName, ResolvedSite, Scope, Verdict, describeSite, getEntry, getTranslations, listEntries, search } from "@hollware/core";
 import * as z from "zod";
 import { WorkerEntrypoint } from "cloudflare:workers";
 //#region src/ports.d.ts
@@ -102,6 +102,27 @@ interface ListQuery {
   /** The `nextCursor` of the previous page. */
   readonly cursor?: string;
 }
+/** A full-text search of the published entries of a site. */
+interface SearchQuery {
+  /** What the person or the agent typed: its words are matched, its punctuation is not. */
+  readonly text: string;
+  readonly collection?: string;
+  readonly locale?: string;
+  readonly limit: number;
+}
+/** An entry that a search found, best first. */
+interface SearchHit {
+  readonly entry: EntrySummaryView;
+  /** The words around the match in the text, the match between `[` and `]`. */
+  readonly snippet: string;
+  /** How well it matches: higher is better. */
+  readonly score: number;
+}
+/** An entry close to another by meaning, and how close: higher is closer. */
+interface RelatedEntry {
+  readonly id: string;
+  readonly score: number;
+}
 /** The answer to a write that the store could not make. */
 type WriteRefusal = {
   readonly outcome: 'conflict';
@@ -179,6 +200,15 @@ interface ContentStore {
     readonly entries: readonly EntrySummaryView[];
     readonly nextCursor: string | null;
   }>;
+  /**
+   * The published entries whose title, tags or text hold every word of the query, best first:
+   * the title weighs most, then the tags, then the text (bm25).
+   */
+  searchEntries(site: string, query: SearchQuery): Promise<readonly SearchHit[]>;
+  /** The entries of those ids that the view has, in the order of the ids. */
+  findSummaries(site: string, ids: readonly string[], view: View): Promise<readonly EntrySummaryView[]>;
+  /** The entries closest to one by meaning, closest first (ADR-030); `[]` when it has no vectors. */
+  relatedOf(site: string, entryId: string): Promise<readonly RelatedEntry[]>;
   /** The entries of a translation group, one per locale, in the given view. */
   listTranslations(site: string, collection: string, translationGroup: string, view: View): Promise<readonly EntrySummaryView[]>;
   /** What cross-entry contracts read, scoped to the site. */
@@ -290,6 +320,83 @@ interface ContentStore {
 interface Clock {
   now(): Date;
 }
+/** Turns texts into vectors, all of the same length. */
+interface Embedder {
+  /** The model, which the stored vectors name: another model makes them stale. */
+  readonly model: string;
+  embed(texts: readonly string[]): Promise<number[][]>;
+}
+/** What a vector says about where it comes from, to filter and to read a match back. */
+interface VectorMetadata {
+  readonly site: string;
+  readonly entry: string;
+  readonly collection: string;
+  readonly locale: string;
+  /** The piece of the entry: 0 for its summary. */
+  readonly piece: number;
+  /** The start of the piece's text, for the snippet of a match. */
+  readonly excerpt: string;
+}
+interface StoredVector {
+  /** `<entry id>:<piece>`. */
+  readonly id: string;
+  readonly values: readonly number[];
+  readonly metadata: VectorMetadata;
+}
+interface VectorMatch {
+  readonly id: string;
+  /** How close: higher is closer. */
+  readonly score: number;
+  readonly metadata: VectorMetadata;
+}
+interface VectorIndex {
+  upsert(vectors: readonly StoredVector[]): Promise<void>;
+  remove(ids: readonly string[]): Promise<void>;
+  /** The stored values of those vectors; an id the index does not have is left out. */
+  get(ids: readonly string[]): Promise<readonly {
+    readonly id: string;
+    readonly values: readonly number[];
+  }[]>;
+  /** The `topK` vectors nearest to `values` among those of the site, narrowed as asked. */
+  query(values: readonly number[], options: {
+    readonly topK: number;
+    readonly site: string;
+    readonly collection?: string;
+    readonly locale?: string;
+    /** Only the summaries, one vector per entry. */
+    readonly summariesOnly?: boolean;
+  }): Promise<readonly VectorMatch[]>;
+}
+/** What semantic search needs: both services, or the deployment has none. */
+interface Semantic {
+  readonly embedder: Embedder;
+  readonly index: VectorIndex;
+}
+/** A page view, as a site's beacon reports it. */
+interface PageView {
+  readonly site: string;
+  /** The path of the page, such as `/blog/edge-caching/`. */
+  readonly path: string;
+  /** The two letters of the reader's country, or `XX` when it is not known. */
+  readonly country: string;
+}
+/** Where page views are counted. */
+interface AnalyticsWriter {
+  record(view: PageView): void;
+}
+/** A page and how often it was read. */
+interface PageCount {
+  readonly path: string;
+  readonly views: number;
+}
+/** Reads the counts back. */
+interface AnalyticsReader {
+  /** The `limit` most read paths of the site in the last `days`, most read first. */
+  topPages(site: string, query: {
+    readonly days: number;
+    readonly limit: number;
+  }): Promise<readonly PageCount[]>;
+}
 //#endregion
 //#region src/events/run.d.ts
 /** A message of the events Queue: the site and the id of an outbox row. */
@@ -371,6 +478,10 @@ interface OperationContext {
    * the Queue now rather than at the next sweep of the cron trigger (ADR-025). Absent in tests.
    */
   readonly notify?: (eventIds: readonly string[]) => void;
+  /** The model and the vector index, when the Worker has both (ADR-030); absent or `null` without. */
+  readonly semantic?: Semantic | null;
+  /** The counts of page views, when the deployment can read them (ADR-031); absent or `null` without. */
+  readonly analytics?: AnalyticsReader | null;
 }
 /** The handler of one operation: its parsed input in, its output out. */
 type OperationHandler<Name extends OperationName> = (input: z.output<OperationByName<Name>['input']>, context: OperationContext) => Promise<z.output<OperationByName<Name>['output']>>;
@@ -418,6 +529,24 @@ export interface HollwareEnv {
   readonly ASSETS?: Fetcher;
   /** The Queue of publication events (ADR-025); without it, the cron trigger delivers them. */
   readonly EVENTS?: EventQueue;
+  /**
+   * Workers AI and a Vectorize index (v0.5): with both, every published entry is embedded and
+   * `search` can be semantic; without either, search is full text only.
+   */
+  readonly AI?: Ai;
+  /** `wrangler types` names a Vectorize binding `VectorizeIndex`; either works. */
+  readonly VECTORIZE?: Vectorize | VectorizeIndex;
+  /** The embedding model of Workers AI, `@cf/baai/bge-m3` when not set; its index must match it. */
+  readonly HOLLWARE_EMBEDDING_MODEL?: string;
+  /**
+   * Analytics (ADR-031): the Analytics Engine dataset that the beacon of the sites writes to, and
+   * what `content_stats` reads it with: the account, an API token with Account Analytics Read
+   * (a secret), and the dataset's name when it is not `hollware_page_views`.
+   */
+  readonly ANALYTICS?: AnalyticsEngineDataset;
+  readonly HOLLWARE_ANALYTICS_ACCOUNT_ID?: string;
+  readonly HOLLWARE_ANALYTICS_TOKEN?: string;
+  readonly HOLLWARE_ANALYTICS_DATASET?: string;
 }
 type Output<Spec extends {
   output: z.ZodType;
@@ -429,6 +558,8 @@ type Output<Spec extends {
 export interface HollwareRpc {
   getEntry(site: string, collection: string, slug: string, locale: string, options?: {
     readonly formats?: readonly ('markdown' | 'document' | 'html')[];
+    /** Also the published entries closest by meaning (ADR-030). */
+    readonly related?: boolean;
   }): Promise<Output<typeof getEntry>>;
   listEntries(site: string, collection: string, options?: {
     readonly locale?: string;
@@ -438,6 +569,13 @@ export interface HollwareRpc {
   }): Promise<Output<typeof listEntries>>;
   getTranslations(site: string, collection: string, translationGroup: string): Promise<Output<typeof getTranslations>>;
   describeSite(site: string): Promise<Output<typeof describeSite>>;
+  /** The published entries that match `query`, best first: by its words, by meaning, or both. */
+  search(site: string, query: string, options?: {
+    readonly collection?: string;
+    readonly locale?: string;
+    readonly limit?: number;
+    readonly mode?: 'fulltext' | 'semantic' | 'hybrid';
+  }): Promise<Output<typeof search>>;
 }
 /**
  * What `createHollware(config)` returns. The user's Worker is
@@ -464,4 +602,4 @@ export type CreateHollware = (config: HollwareConfig) => HollwareWorker;
  */
 export declare const createHollware: CreateHollware;
 //#endregion
-export type { Actor, Clock, ContentStore, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, Principal, PublishWrite, ReviewStatus, RevisionSummary, StoredEntry, StoredPublication, StoredReview, StoredRevision, StoredSchedule, View, WriteRefusal };
+export type { Actor, AnalyticsReader, AnalyticsWriter, Clock, ContentStore, Embedder, EntrySummaryView, EntryView, EventMessage, Handlers, ListQuery, NewRevision, OperationContext, OperationHandler, OutboxEvent, PageCount, PageView, Principal, PublishWrite, RelatedEntry, ReviewStatus, RevisionSummary, SearchHit, SearchQuery, Semantic, StoredEntry, StoredPublication, StoredReview, StoredRevision, StoredSchedule, StoredVector, VectorIndex, VectorMatch, VectorMetadata, View, WriteRefusal };