blume 2.0.2 → 2.1.0

package/dist/types/markdown/mdast.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Minimal structural types and node builders for the (alpha) Satteri MDAST
+ * plugin API. We model only what Blume's plugins read and construct; the full
+ * types live in `satteri`, a transitive dependency. Plugins are bridged to
+ * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
+ */
+/**
+ * A property value on an MDAST node: primitives, nested nodes, and lists of
+ * either. Covers everything Blume's plugins read or build (positions, data
+ * flags, attribute lists) without admitting functions or class instances.
+ */
+export type MdastValue = string | number | boolean | null | undefined | MdastValue[] | {
+    [key: string]: MdastValue;
+};
+/**
+ * The visitor context Blume's plugins use to mutate the tree. A list of
+ * nodes takes the replaced node's place in order.
+ */
+export interface MdastVisitorContext {
+    replaceNode: (node: MdastNode, replacement: MdastNode | MdastNode[]) => void;
+}
+/** Any MDAST node, keyed loosely since we build a small subset by hand. */
+export interface MdastNode {
+    type: string;
+    [key: string]: MdastValue;
+}
+/** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
+export declare const jsxAttribute: (name: string, value?: string | null) => {
+    name: string;
+    type: string;
+    value: string | null;
+};
+type JsxAttribute = ReturnType<typeof jsxAttribute>;
+/** Build a block-level MDX JSX element (`<Name>…</Name>`). */
+export declare const jsxFlowElement: (name: string, attributes: JsxAttribute[], children: MdastValue[]) => {
+    attributes: {
+        name: string;
+        type: string;
+        value: string | null;
+    }[];
+    children: MdastValue[];
+    name: string;
+    type: string;
+};
+/** Build an inline MDX JSX element (phrasing context). */
+export declare const jsxTextElement: (name: string, attributes: JsxAttribute[], children?: MdastValue[]) => {
+    attributes: {
+        name: string;
+        type: string;
+        value: string | null;
+    }[];
+    children: MdastValue[];
+    name: string;
+    type: string;
+};
+/** Build a fenced code block node, optionally with a fence-meta string. */
+export declare const codeBlock: (lang: string, value: string, meta?: string | null) => {
+    lang: string;
+    meta: string | null;
+    type: string;
+    value: string;
+};
+export {};

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

@@ -0,0 +1,70 @@
+import { HTMLElement } from "node-html-parser";
+import type { Node } from "node-html-parser";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ProjectContext } from "../core/types.ts";
+import type { NarrationProvider } from "./provider.ts";
+import type { NarrationCues, NarrationTree } from "./script.ts";
+/**
+ * Generated narration: after Astro writes the HTML, read every page that
+ * carries the player exactly as the browser will (same walker, same blocks),
+ * split it into sentences, and give each sentence a clip from the configured
+ * speech model. Clips are cached by what decides their sound (text, language,
+ * model, voice, instructions, provider options), so a rebuild only pays for
+ * sentences that changed, and one sentence shared by many pages is generated
+ * once. Each page gets a manifest listing its clips; the player plays them in
+ * order and falls back to browser voices wherever a manifest is missing.
+ */
+/** How the build logs: the integration's Astro logger. */
+export interface NarrationLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+}
+/** Speak `text` in `lang`, returning MP3 bytes. */
+export type Speak = (text: string, lang: string) => Promise<Uint8Array>;
+/** What a narration build did, for the log line and tests. */
+export interface NarrationBuildResult {
+    /** Clips that failed to generate; their pages get no manifest. */
+    failed: number;
+    /** Clips generated by the speech model on this build. */
+    generated: number;
+    /** Pages that got a manifest. */
+    pages: number;
+    /** Clips read back from the cache. */
+    reused: number;
+}
+/**
+ * The clip cache directory: `node_modules/.cache/blume/narration`, next to the
+ * OG card cache and restored by the same host build caches (see `ogCacheDir`).
+ */
+export declare const narrationCacheDir: (context: Pick<ProjectContext, "outDir" | "root">) => string;
+/** The walker's view of a node-html-parser tree. */
+export declare const htmlTree: NarrationTree<Node>;
+/** The player's settings on a built page, and the article it reads. */
+interface PlayerPage {
+    article: HTMLElement;
+    audioBase: string;
+    cues: NarrationCues;
+    lang: string;
+    manifest: string;
+}
+/**
+ * The generated player on a built page, or `null` when the page has none (or
+ * a player without generated audio, which reads with browser voices).
+ */
+export declare const readPlayerPage: (html: string) => PlayerPage | null;
+/**
+ * A clip's cache key: a digest of everything that decides how it sounds. The
+ * Blume version is deliberately left out, unlike the OG card's: an upgrade
+ * shouldn't pay to regenerate audio that would sound the same.
+ */
+export declare const clipKey: (provider: NarrationProvider, lang: string, text: string) => string;
+/** Speak through the Vercel AI Gateway with the provider's model and voice. */
+export declare const gatewaySpeaker: (provider: NarrationProvider) => Speak;
+/**
+ * Generate the narration for a built site in `distDir`: a clip per sentence
+ * and a manifest per page. Does nothing unless `narration.provider` is set,
+ * and warns instead of generating when the provider's key is missing (the
+ * pages then read with browser voices). `speak` replaces the gateway call.
+ */
+export declare const buildNarration: (project: BlumeProject, distDir: string, logger: NarrationLogger, speak?: Speak) => Promise<NarrationBuildResult | null>;
+export {};

