blume 2.1.0 → 2.1.2

package/dist/types/deploy/platforms/vercel.d.ts

@@ -1,4 +1,5 @@
 import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ProjectContext } from "../../core/types.ts";
 import type { BuildLog, DeployPlatform, RedirectFile } from "./types.ts";
 /** `vercel.json` with a `redirects` array, for a static deploy of `dist/`. */
 export declare const VERCEL_JSON_FILE: RedirectFile;
@@ -26,6 +27,22 @@ export declare const emitVercelNegotiation: (project: BlumeProject, log: BuildLo
  * prerender a pattern's pages, so the adapter never sees these.
  */
 export declare const emitVercelPatternRedirects: (project: BlumeProject, log: BuildLog) => Promise<void>;
+/**
+ * Move a server build's static files under `deployment.base`.
+ * `@astrojs/vercel` copies them to the root of the Build Output tree's
+ * `static/`, while the pages request `<base>/_astro/…` and link to
+ * `<base>/…`, so nothing the site asks for would be found. Moved to
+ * `static/<base>/`, they're served at the base, as the routes that
+ * {@link rebaseVercelRoutes} moves there expect.
+ */
+export declare const moveStaticUnderBase: (context: ProjectContext, base: string) => Promise<void>;
+/**
+ * Move the adapter's routing config under `deployment.base` to match the
+ * static files (see `rebaseAdapterRoutes`), its exact redirects rebuilt from
+ * the configured ones. Resolves to false when the config can't be read: the
+ * adapter's routes would then miss every path under the base.
+ */
+export declare const rebaseVercelRoutes: (project: BlumeProject, log: BuildLog) => Promise<boolean>;
 /**
  * Vercel. A server build's Build Output tree lands at `.vercel/output` — at
  * the project root, because the adapter is handed that root up front: its
@@ -33,7 +50,9 @@ export declare const emitVercelPatternRedirects: (project: BlumeProject, log: Bu
  * hidden runtime silently drops the function's chunks and `node_modules`.
  * Static assets are served from the tree's `static/` half, so the deploy
  * artifacts are written there; headers (the discovery files', the sandbox on
- * downloaded SVGs) arrive through the routing config rather than a
- * `_headers` file, which Vercel never reads.
+ * downloaded SVGs, `X-Powered-By`) arrive through the routing config rather
+ * than a `_headers` file, which Vercel never reads. The adapter ignores
+ * `deployment.base`, so under one the build moves the static files and the
+ * routes beneath it.
  */
 export declare const vercelPlatform: DeployPlatform;

package/dist/types/deploy/redirects.d.ts

@@ -41,9 +41,25 @@ export declare const applyBaseToAstroRedirects: (redirects: Redirect[], basePath
  * public file (see {@link baseRedirectTarget}).
  */
 export declare const applyBaseToPlatformRedirects: (redirects: Redirect[], basePath: string, deployBase: string, routes: RouteSet) => Redirect[];
+/**
+ * Based `redirects`, each exact one that moves a page followed by the same
+ * redirect for the page's Markdown copies: from a path no page is served at
+ * to one a page is, `/old.md` goes to `/new.md` (and `.mdx` alike), where it
+ * would otherwise 404 for an agent still reading the old URL. A pattern gets
+ * none; one that carries its capture over (`/beta/:slug*` → `/v2/:slug*`)
+ * already moves `/beta/guide.md` along. `pages` are the served page routes
+ * (carrying `basePath`, not `deployment.base`), and `bases` the deployment
+ * base each end carries: Astro's config leaves it off `from` (see
+ * {@link applyBaseToAstroRedirects}).
+ */
+export declare const withMirrorRedirects: (redirects: Redirect[], pages: RouteSet, bases: {
+    from: string;
+    to: string;
+}) => Redirect[];
 /**
  * The configured redirects as the host platform matches them, via
- * {@link applyBaseToPlatformRedirects}, exact paths ahead of patterns: hosts
+ * {@link applyBaseToPlatformRedirects} plus the Markdown copies of each moved
+ * page ({@link withMirrorRedirects}), exact paths ahead of patterns: hosts
  * try rules in order, and an exact redirect wins over a pattern that also
  * covers its path. The one basing every consumer must share: the emitted
  * redirect files and the server wrappers all compare these paths against

package/dist/types/deploy/sitemap.d.ts

@@ -11,7 +11,8 @@ export declare const describeSitemapFiles: (files: readonly SitemapFile[]) => st
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
  * the generated `/changelog` index. Returns null when the sitemap is disabled
  * or no `site` is configured (absolute URLs are required for a valid sitemap).
- * Drafts, hidden, and `noindex` pages are excluded.
+ * Drafts, hidden, and `noindex` pages are excluded, and so is a page whose
+ * `seo.canonical` points elsewhere.
  *
  * Sites within the per-file URL cap get the single classic `sitemap.xml`;
  * larger sites get `sitemap.xml` as a sitemap index over numbered

package/dist/types/deploy/vercel-negotiation.d.ts

@@ -14,25 +14,31 @@
  * prerendered Markdown 404 body with the 404 status, instead of the HTML
  * shell, and one that prefers JSON (or asks for a `.json` URL) gets the
  * prerendered problem-details 404.
+ *
+ * Under `deployment.base` every route here matches the served URL, base
+ * included, and names the files where Blume moves them (`static/<base>/`, see
+ * {@link rebaseAdapterRoutes}); `base` is the normalized base, `""` for none.
  */
-/**
- * Regex for the `accept` header condition. Written to hold under both matching
- * semantics a router may apply — full-string and substring — by anchoring the
- * end and letting `(.*,)?` absorb any earlier list entries: it requires a
- * `text/markdown` or `text/x-markdown` entry terminated by `;`, `,`, or the end
- * of the header. Kept lookaround-free so it stays valid in RE2, and lowercase
- * only — real agents send lowercase media types, and q-values are not compared
- * (a client sending `text/markdown` at `q=0` is pathological). Browsers never
- * send `text/markdown`, so ordinary page requests are unaffected.
- */
-export declare const ACCEPT_MARKDOWN_HEADER_VALUE = "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
+/** One header condition on a Build Output route. */
+export interface VercelCondition {
+    key?: string;
+    type: string;
+    value?: string;
+}
+/** The conditions of one route: all of `has`, none of `missing`. */
+export interface AcceptConditions {
+    has: VercelCondition[];
+    missing?: VercelCondition[];
+}
+/** When a client prefers `text/markdown` (or `text/x-markdown`) over HTML. */
+export declare const ACCEPT_MARKDOWN_CONDITIONS: AcceptConditions[];
 /**
  * The JSON counterpart, for the problem-details 404: `application/json` or
  * `application/problem+json`. Browsers never send either on a navigation
  * (the catch-all wildcard does not match), so ordinary page requests are
  * unaffected.
  */
-export declare const ACCEPT_JSON_HEADER_VALUE = "(.*,)?\\s*application/(problem\\+)?json(\\s*[;,].*)?$";
+export declare const ACCEPT_JSON_CONDITIONS: AcceptConditions[];
 /**
  * A Build Output API route — the subset these helpers read and write. Parsed
  * routes keep whatever other fields they carry at runtime; only these are
@@ -42,12 +48,9 @@ export interface VercelRoute {
     continue?: boolean;
     dest?: string;
     handle?: string;
-    has?: {
-        key?: string;
-        type: string;
-        value?: string;
-    }[];
+    has?: VercelCondition[];
     headers?: Record<string, string>;
+    missing?: VercelCondition[];
     src?: string;
     status?: number;
 }
@@ -82,9 +85,10 @@ export interface NegotiationRoutes {
  * rewrite also stamps `x-markdown-tokens` — the estimated token count of the
  * homepage mirror (Cloudflare's Markdown for Agents convention). Only the home
  * route can carry it: the other rewrites are chunked alternations spanning
- * many pages, and a count is per-page.
+ * many pages, and a count is per-page. Under a `base`, each path is matched
+ * and rewritten where it's served (`/docs` → `/docs/index.md`).
  */
-export declare const buildNegotiationRoutes: (routePaths: readonly string[], homeTokens?: number) => NegotiationRoutes;
+export declare const buildNegotiationRoutes: (routePaths: readonly string[], homeTokens?: number, base?: string) => NegotiationRoutes;
 /**
  * Splice the negotiation routes into a Build Output `config.json`, plus — when
  * given — a homepage `Link` header route for agent discovery (see
@@ -102,12 +106,16 @@ export declare const buildNegotiationRoutes: (routePaths: readonly string[], hom
  * phase right before the adapter's `/404.html` fallback — and nowhere when
  * that fallback is absent, since a `dest` with no file behind it would serve
  * nothing. With `svgAssets`, a main-phase route also sandboxes the SVGs a
- * content source downloaded (see {@link svgAssetRoute}). Returns the updated JSON
+ * content source downloaded (see {@link svgAssetRoute}). With `poweredBy`, a
+ * route at the head of the config, ahead of the adapter's redirects, names
+ * Blume on every response (see {@link poweredByRoute}). Under a `base`, every
+ * route matches and names paths beneath it, and the fallback anchor is the
+ * one {@link rebaseAdapterRoutes} moved there. Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
  */
-export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean) => string | null;
+export declare const injectNegotiationRoutes: (configText: string, routePaths: readonly string[], homeLinkHeader?: string | null, contentTypeOverrides?: Record<string, string>, homeTokens?: number, notFound?: NotFoundVariants, corsPaths?: readonly string[], svgAssets?: boolean, base?: string, poweredBy?: boolean) => string | null;
 /**
  * Splice routes for the pattern redirects (see `vercelPatternRoutes`) into a
  * Build Output `config.json`, in the main phase just ahead of
@@ -117,3 +125,18 @@ export declare const injectNegotiationRoutes: (configText: string, routePaths: r
  * unparsable config, no `routes` array, or no `handle: "filesystem"` marker.
  */
 export declare const injectRedirectRoutes: (configText: string, redirectRoutes: readonly VercelRoute[]) => string | null;
+/**
+ * Move the adapter's routes under `deployment.base`, to match the static files
+ * Blume moves to `static/<base>/`. `@astrojs/vercel` routes a server build as
+ * if it were served from the root: its route patterns (the `_astro/` cache
+ * header, every server route) match base-less paths, its 404 fallback names
+ * `/404.html`, and it joins the base onto each redirect with no slash on the
+ * `from` side and a second time on the `to` side, which Astro hands it
+ * already based (`^/docsold$` → `/docs/docs/new`). Each pattern is
+ * re-anchored under the base and the fallback names the base's `404.html`;
+ * the adapter's redirects make way for `redirectRoutes`, the exact redirects
+ * as the host matches them. Returns the updated JSON text, or `null` when
+ * there is nowhere safe to splice: an unparsable config, no `routes` array,
+ * or no `handle: "filesystem"` marker.
+ */
+export declare const rebaseAdapterRoutes: (configText: string, base: string, redirectRoutes: readonly VercelRoute[]) => string | null;

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

@@ -2,17 +2,18 @@ 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 { GatewayNarrationProvider, NarrationProvider, OpenAINarrationProvider } 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.
+ * model, voice, instructions, provider options, endpoint), 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 {
@@ -23,7 +24,10 @@ export interface NarrationLogger {
 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. */
+    /**
+     * Clips that failed to generate, or that a missing key left ungenerated;
+     * their pages get no manifest.
+     */
     failed: number;
     /** Clips generated by the speech model on this build. */
     generated: number;
@@ -55,16 +59,34 @@ 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.
+ * shouldn't pay to regenerate audio that would sound the same. A build
+ * resolves `endpoint` once and passes it in, rather than reading the
+ * environment for every sentence.
  */
-export declare const clipKey: (provider: NarrationProvider, lang: string, text: string) => string;
+export declare const clipKey: (provider: NarrationProvider, lang: string, text: string, endpoint?: string | undefined) => string;
 /** Speak through the Vercel AI Gateway with the provider's model and voice. */
-export declare const gatewaySpeaker: (provider: NarrationProvider) => Speak;
+export declare const gatewaySpeaker: (provider: GatewayNarrationProvider) => Speak;
+/**
+ * Speak through OpenAI's speech API, or with `baseUrl` through any server
+ * that serves it (`POST /audio/speech`): Kokoro-FastAPI, Speaches, LiteLLM.
+ * That API takes no language, so none is sent and the model or voice
+ * decides it. Without a key, no bearer token is sent (an `Authorization` in
+ * `headers` still is). A build resolves `baseURL` once and passes it in.
+ */
+export declare const openaiSpeaker: (provider: OpenAINarrationProvider, baseURL?: string) => Speak;
+/**
+ * The env var a build needs to generate with `provider` and doesn't have, or
+ * `null` when it can go ahead: the key is set, Vercel's OIDC token stands in
+ * for the gateway's, or the provider names no key (`openai()` with a
+ * `baseUrl` and no `apiKeyEnv`).
+ */
+export declare const missingKey: (provider: NarrationProvider) => string | null;
 /**
  * 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.
+ * and a manifest per page. Does nothing unless `narration.provider` is set.
+ * When new clips are needed and the provider's key is missing, it warns and
+ * generates nothing, so only pages whose clips are all cached get audio (the
+ * rest read with browser voices). `speak` replaces the provider call.
  */
 export declare const buildNarration: (project: BlumeProject, distDir: string, logger: NarrationLogger, speak?: Speak) => Promise<NarrationBuildResult | null>;
 export {};

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

@@ -1,19 +1,36 @@
 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. */
+/** The voice narration uses when the provider 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.
+ * The AI SDK provider `openai()` narration speaks through, with or without a
+ * `baseUrl`: `@ai-sdk/openai-compatible` has no speech models.
  */
-export declare const narrationProviderSchema: z.ZodObject<{
+export declare const OPENAI_SPEECH_DEP = "@ai-sdk/openai";
+/**
+ * Whether `url` carries a username or password, which `fetch` refuses to
+ * send and whose error message would print them. A URL that doesn't parse
+ * has none.
+ */
+export declare const hasCredentials: (url: string) => boolean;
+/**
+ * `narration.provider`: the `gateway()` or `openai()` descriptor from
+ * `blume/ai`, read with speech defaults. `reasoning` (and `openai()`'s
+ * `name`, which speech models don't read) are assistant options and are
+ * rejected here; `voice` and `instructions` are narration options and are
+ * rejected by the assistant.
+ *
+ * `openai()` is read for what narration needs, not what the assistant does:
+ * it speaks through `@ai-sdk/openai` whatever the `baseUrl`, and a custom
+ * endpoint gets only the key `apiKeyEnv` names, never `OPENAI_API_KEY` by
+ * default, so it may take none at all. A key that is named is required.
+ */
+export declare const narrationProviderSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"gateway">;
     options: z.ZodObject<{
-        instructions: z.ZodOptional<z.ZodString>;
         model: z.ZodDefault<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
         voice: z.ZodDefault<z.ZodString>;
         apiKeyEnv: z.ZodDefault<z.ZodString>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -21,6 +38,77 @@ export declare const narrationProviderSchema: z.ZodObject<{
     }, z.core.$strict>;
     requiredSecrets: z.ZodArray<z.ZodString>;
     runtimeDeps: z.ZodArray<z.ZodString>;
-}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"openai">;
+    options: z.ZodObject<{
+        apiKeyEnv: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodURL>;
+        model: z.ZodString;
+        instructions: z.ZodOptional<z.ZodString>;
+        voice: 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>], "kind">, z.ZodTransform<{
+    kind: "gateway";
+    options: {
+        model: string;
+        voice: string;
+        apiKeyEnv: string;
+        instructions?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        providerOptions?: Record<string, Record<string, z.core.util.JSONType>> | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    options: {
+        model: string;
+        voice: string;
+        apiKeyEnv?: string | undefined;
+        baseUrl?: string | undefined;
+        instructions?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        providerOptions?: Record<string, Record<string, z.core.util.JSONType>> | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    kind: "openai";
+}, {
+    kind: "gateway";
+    options: {
+        model: string;
+        voice: string;
+        apiKeyEnv: string;
+        instructions?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        providerOptions?: Record<string, Record<string, z.core.util.JSONType>> | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+} | {
+    kind: "openai";
+    options: {
+        model: string;
+        voice: string;
+        apiKeyEnv?: string | undefined;
+        baseUrl?: string | undefined;
+        instructions?: string | undefined;
+        headers?: Record<string, string> | undefined;
+        providerOptions?: Record<string, Record<string, z.core.util.JSONType>> | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+}>>;
 /** A validated narration provider, defaults filled in. */
 export type NarrationProvider = z.output<typeof narrationProviderSchema>;
+/** A validated `gateway()` narration provider. */
+export type GatewayNarrationProvider = Extract<NarrationProvider, {
+    kind: "gateway";
+}>;
+/** A validated `openai()` narration provider. */
+export type OpenAINarrationProvider = Extract<NarrationProvider, {
+    kind: "openai";
+}>;

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

@@ -0,0 +1,27 @@
+import type { ApiDocument } from "./model.ts";
+/**
+ * Targeted checks for spec mistakes that would otherwise render silently
+ * wrong. This is not a validator — a linter such as Spectral or oasdiff owns
+ * that — and a spec that fails one of these still renders. Each check names
+ * one mistake whose symptom on the page is quiet: a path placeholder sent
+ * as literal text, a Try it input whose value goes nowhere, an Authorization
+ * section with no scheme to describe. Each reports a warning with its own
+ * code, so a build says what's wrong instead of shipping it.
+ */
+/** One mistake a check found, before the source names the spec it's in. */
+export interface SpecIssue {
+    code: string;
+    message: string;
+    suggestion: string;
+}
+/**
+ * How a warning names an operation: `GET /pets`, or a webhook by its name
+ * (`Webhook "newPet" (POST)`), since a webhook has no path.
+ */
+export declare const operationLabel: (name: string, method: string, webhook: boolean) => string;
+/**
+ * Check a parsed document for the mistakes above, and for the OpenAPI 3.2
+ * features Blume doesn't render yet. `$ref` path items are skipped: the
+ * extractor already reports them as missing from the reference.
+ */
+export declare const specIssues: (document: ApiDocument) => SpecIssue[];

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;
@@ -79,6 +88,8 @@ 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[];

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[];
 }
 /**

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";
@@ -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. */
@@ -70,6 +77,8 @@ export interface ReferenceSource {
      * (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
@@ -112,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;
 /**

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

@@ -1,7 +1,17 @@
+/** Whether `text` ends in a colon that leads in to what follows it. */
+export declare const endsInLeadIn: (text: string) => boolean;
+/**
+ * Close prose with a period unless it already ends a sentence. A colon at the
+ * end is kept and gains the period: use this when the caller has already told
+ * a lead-in apart from a literal (`tenant:` in inline code). Empty text stays
+ * empty.
+ */
+export declare const closeSentence: (text: string) => string;
 /**
  * Close a fragment of spec prose as a sentence. OpenAPI `summary` values are
  * usually title-like ("Get a flag", no period), so prose that runs straight
  * into the next generated sentence ("Get a flag Reference for …") needs one.
- * Empty text stays empty.
+ * A lead-in colon becomes the period rather than gaining one after it, and
+ * prose that already ended before it ("e.g.:") keeps its own mark.
  */
 export declare const asSentence: (text: string) => string;

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

@@ -24,4 +24,4 @@ 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";
+export type { UpstashAdapter, UpstashOptions } from "./upstash.ts";

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

@@ -22,6 +22,8 @@ export declare const rateLimitAdapterSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     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>;
@@ -55,6 +57,8 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     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>;
@@ -80,6 +84,8 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     options: {
         requests?: number | undefined;
         window?: number | undefined;
+        tokenEnv?: string | undefined;
+        urlEnv?: string | undefined;
     };
     requiredSecrets: string[];
     runtimeDeps: string[];
@@ -105,6 +111,8 @@ export declare const rateLimitConfigSchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<r
     options: {
         requests?: number | undefined;
         window?: number | undefined;
+        tokenEnv?: string | undefined;
+        urlEnv?: string | undefined;
     };
     requiredSecrets: string[];
     runtimeDeps: string[];