blume 2.0.3 → 2.1.1

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

@@ -37,6 +37,10 @@ export interface GraphqlTypeRef {
     display: string;
     name: string;
 }
+/** A GraphQL input value as JSON carries it in `variables` (enums by name). */
+export type GraphqlJsonValue = string | number | boolean | null | GraphqlJsonValue[] | {
+    [key: string]: GraphqlJsonValue;
+};
 /** An argument or input-object field. */
 export interface GraphqlInputValue {
     name: string;
@@ -44,6 +48,8 @@ export interface GraphqlInputValue {
     type: GraphqlTypeRef;
     /** Default value printed as a GraphQL literal (`10`, `"asc"`, `[1, 2]`). */
     default?: string;
+    /** The same default as JSON, for the example variables. */
+    defaultValue?: GraphqlJsonValue;
     deprecationReason?: string;
 }
 /** An output field of an object or interface type (root fields included). */

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

@@ -1,4 +1,5 @@
-import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
+import type { Document, OperationObject } from "@scalar/openapi-types/3.2";
+import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { AsyncApiAction, AsyncApiDocument, AsyncApiSpecValue } from "./asyncapi.ts";
 import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
@@ -12,10 +13,18 @@ export { slugify } from "./references.ts";
  * Each operation is flattened into an {@link ApiOperationRef} with a real,
  * per-operation route so it becomes a first-class Blume page.
  */
-/** A normalized OpenAPI 3.1 document, internal `$ref`s intact. */
+/**
+ * A normalized OpenAPI document, internal `$ref`s intact. Typed as 3.2, which
+ * is backward compatible with 3.1, so one type covers both the upgraded 3.1
+ * documents and the 3.2 ones read as written.
+ */
 export type ApiDocument = Document;
-/** The HTTP methods an OpenAPI path item may declare, in spec order. */
-export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/**
+ * The HTTP methods an OpenAPI path item may declare, in spec order. `query`
+ * is OpenAPI 3.2's (the QUERY method: a safe request that carries a body); a
+ * 3.1 path item can't declare it, so listing it changes nothing there.
+ */
+export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace", "query"];
 export type HttpMethod = (typeof HTTP_METHODS)[number];
 /** A stable, URL-safe key for an operation: its `operationId`, else method+path. */
 export declare const operationKey: (method: string, path: string, operationId?: string) => string;
@@ -45,6 +54,12 @@ export interface ApiOperationRef {
     deprecated: boolean;
     /** The channel the operation acts on (AsyncAPI only). */
     channelId?: string;
+    /**
+     * An OpenAPI 3.1 webhook: a request the API sends to the reader's endpoint
+     * rather than one it serves. `path` then holds the webhook's name, the key
+     * it has under the document's `webhooks`.
+     */
+    webhook?: true;
 }
 /**
  * A tag/section: the spec's declared tags in their declared order, then any
@@ -73,11 +88,13 @@ export interface ApiSpecData {
      * (GraphQL only; OpenAPI documents carry their servers in the document).
      */
     endpoint?: string;
+    /** How the GraphQL endpoint authenticates (GraphQL only). */
+    auth?: GraphqlAuthOptions;
     /** Operations keyed by {@link ApiOperationRef.key}. */
     operations: Record<string, ApiOperationRef>;
     tags: ApiTagRef[];
-    /** Code-sample languages to render per operation. */
-    codeSamples: string[];
+    /** Code-sample languages to render per operation; `false` for none. */
+    codeSamples: string[] | false;
     /** Whether nested schema rows start expanded. */
     expandSchemas: boolean;
     /**
@@ -162,10 +179,10 @@ export interface ExtractedOperations extends CollectedOperations {
 export declare const operationCollector: (baseRoute: string, tagMeta: ReadonlyMap<string, string>) => OperationCollector;
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
- * tags. Operations inherit the first tag they declare; keys are de-duplicated so
- * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item, webhooks), so missing operations
- * aren't silent.
+ * tags, webhooks included. Operations inherit the first tag they declare; keys
+ * are de-duplicated so a repeated `operationId` still yields distinct routes.
+ * `warnings` reports anything skipped (a `$ref` path item), so missing
+ * operations aren't silent.
  */
 export declare const extractOperations: (document: ApiDocument, baseRoute: string) => ExtractedOperations;
 /** Resolve the operation object for a ref out of its (OpenAPI) document. */

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

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { JsonValue } from "../core/adapter.ts";
+/**
+ * OpenAPI Overlays: the OpenAPI Initiative's format for changing an API
+ * description without editing it — an ordered list of actions, each an RFC
+ * 9535 JSONPath `target` with an `update` to merge in, a `copy` of another
+ * node to merge in, or `remove`. A spec generated by another tool or owned by
+ * another team can then carry docs-only changes (better descriptions, hidden
+ * internal operations, a public server URL) in a file of its own.
+ *
+ * Implements Overlay Specification 1.0 and 1.1 over `jsonpath-rfc9535`, which
+ * passes the JSONPath compliance suite in full, as the spec requires. The
+ * documents here are already parsed; `parse.ts` reads the files.
+ */
+/** An overlay document or action that doesn't follow the spec. */
+export declare class OverlayError extends Error {
+    constructor(message: string);
+}
+/** An object node, the only kind that holds named properties. */
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * A parsed YAML or JSON mapping, as the document an overlay acts on: the
+ * parser's own types say nothing of JSON, but what it parses is JSON.
+ */
+export declare const isJsonObject: <Value>(value: Value) => value is Value & JsonObject;
+declare const overlaySchema: z.ZodObject<{
+    actions: z.ZodArray<z.ZodObject<{
+        copy: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        remove: z.ZodDefault<z.ZodBoolean>;
+        target: z.ZodString;
+        update: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$loose>>;
+    extends: z.ZodOptional<z.ZodString>;
+    info: z.ZodObject<{
+        title: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>;
+    overlay: z.ZodString;
+}, z.core.$loose>;
+/** A validated overlay document. */
+export type OverlayDocument = z.output<typeof overlaySchema>;
+/** Validate a parsed overlay document, naming the file in any error. */
+export declare const overlayDocument: <Value>(value: Value, name: string) => OverlayDocument;
+/**
+ * Apply an overlay to a parsed document, in place and in action order: each
+ * action sees the result of the one before. A target that matches nothing
+ * changes nothing. Throws an {@link OverlayError} naming the overlay file and
+ * the action that failed.
+ */
+export declare const applyOverlay: (document: JsonValue, overlay: OverlayDocument, name: string) => void;
+export {};

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

@@ -1,8 +1,11 @@
 import type { AsyncApiDocument } from "./asyncapi.ts";
+import type { SpecIssue } from "./checks.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
 export interface ParsedSpec {
     document: ApiDocument;
+    /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+    issues: SpecIssue[];
     warnings: string[];
 }
 /**
@@ -16,6 +19,11 @@ export declare class InvalidSpecError extends Error {
 }
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
+    /**
+     * Overlay documents (local paths or `http(s)` URLs) applied in order to
+     * the parsed spec, before it's upgraded. See `overlay.ts`.
+     */
+    overlays?: readonly string[];
     /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
     cacheDir?: string;
     /**
@@ -24,6 +32,14 @@ export interface SpecFetchOptions {
      */
     refresh?: boolean;
 }
+/**
+ * A spec with its overlays applied, as JSON text: what the Scalar embed
+ * inlines, since it can't apply overlays itself.
+ */
+export declare const readOverlaidSpec: (spec: string, root: string, options: SpecFetchOptions) => Promise<{
+    text: string;
+    warnings: string[];
+}>;
 export declare const parseSpec: (spec: string, root: string, options?: SpecFetchOptions) => Promise<ParsedSpec>;
 export interface ParsedAsyncApiSpec {
     document: AsyncApiDocument;

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

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { ScalarOptions } from "../reference/scalar.ts";
 import type { ResolvedReferenceAdapter } from "../reference/schema.ts";
 export { normalizeRoute } from "../core/base-path.ts";
@@ -19,8 +20,8 @@ export type ReferenceKind = ResolvedReferenceAdapter["kind"];
 export type BlumeReferenceKind = Exclude<ReferenceKind, "scalar">;
 /** Per-adapter display options for the Blume renderer. */
 export interface ReferenceDisplay {
-    /** Code-sample languages shown per operation. */
-    codeSamples: string[];
+    /** Code-sample languages shown per operation; `false` for none. */
+    codeSamples: string[] | false;
     /** Whether nested schema rows start expanded. */
     expandSchemas: boolean;
     /**
@@ -47,6 +48,12 @@ export interface ReferenceSource {
      */
     basePath: string;
     label: string;
+    /**
+     * The source's own `label`, when it sets one: it names the sidebar group
+     * of the source's route. An unlabeled source's group keeps the name its
+     * route gives it.
+     */
+    groupLabel?: string;
     /** Whether generated pages are included in llms.txt/llms-full.txt. */
     includeInLlms: boolean;
     /** Whether generated pages are included in site search. */
@@ -60,11 +67,18 @@ export interface ReferenceSource {
     seoDescriptionSuffix: boolean;
     /** Local path or `http(s)` URL, verbatim from config. */
     spec: string;
+    /**
+     * OpenAPI Overlay documents applied to `spec` in order (`openapi()` and
+     * `scalar()` only).
+     */
+    overlays?: string[];
     /**
      * URL of the live GraphQL endpoint the playground and code samples target
      * (GraphQL only — a schema, unlike an OpenAPI document, names no server).
      */
     endpoint?: string;
+    /** How the GraphQL endpoint authenticates (GraphQL only). */
+    auth?: GraphqlAuthOptions;
     /**
      * The `scalar()` adapter's own options (`scalar` kind only): `theme` plus
      * any Scalar config forwarded verbatim to `<ScalarComponent>`, which takes
@@ -107,6 +121,13 @@ export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSou
 export declare const referenceRoutes: (config: ResolvedConfig) => string[];
 /** Blume-rendered references (every kind but Scalar), deduped by route (first wins). */
 export declare const blumeReferences: (config: ResolvedConfig) => BlumeReferenceSource[];
+/**
+ * The local files every reference reads, as absolute paths: each spec and
+ * overlay that isn't an `http(s)` URL, resolved from the project root the way
+ * the parser resolves them. `blume dev` watches these, so an edit to a spec
+ * regenerates its reference like an edit to a page does.
+ */
+export declare const referenceSpecFiles: (config: ResolvedConfig, root: string) => string[];
 /** Whether any reference is Scalar-rendered (gates the Scalar pages). */
 export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;
 /**
@@ -120,10 +141,15 @@ export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;
  * definition with {@link needsPlaygroundProxy}.
  */
 export declare const builtinProxyReferences: (config: ResolvedConfig) => BlumeReferenceSource[];
+/**
+ * Whether hand-written endpoint pages (`api` frontmatter) send their Try it
+ * requests through the built-in proxy: `api.playground.proxy: true`.
+ */
+export declare const apiPagesUseBuiltinProxy: (config: ResolvedConfig) => boolean;
 /**
  * Whether the built-in playground CORS proxy endpoint (`/_api-proxy`) must be
  * generated: some Blume-rendered reference's playground opted into it with
- * `proxy: true`. Shared by the server feature gate and the generator so the
- * two can never disagree.
+ * `proxy: true`, or the hand-written endpoint pages' did. Shared by the server
+ * feature gate and the generator so the two can never disagree.
  */
 export declare const needsPlaygroundProxy: (config: ResolvedConfig) => boolean;

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

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+/** The Worker binding Blume declares for the rate limiter. */
+export declare const RATE_LIMIT_BINDING = "BLUME_RATE_LIMIT";
+/** Options for {@link cloudflare}. */
+export interface CloudflareRateLimitOptions {
+    /**
+     * The rate limiting namespace, a positive integer unique in your
+     * Cloudflare account. Defaults to one derived from the site.
+     */
+    namespaceId?: string;
+    /** Requests each reader may make per window, per route. Defaults to 10. */
+    requests?: number;
+    /** The window, in seconds: Cloudflare allows 10 or 60. Defaults to 60. */
+    window?: 10 | 60;
+}
+export declare const cloudflareRateLimitOptionsSchema: 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>;
+export type CloudflareRateLimitAdapter = AdapterDescriptor<"cloudflare", CloudflareRateLimitOptions>;
+export declare const cloudflareRateLimitAdapterSchema: 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>;
+/**
+ * Counts with Cloudflare's Workers rate limiting, for a site deployed with
+ * `deployment: cloudflare()`: Blume declares the binding in the Worker's
+ * config, so there is nothing to set up. Cloudflare counts per location and
+ * allows a window of 10 or 60 seconds.
+ */
+export declare const cloudflare: (options?: CloudflareRateLimitOptions) => CloudflareRateLimitAdapter;

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

@@ -0,0 +1,27 @@
+/**
+ * Rate limiters for `blume.config.ts`. The server routes a reader can call —
+ * the assistant, the API playground proxy, and server-side search — limit
+ * each reader (by IP address) to a number of requests per window, answering
+ * `429 Too Many Requests` past it:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { upstash } from "blume/ratelimit";
+ *
+ * export default defineConfig({
+ *   rateLimit: upstash({ requests: 30, window: 600 }),
+ * });
+ * ```
+ *
+ * `memory()` is on by default; `rateLimit: false` turns limiting off. Each
+ * factory returns a plain descriptor (see `core/adapter.ts`), and the
+ * generated routes count with `runtime.ts`.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { cloudflare } from "./cloudflare.ts";
+export type { CloudflareRateLimitAdapter, CloudflareRateLimitOptions, } from "./cloudflare.ts";
+export { memory } from "./memory.ts";
+export type { MemoryAdapter, RateLimitOptions } from "./memory.ts";
+export type { RateLimitAdapter } from "./schema.ts";
+export { upstash } from "./upstash.ts";
+export type { UpstashAdapter, UpstashOptions } from "./upstash.ts";

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

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+/** How many requests a reader gets per window, unless set. */
+export declare const DEFAULT_REQUESTS = 30;
+/** The window those requests are counted over, in seconds, unless set. */
+export declare const DEFAULT_WINDOW = 600;
+/** The limit every rate limiter takes: a count of requests per window. */
+export interface RateLimitOptions {
+    /** Requests each reader may make per window, per route. */
+    requests?: number;
+    /** The window, in seconds. */
+    window?: number;
+}
+export declare const rateLimitOptionsSchema: z.ZodObject<{
+    requests: z.ZodOptional<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MemoryAdapter = AdapterDescriptor<"memory", RateLimitOptions>;
+export declare const memoryAdapterSchema: 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>;
+/**
+ * Counts each reader's requests in the server's own memory, the default. On
+ * a server that runs as one process (`node()`) the count is exact; on a
+ * platform that runs many short-lived instances (Vercel, Netlify,
+ * Cloudflare) each instance keeps its own, so it stops a burst from one
+ * reader rather than enforcing the limit exactly. For that, share the count
+ * with `upstash()` or `cloudflare()`.
+ */
+export declare const memory: (options?: RateLimitOptions) => MemoryAdapter;

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

@@ -0,0 +1,119 @@
+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>;
+        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>], "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>;
+        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>], "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;
+        tokenEnv?: string | undefined;
+        urlEnv?: string | 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;
+        tokenEnv?: string | undefined;
+        urlEnv?: string | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | undefined>>;

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

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { RateLimitOptions } from "./memory.ts";
+/** 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`, or the env vars
+ * `urlEnv` and `tokenEnv` name.
+ */
+export declare const upstash: (options?: UpstashOptions) => 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;