blume 2.1.0 → 2.1.2

package/dist/types/ratelimit/upstash.d.ts

@@ -1,21 +1,46 @@
+import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.ts";
 import type { RateLimitOptions } from "./memory.ts";
-/** The env vars holding the Upstash Redis REST endpoint and its token. */
-export declare const UPSTASH_SECRETS: readonly ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"];
-export type UpstashAdapter = AdapterDescriptor<"upstash", RateLimitOptions>;
-export declare const upstashAdapterSchema: import("zod").ZodObject<{
-    kind: import("zod").ZodLiteral<"upstash">;
-    options: import("zod").ZodObject<{
-        requests: import("zod").ZodOptional<import("zod").ZodNumber>;
-        window: import("zod").ZodOptional<import("zod").ZodNumber>;
-    }, import("zod/v4/core").$strict>;
-    requiredSecrets: import("zod").ZodArray<import("zod").ZodString>;
-    runtimeDeps: import("zod").ZodArray<import("zod").ZodString>;
-}, import("zod/v4/core").$strict>;
+/** Options for {@link upstash}. */
+export interface UpstashOptions extends RateLimitOptions {
+    /**
+     * Name of the env var holding the REST token. Defaults to
+     * `UPSTASH_REDIS_REST_TOKEN`; a database added from Vercel's Marketplace
+     * sets `KV_REST_API_TOKEN`.
+     */
+    tokenEnv?: string;
+    /**
+     * Name of the env var holding the REST endpoint. Defaults to
+     * `UPSTASH_REDIS_REST_URL`; a database added from Vercel's Marketplace
+     * sets `KV_REST_API_URL`.
+     */
+    urlEnv?: string;
+}
+export declare const upstashOptionsSchema: z.ZodObject<{
+    requests: z.ZodOptional<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodNumber>;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+    urlEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type UpstashAdapter = AdapterDescriptor<"upstash", UpstashOptions>;
+export declare const upstashAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"upstash">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        urlEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** The env vars the endpoint and its token are read from, in that order. */
+export declare const upstashSecrets: (options: UpstashOptions) => [string, string];
 /**
  * Keeps the count in Upstash Redis, which every instance on every host shares,
  * so the limit holds exactly. It talks to Upstash's REST API, so there is
  * nothing to install; the endpoint and token come from
- * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`.
+ * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`, or the env vars
+ * `urlEnv` and `tokenEnv` name.
  */
-export declare const upstash: (options?: RateLimitOptions) => UpstashAdapter;
+export declare const upstash: (options?: UpstashOptions) => UpstashAdapter;

package/dist/types/reference/graphql.d.ts

@@ -1,8 +1,15 @@
 import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.ts";
-import type { GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
+import type { GraphqlAuthOptions, GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
 /** Options for {@link graphql}. */
 export interface GraphqlOptions {
+    /**
+     * How the endpoint authenticates, like the site's `api.auth`: `bearer`,
+     * `basic`, or `key` (sent in the `name` header, `x-api-key` by default).
+     * The Try it panel gets a field for the credential and the code samples
+     * send a placeholder. Applies to every source; a per-source `auth` wins.
+     */
+    auth?: GraphqlAuthOptions;
     /**
      * Code-sample languages shown per operation, in order. Defaults to
      * `["curl", "js", "python"]`; `false` shows none.
@@ -36,6 +43,15 @@ export interface GraphqlOptions {
  * AsyncAPI documents only.
  */
 export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
+    auth: z.ZodOptional<z.ZodObject<{
+        method: z.ZodEnum<{
+            none: "none";
+            key: "key";
+            bearer: "bearer";
+            basic: "basic";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     endpoint: z.ZodOptional<z.ZodString>;
     sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
         includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -45,6 +61,15 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         route: z.ZodOptional<z.ZodString>;
         seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
         spec: z.ZodString;
+        auth: z.ZodOptional<z.ZodObject<{
+            method: z.ZodEnum<{
+                none: "none";
+                key: "key";
+                bearer: "bearer";
+                basic: "basic";
+            }>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         endpoint: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
     codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
@@ -69,6 +94,10 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         spec: string;
         label?: string | undefined;
         route?: string | undefined;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
     }[];
     codeSamples: false | string[];
@@ -77,6 +106,10 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         proxy: string | boolean;
     };
     route: string;
+    auth?: {
+        method: "none" | "key" | "bearer" | "basic";
+        name?: string | undefined;
+    } | undefined;
     endpoint?: string | undefined;
     spec?: string | undefined;
 }, "spec" | "overlays">, {
@@ -88,6 +121,10 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         spec: string;
         label?: string | undefined;
         route?: string | undefined;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
     }[];
     codeSamples: false | string[];
@@ -96,6 +133,10 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         proxy: string | boolean;
     };
     route: string;
+    auth?: {
+        method: "none" | "key" | "bearer" | "basic";
+        name?: string | undefined;
+    } | undefined;
     endpoint?: string | undefined;
     spec?: string | undefined;
 }>>;
@@ -107,6 +148,15 @@ export type ResolvedGraphqlAdapter = AdapterDescriptor<"graphql", ResolvedGraphq
 export declare const graphqlAdapterSchema: z.ZodObject<{
     kind: z.ZodLiteral<"graphql">;
     options: z.ZodPipe<z.ZodObject<{
+        auth: z.ZodOptional<z.ZodObject<{
+            method: z.ZodEnum<{
+                none: "none";
+                key: "key";
+                bearer: "bearer";
+                basic: "basic";
+            }>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         endpoint: z.ZodOptional<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -116,6 +166,15 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             route: z.ZodOptional<z.ZodString>;
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
+            auth: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<{
+                    none: "none";
+                    key: "key";
+                    bearer: "bearer";
+                    basic: "basic";
+                }>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
@@ -140,6 +199,10 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -148,6 +211,10 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }, "spec" | "overlays">, {
@@ -159,6 +226,10 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -167,6 +238,10 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }>>;

package/dist/types/reference/index.d.ts

@@ -26,7 +26,7 @@ export { graphql } from "./graphql.ts";
 export type { GraphqlAdapter, GraphqlOptions } from "./graphql.ts";
 export { openapi } from "./openapi.ts";
 export type { OpenApiAdapter, OpenApiOptions } from "./openapi.ts";
-export type { GraphqlSourceOptions, PlaygroundOptions, ReferenceSourceOptions, } from "./options.ts";
+export type { GraphqlAuthOptions, GraphqlSourceOptions, PlaygroundOptions, ReferenceSourceOptions, } from "./options.ts";
 export { scalar } from "./scalar.ts";
 export type { ScalarAdapter, ScalarOptions, ScalarSourceOptions, } from "./scalar.ts";
 export type { ReferenceAdapter, ResolvedReferenceAdapter } from "./schema.ts";

package/dist/types/reference/openapi.d.ts

@@ -5,8 +5,8 @@ import type { OpenApiSourceOptions, PlaygroundOptions } from "./options.ts";
 export interface OpenApiOptions {
     /**
      * Code-sample languages generated per operation (Blume renderer), in
-     * order. Defaults to `["curl", "js", "python"]`; `false` generates none, so
-     * only the spec's own `x-codeSamples` show.
+     * order. Defaults to `["curl", "js", "python"]`; `false` (or an empty list)
+     * generates none, so only the spec's own `x-codeSamples` show.
      */
     codeSamples?: string[] | false;
     /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */

package/dist/types/reference/options.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { AuthMethod } from "../components/content/api-page.ts";
 /**
  * A single spec rendered by a reference. `spec` is a local path or an
  * `http(s)` URL (an OpenAPI document for `openapi()`, an AsyncAPI document
@@ -71,10 +72,34 @@ export interface OpenApiSourceOptions extends ReferenceSourceOptions {
      */
     overlays?: string[];
 }
+/**
+ * How a GraphQL endpoint authenticates, in the shape the site's `api.auth`
+ * takes for hand-written endpoints: `bearer`, `basic`, or `key` (sent in the
+ * `name` header, `x-api-key` by default). A schema, unlike an OpenAPI
+ * document, declares no security schemes, so this is what gives the Try it
+ * panel its credential field.
+ */
+export declare const graphqlAuthSchema: z.ZodObject<{
+    method: z.ZodEnum<{
+        none: "none";
+        key: "key";
+        bearer: "bearer";
+        basic: "basic";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The `auth` option of `graphql()` and its sources. */
+export interface GraphqlAuthOptions {
+    /** `bearer`, `basic`, `key`, or `none`. */
+    method: AuthMethod;
+    /** The header an API key goes in. Defaults to `x-api-key`. */
+    name?: string;
+}
 /**
  * A single GraphQL schema: the shared source shape plus `endpoint`, the live
  * GraphQL API URL the playground and code samples target (a schema, unlike an
- * OpenAPI document, names no server).
+ * OpenAPI document, names no server), and `auth`, how that endpoint
+ * authenticates.
  */
 export declare const graphqlSourceSchema: z.ZodObject<{
     includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -84,10 +109,21 @@ export declare const graphqlSourceSchema: z.ZodObject<{
     route: z.ZodOptional<z.ZodString>;
     seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
     spec: z.ZodString;
+    auth: z.ZodOptional<z.ZodObject<{
+        method: z.ZodEnum<{
+            none: "none";
+            key: "key";
+            bearer: "bearer";
+            basic: "basic";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     endpoint: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** One schema source, as `graphql()` accepts it. */
 export interface GraphqlSourceOptions extends ReferenceSourceOptions {
+    /** How the endpoint authenticates; wins over the adapter's `auth`. */
+    auth?: GraphqlAuthOptions;
     /** URL of the live GraphQL endpoint (playground + code samples); wins over the adapter's `endpoint`. */
     endpoint?: string;
 }

package/dist/types/reference/schema.d.ts

@@ -81,6 +81,15 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"graphql">;
     options: z.ZodPipe<z.ZodObject<{
+        auth: z.ZodOptional<z.ZodObject<{
+            method: z.ZodEnum<{
+                none: "none";
+                key: "key";
+                bearer: "bearer";
+                basic: "basic";
+            }>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         endpoint: z.ZodOptional<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -90,6 +99,15 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             route: z.ZodOptional<z.ZodString>;
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
+            auth: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<{
+                    none: "none";
+                    key: "key";
+                    bearer: "bearer";
+                    basic: "basic";
+                }>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
@@ -114,6 +132,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -122,6 +144,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }, "spec" | "overlays">, {
@@ -133,6 +159,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -141,6 +171,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }>>;
@@ -286,6 +320,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -294,6 +332,10 @@ export declare const referenceAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }, "spec" | "overlays">;
@@ -398,6 +440,15 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"graphql">;
     options: z.ZodPipe<z.ZodObject<{
+        auth: z.ZodOptional<z.ZodObject<{
+            method: z.ZodEnum<{
+                none: "none";
+                key: "key";
+                bearer: "bearer";
+                basic: "basic";
+            }>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         endpoint: z.ZodOptional<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             includeInLlms: z.ZodDefault<z.ZodBoolean>;
@@ -407,6 +458,15 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             route: z.ZodOptional<z.ZodString>;
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
+            auth: z.ZodOptional<z.ZodObject<{
+                method: z.ZodEnum<{
+                    none: "none";
+                    key: "key";
+                    bearer: "bearer";
+                    basic: "basic";
+                }>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
         codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
@@ -431,6 +491,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -439,6 +503,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }, "spec" | "overlays">, {
@@ -450,6 +518,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -458,6 +530,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }>>;
@@ -603,6 +679,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
+            auth?: {
+                method: "none" | "key" | "bearer" | "basic";
+                name?: string | undefined;
+            } | undefined;
             endpoint?: string | undefined;
         }[];
         codeSamples: false | string[];
@@ -611,6 +691,10 @@ export declare const referenceConfigSchema: z.ZodDefault<z.ZodArray<z.ZodPipe<z.
             proxy: string | boolean;
         };
         route: string;
+        auth?: {
+            method: "none" | "key" | "bearer" | "basic";
+            name?: string | undefined;
+        } | undefined;
         endpoint?: string | undefined;
         spec?: string | undefined;
     }, "spec" | "overlays">;

package/dist/types/search/adapters/registry.d.ts

@@ -69,6 +69,7 @@ declare const adapterVariants: readonly [z.ZodObject<{
         apiKey: z.ZodString;
         collection: z.ZodString;
         host: z.ZodString;
+        locale: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodNumber>;
         protocol: z.ZodOptional<z.ZodEnum<{
             http: "http";
@@ -141,6 +142,7 @@ export declare const resolvedSearchAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUn
         apiKey: z.ZodString;
         collection: z.ZodString;
         host: z.ZodString;
+        locale: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodNumber>;
         protocol: z.ZodOptional<z.ZodEnum<{
             http: "http";
@@ -212,6 +214,7 @@ export declare const resolvedSearchAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUn
         apiKey: string;
         collection: string;
         host: string;
+        locale?: string | undefined;
         port?: number | undefined;
         protocol?: "http" | "https" | undefined;
     };

package/dist/types/search/adapters/typesense.d.ts

@@ -4,14 +4,22 @@ import type { SearchAdapter } from "./types.ts";
 /**
  * Connection details for a self-hosted or cloud Typesense node. The browser
  * queries the collection with the search-only `apiKey`; the build-time sync
- * recreates the collection with `TYPESENSE_ADMIN_API_KEY`, which never enters
- * the config.
+ * rebuilds it with `TYPESENSE_ADMIN_API_KEY`, which never enters the config.
  */
 export interface TypesenseNamedOptions {
     /** The search-only API key (public — it ships to the browser). */
     apiKey: string;
+    /** The alias the sync points at each new collection, and searches read. */
     collection: string;
     host: string;
+    /**
+     * The language Typesense tokenizes the text fields for, as a two-letter
+     * code (`ja`, `zh`, `ko`, `th`, …). Typesense's default tokenizer splits on
+     * spaces, so text in a script written without them — Chinese, Japanese,
+     * Thai — only matches from the start of a run. Omitted, the fields keep
+     * that default.
+     */
+    locale?: string;
     /** Defaults to 443. */
     port?: number;
     /** Defaults to `https`. */
@@ -29,6 +37,7 @@ export declare const typesenseOptionsSchema: z.ZodObject<{
     apiKey: z.ZodString;
     collection: z.ZodString;
     host: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
     port: z.ZodOptional<z.ZodNumber>;
     protocol: z.ZodOptional<z.ZodEnum<{
         http: "http";
@@ -36,7 +45,8 @@ export declare const typesenseOptionsSchema: z.ZodObject<{
     }>>;
 }, z.core.$catchall<z.ZodJSONSchema>>;
 /**
- * Hosted search on Typesense. Each `blume build` drops and recreates the
- * collection so deleted or renamed pages don't linger as stale hits.
+ * Hosted search on Typesense. Each `blume build` imports into a new
+ * collection and swaps the `collection` alias onto it, so deleted or renamed
+ * pages don't linger as stale hits and searches never read a partial index.
  */
 export declare const typesense: (options: TypesenseOptions) => TypesenseAdapter;

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

@@ -18,6 +18,8 @@
  * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
  * that fix.
  *
- * Returns the number of pages indexed.
+ * Returns the number of pages indexed: the index's own count, summed over its
+ * languages from `pagefind-entry.json`. `addDirectory`'s `page_count` counts
+ * every HTML file it read, including the ones kept out of the index.
  */
 export declare const buildSearchIndex: (outDir: string) => Promise<number>;

package/dist/types/search/orama-index.d.ts

@@ -35,11 +35,11 @@ export interface OramaDoc {
  * so ranking is identical wherever docs are queried. `locale` — the site's
  * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for every
  * non-Latin script, all of which Orama's default tokenizer reduces to zero
- * tokens; the tokenizer belongs to the database, so on a mixed-locale site it
- * applies to every document. That is safe in one direction only: Latin words
+ * tokens. A non-Latin default's tokenizer serves every page: Latin words
  * survive segmentation intact, so English pages on a segmented index stay
- * searchable, but non-Latin translations on a Latin-default index still
- * collapse to zero tokens.
+ * searchable. A Latin default keeps Orama's tokenizer for its Latin-script
+ * pages, and each page in a non-Latin locale (the Japanese and Hindi
+ * translations of an English site) is indexed with its own locale's tokenizer.
  */
 export declare const buildOramaIndex: (documents: OramaDoc[], locale?: string) => Promise<AnyOrama>;
 /** Optional exact-match filters applied to a query via Orama's `where`. */
@@ -65,10 +65,10 @@ export interface OramaQueryFilters {
  * `locale` to one language, `contentTypes` to a set of page types, `facets`
  * to documents carrying every requested `key:value` term.
  *
- * On a bigrammed index the strict pass runs first: a term is only meant to
- * match where its bigrams sit together, and scoring them independently lets a
- * page sharing a couple of windows outrank the page the term is about. Terms
- * spanning several words rarely appear in full on one page, so an empty strict
- * result falls back to the default pass rather than reporting no matches.
+ * On an index whose translations have tokenizers of their own, a query scoped
+ * to a locale is tokenized with that locale's tokenizer. An unscoped query
+ * searches each locale's pages with its own tokenizer, and the Latin-script
+ * pages with Orama's, then merges the matches by score: every search runs over
+ * the one index, so their scores share its term statistics.
  */
 export declare const queryOramaIndex: (db: AnyOrama, term: string, limit: number, filters?: OramaQueryFilters) => Promise<OramaDoc[]>;

package/dist/types/search/sync/algolia.d.ts

@@ -9,8 +9,11 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * hits that 404 when clicked. A page too long for one record is split across
+ * several (see {@link toObjects}). Then adds `filterOnly(locale)` and
  * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
- * the site declared itself, so the dialog's locale and version filters match.
+ * the site declared itself, so the dialog's locale and version filters match,
+ * and, once a page is split, `url` as the index's `attributeForDistinct`
+ * unless the site set its own.
  */
 export declare const syncAlgolia: (records: SearchRecord[], config: AlgoliaSyncConfig) => Promise<void>;

package/dist/types/search/sync/index.d.ts

@@ -9,6 +9,8 @@ export interface SyncReporter {
  * After a build, upload the per-page records to the configured hosted adapter.
  * Reads secret admin keys from the environment; if a key (or option) is
  * missing the sync is skipped with a warning rather than failing the build —
- * CI may sync in a separate step.
+ * a local build has no secrets, and CI may sync in a separate step. Once the
+ * sync is set up, a failure fails the build (`BLUME_SEARCH_SYNC_FAILED`):
+ * the site would otherwise deploy against an index this build didn't update.
  */
 export declare const syncSearchProvider: (project: BlumeProject, reporter: SyncReporter) => Promise<void>;