@beechcms/api 0.6.7 → 0.8.0

package/dist/features/oauth/revoke.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from 'hono';
+import type { Env, Variables } from '../../types';
+/** Context type alias for OAuth route handlers. */
+type OAuthContext = Context<{
+    Bindings: Env;
+    Variables: Variables;
+}>;
+/**
+ * `POST /oauth/revoke`
+ *
+ * Token revocation endpoint complying with RFC 7009.
+ * Allows a client to invalidate an active access or refresh token.
+ *
+ * Behavior and RFC 7009 conformance:
+ * 1. Rate limiting is applied per client IP using the `oauthToken` limiter.
+ * 2. Requires `token` and `client_id` in url-encoded form body (returns HTTP 400 if missing).
+ * 3. Supports optional `token_type_hint` ('access_token' or 'refresh_token') to optimize lookup order.
+ * 4. Hash lookup: Searches for an active token matching `sha256hex(token)`.
+ * 5. **Token Family Revocation**: If found and the token's `clientId` matches the caller,
+ *    revokes the entire token family via `authorizationCodeHash` (revoking an access token
+ *    revokes its sibling refresh token, and vice-versa).
+ * 6. **Always returns HTTP 200 `{}`** unless the request syntax is malformed (RFC 7009 §2.2),
+ *    preventing token enumeration and leaking token existence or state to unauthorized parties.
+ *
+ * @param context - Hono request context.
+ * @returns HTTP 200 `{}` on success, 400 on malformed syntax, or 429 when rate limited.
+ */
+export declare function revokeHandler(context: OAuthContext): Promise<Response>;
+export {};

package/dist/features/oauth/token-issuance.d.ts

@@ -0,0 +1,49 @@
+import { type IIdGenerator, type IOAuthTokenRepository, type OAuthScope } from '@beechcms/core';
+/**
+ * Input arguments for generating and storing an access/refresh token pair.
+ */
+export interface IssueTokenPairInput {
+    /** Repository for persisting OAuth token records. */
+    tokenRepository: IOAuthTokenRepository;
+    /** Service for generating unique UUIDs for token records. */
+    idGenerator: IIdGenerator;
+    /** The client identifier receiving the token pair. */
+    clientId: string;
+    /** The user/resource owner identifier who authorized the grant. */
+    userId: string;
+    /** The granted OAuth scopes bound to these tokens. */
+    scope: OAuthScope[];
+    /** SHA-256 hash of the root authorization code from which this token family descends. */
+    authorizationCodeHash: string;
+    /** Current Unix epoch timestamp in seconds. */
+    nowSeconds: number;
+}
+/**
+ * Result of issuing an access/refresh token pair.
+ */
+export interface IssuedTokenPair {
+    /** Plaintext opaque access token returned to the client. */
+    accessToken: string;
+    /** SHA-256 digest of the access token stored in the database. */
+    accessTokenHash: string;
+    /** Plaintext opaque refresh token returned to the client. */
+    refreshToken: string;
+    /** SHA-256 digest of the refresh token stored in the database. */
+    refreshTokenHash: string;
+    /** Access token lifetime in seconds. */
+    expiresIn: number;
+}
+/**
+ * Generates and persists an access/refresh token pair for an authorized client.
+ *
+ * Security guarantees:
+ * - Plaintext tokens are generated via CSPRNG (`generateOpaqueToken`).
+ * - Only SHA-256 hashes (`tokenHash`) reach D1 persistence; plaintext tokens are
+ *   never stored in the database.
+ * - Both tokens share the same `authorizationCodeHash` to link the token family
+ *   for atomic revocation and replay attack mitigation.
+ *
+ * @param input - The token issuance dependencies and subject parameters.
+ * @returns The issued token pair, hashes, and access token expiration.
+ */
+export declare function issueTokenPair(input: IssueTokenPairInput): Promise<IssuedTokenPair>;

