svedocs 0.1.0-beta.10

package/dist/search/local.js

@@ -0,0 +1,165 @@
+import MiniSearch from 'minisearch';
+import { createExcerpt, jsonResponse, normalizeSearchText, tokenizeSearchQuery, tokenizeSearchText } from './utils.js';
+const miniSearchCache = new WeakMap();
+const localSearchBoost = {
+    title: 5,
+    section: 4,
+    url: 1.5,
+    metadataText: 0.8,
+    content: 1
+};
+export function createLocalSearchProvider(records = []) {
+    let indexed = records;
+    return {
+        name: 'local-json',
+        index(nextRecords) {
+            indexed = nextRecords;
+        },
+        search(input) {
+            return searchRecords(indexed, input);
+        }
+    };
+}
+export const localSearchProvider = createLocalSearchProvider();
+export function searchRecords(records, input) {
+    const query = normalizeSearchText(input.query);
+    if (!query)
+        return [];
+    const limit = input.limit ?? 10;
+    const entry = getMiniSearchIndex(records);
+    const primary = runLocalSearch(entry, input, 'AND');
+    const selected = primary.slice(0, limit);
+    if (selected.length < limit && tokenizeSearchQuery(input.query).length > 1) {
+        const seen = new Set(selected.map((hit) => hit.record.id));
+        const fallbackScoreCeiling = selected.at(-1)?.score;
+        selected.push(...runLocalSearch(entry, input, 'OR')
+            .filter((hit) => !seen.has(hit.record.id))
+            .map((hit) => ({
+            ...hit,
+            score: fallbackScoreCeiling ? Math.min(hit.score * 0.6, fallbackScoreCeiling * 0.95) : hit.score * 0.6
+        }))
+            .slice(0, limit - selected.length));
+    }
+    return selected.map(({ record, score }) => ({
+        id: record.id,
+        title: record.title,
+        url: record.url,
+        ...(record.section ? { section: record.section } : {}),
+        excerpt: createExcerpt(record.content, input.query),
+        score,
+        metadata: record.metadata
+    }));
+}
+function runLocalSearch(entry, input, combineWith) {
+    const scoped = entry.index.search(input.query, {
+        prefix: true,
+        fuzzy: (term) => term.length > 4 ? 0.18 : false,
+        combineWith,
+        boost: localSearchBoost
+    });
+    return scoped
+        .map((hit) => {
+        const record = entry.recordsById.get(hit.id);
+        return record ? { record, score: scoreLocalSearchHit(record, hit.score, input.query) } : undefined;
+    })
+        .filter((item) => Boolean(item))
+        .filter((item) => matchesSearchScope(item.record, input))
+        .sort((a, b) => b.score - a.score)
+        .map((hit) => ({ ...hit, score: Number(hit.score.toFixed(4)) }));
+}
+export function filterSearchRecords(records, scope = {}) {
+    return records.filter((record) => matchesSearchScope(record, scope));
+}
+export function matchesSearchScope(record, scope = {}) {
+    return matchesMetadata(record.metadata.locale, scope.locale)
+        && matchesMetadata(record.metadata.kind, scope.kind);
+}
+export async function createSearchResponse(records, request) {
+    const url = new URL(request.url);
+    const query = url.searchParams.get('q') ?? url.searchParams.get('query') ?? '';
+    const limit = clampLimit(Number(url.searchParams.get('limit') ?? 10));
+    const locale = readScopeParam(url, 'locale');
+    const kind = readScopeParam(url, 'kind');
+    const results = searchRecords(records, {
+        query,
+        limit,
+        ...(locale ? { locale } : {}),
+        ...(kind ? { kind } : {})
+    });
+    return jsonResponse({ query, results });
+}
+function getMiniSearchIndex(records) {
+    const cached = miniSearchCache.get(records);
+    if (cached)
+        return cached;
+    const documents = records.map(toMiniSearchDocument);
+    const index = new MiniSearch({
+        fields: ['title', 'section', 'url', 'content', 'metadataText'],
+        storeFields: ['id', 'title', 'section', 'url', 'content', 'metadata'],
+        idField: 'id',
+        searchOptions: {
+            prefix: true,
+            fuzzy: 0.18
+        },
+        tokenize: tokenizeSearchText,
+        processTerm: (term) => normalizeSearchText(term) || false
+    });
+    index.addAll(documents);
+    const entry = {
+        index,
+        recordsById: new Map(records.map((record) => [record.id, record]))
+    };
+    miniSearchCache.set(records, entry);
+    return entry;
+}
+function toMiniSearchDocument(record) {
+    return {
+        id: record.id,
+        title: record.title,
+        section: record.section ?? '',
+        url: record.url,
+        content: record.content,
+        metadataText: Object.values(record.metadata).flat().join(' '),
+        metadata: record.metadata
+    };
+}
+function matchesMetadata(value, expected) {
+    if (!expected)
+        return true;
+    if (Array.isArray(value))
+        return value.some((item) => String(item) === expected);
+    return value === expected;
+}
+function scoreLocalSearchHit(record, score, query) {
+    const normalizedQuery = normalizeSearchText(query);
+    const title = normalizeSearchText(record.title);
+    const section = normalizeSearchText(record.section ?? '');
+    const url = normalizeSearchText(record.url);
+    const sourcePath = normalizeSearchText(typeof record.metadata.sourcePath === 'string' ? record.metadata.sourcePath : '');
+    const terms = tokenizeSearchQuery(query);
+    let multiplier = 1;
+    if (title === normalizedQuery || section === normalizedQuery) {
+        multiplier *= 1.6;
+    }
+    else if (title.startsWith(normalizedQuery) || section.startsWith(normalizedQuery)) {
+        multiplier *= 1.35;
+    }
+    else if (title.includes(normalizedQuery) || section.includes(normalizedQuery)) {
+        multiplier *= 1.2;
+    }
+    else if (terms.length > 1 && terms.every((term) => title.includes(term) || section.includes(term))) {
+        multiplier *= 1.15;
+    }
+    if (url.includes(normalizedQuery) || sourcePath.includes(normalizedQuery))
+        multiplier *= 1.1;
+    return score * multiplier;
+}
+function readScopeParam(url, key) {
+    const value = url.searchParams.get(key);
+    return value?.trim() || undefined;
+}
+function clampLimit(value) {
+    if (!Number.isFinite(value))
+        return 10;
+    return Math.min(50, Math.max(1, Math.floor(value)));
+}

