blume 2.1.0 → 2.1.2

package/src/openapi/references.ts

@@ -1,6 +1,9 @@
+import { isAbsolute, join } from "pathe";
+
 import { normalizeRoute, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
+import type { GraphqlAuthOptions } from "../reference/options.ts";
 import type { ScalarOptions } from "../reference/scalar.ts";
 import type { ResolvedReferenceAdapter } from "../reference/schema.ts";
 
@@ -54,6 +57,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. */
@@ -77,6 +86,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
@@ -181,6 +192,7 @@ const scalarOptionsOf = (
 
 /** A source row with every kind's fields reconciled onto one shape. */
 interface SourceRow {
+  auth?: GraphqlAuthOptions;
   endpoint?: string;
   includeInLlms: boolean;
   includeInSearch: boolean;
@@ -194,9 +206,9 @@ interface SourceRow {
 
 /**
  * One row per source, with the kind-specific fields already reconciled: a
- * GraphQL source's `endpoint` falls back to the adapter-wide default (the
- * common single-schema case pairs it with the `spec` shorthand); the other
- * kinds have no endpoint at all. A Scalar source carries only `noindex` of
+ * GraphQL source's `endpoint` and `auth` fall back to the adapter-wide
+ * defaults (the common single-schema case pairs them with the `spec`
+ * shorthand); the other kinds have neither. A Scalar source carries only `noindex` of
  * the per-source controls — the embed sits outside search and llms.txt, so
  * the other two read as off.
  */
@@ -204,6 +216,7 @@ const sourceRowsOf = (adapter: ResolvedReferenceAdapter): SourceRow[] => {
   if (adapter.kind === "graphql") {
     return adapter.options.sources.map((source) => ({
       ...source,
+      auth: source.auth ?? adapter.options.auth,
       endpoint: source.endpoint ?? adapter.options.endpoint,
     }));
   }
@@ -258,9 +271,15 @@ const referencesFor = (
     if (adapter.kind === "scalar") {
       reference.scalar = scalarOptionsOf(adapter.options);
     }
+    if (source.label !== undefined) {
+      reference.groupLabel = source.label;
+    }
     if (source.endpoint !== undefined) {
       reference.endpoint = source.endpoint;
     }
+    if (source.auth !== undefined) {
+      reference.auth = source.auth;
+    }
     if (source.overlays !== undefined) {
       reference.overlays = source.overlays;
     }
@@ -348,6 +367,27 @@ export const blumeReferences = (
   return result;
 };
 
+/** A spec or overlay the parser fetches rather than reads from disk. */
+const REMOTE_SPEC = /^https?:\/\//u;
+
+/**
+ * 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 const referenceSpecFiles = (
+  config: ResolvedConfig,
+  root: string
+): string[] => [
+  ...new Set(
+    resolveReferences(config)
+      .flatMap((ref) => [ref.spec, ...(ref.overlays ?? [])])
+      .filter((path) => !REMOTE_SPEC.test(path))
+      .map((path) => (isAbsolute(path) ? path : join(root, path)))
+  ),
+];
+
 /** Whether any reference is Scalar-rendered (gates the Scalar pages). */
 export const hasScalarReferences = (config: ResolvedConfig): boolean =>
   resolveReferences(config).some((ref) => ref.kind === "scalar");

package/src/openapi/render-mdx.ts

@@ -1,4 +1,4 @@
-import type { Nodes, Root } from "mdast";
+import type { List, Nodes, Paragraph, Root } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
@@ -10,7 +10,7 @@ import type { GraphqlMember } from "./graphql.ts";
 import { isGraphqlOperationKind } from "./graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
 import type { ReferenceSource } from "./references.ts";
-import { asSentence } from "./sentence.ts";
+import { asSentence, closeSentence, endsInLeadIn } from "./sentence.ts";
 import { operationSignature } from "./signature.ts";
 
 /**
@@ -193,6 +193,51 @@ export interface RenderedPage {
 const META_DESCRIPTION_MAX = 160;
 const WHITESPACE = /\s+/gu;
 const TRAILING_WORD = /\s+\S*$/u;
+// A list item's own closing mark, dropped where the items join into one line.
+const ITEM_END = /[.;。；]$/u;
+
+/** Markdown as single-line plain text. */
+const flatten = (node: Nodes): string =>
+  mdastToString(node).replace(WHITESPACE, " ").trim();
+
+/** The innermost last node of `node`: the one its text ends in. */
+const lastLeaf = (node: Nodes): Nodes => {
+  const last = "children" in node ? node.children.at(-1) : undefined;
+  return last ? lastLeaf(last) : node;
+};
+
+/**
+ * Whether a paragraph ends in a lead-in colon. Only a colon in the prose
+ * counts: one closing inline code (`tenant:`) is part of the literal.
+ */
+const leadsIn = (paragraph: Paragraph): boolean => {
+  const leaf = lastLeaf(paragraph);
+  return leaf.type === "text" && endsInLeadIn(leaf.value);
+};
+
+/** A list as one line: each item's first paragraph, joined by semicolons. */
+const listProse = (list: List): string =>
+  list.children
+    .map((item) => {
+      const paragraph = item.children.find(
+        (child) => child.type === "paragraph"
+      );
+      if (!paragraph) {
+        return "";
+      }
+      const text = flatten(paragraph);
+      // A closing mark in inline code (`SELECT 1;`) is part of the literal.
+      if (lastLeaf(paragraph).type !== "text") {
+        return text;
+      }
+      // A nested list's lead-in ("Modes:") closes like any other.
+      return (leadsIn(paragraph) ? asSentence(text) : text).replace(
+        ITEM_END,
+        ""
+      );
+    })
+    .filter(Boolean)
+    .join("; ");
 
 /**
  * Flatten markdown prose to its first paragraph as single-line plain text,
@@ -200,12 +245,25 @@ const TRAILING_WORD = /\s+\S*$/u;
  * was lossy on literal prose — `snake_case` → `snakecase`, `C#` → `C` — and
  * these strings ship as `seo.description` meta tags. A description with no
  * paragraph (say, only a heading or list) falls back to its first block.
+ *
+ * A first paragraph that leads in to a list ("Supports two modes:") is cut
+ * from what it introduces, so the list's items follow it on the same line. A
+ * lead-in to anything else, such as a code block, is closed as a sentence.
  */
 const plainProse = (markdown: string): string => {
-  const tree = fromMarkdown(markdown);
-  const first =
-    tree.children.find((node) => node.type === "paragraph") ?? tree.children[0];
-  return first ? mdastToString(first).replace(WHITESPACE, " ").trim() : "";
+  const { children } = fromMarkdown(markdown);
+  const index = children.findIndex((node) => node.type === "paragraph");
+  const paragraph = children[index];
+  if (paragraph?.type !== "paragraph") {
+    return children[0] ? flatten(children[0]) : "";
+  }
+  const text = flatten(paragraph);
+  if (!leadsIn(paragraph)) {
+    return text;
+  }
+  const next = children[index + 1];
+  const items = next?.type === "list" ? listProse(next) : "";
+  return items ? `${text} ${items}` : asSentence(text);
 };
 
 /** Cap `text` at `max` display columns, cutting on a word boundary. */
@@ -274,14 +332,16 @@ const operationDescription = (
     subject = `${operation.method.toUpperCase()} ${operation.path} ${operation.webhook ? "webhook" : "endpoint"}`;
   }
   const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
-  // Room for the joining space and the period `asSentence` may add, so a
+  // Room for the joining space and the period `closeSentence` may add, so a
   // title-like summary ("Get a flag") ends before the suffix begins.
   const prose = clip(
     plainProse(operation.description || operation.summary),
     META_DESCRIPTION_MAX - stringWidth(suffix) - 2
   );
+  // `plainProse` has already closed a lead-in colon, so one still at the end
+  // is a literal (`tenant:`) and keeps its period after it.
   return clip(
-    [asSentence(prose), suffix].filter(Boolean).join(" "),
+    [closeSentence(prose), suffix].filter(Boolean).join(" "),
     META_DESCRIPTION_MAX
   );
 };

package/src/openapi/sentence.ts

@@ -4,11 +4,38 @@
  */
 const TERMINAL_PUNCTUATION = /[.!?…。！？]["'”’)\]]*$/u;
 
+/**
+ * A colon closing the fragment introduces a list or block it was cut from
+ * ("Supports two modes:" before its bullets). The ASCII or full-width colon,
+ * with the space French typesetting puts before it ("Deux modes :").
+ */
+const LEAD_IN_COLON = /\s*[:：]\s*$/u;
+
+/**
+ * A trailing colon that belongs to a literal rather than the prose: an emoji
+ * shortcode (`:rocket:`) or a `Foo::` scope.
+ */
+const LITERAL_COLON = /(?:[:：]{2}|:[\w+-]+:)\s*$/u;
+
+/** Whether `text` ends in a colon that leads in to what follows it. */
+export const endsInLeadIn = (text: string): boolean =>
+  LEAD_IN_COLON.test(text) && !LITERAL_COLON.test(text);
+
+/**
+ * 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 const closeSentence = (text: string): string =>
+  text === "" || TERMINAL_PUNCTUATION.test(text) ? text : `${text}.`;
+
 /**
  * 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 const asSentence = (text: string): string =>
-  text === "" || TERMINAL_PUNCTUATION.test(text) ? text : `${text}.`;
+  closeSentence(endsInLeadIn(text) ? text.replace(LEAD_IN_COLON, "") : text);

package/src/openapi/source.ts

@@ -11,6 +11,8 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractAsyncApiOperations } from "./asyncapi.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
+import { specIssues } from "./checks.ts";
+import type { SpecIssue } from "./checks.ts";
 import { extractGraphqlOperations } from "./graphql.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import { extractOperations } from "./model.ts";
@@ -173,24 +175,34 @@ const specEntries = (
 };
 
 /**
- * Label each tag's sidebar group with the spec's own tag name. The group label
- * is otherwise re-humanized from the tag's route slug (split on hyphens,
+ * Label each tag's sidebar group with the spec's own tag name, and order the
+ * groups as the overview does: the spec's declared tag order, then first use
+ * (see `operationCollector`), not alphabetically. The group label is
+ * otherwise re-humanized from the tag's route slug (split on hyphens,
  * title-cased), which mangles authored casing and symbols — `OAuth2` →
- * "Oauth2", `Größe` → "Größe" only by luck of the slug. Keys are the tag
- * directories under the reference route, the same group paths `meta.ts` files
- * use, so user-authored meta still overrides these.
+ * "Oauth2", `Größe` → "Größe" only by luck of the slug. A source that names
+ * its own `label` gets it on its route's group the same way (`GitHub (v2)`,
+ * not "Github V2"). Keys are the directories under the reference route, the
+ * same group paths `meta.ts` files use, so user-authored meta still
+ * overrides these.
  */
 const tagFolderMeta = (
   spec: ApiSpecData,
-  tags: { slug: string; name: string }[]
+  tags: { slug: string; name: string }[],
+  groupLabel: string | undefined
 ): Record<string, FolderMeta> => {
   const base = routeToRef(spec.route);
-  return Object.fromEntries(
-    tags.map((tag) => [
+  const meta: Record<string, FolderMeta> = Object.fromEntries(
+    tags.map((tag, order) => [
       base ? `${base}/${tag.slug}` : tag.slug,
-      { title: tag.name },
+      { order, title: tag.name },
     ])
   );
+  // A root-mounted reference has no group of its own to name.
+  if (groupLabel !== undefined && base) {
+    meta[base] = { title: groupLabel };
+  }
+  return meta;
 };
 
 interface LoadedSpec {
@@ -210,6 +222,8 @@ interface ParsedReference {
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
   extractWarnings: string[];
+  /** Spec mistakes that would render silently wrong (OpenAPI only). */
+  issues?: SpecIssue[];
 }
 
 const parseReference = async (
@@ -247,7 +261,7 @@ const parseReference = async (
       warnings,
     };
   }
-  const { document, warnings } = await parseSpec(
+  const { document, issues, warnings } = await parseSpec(
     reference.spec,
     ctx.projectRoot,
     { ...options, overlays: reference.overlays }
@@ -256,6 +270,7 @@ const parseReference = async (
   return {
     document,
     extractWarnings: extracted.warnings,
+    issues: [...issues, ...specIssues(document)],
     operations: extracted.operations,
     tags: extracted.tags,
     warnings,
@@ -276,7 +291,7 @@ export const openApiSource = (
     const kindLabel = KIND_LABELS[reference.kind];
     const codePrefix = CODE_PREFIXES[reference.kind];
     try {
-      const { document, warnings, operations, tags, extractWarnings } =
+      const { document, warnings, operations, tags, extractWarnings, issues } =
         await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
       // The playground proxy resolves here, not client-side: `true` selects
@@ -318,11 +333,15 @@ export const openApiSource = (
         title: info.title ?? reference.label,
         version: info.version ?? "",
       };
-      // Only GraphQL references carry a live endpoint (a schema names no
-      // server); assigned separately so the key stays absent otherwise.
+      // Only GraphQL references carry a live endpoint and its auth (a schema
+      // names no server); assigned separately so the keys stay absent
+      // otherwise.
       if (reference.endpoint !== undefined) {
         spec.endpoint = reference.endpoint;
       }
+      if (reference.auth !== undefined) {
+        spec.auth = reference.auth;
+      }
       return {
         diagnostics: [
           ...warnings.map((message) => ({
@@ -335,6 +354,12 @@ export const openApiSource = (
             message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning" as const,
           })),
+          ...(issues ?? []).map((issue) => ({
+            code: issue.code,
+            message: `In ${kindLabel} spec "${reference.spec}": ${issue.message}`,
+            severity: "warning" as const,
+            suggestion: issue.suggestion,
+          })),
           // A document with no operations (say, a config file that happens to
           // parse as YAML) would otherwise build a nav tab onto an empty
           // reference with no hint why.
@@ -350,7 +375,7 @@ export const openApiSource = (
             : []),
         ],
         entries: specEntries(spec, operations, reference),
-        folderMeta: tagFolderMeta(spec, tags),
+        folderMeta: tagFolderMeta(spec, tags, reference.groupLabel),
         slug: reference.slug,
         spec,
       };

package/src/ratelimit/index.ts

@@ -27,4 +27,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/src/ratelimit/runtime.ts

@@ -16,7 +16,7 @@ import type { ClientContext } from "../core/client-address.ts";
 import { RATE_LIMIT_BINDING } from "./cloudflare.ts";
 import { DEFAULT_REQUESTS, DEFAULT_WINDOW } from "./memory.ts";
 import type { RateLimitAdapter } from "./schema.ts";
-import { UPSTASH_SECRETS } from "./upstash.ts";
+import { upstashSecrets } from "./upstash.ts";
 
 /** What a limiter says about one request. */
 export interface RateLimitResult {
@@ -86,16 +86,32 @@ export const memoryLimiter = (
   };
 };
 
-/** One command's reply from Upstash's REST pipeline. */
+/**
+ * Counts the request and reads what's left of the window, run by Redis as
+ * one step. A key without an expiry — the one `INCR` just created, or one a
+ * failed call left behind — gets the window as its expiry, so a count can't
+ * outlive its window and lock a reader out of the route for good. Separate
+ * commands, even pipelined, let the key expire between them, and the `INCR`
+ * after that created a key that never expired.
+ */
+export const UPSTASH_COUNT_SCRIPT = `local count = redis.call("INCR", KEYS[1])
+local ttl = redis.call("TTL", KEYS[1])
+if ttl < 0 then
+  redis.call("EXPIRE", KEYS[1], ARGV[1])
+  ttl = tonumber(ARGV[1])
+end
+return {count, ttl}`;
+
+/** Upstash's REST reply to one command. */
 interface UpstashReply {
   error?: string;
-  result?: number | string | null;
+  result?: (number | null)[] | null;
 }
 
 /**
- * Count in Upstash Redis over its REST API: one pipeline opens the window
- * (`SET … EX … NX`), counts the request (`INCR`), and reads what's left of
- * the window (`TTL`).
+ * Count in Upstash Redis over its REST API: one `EVAL` of
+ * {@link UPSTASH_COUNT_SCRIPT} counts the request, opens the window when it's
+ * the first, and reads what's left of it.
  */
 export const upstashLimiter = (
   requests: number,
@@ -104,13 +120,15 @@ export const upstashLimiter = (
   token: string,
   fetchImpl: typeof fetch = fetch
 ): Limiter => {
-  const url = `${endpoint.replace(/\/+$/u, "")}/pipeline`;
+  const url = endpoint.replace(/\/+$/u, "");
   return async (key) => {
     const response = await fetchImpl(url, {
       body: JSON.stringify([
-        ["SET", key, "0", "EX", String(window), "NX"],
-        ["INCR", key],
-        ["TTL", key],
+        "EVAL",
+        UPSTASH_COUNT_SCRIPT,
+        "1",
+        key,
+        String(window),
       ]),
       headers: {
         authorization: `Bearer ${token}`,
@@ -121,11 +139,12 @@ export const upstashLimiter = (
     if (!response.ok) {
       throw new Error(`Upstash answered ${response.status}.`);
     }
-    // SAFETY: Upstash's pipeline endpoint answers with one reply object per
-    // command, in order; a missing or failed reply reads as `NaN` below.
-    const replies = (await response.json()) as UpstashReply[];
-    const count = Number(replies[1]?.result ?? Number.NaN);
-    const ttl = Number(replies[2]?.result);
+    // SAFETY: Upstash's REST API answers a command with `{ result }`, here
+    // the script's `{count, ttl}`; a missing or failed reply reads as `NaN`
+    // below.
+    const reply = (await response.json()) as UpstashReply;
+    const count = Number(reply.result?.[0] ?? Number.NaN);
+    const ttl = Number(reply.result?.[1]);
     if (Number.isNaN(count)) {
       throw new TypeError("Upstash sent no count.");
     }
@@ -175,14 +194,13 @@ export const createLimiter = (
     );
   }
   if (adapter.kind === "upstash") {
-    const [endpoint, token] = UPSTASH_SECRETS.map((name) =>
-      runtime.secret?.(name)
-    );
+    const secrets = upstashSecrets(adapter.options);
+    const [endpoint, token] = secrets.map((name) => runtime.secret?.(name));
     if (endpoint && token) {
       return upstashLimiter(requests, window, endpoint, token, runtime.fetch);
     }
     console.warn(
-      `Rate limiting counts in memory: set ${UPSTASH_SECRETS.join(" and ")} to share the count through Upstash.`
+      `Rate limiting counts in memory: set ${secrets.join(" and ")} to share the count through Upstash.`
     );
   }
   return memoryLimiter(requests, window, runtime.now);

package/src/ratelimit/upstash.ts

@@ -1,30 +1,60 @@
+import { z } from "zod";
+
 import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 import { rateLimitOptionsSchema } from "./memory.ts";
 import type { RateLimitOptions } from "./memory.ts";
 
-/** The env vars holding the Upstash Redis REST endpoint and its token. */
-export const UPSTASH_SECRETS = [
-  "UPSTASH_REDIS_REST_URL",
-  "UPSTASH_REDIS_REST_TOKEN",
-] as const;
+/** The env var holding the Upstash Redis REST endpoint, unless set. */
+const UPSTASH_URL_ENV = "UPSTASH_REDIS_REST_URL";
+
+/** The env var holding the endpoint's token, unless set. */
+const UPSTASH_TOKEN_ENV = "UPSTASH_REDIS_REST_TOKEN";
+
+/** 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 type UpstashAdapter = AdapterDescriptor<"upstash", RateLimitOptions>;
+export const upstashOptionsSchema = rateLimitOptionsSchema.extend({
+  tokenEnv: z.string().min(1).optional(),
+  urlEnv: z.string().min(1).optional(),
+});
+
+export type UpstashAdapter = AdapterDescriptor<"upstash", UpstashOptions>;
 
 export const upstashAdapterSchema = adapterDescriptorSchema(
   "upstash",
-  rateLimitOptionsSchema
+  upstashOptionsSchema
 );
 
+/** The env vars the endpoint and its token are read from, in that order. */
+export const upstashSecrets = (options: UpstashOptions): [string, string] => [
+  options.urlEnv ?? UPSTASH_URL_ENV,
+  options.tokenEnv ?? UPSTASH_TOKEN_ENV,
+];
+
 /**
  * Keeps the count in Upstash Redis, which every instance on every host shares,
  * so the limit holds exactly. It talks to Upstash's REST API, so there is
  * nothing to install; the endpoint and token come from
- * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`.
+ * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`, or the env vars
+ * `urlEnv` and `tokenEnv` name.
  */
-export const upstash = (options: RateLimitOptions = {}): UpstashAdapter => ({
+export const upstash = (options: UpstashOptions = {}): UpstashAdapter => ({
   kind: "upstash",
   options,
-  requiredSecrets: [...UPSTASH_SECRETS],
+  requiredSecrets: upstashSecrets(options),
   runtimeDeps: [],
 });

package/src/reference/graphql.ts

@@ -3,16 +3,28 @@ import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 import {
+  graphqlAuthSchema,
   graphqlSourceSchema,
   liftSpec,
   hasSources,
   missingSourcesIssue,
   sharedOptions,
 } from "./options.ts";
-import type { GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
+import type {
+  GraphqlAuthOptions,
+  GraphqlSourceOptions,
+  PlaygroundOptions,
+} from "./options.ts";
 
 /** Options for {@link graphql}. */
 export interface GraphqlOptions {
+  /**
+   * How the endpoint authenticates, like the site's `api.auth`: `bearer`,
+   * `basic`, or `key` (sent in the `name` header, `x-api-key` by default).
+   * The Try it panel gets a field for the credential and the code samples
+   * send a placeholder. Applies to every source; a per-source `auth` wins.
+   */
+  auth?: GraphqlAuthOptions;
   /**
    * Code-sample languages shown per operation, in order. Defaults to
    * `["curl", "js", "python"]`; `false` shows none.
@@ -52,6 +64,8 @@ export const graphqlOptionsSchema = z
       codeSamples: ["curl", "js", "python"],
       route: "/graphql",
     }),
+    /** Default endpoint auth for every source (per-source `auth` wins). */
+    auth: graphqlAuthSchema.optional(),
     /** Default live endpoint URL for every source (per-source `endpoint` wins). */
     endpoint: z.string().optional(),
     /** One or more schemas; each renders on its own route by default. */

package/src/reference/index.ts

@@ -27,6 +27,7 @@ export type { GraphqlAdapter, GraphqlOptions } from "./graphql.ts";
 export { openapi } from "./openapi.ts";
 export type { OpenApiAdapter, OpenApiOptions } from "./openapi.ts";
 export type {
+  GraphqlAuthOptions,
   GraphqlSourceOptions,
   PlaygroundOptions,
   ReferenceSourceOptions,

package/src/reference/openapi.ts

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