blume 2.1.0 → 2.1.1

package/src/openapi/parse.ts

@@ -4,7 +4,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import type * as ConverterModule from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
-import { isAbsolute, join } from "pathe";
+import { dirname, isAbsolute, join, resolve } from "pathe";
 import type * as UndiciModule from "undici";
 
 import {
@@ -15,8 +15,11 @@ import { nodeRequire } from "../core/node-require.ts";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
+import { operationLabel } from "./checks.ts";
+import type { SpecIssue } from "./checks.ts";
 import { buildGraphqlDocument } from "./graphql-build.ts";
 import type { GraphqlDocument } from "./graphql.ts";
+import { HTTP_METHODS } from "./model.ts";
 import type { ApiDocument } from "./model.ts";
 import { applyOverlay, isJsonObject, overlayDocument } from "./overlay.ts";
 import { SpecDependencyError } from "./spec-dependency-error.ts";
@@ -25,6 +28,8 @@ import { SpecDependencyError } from "./spec-dependency-error.ts";
  * Spec loading and normalization. Blume reuses Scalar's parser
  * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
  * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
+ * OpenAPI 3.2 is backward compatible with 3.1, so a 3.2 document is read as
+ * written.
  * Internal `$ref`s are deliberately left in place (see `model.ts`).
  *
  * Remote (`http(s)`) specs are fetched defensively — bounded per attempt, retried
@@ -58,6 +63,8 @@ const PROXY_ENV_VARS = [
 
 export interface ParsedSpec {
   document: ApiDocument;
+  /** `x-codeSamples` entries whose `$ref` couldn't be inlined. */
+  issues: SpecIssue[];
   warnings: string[];
 }
 
@@ -360,6 +367,123 @@ export const readOverlaidSpec = async (
   return { text: JSON.stringify(document), warnings };
 };
 
+/** A `$ref` in place of an `x-codeSamples` entry's `source`. */
+interface SampleRef {
+  $ref: string;
+}
+
+/** An `x-codeSamples` entry whose `source` is a `$ref` rather than the code. */
+const isRefSample = (value: unknown): value is { source: SampleRef } =>
+  isJsonObject(value) &&
+  isJsonObject(value.source) &&
+  typeof value.source.$ref === "string";
+
+/**
+ * Where a code sample's `$ref` points, in the form `readSpecText` reads: a
+ * URL, or a path resolved against the spec's own location. `undefined` for
+ * a JSON pointer (`#/…`, or a file with a fragment), which names a spot
+ * inside a document rather than a file of code.
+ */
+const sampleTarget = (
+  ref: string,
+  spec: string,
+  root: string
+): string | undefined => {
+  if (ref.includes("#")) {
+    return undefined;
+  }
+  if (URL_SPEC.test(ref)) {
+    return ref;
+  }
+  if (URL_SPEC.test(spec)) {
+    return new URL(ref, spec).href;
+  }
+  return resolve(dirname(isAbsolute(spec) ? spec : join(root, spec)), ref);
+};
+
+/**
+ * Inline each `x-codeSamples` entry whose `source` is a `$ref` to a file of
+ * its own, as Redocly's docs describe (`source: { $ref: ../code_samples/… }`):
+ * `redocly bundle` inlines those, and a spec read as written doesn't. Each
+ * file is read relative to the spec,
+ * the way the spec itself was (local, or fetched and cached), so the sample
+ * renders like a written-out one. An entry that can't be read is left out of
+ * the page, with a warning, rather than dropped without a sign.
+ */
+const inlineSampleRefs = async (
+  document: ApiDocument,
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<SpecIssue[]> => {
+  const reads: Promise<SpecIssue | undefined>[] = [];
+  const inline = async (
+    entry: { source: SampleRef | string },
+    ref: string,
+    label: string
+  ): Promise<SpecIssue | undefined> => {
+    const target = sampleTarget(ref, spec, root);
+    if (target === undefined) {
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", a spot inside a document, which Blume doesn't resolve, so the sample is left out.`,
+        suggestion:
+          "Point the `$ref` at a file that holds only the sample's code, or write the code out in `source`.",
+      };
+    }
+    try {
+      const { text } = await readSpecText(target, root, options);
+      entry.source = text;
+      return undefined;
+    } catch (error) {
+      // SAFETY: a failed read throws a Node error, and a failed fetch an
+      // Error (`attemptFetch` wraps anything else); only the message is shown.
+      const { message } = error as Error;
+      return {
+        code: "BLUME_OPENAPI_CODE_SAMPLE_REF",
+        message: `${label} has an \`x-codeSamples\` entry whose \`source\` is a $ref to "${ref}", which couldn't be read (${message}), so the sample is left out.`,
+        suggestion:
+          "Check the path, which is relative to the spec, or write the code out in `source`.",
+      };
+    }
+  };
+  const visit = (
+    name: string,
+    item: NonNullable<ApiDocument["paths"]>[string] | undefined,
+    webhook: boolean
+  ): void => {
+    if (!isJsonObject(item) || "$ref" in item) {
+      return;
+    }
+    for (const method of HTTP_METHODS) {
+      const operation = item[method];
+      // The spelling `customCodeSamples` renders: the current one wins.
+      const samples = isJsonObject(operation)
+        ? (operation["x-codeSamples"] ?? operation["x-code-samples"])
+        : undefined;
+      for (const entry of Array.isArray(samples) ? samples : []) {
+        if (isRefSample(entry)) {
+          reads.push(
+            inline(
+              entry,
+              entry.source.$ref,
+              operationLabel(name, method, webhook)
+            )
+          );
+        }
+      }
+    }
+  };
+  for (const [path, item] of Object.entries(document.paths ?? {})) {
+    visit(path, item, false);
+  }
+  for (const [name, item] of Object.entries(document.webhooks ?? {})) {
+    visit(name, item, true);
+  }
+  const issues = await Promise.all(reads);
+  return issues.filter((issue) => issue !== undefined);
+};
+
 export const parseSpec = async (
   spec: string,
   root: string,
@@ -377,7 +501,8 @@ export const parseSpec = async (
       `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
     );
   }
-  return { document: specification, warnings };
+  const issues = await inlineSampleRefs(specification, spec, root, options);
+  return { document: specification, issues, warnings };
 };
 
 export interface ParsedAsyncApiSpec {

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/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`. */