package/dist/search/runtime.d.ts

@@ -0,0 +1,41 @@
+import type { SvedocsResolvedConfig, SvedocsSearchRecord } from '../core.js';
+import type { CloudflareAiSearchInstance, CloudflareAiSearchNamespace, SearchProvider, SearchQuery } from './types.js';
+export interface SvedocsSearchRuntimeEnv {
+    SVEDOCS_AI_SEARCH?: CloudflareAiSearchInstance | CloudflareAiSearchNamespace | undefined;
+    ALGOLIA_APP_ID?: string | undefined;
+    ALGOLIA_SEARCH_KEY?: string | undefined;
+    ALGOLIA_API_KEY?: string | undefined;
+    ALGOLIA_INDEX_NAME?: string | undefined;
+    SVEDOCS_ALGOLIA_APP_ID?: string | undefined;
+    SVEDOCS_ALGOLIA_SEARCH_KEY?: string | undefined;
+    SVEDOCS_ALGOLIA_API_KEY?: string | undefined;
+    SVEDOCS_ALGOLIA_INDEX_NAME?: string | undefined;
+    TYPESENSE_HOST?: string | undefined;
+    TYPESENSE_URL?: string | undefined;
+    TYPESENSE_SEARCH_KEY?: string | undefined;
+    TYPESENSE_API_KEY?: string | undefined;
+    TYPESENSE_COLLECTION?: string | undefined;
+    TYPESENSE_COLLECTION_NAME?: string | undefined;
+    SVEDOCS_TYPESENSE_HOST?: string | undefined;
+    SVEDOCS_TYPESENSE_URL?: string | undefined;
+    SVEDOCS_TYPESENSE_SEARCH_KEY?: string | undefined;
+    SVEDOCS_TYPESENSE_API_KEY?: string | undefined;
+    SVEDOCS_TYPESENSE_COLLECTION?: string | undefined;
+    SVEDOCS_TYPESENSE_COLLECTION_NAME?: string | undefined;
+    [key: string]: unknown;
+}
+export interface CreateConfiguredSearchProviderOptions {
+    config: Pick<SvedocsResolvedConfig, 'search' | 'cloudflare'>;
+    records?: SvedocsSearchRecord[];
+    env?: SvedocsSearchRuntimeEnv;
+    provider?: string;
+    fetch?: typeof fetch;
+}
+export interface CreateConfiguredSearchResponseOptions extends Omit<CreateConfiguredSearchProviderOptions, 'config' | 'records' | 'provider'> {
+    provider?: string;
+}
+export declare function createConfiguredSearchProvider(options: CreateConfiguredSearchProviderOptions): SearchProvider;
+export declare function createConfiguredSearchResponse(config: Pick<SvedocsResolvedConfig, 'search' | 'cloudflare'>, records: SvedocsSearchRecord[], request: Request, options?: CreateConfiguredSearchResponseOptions): Promise<Response>;
+export declare function readSearchQuery(request: Request): SearchQuery;
+export declare function readProviderParam(request: Request): string | undefined;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/search/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/search/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAK7E,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,cAAc,EACd,WAAW,EAEZ,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,CAAC,EAAE,0BAA0B,GAAG,2BAA2B,GAAG,SAAS,CAAC;IACzF,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,0BAA0B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,0BAA0B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,yBAAyB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,4BAA4B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,yBAAyB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,4BAA4B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,iCAAiC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qCAAqC;IACpD,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;IAC7D,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,GAAG,CAAC,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,qCAAsC,SAAQ,IAAI,CAAC,qCAAqC,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IAC3I,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qCAAqC,GAAG,cAAc,CAmD7G;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,YAAY,CAAC,EAC5D,OAAO,EAAE,mBAAmB,EAAE,EAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,qCAA0C,GAClD,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAU7D;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGtE"}