package/dist/features/oauth/token.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from 'hono';
+import type { Env, Variables } from '../../types';
+/** Context type alias for OAuth route handlers. */
+type OAuthContext = Context<{
+    Bindings: Env;
+    Variables: Variables;
+}>;
+/**
+ * Successful token response body adhering to RFC 6749 §5.1.
+ */
+export interface TokenResponseBody {
+    /** The issued access token string. */
+    access_token: string;
+    /** Fixed Bearer token type identifier. */
+    token_type: 'Bearer';
+    /** The lifetime in seconds of the access token (e.g. 900). */
+    expires_in: number;
+    /** The issued refresh token string used to obtain new access tokens. */
+    refresh_token: string;
+    /** Space-separated list of scopes granted to this token. */
+    scope: string;
+}
+/**
+ * `POST /oauth/token`
+ *
+ * Client-facing token endpoint (RFC 6749 §3.2). Unauthenticated by user session;
+ * authenticated by the grant parameters themselves (authorization code + PKCE verifier, or refresh token).
+ *
+ * Protections:
+ * - Dual-key rate limiting (per client IP and per `client_id` account key).
+ * - Supported grants: `authorization_code` and `refresh_token`.
+ * - Strictly sets `Cache-Control: no-store, Pragma: no-cache`.
+ *
+ * @param context - Hono request context.
+ * @returns HTTP response with token payload, RFC error object, or rate limit notification.
+ */
+export declare function tokenHandler(context: OAuthContext): Promise<Response>;
+export {};

package/dist/features/search/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @module search/constants
+ * Error messages and validation limits for the search feature slice.
+ * All user-facing strings are centralised here to keep handlers free of literals.
+ */
+/** Validation and error messages returned by search route handlers. */
+export declare const SEARCH_ERRORS: {
+    /** The `q` query parameter is absent or empty. */
+    readonly QUERY_REQUIRED: "Parametro 'q' obbligatorio.";
+    /** The `q` query parameter is shorter than the minimum allowed length. */
+    readonly QUERY_TOO_SHORT: "Il parametro 'q' deve avere almeno 2 caratteri.";
+    /** The `q` query parameter exceeds the maximum allowed length. */
+    readonly QUERY_TOO_LONG: "Il parametro 'q' supera la lunghezza massima di 150 caratteri.";
+    /** The request was blocked by the rate limiter. */
+    readonly RATE_LIMIT_EXCEEDED: "Too Many Requests";
+    /** The Cloudflare Workers AI binding is not configured. */
+    readonly AI_BINDING_UNAVAILABLE: "AI binding not available.";
+    /** The AI model returned an unrecognisable response shape. */
+    readonly EMBEDDING_GENERATION_FAILED: "Failed to generate embedding.";
+};
+/** Validation limits applied to search query parameters. */
+export declare const SEARCH_LIMITS: {
+    /** Minimum number of characters required in the `q` parameter for FTS search. */
+    readonly QUERY_MIN_LENGTH: 2;
+    /** Maximum number of characters allowed in the `q` parameter for embed requests. */
+    readonly EMBED_QUERY_MAX_LENGTH: 150;
+    /** Default number of results returned per page when no `limit` parameter is provided. */
+    readonly DEFAULT_PAGE_SIZE: 20;
+    /** Maximum number of results that can be requested in a single page. */
+    readonly MAX_PAGE_SIZE: 50;
+    /** Minimum number of results that can be requested in a single page. */
+    readonly MIN_PAGE_SIZE: 1;
+    /** Minimum number of characters a single FTS term must have to be included in the match expression. */
+    readonly FTS_TERM_MIN_LENGTH: 2;
+    /** Minimum prefix length used when expanding a term into prefix tokens. */
+    readonly FTS_PREFIX_MIN_LENGTH: 3;
+    /** Maximum number of seconds the embed response is cached on the CDN edge. */
+    readonly EMBED_CACHE_MAX_AGE_SECONDS: 604800;
+};
+/** Worker AI model identifier used to generate text embeddings. */
+export declare const EMBEDDING_MODEL: "@cf/baai/bge-small-en-v1.5";
+/** Rate limiter key used for the public embed endpoint. */
+export declare const EMBED_RATE_LIMITER_KEY: "publicApiRead";

