blume 2.0.2 → 2.1.0

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

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/** The configured rate limiter, as its factory returned it. */
+export declare const rateLimitAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        namespaceId: z.ZodOptional<z.ZodString>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"memory">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upstash">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export type RateLimitAdapter = z.output<typeof rateLimitAdapterSchema>;
+/**
+ * `blume.config.rateLimit`: how the server routes a reader can call (the
+ * assistant, the API playground proxy, server-side search) limit requests
+ * per reader. On by default with `memory()`; `false` turns it off (`null`
+ * once resolved).
+ */
+export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        namespaceId: z.ZodOptional<z.ZodString>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<60>]>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"memory">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upstash">;
+    options: z.ZodObject<{
+        requests: z.ZodOptional<z.ZodNumber>;
+        window: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "kind">]>>, z.ZodTransform<{
+    kind: "cloudflare";
+    options: {
+        namespaceId?: string | undefined;
+        requests?: number | undefined;
+        window?: 10 | 60 | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "memory";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "upstash";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | null, false | {
+    kind: "cloudflare";
+    options: {
+        namespaceId?: string | undefined;
+        requests?: number | undefined;
+        window?: 10 | 60 | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "memory";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "upstash";
+    options: {
+        requests?: number | undefined;
+        window?: number | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | undefined>>;

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

@@ -0,0 +1,21 @@
+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>;
+/**
+ * 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`.
+ */
+export declare const upstash: (options?: RateLimitOptions) => UpstashAdapter;

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

@@ -0,0 +1,23 @@
+import type { CloudflareRateLimitAdapter } from "./cloudflare.ts";
+/** The Workers rate limiting binding, as the Worker's config declares it. */
+export interface RateLimitBindingConfig {
+    name: string;
+    namespace_id: string;
+    simple: {
+        limit: number;
+        period: 10 | 60;
+    };
+}
+/**
+ * A namespace id for a Worker that sets none: a positive integer derived from
+ * its name, so two Blume sites on one account don't share one.
+ */
+export declare const rateLimitNamespace: (workerName: string) => string;
+/** The binding `cloudflare()` asks for, on the Worker named `workerName`. */
+export declare const rateLimitBinding: (adapter: CloudflareRateLimitAdapter, workerName: string) => RateLimitBindingConfig;
+/**
+ * The built Worker's config (`dist/server/wrangler.json`) with Blume's rate
+ * limiting binding in `ratelimits`, replacing an earlier one of the same name
+ * and keeping any others. `null` when the config isn't a JSON object.
+ */
+export declare const withRateLimitBinding: (wranglerText: string, adapter: CloudflareRateLimitAdapter) => string | null;

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

@@ -5,9 +5,9 @@ import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
 export interface AsyncApiOptions {
     /**
      * Code-sample tools shown per operation (Blume renderer). Defaults to every
-     * tool appropriate to the operation's protocol binding.
+     * tool appropriate to the operation's protocol binding; `false` shows none.
      */
-    codeSamples?: string[];
+    codeSamples?: string[] | false;
     /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
     expandSchemas?: boolean;
     /**
@@ -34,7 +34,7 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
         spec: z.ZodString;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -58,14 +58,14 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     expandSchemas: boolean;
     sources: {
         includeInLlms: boolean;
@@ -76,7 +76,7 @@ export declare const asyncapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -102,7 +102,7 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -126,14 +126,14 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         expandSchemas: boolean;
         sources: {
             includeInLlms: boolean;
@@ -144,7 +144,7 @@ export declare const asyncapiAdapterSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;

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

@@ -3,8 +3,11 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 import type { GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
 /** Options for {@link graphql}. */
 export interface GraphqlOptions {
-    /** Code-sample languages shown per operation. Defaults to `["curl", "js", "python"]`. */
-    codeSamples?: string[];
+    /**
+     * Code-sample languages shown per operation, in order. Defaults to
+     * `["curl", "js", "python"]`; `false` shows none.
+     */
+    codeSamples?: string[] | false;
     /**
      * URL of the live GraphQL endpoint the playground and code samples target —
      * a schema, unlike an OpenAPI document, names no server. Applies to every
@@ -44,7 +47,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         spec: z.ZodString;
         endpoint: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -68,7 +71,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         route?: string | undefined;
         endpoint?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -76,7 +79,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
     route: string;
     endpoint?: string | undefined;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     sources: {
         includeInLlms: boolean;
         includeInSearch: boolean;
@@ -87,7 +90,7 @@ export declare const graphqlOptionsSchema: z.ZodPipe<z.ZodObject<{
         route?: string | undefined;
         endpoint?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
@@ -115,7 +118,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             spec: z.ZodString;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -139,7 +142,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
@@ -147,7 +150,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
         route: string;
         endpoint?: string | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         sources: {
             includeInLlms: boolean;
             includeInSearch: boolean;
@@ -158,7 +161,7 @@ export declare const graphqlAdapterSchema: z.ZodObject<{
             route?: string | undefined;
             endpoint?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;

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

@@ -1,10 +1,14 @@
 import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.ts";
-import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
+import type { OpenApiSourceOptions, PlaygroundOptions } from "./options.ts";
 /** Options for {@link openapi}. */
 export interface OpenApiOptions {
-    /** Code-sample languages shown per operation (Blume renderer). Defaults to `["curl", "js", "python"]`. */
-    codeSamples?: string[];
+    /**
+     * 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.
+     */
+    codeSamples?: string[] | false;
     /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
     expandSchemas?: boolean;
     /**
@@ -15,15 +19,21 @@ export interface OpenApiOptions {
      * `vercel()` in `deployment`).
      */
     playground?: PlaygroundOptions;
+    /**
+     * OpenAPI Overlay documents for `spec`, applied in order before it renders.
+     * With `sources`, each source takes its own `overlays`.
+     */
+    overlays?: string[];
     /** Where the reference mounts. Defaults to `/reference`. */
     route?: string;
     /** One or more specs; each renders on its own route by default. */
-    sources?: ReferenceSourceOptions[];
+    sources?: OpenApiSourceOptions[];
     /** Shorthand for a single source: `sources: [{ spec }]`. */
     spec?: string;
 }
 export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
     expandSchemas: z.ZodDefault<z.ZodBoolean>;
+    overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
         includeInLlms: z.ZodDefault<z.ZodBoolean>;
         includeInSearch: z.ZodDefault<z.ZodBoolean>;
@@ -32,8 +42,9 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         route: z.ZodOptional<z.ZodString>;
         seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
         spec: z.ZodString;
+        overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -54,17 +65,19 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         noindex: boolean;
         seoDescriptionSuffix: boolean;
         spec: string;
+        overlays: string[];
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
+    overlays?: string[] | undefined;
     spec?: string | undefined;
-}, "spec">, {
+}, "spec" | "overlays">, {
     expandSchemas: boolean;
     sources: {
         includeInLlms: boolean;
@@ -72,15 +85,17 @@ export declare const openapiOptionsSchema: z.ZodPipe<z.ZodObject<{
         noindex: boolean;
         seoDescriptionSuffix: boolean;
         spec: string;
+        overlays: string[];
         label?: string | undefined;
         route?: string | undefined;
     }[];
-    codeSamples: string[];
+    codeSamples: false | string[];
     playground: {
         enabled: boolean;
         proxy: string | boolean;
     };
     route: string;
+    overlays?: string[] | undefined;
     spec?: string | undefined;
 }>>;
 /** `openapi()` options with every default applied and `spec` folded into `sources`. */
@@ -92,6 +107,7 @@ export declare const openapiAdapterSchema: z.ZodObject<{
     kind: z.ZodLiteral<"openapi">;
     options: z.ZodPipe<z.ZodObject<{
         expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             includeInLlms: z.ZodDefault<z.ZodBoolean>;
             includeInSearch: z.ZodDefault<z.ZodBoolean>;
@@ -100,8 +116,9 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             route: z.ZodOptional<z.ZodString>;
             seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>>;
-        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
         playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
@@ -122,17 +139,19 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             noindex: boolean;
             seoDescriptionSuffix: boolean;
             spec: string;
+            overlays: string[];
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
+        overlays?: string[] | undefined;
         spec?: string | undefined;
-    }, "spec">, {
+    }, "spec" | "overlays">, {
         expandSchemas: boolean;
         sources: {
             includeInLlms: boolean;
@@ -140,15 +159,17 @@ export declare const openapiAdapterSchema: z.ZodObject<{
             noindex: boolean;
             seoDescriptionSuffix: boolean;
             spec: string;
+            overlays: string[];
             label?: string | undefined;
             route?: string | undefined;
         }[];
-        codeSamples: string[];
+        codeSamples: false | string[];
         playground: {
             enabled: boolean;
             proxy: string | boolean;
         };
         route: string;
+        overlays?: string[] | undefined;
         spec?: string | undefined;
     }>>;
     requiredSecrets: z.ZodArray<z.ZodString>;

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

@@ -36,6 +36,41 @@ export interface ReferenceSourceOptions {
 }
 /** A spec source with every default applied. */
 export type ResolvedReferenceSource = z.output<typeof referenceSourceSchema>;
+/**
+ * [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html) documents
+ * (local paths or `http(s)` URLs) applied in order to an OpenAPI spec before
+ * it renders: changes to a spec you don't edit by hand.
+ */
+export declare const overlaysSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
+/** Whether adapter-level `overlays` has the `spec` it belongs to. */
+export declare const overlaysHaveSpec: (options: {
+    overlays?: string[];
+    spec?: string;
+}) => boolean;
+/** The refinement issue for `overlays` set beside `sources` instead of `spec`. */
+export declare const overlaysNeedSpecIssue: {
+    message: string;
+    path: string[];
+};
+/** An OpenAPI spec source: the shared shape plus its `overlays`. */
+export declare const openapiSourceSchema: z.ZodObject<{
+    includeInLlms: z.ZodDefault<z.ZodBoolean>;
+    includeInSearch: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
+    spec: z.ZodString;
+    overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** One OpenAPI spec source, as `openapi()` accepts it. */
+export interface OpenApiSourceOptions extends ReferenceSourceOptions {
+    /**
+     * OpenAPI Overlay documents (local paths or `http(s)` URLs) applied in
+     * order to the spec before it renders.
+     */
+    overlays?: 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
@@ -110,8 +145,11 @@ export declare const sharedOptions: (defaults: {
     codeSamples: string[];
     route: string;
 }) => {
-    /** Code-sample languages/tools shown per operation (Blume renderer). */
-    codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /**
+     * Code-sample languages/tools shown per operation (Blume renderer), or
+     * `false` for none: only the spec's own `x-codeSamples` then.
+     */
+    codeSamples: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodString>]>>;
     /** The "Try it" panel; see {@link playgroundSchema}. */
     playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -129,8 +167,9 @@ export declare const sharedOptions: (defaults: {
     spec: z.ZodOptional<z.ZodString>;
 };
 /**
- * Resolve the `spec` shorthand into `sources` so downstream code reads one
- * field: the shorthand becomes the first source (with the source defaults
+ * Resolve the `spec` shorthand (and, on OpenAPI kinds, the `overlays` beside
+ * it) into `sources` so downstream code reads one field: the shorthand becomes
+ * the first source (with the source defaults
  * applied through the source schema itself, so the two can never drift) and
  * the `spec` key is dropped. An adapter with neither renders nothing, which
  * is a config mistake rather than a choice — `refine` it away with
@@ -143,7 +182,8 @@ export declare const liftSpec: <Source extends {
 }>) => <Options extends {
     sources: Source[];
     spec?: string;
-}>({ spec, ...options }: Options) => Omit<Options, "spec">;
+    overlays?: string[];
+}>({ overlays, spec, ...options }: Options) => Omit<Options, "spec" | "overlays">;
 /** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */
 export declare const hasSources: (options: {
     sources: {

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

@@ -15,6 +15,7 @@ export declare const SCALAR_RUNTIME_DEPS: readonly string[];
 export declare const scalarSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
+    overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
     route: z.ZodOptional<z.ZodString>;
     spec: z.ZodString;
 }, z.core.$strict>;
@@ -24,6 +25,8 @@ export interface ScalarSourceOptions {
     label?: string;
     /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
     noindex?: boolean;
+    /** OpenAPI Overlay documents applied in order to the document before it's embedded. */
+    overlays?: string[];
     /** Per-source route; defaults to the adapter's `route` (or a derived path). */
     route?: string;
     /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -44,6 +47,8 @@ export type ResolvedScalarOptions = {
 };
 /** The options {@link scalar} maps itself. */
 export interface ScalarNamedOptions {
+    /** OpenAPI Overlay documents for `spec`; with `sources`, each takes its own. */
+    overlays?: string[];
     /** Where the reference mounts. Defaults to `/reference`. */
     route?: string;
     /** One or more documents; each renders on its own route by default. */
@@ -73,10 +78,12 @@ export type ScalarOptions = ScalarNamedOptions & {
  * the named ones is Scalar configuration and passes through untouched.
  */
 export declare const scalarOptionsSchema: z.ZodPipe<z.ZodObject<{
+    overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
     route: z.ZodDefault<z.ZodString>;
     sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         noindex: z.ZodDefault<z.ZodBoolean>;
+        overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
         route: z.ZodOptional<z.ZodString>;
         spec: z.ZodString;
     }, z.core.$strict>>>;
@@ -87,10 +94,12 @@ export declare const scalarOptionsSchema: z.ZodPipe<z.ZodObject<{
     route: string;
     sources: {
         noindex: boolean;
+        overlays: string[];
         spec: string;
         label?: string | undefined;
         route?: string | undefined;
     }[];
+    overlays?: string[] | undefined;
     spec?: string | undefined;
     theme?: string | undefined;
 }>>;
@@ -100,10 +109,12 @@ export type ResolvedScalarAdapter = AdapterDescriptor<"scalar", ResolvedScalarOp
 export declare const scalarAdapterSchema: z.ZodObject<{
     kind: z.ZodLiteral<"scalar">;
     options: z.ZodPipe<z.ZodObject<{
+        overlays: z.ZodOptional<z.ZodArray<z.ZodString>>;
         route: z.ZodDefault<z.ZodString>;
         sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
+            overlays: z.ZodDefault<z.ZodArray<z.ZodString>>;
             route: z.ZodOptional<z.ZodString>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
@@ -114,10 +125,12 @@ export declare const scalarAdapterSchema: z.ZodObject<{
         route: string;
         sources: {
             noindex: boolean;
+            overlays: string[];
             spec: string;
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        overlays?: string[] | undefined;
         spec?: string | undefined;
         theme?: string | undefined;
     }>>;