package/dist/search/runtime.js

@@ -0,0 +1,152 @@
+import { createAlgoliaSearchProvider } from './algolia.js';
+import { createCloudflareAiSearchProvider } from './cloudflare.js';
+import { createLocalSearchProvider, createSearchResponse } from './local.js';
+import { createTypesenseSearchProvider } from './typesense.js';
+import { jsonResponse } from './utils.js';
+export function createConfiguredSearchProvider(options) {
+    const provider = normalizeProviderName(options.provider ?? options.config.search.provider);
+    const records = options.records ?? [];
+    if (!options.config.search.enabled)
+        return createDisabledSearchProvider();
+    if (provider === 'cloudflare-ai-search') {
+        const binding = readCloudflareAiSearchBinding(options.env, options.config);
+        if (binding) {
+            return createCloudflareAiSearchProvider({
+                binding,
+                instanceName: options.config.cloudflare.aiSearch.instanceName,
+                namespace: Boolean(options.config.cloudflare.aiSearch.namespace)
+            });
+        }
+        return createLocalSearchProvider(records);
+    }
+    if (provider === 'algolia') {
+        const appId = readFirstEnv(options.env, ['SVEDOCS_ALGOLIA_APP_ID', 'ALGOLIA_APP_ID']);
+        const apiKey = readFirstEnv(options.env, ['SVEDOCS_ALGOLIA_SEARCH_KEY', 'SVEDOCS_ALGOLIA_API_KEY', 'ALGOLIA_SEARCH_KEY', 'ALGOLIA_API_KEY']);
+        const indexName = readFirstEnv(options.env, ['SVEDOCS_ALGOLIA_INDEX_NAME', 'ALGOLIA_INDEX_NAME']);
+        if (appId && apiKey && indexName) {
+            return createAlgoliaSearchProvider({
+                appId,
+                apiKey,
+                indexName,
+                filters: createAlgoliaScopeFilters,
+                ...(options.fetch ? { fetch: options.fetch } : {})
+            });
+        }
+        return createLocalSearchProvider(records);
+    }
+    if (provider === 'typesense') {
+        const host = readFirstEnv(options.env, ['SVEDOCS_TYPESENSE_HOST', 'SVEDOCS_TYPESENSE_URL', 'TYPESENSE_HOST', 'TYPESENSE_URL']);
+        const apiKey = readFirstEnv(options.env, ['SVEDOCS_TYPESENSE_SEARCH_KEY', 'SVEDOCS_TYPESENSE_API_KEY', 'TYPESENSE_SEARCH_KEY', 'TYPESENSE_API_KEY']);
+        const collection = readFirstEnv(options.env, [
+            'SVEDOCS_TYPESENSE_COLLECTION',
+            'SVEDOCS_TYPESENSE_COLLECTION_NAME',
+            'TYPESENSE_COLLECTION',
+            'TYPESENSE_COLLECTION_NAME'
+        ]) ?? 'docs';
+        if (host && apiKey) {
+            return createTypesenseSearchProvider({
+                host,
+                apiKey,
+                collection,
+                filterBy: createTypesenseScopeFilters,
+                ...(options.fetch ? { fetch: options.fetch } : {})
+            });
+        }
+        return createLocalSearchProvider(records);
+    }
+    return createLocalSearchProvider(records);
+}
+export async function createConfiguredSearchResponse(config, records, request, options = {}) {
+    if (!config.search.enabled) {
+        return jsonResponse({ query: readSearchQuery(request).query, results: [] });
+    }
+    const providerName = options.provider ?? config.search.provider;
+    const provider = createConfiguredSearchProvider({
+        config,
+        records,
+        provider: providerName,
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {})
+    });
+    if (provider.name === 'local-json' || provider.name === 'disabled') {
+        return createSearchResponse(records, request);
+    }
+    const query = readSearchQuery(request);
+    const results = await provider.search(query);
+    return jsonResponse({ query: query.query, provider: provider.name, results });
+}
+export function readSearchQuery(request) {
+    const url = new URL(request.url);
+    const locale = readScopeParam(url, 'locale');
+    const kind = readScopeParam(url, 'kind');
+    return {
+        query: url.searchParams.get('q') ?? url.searchParams.get('query') ?? '',
+        limit: clampLimit(Number(url.searchParams.get('limit') ?? 10)),
+        ...(locale ? { locale } : {}),
+        ...(kind ? { kind } : {})
+    };
+}
+export function readProviderParam(request) {
+    const provider = new URL(request.url).searchParams.get('provider')?.trim();
+    return provider || undefined;
+}
+function createDisabledSearchProvider() {
+    return {
+        name: 'disabled',
+        index() { },
+        search() {
+            return [];
+        }
+    };
+}
+function readCloudflareAiSearchBinding(env, config) {
+    const bindingName = config.cloudflare.aiSearch.binding;
+    const dynamicBinding = env?.[bindingName];
+    if (isCloudflareAiSearchBinding(dynamicBinding))
+        return dynamicBinding;
+    if (isCloudflareAiSearchBinding(env?.SVEDOCS_AI_SEARCH))
+        return env.SVEDOCS_AI_SEARCH;
+    return undefined;
+}
+function isCloudflareAiSearchBinding(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return 'search' in value || 'get' in value;
+}
+function readFirstEnv(env, keys) {
+    for (const key of keys) {
+        const value = env?.[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function createAlgoliaScopeFilters(query) {
+    return [
+        query.locale ? `locale:${quoteAlgoliaFilterValue(query.locale)}` : undefined,
+        query.kind ? `kind:${quoteAlgoliaFilterValue(query.kind)}` : undefined
+    ].filter(Boolean).join(' AND ') || undefined;
+}
+function quoteAlgoliaFilterValue(value) {
+    return /^[\w-]+$/.test(value) ? value : JSON.stringify(value);
+}
+function createTypesenseScopeFilters(query) {
+    return [
+        query.locale ? `locale:=${quoteTypesenseFilterValue(query.locale)}` : undefined,
+        query.kind ? `kind:=${quoteTypesenseFilterValue(query.kind)}` : undefined
+    ].filter(Boolean).join(' && ') || undefined;
+}
+function quoteTypesenseFilterValue(value) {
+    return /^[\w-]+$/.test(value) ? value : `\`${value.replace(/`/g, '\\`')}\``;
+}
+function normalizeProviderName(provider) {
+    return provider?.trim().toLowerCase() || 'local';
+}
+function readScopeParam(url, key) {
+    return url.searchParams.get(key)?.trim() || undefined;
+}
+function clampLimit(value) {
+    if (!Number.isFinite(value))
+        return 10;
+    return Math.min(50, Math.max(1, Math.floor(value)));
+}

package/dist/search/types.d.ts

@@ -0,0 +1,172 @@
+import type { SvedocsSearchRecord } from '../core.js';
+export interface SearchQuery {
+    query: string;
+    limit?: number;
+    locale?: string;
+    kind?: string;
+}
+export interface SearchScope {
+    locale?: string;
+    kind?: string;
+}
+export interface SearchResult {
+    id: string;
+    title: string;
+    url: string;
+    excerpt: string;
+    score: number;
+    section?: string;
+    metadata: SvedocsSearchRecord['metadata'];
+}
+export interface SearchProvider {
+    name: string;
+    index(records: SvedocsSearchRecord[]): Promise<void> | void;
+    search(query: SearchQuery): Promise<SearchResult[]> | SearchResult[];
+}
+export interface CloudflareAiSearchSyncDocument {
+    id: string;
+    title: string;
+    url: string;
+    content: string;
+    metadata: Record<string, string>;
+}
+export interface CloudflareAiSearchSyncOptions {
+    records: SvedocsSearchRecord[];
+    accountId?: string;
+    apiToken?: string;
+    instanceName: string;
+    namespace?: string;
+    endpoint?: string;
+    dryRun?: boolean;
+    waitForCompletion?: boolean;
+    strategy?: 'append' | 'replace';
+    deleteIds?: string[];
+    existingIds?: string[];
+    batchSize?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    fetch?: typeof fetch;
+}
+export interface CloudflareAiSearchSyncResult {
+    provider: 'cloudflare-ai-search';
+    instanceName: string;
+    endpoint: string;
+    dryRun: boolean;
+    indexed: number;
+    deleted: number;
+    failed: number;
+    planned: {
+        uploadIds: string[];
+        deleteIds: string[];
+    };
+    errors: Array<{
+        id: string;
+        message: string;
+    }>;
+}
+export interface CloudflareAiSearchInstance {
+    search(input: CloudflareAiSearchInput): Promise<CloudflareAiSearchOutput>;
+    chatCompletions?(input: CloudflareAiSearchChatInput): Promise<CloudflareAiSearchChatOutput | ReadableStream<Uint8Array> | Response>;
+    items?: CloudflareAiSearchItemsBinding;
+}
+export interface CloudflareAiSearchItemsBinding {
+    upload(input: File | Blob | ArrayBuffer | string, options?: CloudflareAiSearchItemUploadOptions): Promise<unknown>;
+    uploadAndPoll?(input: File | Blob | ArrayBuffer | string, options?: CloudflareAiSearchItemUploadOptions): Promise<unknown>;
+    delete?(itemId: string): Promise<unknown>;
+    get?(itemId: string): Promise<unknown>;
+    list?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<unknown>;
+}
+export interface CloudflareAiSearchItemUploadOptions {
+    id?: string;
+    metadata?: Record<string, string>;
+    contentType?: string;
+    filename?: string;
+}
+export interface CloudflareAiSearchMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+export interface CloudflareAiSearchInput {
+    query?: string;
+    messages?: CloudflareAiSearchMessage[];
+    ai_search_options?: {
+        instance_ids?: string[];
+        query_rewrite?: boolean | {
+            enabled?: boolean;
+            model?: string;
+        };
+        retrieval?: {
+            retrieval_type?: 'vector' | 'keyword' | 'hybrid';
+            match_threshold?: number;
+            max_num_results?: number;
+            filters?: Record<string, unknown>;
+            context_expansion?: number;
+            fusion_method?: 'rrf' | 'max';
+            keyword_match_mode?: string;
+            reranking?: {
+                enabled?: boolean;
+                model?: string;
+            };
+        };
+    };
+    max_num_results?: number;
+}
+export interface CloudflareAiSearchItem {
+    id?: string;
+    title?: string;
+    url?: string;
+    content?: string;
+    text?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CloudflareAiSearchChunk {
+    id?: string;
+    type?: string;
+    text?: string;
+    content?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+    attributes?: Record<string, unknown>;
+    item?: {
+        id?: string;
+        key?: string;
+        filename?: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface CloudflareAiSearchOutput {
+    response?: string;
+    answer?: string;
+    data?: CloudflareAiSearchItem[];
+    chunks?: CloudflareAiSearchChunk[];
+}
+export interface CloudflareAiSearchChatInput {
+    messages: CloudflareAiSearchMessage[];
+    ai_search_options?: CloudflareAiSearchInput['ai_search_options'];
+    model?: string;
+    stream?: boolean;
+}
+export interface CloudflareAiSearchChatOutput extends CloudflareAiSearchOutput {
+    choices?: Array<{
+        text?: string;
+        message?: {
+            content?: string;
+        };
+    }>;
+    citations?: Array<{
+        title?: string;
+        url?: string;
+        section?: string;
+    }>;
+}
+export interface CloudflareAiSearchNamespace {
+    get(instanceName: string): CloudflareAiSearchInstance;
+    search?(input: CloudflareAiSearchInput): Promise<CloudflareAiSearchOutput>;
+    chatCompletions?(input: CloudflareAiSearchChatInput): Promise<CloudflareAiSearchChatOutput | ReadableStream<Uint8Array> | Response>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/search/types.js

@@ -0,0 +1 @@
+export {};

package/dist/search/typesense.d.ts

@@ -0,0 +1,11 @@
+import type { SearchProvider, SearchQuery } from './types.js';
+export interface TypesenseSearchProviderOptions {
+    host: string;
+    apiKey: string;
+    collection: string | ((query: SearchQuery) => string);
+    queryBy?: string | string[];
+    filterBy?: string | ((query: SearchQuery) => string | undefined);
+    fetch?: typeof fetch;
+}
+export declare function createTypesenseSearchProvider(options: TypesenseSearchProviderOptions): SearchProvider;
+//# sourceMappingURL=typesense.d.ts.map

package/dist/search/typesense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesense.d.ts","sourceRoot":"","sources":["../../src/search/typesense.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAG5E,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACjE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AA6BD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,cAAc,CAsBrG"}

package/dist/search/typesense.js

@@ -0,0 +1,91 @@
+import { matchesSearchScope } from './local.js';
+import { createExcerpt, stringMetadata, stringifyMetadata } from './utils.js';
+export function createTypesenseSearchProvider(options) {
+    return {
+        name: 'typesense',
+        index() {
+            // Typesense indexing is commonly handled by a crawler or CI sync script.
+        },
+        async search(query) {
+            const requestFetch = options.fetch ?? fetch;
+            const response = await requestFetch(createTypesenseSearchUrl(options, query), {
+                headers: {
+                    'x-typesense-api-key': options.apiKey
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`Typesense search returned ${response.status}: ${(await response.text()).slice(0, 500)}`);
+            }
+            const payload = await response.json();
+            return (payload.hits ?? [])
+                .map((hit, index) => createTypesenseResult(hit, index, query.query))
+                .filter((result) => matchesSearchScope({ metadata: result.metadata }, query));
+        }
+    };
+}
+function createTypesenseSearchUrl(options, query) {
+    const collection = typeof options.collection === 'function' ? options.collection(query) : options.collection;
+    const base = options.host.replace(/\/$/, '');
+    const url = new URL(`${base}/collections/${encodeURIComponent(collection)}/documents/search`);
+    url.searchParams.set('q', query.query || '*');
+    url.searchParams.set('query_by', Array.isArray(options.queryBy) ? options.queryBy.join(',') : options.queryBy ?? 'title,section,content');
+    url.searchParams.set('per_page', String(query.limit ?? 10));
+    const filterBy = typeof options.filterBy === 'function' ? options.filterBy(query) : options.filterBy;
+    if (filterBy)
+        url.searchParams.set('filter_by', filterBy);
+    return url.toString();
+}
+function createTypesenseResult(hit, index, query) {
+    const document = hit.document ?? {};
+    const metadata = normalizeTypesenseMetadata(document);
+    const section = stringMetadata(document.section) ?? stringMetadata(metadata.section);
+    const content = stringMetadata(document.content) ?? stringMetadata(metadata.content) ?? stringMetadata(document.title) ?? '';
+    return {
+        id: stringMetadata(document.id) ?? stringMetadata(document.objectID) ?? `typesense:${index}`,
+        title: stringMetadata(document.title) ?? stringMetadata(metadata.title) ?? 'Result',
+        url: createTypesenseUrl(document, metadata),
+        ...(section ? { section } : {}),
+        excerpt: createExcerpt(content, query),
+        score: createTypesenseScore(hit, index),
+        metadata
+    };
+}
+function createTypesenseUrl(document, metadata) {
+    const url = stringMetadata(document.url) ?? stringMetadata(metadata.url) ?? '#';
+    const anchor = stringMetadata(document.anchor) ?? stringMetadata(metadata.anchor);
+    if (!anchor || url.includes('#'))
+        return url;
+    return `${url}#${anchor}`;
+}
+function normalizeTypesenseMetadata(document) {
+    const metadata = stringifyMetadata({
+        ...(document.metadata ?? {}),
+        locale: document.locale ?? document.metadata?.locale,
+        kind: document.kind ?? document.metadata?.kind
+    });
+    const embedded = stringMetadata(document.svedocs) ?? stringMetadata(document.metadata?.svedocs);
+    if (!embedded)
+        return metadata;
+    try {
+        const parsed = JSON.parse(embedded);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return metadata;
+        return {
+            ...metadata,
+            ...stringifyMetadata(parsed)
+        };
+    }
+    catch {
+        return metadata;
+    }
+}
+function createTypesenseScore(hit, index) {
+    if (typeof hit.text_match === 'number')
+        return hit.text_match;
+    const score = hit.text_match_info?.score;
+    if (typeof score === 'number')
+        return score;
+    if (typeof score === 'string' && Number.isFinite(Number(score)))
+        return Number(score);
+    return 1 / (index + 1);
+}

package/dist/search/utils.d.ts

@@ -0,0 +1,11 @@
+export declare function createExcerpt(content: string, query: string): string;
+export declare function normalizeSearchText(value: string): string;
+export declare function tokenizeSearchText(value: string): string[];
+export declare function tokenizeSearchQuery(query: string): string[];
+export declare function stringMetadata(value: unknown): string | undefined;
+export declare function stringifyMetadata(metadata: Record<string, unknown>): Record<string, string>;
+export declare function uniqueStrings(values: string[]): string[];
+export declare function jsonResponse(value: unknown, status?: number): Response;
+export declare function chunkArray<T>(items: T[], size: number): T[][];
+export declare function wait(ms: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/search/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/search/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAE3D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAExD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAM,GAAG,QAAQ,CAOnE;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAO7D;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9C"}