package/dist/features/search/handlers/embed.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module search/handlers/embed
+ * Thin route handler for `GET /api/v1/public/search/embed`.
+ *
+ * Generates a text embedding vector for the provided query string using
+ * the Cloudflare Workers AI binding. The vector is returned as a flat
+ * array of 32-bit floats and is aggressively cached at the CDN edge.
+ *
+ * Responsibilities:
+ * - Validate the `q` query parameter.
+ * - Apply per-IP rate limiting via the injected `rateLimiters` registry.
+ * - Call the Workers AI model and normalise its response into a Float32Array.
+ * - Set cache headers and return the embedding.
+ */
+import type { Context } from 'hono';
+import type { AppEnv } from '../../../types';
+/**
+ * Handles `GET /api/v1/public/search/embed?q=…`.
+ *
+ * Query parameters:
+ * - `q` / `query` / `text` – Query string to embed (required, ≤ 150 characters).
+ *   The first non-empty value among the three aliases is used.
+ *
+ * Response headers:
+ * - `Cache-Control: public, max-age=604800`
+ * - `Edge-Control: s-maxage=604800`
+ *
+ * @param c - Hono context with typed `AppEnv` bindings and variables.
+ * @returns A JSON {@link EmbedResponse} containing the embedding vector.
+ */
+export declare function embedHandler(c: Context<AppEnv>): Promise<Response>;

package/dist/features/search/handlers/full-text-search.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @module search/handlers/full-text-search
+ * Thin route handler for `GET /api/search`.
+ *
+ * Responsibilities:
+ * - Parse and validate query parameters.
+ * - Delegate the data fetch and count to the injected `searchRepository`.
+ * - Assemble and return the paginated {@link SearchResponse}.
+ *
+ * The handler intentionally contains no SQL — all data access is performed
+ * through the `searchRepository` injected by `repositoryMiddleware`.
+ */
+import type { Context } from 'hono';
+import type { AppEnv } from '../../../types';
+/**
+ * Handles `GET /api/search?q=…&schema_slug=…&status=…&limit=20&cursor=…`.
+ *
+ * Query parameters:
+ * - `q`           – Full-text search term (required, ≥ 2 characters).
+ * - `schema_slug` – Restrict results to a single seed slug (optional).
+ * - `status`      – Restrict results by publication status (optional).
+ * - `limit`       – Number of results per page, clamped to `[1, 50]` (default: 20).
+ * - `cursor`      – Opaque pagination cursor from a previous response (optional).
+ *
+ * @param c - Hono context with typed `AppEnv` bindings and variables.
+ * @returns A JSON {@link SearchResponse} with items, nextCursor, and total.
+ */
+export declare function fullTextSearchHandler(c: Context<AppEnv>): Promise<Response>;

package/dist/features/search/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module search
+ * Public barrel for the search vertical slice.
+ *
+ * External code (e.g. `factory.ts`) **must** import exclusively from this file.
+ * Internal directories (`handlers/`, `constants.ts`, `types.ts`, `search-utils.ts`)
+ * are slice-private and must not be imported from outside this feature.
+ *
+ * Exports:
+ * - {@link searchRouter}        – Authenticated FTS Hono sub-app (`/api/search`).
+ * - {@link publicSearchRouter}  – Public embedding Hono sub-app (`/api/v1/public/search`).
+ * - {@link semanticSearchHooks} – Content lifecycle hooks for vector index maintenance.
+ * - {@link semanticSearchJobs}  – Background job registry for vector computation.
+ * - {@link compileR2Manifest}   – Utility to manually trigger R2 manifest recompilation.
+ */
+export { searchRouter } from './search';
+export { publicSearchRouter } from './public-search.router';
+export { semanticSearchHooks } from './jobs/semantic-search.hooks';
+export { semanticSearchJobs, compileR2Manifest, computeVectorJob, deleteVectorJob, updateR2ManifestJob, type ComputeVectorPayload, type UpdateR2ManifestPayload, } from './jobs/semantic-search.worker';
+export type { SearchResultItem, SearchResponse, FtsQueryParams, EmbedResponse, } from './types';

