libsql-search 0.2.4 → 0.3.0

package/README.md

@@ -13,16 +13,16 @@ Use it when you want:
 
 - a small TypeScript library instead of a hosted search product
 - one search index shared across static-site builds and app routes
-- local or API-based embeddings behind the same indexing/search API
+- local or hosted embeddings behind the same indexing/search API
 - direct control over table names, dimensions, content shape, and deployment
 
 ## What It Supports
 
 - Markdown indexing from local directories with frontmatter via `gray-matter`
 - libSQL/Turso storage and vector search
-- Embedding providers that exist in the code today: local
-  `Xenova/all-MiniLM-L6-v2`, Google Gemini `text-embedding-004`, and OpenAI
-  `text-embedding-3-small` and `text-embedding-3-large`
+- Embedding providers: local `Xenova/all-MiniLM-L6-v2`, Cloudflare Workers AI
+  `@cf/baai/bge-m3`, Google Gemini `text-embedding-004`, and OpenAI
+  `text-embedding-3-small` / `text-embedding-3-large`
 - npm distribution plus JSR publishing
 
 ## Install
@@ -97,6 +97,8 @@ Important behavior:
 - Call `createTable()` before indexing or searching.
 - Keep dimensions aligned across table creation, indexing, and search queries.
 - `indexContent()` clears existing rows before rebuilding the index.
+- `local` is the default offline provider; Cloudflare is the recommended hosted
+  option and uses 1024 dimensions.
 
 ## Core API
 

package/dist/index.cjs

@@ -12,6 +12,8 @@ const GEMINI_MODEL = "text-embedding-004";
 const OPENAI_SMALL_MODEL = "text-embedding-3-small";
 const OPENAI_LARGE_MODEL = "text-embedding-3-large";
 const OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
+const CLOUDFLARE_MODEL = "@cf/baai/bge-m3";
+const CLOUDFLARE_DIMENSIONS = 1024;
 const localModelCacheByModel = /* @__PURE__ */ new Map();
 function getEnvironmentVariable(name) {
   const runtime = globalThis;
@@ -51,6 +53,7 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "cloudflare":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -71,6 +74,10 @@ function truncateTexts(texts, maxLength) {
 function getOpenAIModel(dimensions) {
   return dimensions <= 1536 ? OPENAI_SMALL_MODEL : OPENAI_LARGE_MODEL;
 }
+function getOptionalTrimmedCredential(value) {
+  const trimmed = value?.trim();
+  return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
+}
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
@@ -97,6 +104,16 @@ function providerError(provider, message, cause, exactSecrets = []) {
 function getResponseHeader(response, name) {
   return response.headers.get(name) ?? void 0;
 }
+function getSafeResponseHeader(response, name) {
+  const value = getResponseHeader(response, name)?.trim();
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/[^A-Za-z0-9._:-]/g, "").slice(0, 128);
+}
+function createCloudflareEmbeddingsUrl(accountId) {
+  return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -225,12 +242,28 @@ function createProviderMetadata(provider, dimensions) {
         dimensions,
         batch: Object.freeze({ mode: "native", maxSize: 2048 })
       });
+    case "cloudflare":
+      return Object.freeze({
+        name: "cloudflare",
+        model: CLOUDFLARE_MODEL,
+        dimensions: CLOUDFLARE_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
     return DEFAULT_DIMENSIONS;
   }
+  if (provider === "cloudflare") {
+    if (dimensions !== void 0 && dimensions !== CLOUDFLARE_DIMENSIONS) {
+      throw providerError(
+        "cloudflare",
+        `@cf/baai/bge-m3 returns ${CLOUDFLARE_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return CLOUDFLARE_DIMENSIONS;
+  }
   return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -394,6 +427,73 @@ class OpenAIEmbeddingProvider {
     );
   }
 }
+class CloudflareEmbeddingProvider {
+  metadata;
+  #accountId;
+  #apiToken;
+  #timeoutMs;
+  constructor(metadata, accountId, apiToken, timeoutMs) {
+    this.metadata = metadata;
+    this.#accountId = accountId;
+    this.#apiToken = apiToken;
+    this.#timeoutMs = timeoutMs;
+  }
+  async embed(texts, options = {}) {
+    const intent = resolveIntent(options.intent);
+    if (texts.length === 0) {
+      return createEmbeddingBatchResult(this.metadata, intent, []);
+    }
+    assertBatchSize(this.metadata, texts.length);
+    const endpoint = createCloudflareEmbeddingsUrl(this.#accountId);
+    const items = await withTimeout(
+      "cloudflare",
+      "API request",
+      this.#timeoutMs,
+      async (signal) => {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.#apiToken}`
+          },
+          signal,
+          body: JSON.stringify({
+            model: this.metadata.model,
+            input: texts
+          })
+        });
+        if (!response.ok) {
+          const cfRay = getSafeResponseHeader(response, "cf-ray");
+          const context = cfRay ? ` status ${response.status}, cf-ray ${cfRay}` : ` status ${response.status}`;
+          throw new Error(context);
+        }
+        const data = await response.json();
+        if (!Array.isArray(data.data)) {
+          throw new Error("Cloudflare response did not include a data array");
+        }
+        return data.data.map((item) => {
+          const typed = item;
+          const embedding = typed.embedding;
+          if (!Array.isArray(embedding)) {
+            throw new Error("Cloudflare response item did not include an embedding array");
+          }
+          const parsed = { embedding };
+          if (hasOwnProperty(typed, "index")) {
+            parsed.index = typed.index;
+          }
+          return parsed;
+        });
+      },
+      options.signal,
+      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
+    );
+  }
+}
 function createEmbeddingProvider(options = {}) {
   const provider = resolveProviderName(options.provider);
   const metadata = getEmbeddingProviderMetadata(options);
@@ -415,6 +515,21 @@ function createEmbeddingProvider(options = {}) {
       }
       return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
     }