package/dist/types/narration/provider.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+/** The speech model narration uses when `gateway()` names none. */
+export declare const DEFAULT_NARRATION_MODEL = "openai/tts-1-hd";
+/** The voice narration uses when `gateway()` names none. */
+export declare const DEFAULT_NARRATION_VOICE = "alloy";
+/**
+ * `narration.provider`: the `gateway()` descriptor from `blume/ai`, read with
+ * speech defaults. `reasoning` is an assistant option and is rejected here;
+ * `voice` and `instructions` are narration options and are rejected by the
+ * assistant.
+ */
+export declare const narrationProviderSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"gateway">;
+    options: z.ZodObject<{
+        instructions: z.ZodOptional<z.ZodString>;
+        model: z.ZodDefault<z.ZodString>;
+        voice: z.ZodDefault<z.ZodString>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** A validated narration provider, defaults filled in. */
+export type NarrationProvider = z.output<typeof narrationProviderSchema>;

package/dist/types/narration/script.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Narration's reading script: what "Listen to this page" says, in order, and
+ * where each spoken sentence sits in the page's text.
+ *
+ * One walker serves both sides. `blume build` runs it over the built HTML
+ * (parsed with node-html-parser) to generate a clip per sentence, and the
+ * player runs it over the live `<article>` to highlight the sentence being
+ * read. Both see the same markup and apply the same rules, so they agree on
+ * every block's text; the sentence split is only ever computed once per
+ * engine (by the build for generated audio, by the browser for its own
+ * voices), so an ICU difference between Node and the browser can't move a
+ * highlight.
+ *
+ * The rules follow what reads well aloud: the title, description, headings,
+ * and prose are read in order; callouts, steps, tabs, and collapsible
+ * sections are announced with a short spoken cue; code, tables, media,
+ * diagrams, math, API field tables, and anything marked
+ * `data-blume-narration="skip"` are left out.
+ */
+/**
+ * The slice of a DOM-like tree the walker reads. The browser DOM and
+ * node-html-parser both satisfy it through a small adapter, so the walker
+ * never touches either API directly.
+ */
+export interface NarrationTree<N> {
+    /** An element's attribute, or `null` when it is absent. */
+    attr: (node: N, name: string) => string | null;
+    children: (node: N) => readonly N[];
+    /** An element's lowercase tag name; `null` for text and other nodes. */
+    tag: (node: N) => string | null;
+    /** A text node's decoded text; `null` for elements and other nodes. */
+    text: (node: N) => string | null;
+}
+/**
+ * The spoken cues, already localized for the page. `{n}` in `step` is the
+ * step's number and `{title}` in `tab` is the tab's label. An empty string
+ * silences that cue.
+ */
+export interface NarrationCues {
+    danger: string;
+    info: string;
+    note: string;
+    section: string;
+    step: string;
+    success: string;
+    tab: string;
+    tip: string;
+    warning: string;
+}
+/**
+ * A run of text read as one unit: a paragraph, heading, list item, or any
+ * other block. `nodes` are the text nodes it was read from; `nodeOf[i]` and
+ * `offsetOf[i]` locate character `i` of `text` in them, so a sentence's
+ * `[start, end)` maps back to a DOM range for highlighting.
+ */
+export interface NarrationBlock<N> {
+    nodeOf: number[];
+    nodes: N[];
+    offsetOf: number[];
+    text: string;
+}
+/** One step of the reading order: a spoken cue, or a block of page text. */
+export type NarrationItem = {
+    block: number;
+    kind: "block";
+} | {
+    kind: "cue";
+    text: string;
+};
+/** What {@link extractNarration} reads from a page. */
+export interface NarrationExtract<N> {
+    blocks: NarrationBlock<N>[];
+    items: NarrationItem[];
+}
+/**
+ * One spoken unit. A sentence carries its block and its `[start, end)` in
+ * that block's text; a cue carries `block: null`. `text` is what is spoken.
+ */
+export interface NarrationSegment {
+    block: number | null;
+    end: number;
+    start: number;
+    text: string;
+}
+/**
+ * The per-page manifest `blume build` writes for generated narration. The
+ * player aligns `blocks` (the build's block texts) with the live page by
+ * text, then plays one clip per segment. A sentence names its block and range;
+ * a cue carries its spoken `text` instead.
+ */
+export interface NarrationManifest {
+    blocks: string[];
+    segments: NarrationManifestSegment[];
+    version: 1;
+}
+/** One clip of a {@link NarrationManifest}: a sentence or a cue. */
+export type NarrationManifestSegment = {
+    audio: string;
+    block: number;
+    end: number;
+    start: number;
+} | {
+    audio: string;
+    text: string;
+};
+/**
+ * A page needs at least this many spoken characters (title and description
+ * included) to offer narration: roughly 50 English words. Shorter pages, and
+ * pages that are mostly code, tables, or API fields, get no player.
+ */
+export declare const NARRATION_MIN_CHARS = 280;
+/**
+ * Sentences longer than this are split at a clause, then a word boundary.
+ * Browser speech engines drop an utterance that runs past about 15 seconds,
+ * and shorter clips also keep the highlight moving.
+ */
+export declare const NARRATION_MAX_SEGMENT_CHARS = 220;
+/** The attribute that keeps an element (and everything in it) out of narration. */
+export declare const NARRATION_SKIP_ATTRIBUTE = "data-blume-narration";
+/**
+ * Walk `root` and return its reading order: each block of text, with the
+ * cues that introduce callouts, steps, tabs, and collapsible sections.
+ * Whitespace collapses to single spaces, as it renders.
+ */
+export declare const extractNarration: <N>(root: N, tree: NarrationTree<N>, cues: NarrationCues) => NarrationExtract<N>;
+/**
+ * Split an extract into spoken segments: a cue as it is, and each block into
+ * its sentences for `lang` (long ones broken further, see
+ * {@link NARRATION_MAX_SEGMENT_CHARS}).
+ */
+export declare const segmentNarration: <N>(extract: NarrationExtract<N>, lang: string, max?: number) => NarrationSegment[];
+/** How many characters the page's blocks will speak, cues excluded. */
+export declare const narrationLength: <N>(extract: NarrationExtract<N>) => number;
+/** Whether a page has enough prose to offer narration. */
+export declare const isNarratable: <N>(extract: NarrationExtract<N>) => boolean;
+/**
+ * Characters read per second at 1x: about 170 words a minute for
+ * space-separated scripts, and a slower character rate where a character is a
+ * word or more. Estimates only; neither engine reports durations up front.
+ */
+export declare const narrationCharsPerSecond: (lang: string) => number;
+/** The page's estimated listening time at 1x, in whole minutes (at least 1). */
+export declare const narrationMinutes: (chars: number, lang: string) => number;
+/**
+ * Map each manifest block onto the live page's blocks by exact text, in
+ * order, skipping page blocks the build didn't see (a script may have added
+ * some). A manifest block with no match maps to `-1`: its sentences still
+ * play, without a highlight.
+ */
+export declare const alignBlocks: (manifestBlocks: readonly string[], pageBlocks: readonly string[]) => number[];
+/** Whether a value (the player's `data-cues` JSON) is a full set of cues. */
+export declare const isNarrationCues: (value: unknown) => value is NarrationCues;
+/** Whether a fetched manifest has the shape the player plays. */
+export declare const isNarrationManifest: (value: unknown) => value is NarrationManifest;

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

@@ -34,7 +34,8 @@ export interface AsyncApiChannelObject {
     messages?: Record<string, AsyncApiRefLike>;
     parameters?: Record<string, AsyncApiRefLike>;
     servers?: AsyncApiRefLike[];
-    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+    bindings?: Record<string, AsyncApiSpecValue>;
     [key: string]: AsyncApiSpecValue;
 }
 /** A permissive view of an AsyncAPI 3.x operation — only the fields we render. */
@@ -51,7 +52,8 @@ export interface AsyncApiOperationObject {
     }[];
     security?: AsyncApiRefLike[];
     messages?: AsyncApiRefLike[];
-    bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+    /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+    bindings?: Record<string, AsyncApiSpecValue>;
     [key: string]: AsyncApiSpecValue;
 }
 /** A permissive view of an AsyncAPI 3.x server object. */

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

@@ -45,6 +45,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
@@ -76,8 +82,8 @@ export interface ApiSpecData {
     /** 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 +168,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

@@ -16,6 +16,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 +29,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

@@ -19,8 +19,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;
     /**
@@ -60,6 +60,11 @@ 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).
@@ -120,10 +125,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 } 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;