package/dist/features/search/jobs/semantic-search.hooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module search/semantic-search.hooks
+ * Lifecycle hooks that keep the semantic search index in sync with content changes.
+ *
+ * Each hook is registered on the `BeechHooks` object consumed by the content
+ * repository. Hooks use the queue service to dispatch async jobs so they
+ * never block the HTTP response.
+ *
+ * Job names match the keys registered in {@link semanticSearchJobs}:
+ * - `compute_vector`    – generate/refresh the embedding for a published entry.
+ * - `update_r2_manifest` – recompile the R2 binary manifest after a deletion.
+ */
+import type { BeechHooks } from '@beechcms/core';
+/**
+ * Lifecycle hooks that maintain the semantic search vector index.
+ *
+ * Registered via `BeechConfig.hooks` in the application factory. All async
+ * side-effects are dispatched through the queue so they never block the
+ * HTTP response path.
+ */
+export declare const semanticSearchHooks: BeechHooks;

package/dist/features/search/jobs/semantic-search.worker.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module search/semantic-search.worker
+ * Background job handlers for semantic (vector) search indexing.
+ *
+ * Jobs are dispatched by {@link semanticSearchHooks} via the queue service
+ * and consumed by the Cloudflare Queue worker export.
+ *
+ * Exported jobs:
+ * - {@link computeVectorJob}    – Generate an embedding and persist it to D1, then compile R2.
+ * - {@link updateR2ManifestJob} – Recompile R2 binary manifest without touching embeddings.
+ *
+ * Exported registry:
+ * - {@link semanticSearchJobs}  – `JobRegistry` map passed to `BeechConfig.jobs`.
+ */
+import type { JobHandler, JobRegistry, Seed } from '@beechcms/core';
+/**
+ * Payload for the `compute_vector` job.
+ * Enqueued by {@link semanticSearchHooks.afterCreate} and {@link semanticSearchHooks.afterUpdate}.
+ */
+export interface ComputeVectorPayload {
+    /** Slug of the seed (content type) the entry belongs to. */
+    seedSlug: string;
+    /** Unique identifier of the entry whose embedding should be computed. */
+    entryId: string;
+}
+/**
+ * Payload for the `update_r2_manifest` job.
+ * Enqueued by {@link semanticSearchHooks.afterUpdate} and {@link semanticSearchHooks.afterDelete}.
+ */
+export interface UpdateR2ManifestPayload {
+    /** Slug of the seed whose R2 manifest files should be recompiled. */
+    seedSlug: string;
+}
+/**
+ * Compiles all stored vectors for a seed into binary and JSON manifest files
+ * and writes them to the `SEARCH_R2` bucket.
+ *
+ * The two files produced per seed are:
+ * - `{slug}.bin`  – Concatenated `Float32Array` buffers in entry-index order.
+ * - `{slug}.json` – JSON array of entry IDs in the same order as the binary file.
+ *
+ * These files are consumed by the client-side semantic search runtime to perform
+ * in-memory cosine-similarity ranking without a Vectorize index.
+ *
+ * When `searchR2` is `undefined` (e.g. in local development without an R2
+ * binding), the function returns immediately without writing anything.
+ *
+ * @param seed     - Seed whose vectors should be compiled.
+ * @param db       - D1 database instance used to load stored vectors.
+ * @param searchR2 - R2 bucket to write the manifest files to, or `undefined` to skip.
+ */
+export declare function compileR2Manifest(seed: Seed, db: D1Database, searchR2?: R2Bucket): Promise<void>;
+/**
+ * Worker job that generates the embedding vector for a content entry,
+ * persists it to D1, and recompiles the R2 manifest files.
+ *
+ * The job is a no-op (with a warning log) when:
+ * - The `DB` binding is missing.
+ * - The seed cannot be found.
+ * - The seed has no indexable branches.
+ * - The entry does not exist or is not published — in which case any
+ *   existing vector is deleted and the manifest is recompiled.
+ * - The entry has no indexable text content.
+ * - The `AI` binding is missing.
+ *
+ * @param payload - `{ seedSlug, entryId }` identifying the entry to vectorise.
+ * @param context - Job execution context providing repository and env bindings.
+ */
+export declare const computeVectorJob: JobHandler<ComputeVectorPayload>;
+/**
+ * Worker job that removes an embedding vector from D1 for a specific entry
+ * and recompiles the R2 binary and JSON manifest files.
+ *
+ * Enqueued when an entry is unpublished or deleted.
+ *
+ * @param payload - `{ seedSlug, entryId }` identifying the entry whose vector should be removed.
+ * @param context - Job execution context providing env bindings.
+ */
+export declare const deleteVectorJob: JobHandler<ComputeVectorPayload>;
+/**
+ * Worker job that recompiles the R2 binary and JSON manifest files for a seed
+ * without touching the stored embedding vectors.
+ *
+ * Enqueued after a vector is deleted (entry unpublished or deleted) to keep
+ * the R2 manifests consistent with the D1 vector store.
+ *
+ * @param payload - `{ seedSlug }` identifying the seed to recompile.
+ * @param context - Job execution context providing env bindings.
+ */
+export declare const updateR2ManifestJob: JobHandler<UpdateR2ManifestPayload>;
+/**
+ * Job registry for semantic search background jobs.
+ * Pass this to `BeechConfig.jobs` (or merge it with other job registries)
+ * to enable semantic indexing in your deployment.
+ *
+ * @example
+ * ```ts
+ * createBeechApp({ jobs: semanticSearchJobs, ... })
+ * ```
+ */
+export declare const semanticSearchJobs: JobRegistry;