+    case "cloudflare": {
+      const accountId = getOptionalTrimmedCredential(
+        options.accountId ?? getEnvironmentVariable("CLOUDFLARE_ACCOUNT_ID")
+      );
+      const apiToken = getOptionalTrimmedCredential(
+        options.apiToken ?? getEnvironmentVariable("CLOUDFLARE_API_TOKEN")
+      );
+      if (!accountId) {
+        throw new Error("CLOUDFLARE_ACCOUNT_ID is required for Cloudflare embeddings");
+      }
+      if (!apiToken) {
+        throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
+      }
+      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+    }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@libsql/client';
 
-type EmbeddingProvider = 'local' | 'gemini' | 'openai';
+type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'cloudflare';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';
 interface EmbeddingBatchBehavior {
@@ -31,6 +31,8 @@ interface EmbeddingBatchResult {
 interface EmbeddingOptions {
     provider?: EmbeddingProvider;
     apiKey?: string;
+    accountId?: string;
+    apiToken?: string;
     dimensions?: number;
     maxLength?: number;
     intent?: EmbeddingIntent;

package/dist/index.esm.js

@@ -10,6 +10,8 @@ const GEMINI_MODEL = "text-embedding-004";
 const OPENAI_SMALL_MODEL = "text-embedding-3-small";
 const OPENAI_LARGE_MODEL = "text-embedding-3-large";
 const OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
+const CLOUDFLARE_MODEL = "@cf/baai/bge-m3";
+const CLOUDFLARE_DIMENSIONS = 1024;
 const localModelCacheByModel = /* @__PURE__ */ new Map();
 function getEnvironmentVariable(name) {
   const runtime = globalThis;
@@ -49,6 +51,7 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "cloudflare":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -69,6 +72,10 @@ function truncateTexts(texts, maxLength) {
 function getOpenAIModel(dimensions) {
   return dimensions <= 1536 ? OPENAI_SMALL_MODEL : OPENAI_LARGE_MODEL;
 }
+function getOptionalTrimmedCredential(value) {
+  const trimmed = value?.trim();
+  return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
+}
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
@@ -95,6 +102,16 @@ function providerError(provider, message, cause, exactSecrets = []) {
 function getResponseHeader(response, name) {
   return response.headers.get(name) ?? void 0;
 }
+function getSafeResponseHeader(response, name) {
+  const value = getResponseHeader(response, name)?.trim();
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/[^A-Za-z0-9._:-]/g, "").slice(0, 128);
+}
+function createCloudflareEmbeddingsUrl(accountId) {
+  return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -223,12 +240,28 @@ function createProviderMetadata(provider, dimensions) {
         dimensions,
         batch: Object.freeze({ mode: "native", maxSize: 2048 })
       });
+    case "cloudflare":
+      return Object.freeze({
+        name: "cloudflare",
+        model: CLOUDFLARE_MODEL,
+        dimensions: CLOUDFLARE_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
     return DEFAULT_DIMENSIONS;
   }
+  if (provider === "cloudflare") {
+    if (dimensions !== void 0 && dimensions !== CLOUDFLARE_DIMENSIONS) {
+      throw providerError(
+        "cloudflare",
+        `@cf/baai/bge-m3 returns ${CLOUDFLARE_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return CLOUDFLARE_DIMENSIONS;
+  }
   return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -392,6 +425,73 @@ class OpenAIEmbeddingProvider {
     );
   }
 }
+class CloudflareEmbeddingProvider {
+  metadata;
+  #accountId;
+  #apiToken;
+  #timeoutMs;
+  constructor(metadata, accountId, apiToken, timeoutMs) {
+    this.metadata = metadata;
+    this.#accountId = accountId;
+    this.#apiToken = apiToken;
+    this.#timeoutMs = timeoutMs;
+  }
+  async embed(texts, options = {}) {
+    const intent = resolveIntent(options.intent);
+    if (texts.length === 0) {
+      return createEmbeddingBatchResult(this.metadata, intent, []);
+    }
+    assertBatchSize(this.metadata, texts.length);
+    const endpoint = createCloudflareEmbeddingsUrl(this.#accountId);
+    const items = await withTimeout(
+      "cloudflare",
+      "API request",
+      this.#timeoutMs,
+      async (signal) => {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.#apiToken}`
+          },
+          signal,
+          body: JSON.stringify({
+            model: this.metadata.model,
+            input: texts
+          })
+        });
+        if (!response.ok) {
+          const cfRay = getSafeResponseHeader(response, "cf-ray");
+          const context = cfRay ? ` status ${response.status}, cf-ray ${cfRay}` : ` status ${response.status}`;
+          throw new Error(context);
+        }
+        const data = await response.json();
+        if (!Array.isArray(data.data)) {
+          throw new Error("Cloudflare response did not include a data array");
+        }
+        return data.data.map((item) => {
+          const typed = item;
+          const embedding = typed.embedding;
+          if (!Array.isArray(embedding)) {
+            throw new Error("Cloudflare response item did not include an embedding array");
+          }
+          const parsed = { embedding };
+          if (hasOwnProperty(typed, "index")) {
+            parsed.index = typed.index;
+          }
+          return parsed;
+        });
+      },
+      options.signal,
+      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
+    );
+  }
+}
 function createEmbeddingProvider(options = {}) {
   const provider = resolveProviderName(options.provider);
   const metadata = getEmbeddingProviderMetadata(options);
@@ -413,6 +513,21 @@ function createEmbeddingProvider(options = {}) {
       }
       return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
     }
+    case "cloudflare": {
+      const accountId = getOptionalTrimmedCredential(
+        options.accountId ?? getEnvironmentVariable("CLOUDFLARE_ACCOUNT_ID")
+      );
+      const apiToken = getOptionalTrimmedCredential(
+        options.apiToken ?? getEnvironmentVariable("CLOUDFLARE_API_TOKEN")
+      );
+      if (!accountId) {
+        throw new Error("CLOUDFLARE_ACCOUNT_ID is required for Cloudflare embeddings");
+      }
+      if (!apiToken) {
+        throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
+      }
+      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+    }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {

package/docs/API.md

@@ -210,7 +210,8 @@ Provider metadata includes:
 - `batch.maxSize`, when the provider has a hard maximum
 
 Hosted provider clients are scoped to their options. The library does not reuse
-a Gemini or OpenAI client created with a different API key or configuration.
+a Cloudflare, Gemini, or OpenAI client created with different credentials or
+configuration.
 
 ### `getEmbeddingProviderMetadata(options?)`
 
@@ -238,7 +239,7 @@ Provider clients return:
 ```ts
 interface EmbeddingBatchResult {
   embeddings: number[][];
-  provider: "local" | "gemini" | "openai";
+  provider: "local" | "cloudflare" | "gemini" | "openai";
   model: string;
   dimensions: number;
   intent: "document" | "query";
@@ -254,8 +255,10 @@ cardinality, dimensions, finite numeric values, and indexed batch ordering.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "gemini" | "openai";
   apiKey?: string;
+  accountId?: string;
+  apiToken?: string;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -264,6 +267,10 @@ interface EmbeddingOptions {
 }
 ```
 
+`apiKey` is used by Gemini and OpenAI. Cloudflare uses `accountId` and
+`apiToken`, which fall back to `CLOUDFLARE_ACCOUNT_ID` and
+`CLOUDFLARE_API_TOKEN`.
+
 ### `padEmbedding(embedding, targetDimensions)`
 
 Pads or truncates an embedding array to the requested length.

package/docs/INTEGRATIONS.md

@@ -127,14 +127,18 @@ const client = createClient({
   authToken: process.env.TURSO_AUTH_TOKEN!,
 });
 
-await createTable(client, "articles", 768);
+const embeddingProvider =
+  process.env.EMBEDDING_PROVIDER as "local" | "cloudflare" | "gemini" | "openai" | undefined;
+const embeddingDimensions = embeddingProvider === "cloudflare" ? 1024 : 768;
+
+await createTable(client, "articles", embeddingDimensions);
 
 await indexContent({
   client,
   contentPath: "./content",
   embeddingOptions: {
-    provider: process.env.EMBEDDING_PROVIDER as "local" | "gemini" | "openai" | undefined,
-    dimensions: 768,
+    provider: embeddingProvider,
+    dimensions: embeddingDimensions,
   },
 });
 ```

package/docs/PROVIDERS.md

@@ -1,8 +1,9 @@
 # Embedding Providers
 
-`libsql-search` currently supports three embedding providers:
+`libsql-search` currently supports four embedding providers:
 
 - `local`
+- `cloudflare`
 - `gemini`
 - `openai`
 
@@ -14,8 +15,10 @@ query time.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "gemini" | "openai";
   apiKey?: string;
+  accountId?: string;
+  apiToken?: string;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -30,8 +33,10 @@ interface EmbeddingOptions {
 - `intent` can be `"document"` or `"query"`; indexing defaults to
   `"document"` and search defaults to `"query"` unless explicitly set
 - `timeoutMs` defaults to `30000`
-- `apiKey` is optional in code, but required for hosted providers unless the
-  matching environment variable is available
+- `apiKey` is used by Gemini and OpenAI and falls back to `GEMINI_API_KEY` or
+  `OPENAI_API_KEY`
+- `accountId` and `apiToken` are used by Cloudflare and fall back to
+  `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`
 
 ## Provider Contract
 
@@ -39,7 +44,7 @@ Each provider exposes immutable metadata:
 
 ```ts
 interface EmbeddingProviderMetadata {
-  name: "local" | "gemini" | "openai";
+  name: "local" | "cloudflare" | "gemini" | "openai";
   model: string;
   dimensions: number;
   batch: {
@@ -78,9 +83,9 @@ Lower-level provider clients return an `EmbeddingBatchResult` with the validated
 vectors plus provider, model, dimensions, and intent. The compatibility helpers
 `generateEmbedding()` and `generateEmbeddings()` return only arrays.
 
-Gemini and OpenAI clients are scoped to their current options. They are not
-cached globally across different credentials or configurations. The local Xenova
-model can be cached by model name.
+Cloudflare, Gemini, and OpenAI clients are scoped to their current options. They
+are not cached globally across different credentials or configurations. The
+local Xenova model can be cached by model name.
 
 Hosted provider failures are reported with bounded provider/status/request-id
 context and without raw upstream bodies, credentials, Authorization headers, or
@@ -108,6 +113,36 @@ Notes:
 - batch metadata is `{ mode: "sequential" }`
 - the first run downloads the model and can take longer on a fresh machine
 - no API key is required
+- this remains the default provider for backward compatibility and offline use
+
+## Cloudflare Workers AI
+
+Provider value: `cloudflare`
+
+Cloudflare is the recommended hosted provider for low-cost Markdown search.
+It uses Workers AI `@cf/baai/bge-m3` through Cloudflare's OpenAI-compatible
+embeddings endpoint.
+
+```ts
+embeddingOptions: {
+  provider: "cloudflare",
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+}
+```
+
+Behavior:
+
+- if `accountId` is omitted, the library reads `CLOUDFLARE_ACCOUNT_ID`
+- if `apiToken` is omitted, the library reads `CLOUDFLARE_API_TOKEN`
+- blank Cloudflare credentials are treated as missing
+- `@cf/baai/bge-m3` returns 1024 dimensions
+- metadata reports `@cf/baai/bge-m3` and 1024 dimensions without requiring
+  credentials
+- batch metadata is `{ mode: "native" }`
+- response items are reordered by provider-supplied index before being returned
+- Cloudflare does not accept custom dimensions in this provider; use
+  `createTable(client, "articles", 1024)` for Cloudflare-backed indexes
 
 ## Gemini
 
@@ -156,7 +191,8 @@ Behavior:
 
 ## Dimension Guidelines
 
-- `768` is the easiest cross-provider target in the current implementation
+- `local` defaults to `768`
+- `cloudflare` is fixed at `1024`
 - local embeddings are padded from 384 to your target size
 - Gemini stays at 768
 - OpenAI can be used at 1536 or 3072, or another supported OpenAI dimension

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",