package/dist/features/search/public-search.router.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module search/public-search.router
+ * Public (unauthenticated) search Hono sub-app.
+ *
+ * Mounted under the public API prefix in `factory.ts`.
+ * Authentication is handled upstream via API-key middleware; individual
+ * endpoints apply per-IP rate limiting through the injected `rateLimiters`.
+ *
+ * Routes:
+ * - `GET /embed` → {@link embedHandler}
+ */
+import { Hono } from 'hono';
+import type { AppEnv } from '../../types';
+/** Hono sub-app for the public search endpoints (embedding generation). */
+export declare const publicSearchRouter: Hono<AppEnv, import("hono/types").BlankSchema, "/">;

package/dist/features/search/search.d.ts

@@ -1,6 +1,14 @@
-import { Hono } from "hono";
-import type { Env, Variables } from "../../types";
-export declare const searchRouter: Hono<{
-    Bindings: Env;
-    Variables: Variables;
-}, import("hono/types").BlankSchema, "/">;
+/**
+ * @module search/search
+ * Authenticated full-text search Hono sub-app.
+ *
+ * Mounted at `/api/search` in `factory.ts`.
+ * Requires a valid JWT — auth is enforced via `authMiddleware`.
+ *
+ * Routes:
+ * - `GET /` → {@link fullTextSearchHandler}
+ */
+import { Hono } from 'hono';
+import type { AppEnv } from '../../types';
+/** Hono sub-app for the authenticated full-text search endpoint. */
+export declare const searchRouter: Hono<AppEnv, import("hono/types").BlankSchema, "/">;

package/dist/features/search/semantic-search.hooks.d.ts

@@ -0,0 +1,2 @@
+import type { BeechHooks } from '@beechcms/core';
+export declare const semanticSearchHooks: BeechHooks;

package/dist/features/search/semantic-search.worker.d.ts

@@ -0,0 +1,21 @@
+import type { JobHandler, JobRegistry, Seed } from '@beechcms/core';
+export interface ComputeVectorPayload {
+    seedSlug: string;
+    entryId: string;
+}
+export interface UpdateR2ManifestPayload {
+    seedSlug: string;
+}
+/**
+ * Compiles all vectors for a seed into binary Float32Array and JSON manifest on R2.
+ */
+export declare function compileManifest(seed: Seed, db: D1Database, searchR2?: R2Bucket): Promise<void>;
+/**
+ * Worker job to compute the embedding vector for an entry, save it in D1, and compile R2 manifests.
+ */
+export declare const computeVectorJob: JobHandler<ComputeVectorPayload>;
+/**
+ * Worker job to recompile the R2 manifest files for a seed.
+ */
+export declare const updateR2ManifestJob: JobHandler<UpdateR2ManifestPayload>;
+export declare const semanticSearchJobs: JobRegistry;

package/dist/features/search/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @module search/types
+ * Feature-scoped TypeScript types for the search vertical slice.
+ * Kept separate from `search-utils.ts` so utilities stay importable without
+ * dragging in HTTP-layer concerns, and to align with the VSA type file convention.
+ */
+import type { SearchResultRow } from '@beechcms/core';
+/**
+ * Raw database row returned by the UNION ALL FTS query.
+ * Field names use snake_case to match SQLite column aliases verbatim.
+ */
+export interface FtsRow {
+    /** Unique identifier of the matching content entry. */
+    entry_id: string;
+    /** Slug of the seed (content type) the entry belongs to. */
+    schema_slug: string;
+    /** URL-friendly slug of the entry, if set. */
+    slug: string | null;
+    /** Publication status of the entry (e.g. `published`, `draft`). */
+    status: string;
+    /** Display title of the entry, sourced from the seed's `displayNameAlias` column. */
+    title: string | null;
+    /** HTML snippet produced by SQLite's `snippet()` function highlighting matched terms. */
+    excerpt: string;
+    /** BM25 relevance score; lower (more negative) means more relevant. */
+    rank: number;
+}
+/**
+ * A single search result item returned to the API consumer.
+ * HTML tags are stripped from the excerpt except for `<mark>` highlighting wrappers.
+ */
+export interface SearchResultItem {
+    /** Unique identifier of the matching content entry. */
+    id: string;
+    /** Slug of the seed (content type) the entry belongs to. */
+    schema_slug: string;
+    /** URL-friendly slug of the entry, if set. */
+    slug: string | null;
+    /** Publication status of the entry. */
+    status: string;
+    /** Display title of the entry; empty string when the entry has no title. */
+    title: string;
+    /** Plain-text excerpt with `<mark>…</mark>` wrappers around matched terms. */
+    excerpt: string;
+    /**
+     * Additional entry fields.
+     * Currently always `{}` — reserved for future field projection support.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * Paginated response envelope returned by `GET /api/search`.
+ */
+export interface SearchResponse {
+    /** Matched entries for the current page. */
+    items: SearchResultItem[];
+    /**
+     * Opaque cursor for the next page, or `null` when there are no more results.
+     * Pass as the `cursor` query parameter on the next request.
+     */
+    nextCursor: string | null;
+    /** Total number of matching entries across all pages. */
+    total: number;
+}
+/**
+ * Normalised, validated query parameters consumed by {@link buildFtsQuery}.
+ * The handler clamps `pageSize` before passing it here; this type assumes
+ * all values are already within their valid ranges.
+ */
+export interface FtsQueryParams {
+    /** Full-text search term entered by the user; must be ≥ 2 characters. */
+    queryText: string;
+    /**
+     * When set, restricts the search to entries belonging to this seed slug.
+     * `null` searches across all searchable seeds.
+     */
+    schemaSlug: string | null;
+    /**
+     * When set, adds a `status = ?` filter to each per-seed sub-query.
+     * `null` returns entries in any status.
+     */
+    statusFilter: string | null;
+    /** Maximum entries to return, already clamped to `[1, 50]` by the handler. */
+    pageSize: number;
+    /**
+     * Opaque pagination cursor produced by {@link encodeCursor}.
+     * `null` starts from the first page.
+     */
+    cursor: string | null;
+}
+/**
+ * Response body returned by `GET /api/v1/public/search/embed`.
+ */
+export interface EmbedResponse {
+    /** Flat array of 32-bit floats representing the embedding vector. */
+    data: number[];
+    /** Tuple describing the shape of the vector, e.g. `[384]`. */
+    shape: [number];
+}
+export type { SearchResultRow };

package/dist/features/search/utils/search-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module search/search-utils
+ * Pure utility functions for the search feature slice.
+ *
+ * Zero Hono dependencies — fully importable from Vitest without a running worker.
+ * FTS is per-seed (`fts_{slug}`), joined with `content_{slug}` for metadata.
+ */
+import type { FtsRow, FtsQueryParams, SearchResultItem } from '../types';
+export type { FtsRow, FtsQueryParams, SearchResultItem };
+/**
+ * Encodes a BM25 rank and an entry ID into an opaque, URL-safe pagination cursor.
+ *
+ * The cursor is base64-encoded so it can be passed safely as a query parameter.
+ * Use {@link decodeCursor} to reverse the operation.
+ *
+ * @param rank    - BM25 relevance score of the last row on the current page.
+ * @param entryId - Unique identifier of the last row on the current page.
+ * @returns An opaque base64 string suitable for the `cursor` query parameter.
+ */
+export declare function encodeCursor(rank: number, entryId: string): string;
+/**
+ * Decodes a pagination cursor produced by {@link encodeCursor}.
+ *
+ * Returns `null` when the input is not valid base64 or does not contain
+ * the expected `rank:entryId` separator, so callers can safely ignore
+ * malformed cursors without throwing.
+ *
+ * @param cursor - Opaque cursor string from a previous search response.
+ * @returns Parsed `{ rank, entryId }` or `null` if the cursor is invalid.
+ */
+export declare function decodeCursor(cursor: string): {
+    rank: number;
+    entryId: string;
+} | null;
+export { buildFtsQuery, type FtsQueryResult, type FtsQueryParams as RepositoryFtsQueryParams, } from '../../../shared/db/repositories/d1-search.query';
+/**
+ * Maps a raw database {@link FtsRow} (snake_case) to the wire-format
+ * {@link SearchResultItem} returned to API consumers.
+ *
+ * HTML tags in the excerpt are stripped via {@link stripHtmlPreservingMarkTags}.
+ *
+ * @param row - Raw row from the UNION ALL FTS query.
+ * @returns A sanitised {@link SearchResultItem} ready for JSON serialisation.
+ */
+export declare function mapFtsRow(row: FtsRow): SearchResultItem;
+/**
+ * Maps a repository-shaped {@link SearchResultRow} (camelCase) to the
+ * wire-format {@link SearchResultItem} returned by the `GET /api/search` route.
+ *
+ * This is the counterpart of {@link mapFtsRow} for rows that have already been
+ * normalised by the search repository layer.
+ *
+ * @param row - Repository result row with camelCase field names.
+ * @returns A sanitised {@link SearchResultItem} ready for JSON serialisation.
+ */
+export declare function mapSearchResultRow(row: import('@beechcms/core').SearchResultRow): SearchResultItem;

package/dist/features/seeds/seeds.destructive.d.ts

@@ -0,0 +1,6 @@
+import { Hono } from 'hono';
+import type { Env, Variables } from '../../types';
+export declare const destructiveApp: Hono<{
+    Bindings: Env;
+    Variables: Variables;
+}, import("hono/types").BlankSchema, "/">;

package/dist/features/seeds/seeds.handler.d.ts

@@ -1,6 +1,20 @@
+/**
+ * @module features/seeds
+ *
+ * HTTP route handlers for Seed and Schema Management in BeechCMS.
+ *
+ * Provides RESTful administration endpoints for Content Types ("Seeds"),
+ * executing additive DDL migrations against SQLite/D1, managing branches (fields),
+ * rebuilding full-text search (FTS5) virtual tables, and composing sub-routers
+ * for destructive operations and MCP agent workflows.
+ */
 import { Hono } from 'hono';
 import type { Env, Variables } from '../../types';
 export declare const seedsApp: Hono<{
     Bindings: Env;
     Variables: Variables;
 }, import("hono/types").BlankSchema, "/">;
+export { McpClassification, classifyCandidate } from './seeds.mcp';
+export * from './seeds.helpers';
+export { destructiveApp } from './seeds.destructive';
+export { mcpApp } from './seeds.mcp';