blume 2.0.3 → 2.1.0

package/src/components/openapi/Operation.astro

@@ -1,6 +1,6 @@
 ---
 import specs from "blume:openapi";
-import { operationOf, specOf } from "../../openapi/model.ts";
+import { HTTP_METHODS, operationOf, specOf } from "../../openapi/model.ts";
 import {
   mergeParameters,
   type ParameterLike,
@@ -21,10 +21,13 @@ import {
   type SecuritySchemeLike,
 } from "./security.ts";
 import { DEPRECATED_LABEL_CLASS } from "../colors.ts";
+import { customCodeSamples } from "./code-samples.ts";
+import type { CodeSamplesCarrier } from "./code-samples.ts";
 import { sampleLanguages } from "./snippets.ts";
 import AsyncApiOperation from "./AsyncApiOperation.astro";
 import GraphqlOperation from "./GraphqlOperation.astro";
 import Authorization from "./Authorization.astro";
+import Description from "./Description.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
 import Playground from "./Playground.astro";
@@ -57,7 +60,18 @@ interface ResponseLike {
   content?: Record<string, MediaTypeLike>;
 }
 
-interface FullOperation {
+/**
+ * One callback: a map of runtime URL expressions
+ * (`{$request.body#/callbackUrl}`) to the path item the API will call there,
+ * or a `$ref` to one under `components.callbacks`.
+ */
+type CallbackLike = { $ref?: string } & Record<
+  string,
+  Record<string, unknown> | string | undefined
+>;
+
+interface FullOperation extends CodeSamplesCarrier {
+  callbacks?: Record<string, CallbackLike>;
   summary?: string;
   description?: string;
   deprecated?: boolean;
@@ -77,15 +91,17 @@ const ref = spec ? operationOf(spec, id) : undefined;
 const isAsyncApi = spec?.kind === "asyncapi";
 const isGraphql = spec?.kind === "graphql";
 
+type PathItemLike = Record<string, unknown> & {
+  parameters?: ParameterLike[];
+  servers?: ServerLike[];
+};
+
 const doc = (spec?.document ?? {}) as {
-  paths?: Record<
-    string,
-    Record<string, unknown> & {
-      parameters?: ParameterLike[];
-      servers?: ServerLike[];
-    }
-  >;
+  paths?: Record<string, PathItemLike>;
+  // OpenAPI 3.1 webhooks: requests the API sends, keyed by name.
+  webhooks?: Record<string, PathItemLike>;
   components?: {
+    callbacks?: Record<string, CallbackLike>;
     schemas?: Record<string, SchemaLike>;
     parameters?: Record<string, ParameterLike>;
     requestBodies?: Record<string, RequestBodyLike>;
@@ -95,7 +111,12 @@ const doc = (spec?.document ?? {}) as {
   security?: SecurityRequirementLike[];
   servers?: ServerLike[];
 };
-const pathItem = ref ? doc.paths?.[ref.path] : undefined;
+const isWebhook = ref?.webhook === true;
+const pathItem = ref
+  ? isWebhook
+    ? doc.webhooks?.[ref.path]
+    : doc.paths?.[ref.path]
+  : undefined;
 const operation = (
   pathItem && ref ? pathItem[ref.method] : undefined
 ) as FullOperation | undefined;
@@ -118,14 +139,16 @@ const responses = Object.fromEntries(
 );
 
 const security = resolveSecurity(
-  effectiveSecurity(operation?.security, doc.security),
+  effectiveSecurity(operation?.security, doc.security, isWebhook),
   doc.components?.securitySchemes
 );
 
 // One derived model feeds the static default sample, the playground form,
-// and (client-side) the live samples + fetch — they can never drift apart.
+// and (client-side) the live samples + fetch — they can never drift apart. A
+// webhook has none: the API sends it, so there is nothing for a reader to
+// call, and its rail shows the payload instead.
 const model =
-  ref && operation
+  ref && operation && !isWebhook
     ? operationModel({
         components,
         method: ref.method,
@@ -145,6 +168,59 @@ const model =
     : null;
 const sample = model ? buildRequest(model, defaultValues(model)) : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
+// The spec's own `x-codeSamples`, shown ahead of the generated ones.
+const customSamples = operation ? customCodeSamples(operation) : [];
+
+/** One request the API makes back to the reader, flattened for rendering. */
+interface CallbackEntry {
+  expression: string;
+  key: string;
+  method: string;
+  name: string;
+  operation: FullOperation;
+}
+
+// Callbacks: for each named callback (resolved through
+// `components.callbacks`), each URL expression, each method it declares.
+const callbacks: CallbackEntry[] = Object.entries(
+  operation?.callbacks ?? {}
+).flatMap(([name, raw]) => {
+  const callback = resolveComponentRef(raw, components, "callbacks");
+  return Object.entries(callback).flatMap(([expression, item]) => {
+    if (expression === "$ref" || typeof item !== "object" || item === null) {
+      return [];
+    }
+    return HTTP_METHODS.flatMap((method) => {
+      const entry = item[method];
+      return typeof entry === "object" && entry !== null
+        ? [
+            {
+              expression,
+              key: `${name}-${expression}-${method}`,
+              method,
+              name,
+              // SAFETY: a path item's method entry is an operation object; the
+              // object check above guards a spec that put a scalar there.
+              operation: entry as FullOperation,
+            },
+          ]
+        : [];
+    });
+  });
+});
+
+/** A callback's request body and responses, `$ref`s resolved. */
+const callbackParts = (entry: CallbackEntry) => ({
+  requestBody: entry.operation.requestBody
+    ? resolveComponentRef(entry.operation.requestBody, components, "requestBodies")
+    : undefined,
+  responses: Object.fromEntries(
+    Object.entries(entry.operation.responses ?? {}).map(([status, response]) => [
+      status,
+      resolveComponentRef(response, components, "responses"),
+    ])
+  ),
+});
 ---
 {
   isAsyncApi ? (
@@ -160,6 +236,11 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
         <code class="break-all font-mono text-foreground text-sm">
           {ref.path}
         </code>
+        {isWebhook && (
+          <span class="rounded-md border border-border px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+            Webhook
+          </span>
+        )}
         {operation.deprecated && (
           <span class={DEPRECATED_LABEL_CLASS}>
             deprecated
@@ -184,7 +265,73 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               schemas={schemas}
             />
           )}
+          {callbacks.length > 0 && (
+            <section class="mt-10">
+              <div
+                aria-level="2"
+                class="mb-3 font-semibold text-foreground text-lg"
+                role="heading"
+              >
+                Callbacks
+              </div>
+              <div class="flex flex-col gap-6">
+                {callbacks.map((entry) => {
+                  const parts = callbackParts(entry);
+                  return (
+                    <div class="rounded-blume border border-border p-4">
+                      <div
+                        aria-level="3"
+                        class="font-semibold text-foreground"
+                        role="heading"
+                      >
+                        {entry.operation.summary || entry.name}
+                      </div>
+                      <div class="mt-2 flex flex-wrap items-center gap-2">
+                        <MethodBadge method={entry.method} />
+                        <code class="break-all font-mono text-muted-foreground text-xs">
+                          {entry.expression}
+                        </code>
+                      </div>
+                      {entry.operation.description && (
+                        <Description
+                          class="mt-2 text-muted-foreground text-sm"
+                          text={entry.operation.description}
+                        />
+                      )}
+                      {parts.requestBody && (
+                        <RequestBody
+                          expandAll={spec.expandSchemas}
+                          level={4}
+                          requestBody={parts.requestBody}
+                          schemas={schemas}
+                        />
+                      )}
+                      {entry.operation.responses && (
+                        <Responses
+                          expandAll={spec.expandSchemas}
+                          level={4}
+                          responses={parts.responses}
+                          schemas={schemas}
+                        />
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            </section>
+          )}
         </div>
+        {isWebhook && (requestBody?.content || operation.responses) && (
+          <OperationPanel>
+            <RequestPanel
+              components={components}
+              customSamples={customSamples}
+              payload={requestBody?.content}
+              responses={responses}
+              schemas={schemas}
+            />
+          </OperationPanel>
+        )}
         {sample && model && (
           <OperationPanel>
             {spec.playground.enabled && (
@@ -197,6 +344,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
             )}
             <RequestPanel
               components={components}
+              customSamples={customSamples}
               languages={languages}
               responses={responses}
               sample={sample}

package/src/components/openapi/RequestBody.astro

@@ -17,9 +17,11 @@ interface Props {
   requestBody: RequestBodyLike;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { requestBody, schemas, expandAll = false } = Astro.props;
+const { requestBody, schemas, expandAll = false, level = 2 } = Astro.props;
 
 const entries = Object.entries(requestBody.content ?? {});
 const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
@@ -27,11 +29,11 @@ const contentType = chosen?.[0] ?? "application/json";
 const schema = chosen?.[1]?.schema ?? {};
 ---
 
-<section class="mt-8">
+<section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
   <div class="mb-2 flex flex-wrap items-center gap-2">
     <div
-      aria-level="2"
-      class="font-semibold text-foreground text-lg"
+      aria-level={level}
+      class:list={["font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
       role="heading"
     >
       Request body

package/src/components/openapi/RequestPanel.astro

@@ -9,6 +9,7 @@ import {
   type SpecValue,
   toJson,
 } from "./helpers.ts";
+import type { CustomCodeSample } from "./code-samples.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
@@ -27,19 +28,69 @@ interface ResponseLike {
 interface Props {
   /** The document's `components`, which `$ref`'d examples resolve against. */
   components?: ComponentsLike;
-  sample: RequestSample;
-  languages: SampleLanguage[];
+  /** The spec's hand-written `x-codeSamples`, shown first and never re-rendered live. */
+  customSamples?: CustomCodeSample[];
+  /**
+   * A webhook's body: the rail shows it as a "Payload" example per media
+   * type in place of client code, since the API sends the request.
+   */
+  payload?: Record<string, MediaTypeLike>;
+  sample?: RequestSample;
+  languages?: SampleLanguage[];
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
 }
 
-const { components, sample, languages, responses, schemas } = Astro.props;
-
-const requestPanels = await languageSamplePanels(
-  languages,
+const {
+  components,
+  customSamples = [],
+  payload,
   sample,
-  data.config.codeThemes
+  languages = [],
+  responses,
+  schemas,
+} = Astro.props;
+
+/** A media type's example, highlighted, or null when it has none. */
+const highlightExample = async (media: MediaTypeLike, type: string) => {
+  const example = responseExample(media, schemas, components);
+  if (example === undefined || example === null) {
+    return null;
+  }
+  const json = type.includes("json");
+  return highlightCode(
+    json || typeof example !== "string" ? toJson(example) : example,
+    json ? "json" : "text",
+    { icons: false, themes: data.config.codeThemes }
+  );
+};
+
+// Hand-written samples carry no `lang` key, so the playground leaves them
+// as written when it re-renders the generated ones from the form.
+const customPanels = await Promise.all(
+  customSamples.map(async (custom) => ({
+    html: await highlightCode(custom.source, custom.lang, {
+      icons: false,
+      themes: data.config.codeThemes,
+    }),
+    key: custom.key,
+    label: custom.label,
+  }))
+);
+const payloadPanels = await Promise.all(
+  Object.entries(payload ?? {}).map(async ([type, media]) => ({
+    html: await highlightExample(media, type),
+    key: type,
+    label: type,
+    text: "No example payload.",
+  }))
 );
+const requestPanels = [
+  ...customPanels,
+  ...(sample
+    ? await languageSamplePanels(languages, sample, data.config.codeThemes)
+    : []),
+];
 
 const responsePanels = await Promise.all(
   Object.entries(responses).map(async ([status, response]) => {
@@ -66,6 +117,7 @@ const responsePanels = await Promise.all(
 ---
 
 <div class="not-prose flex flex-col gap-6">
+  <PanelTabs copy heading="Payload" mono panels={payloadPanels} />
   <PanelTabs copy heading="Request" panels={requestPanels} />
   <PanelTabs heading="Response" mono panels={responsePanels} />
 </div>

package/src/components/openapi/Responses.astro

@@ -17,19 +17,21 @@ interface Props {
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { responses, schemas, expandAll = false } = Astro.props;
+const { responses, schemas, expandAll = false, level = 2 } = Astro.props;
 
 const items = Object.entries(responses);
 ---
 
 {
   items.length > 0 && (
-    <section class="mt-8">
+    <section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
       <div
-        aria-level="2"
-        class="mb-3 font-semibold text-foreground text-lg"
+        aria-level={level}
+        class:list={["mb-3 font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
         role="heading"
       >
         Responses

package/src/components/openapi/async-snippets.ts

@@ -157,15 +157,15 @@ const ALIASES = new Map<string, ToolId>([
 /**
  * The sample tools to render for an operation. The protocol picks the
  * candidate set; a non-empty `codeSamples` config filters and orders it
- * (unknown ids are dropped, aliases accepted). No protocol, an unsupported
- * one, or a filter that matches nothing yields no samples.
+ * (unknown ids are dropped, aliases accepted). `false`, no protocol, an
+ * unsupported one, or a filter that matches nothing yields no samples.
  */
 export const asyncSampleLanguages = (
-  ids: string[],
+  ids: string[] | false,
   protocol?: string
 ): AsyncSampleLanguage[] => {
   const candidates = PROTOCOL_TOOLS.get(protocol ?? "") ?? [];
-  if (candidates.length === 0) {
+  if (ids === false || candidates.length === 0) {
     return [];
   }
   if (ids.length === 0) {

package/src/components/openapi/code-samples.ts

@@ -0,0 +1,97 @@
+import { sampleLanguageInfo } from "./snippets.ts";
+import type { SampleLanguageInfo } from "./snippets.ts";
+
+/**
+ * Hand-written code samples from a spec: the `x-codeSamples` extension on an
+ * operation (Redocly's, which Mintlify, Speakeasy, and Stainless write too),
+ * or its older spelling `x-code-samples`. Each entry names a `lang`, holds
+ * the `source`, and may carry a `label`. They render as their own tabs ahead
+ * of the generated samples and, being fixed text, the playground leaves them
+ * as written.
+ */
+
+/** One hand-written sample, ready to render as a tab. */
+export interface CustomCodeSample {
+  /** A stable, unique tab key. */
+  key: string;
+  /** The tab label: the entry's own, else the language's name. */
+  label: string;
+  /** The Shiki language to highlight `source` with. */
+  lang: string;
+  source: string;
+}
+
+/** The two places an operation keeps them. */
+export interface CodeSamplesCarrier {
+  "x-code-samples"?: unknown;
+  "x-codeSamples"?: unknown;
+}
+
+interface RawSample {
+  label?: string;
+  lang: string;
+  source: string;
+}
+
+const isRawSample = (value: unknown): value is RawSample =>
+  typeof value === "object" &&
+  value !== null &&
+  "lang" in value &&
+  typeof value.lang === "string" &&
+  "source" in value &&
+  typeof value.source === "string" &&
+  (!("label" in value) || typeof value.label === "string");
+
+// Shell tools in an `x-codeSamples` entry are usually an SDK's CLI, not curl,
+// so they're named for the shell rather than "cURL".
+const SHELL_LANGS = new Set(["bash", "sh", "shell", "zsh"]);
+
+/** The display name and highlighter for a sample's `lang`. */
+const describe = (lang: string): SampleLanguageInfo => {
+  const lower = lang.toLowerCase();
+  if (SHELL_LANGS.has(lower)) {
+    return { label: "Shell", lang: "bash" };
+  }
+  // A language Blume doesn't generate keeps its own name, and Shiki tries
+  // it as written (it knows most languages by their common names).
+  return sampleLanguageInfo(lower) ?? { label: lang, lang: lower };
+};
+
+/**
+ * The operation's hand-written samples, with a unique tab label each. A label
+ * two samples share gains its language (`List plants · JavaScript`), and one
+ * that still repeats gains a number. Malformed entries are skipped.
+ */
+export const customCodeSamples = (
+  operation: CodeSamplesCarrier
+): CustomCodeSample[] => {
+  const raw = operation["x-codeSamples"] ?? operation["x-code-samples"];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const entries = raw.filter(isRawSample).map((entry) => {
+    const language = describe(entry.lang);
+    return {
+      base: entry.label?.trim() || language.label,
+      language,
+      source: entry.source.replace(/\n$/u, ""),
+    };
+  });
+  const counts = new Map<string, number>();
+  for (const { base } of entries) {
+    counts.set(base, (counts.get(base) ?? 0) + 1);
+  }
+  const used = new Set<string>();
+  return entries.map(({ base, language, source }, index) => {
+    const first =
+      (counts.get(base) ?? 0) > 1 && base !== language.label
+        ? `${base} · ${language.label}`
+        : base;
+    let label = first;
+    for (let n = 2; used.has(label); n += 1) {
+      label = `${first} (${n})`;
+    }
+    used.add(label);
+    return { key: `x-${index}`, label, lang: language.lang, source };
+  });
+};

package/src/components/openapi/security.ts

@@ -45,12 +45,15 @@ export interface OperationSecurity {
 /**
  * The requirement list an operation actually enforces: its own `security` when
  * declared — the OpenAPI override rule, where `[]` removes the default and
- * makes the operation public — else the document's root `security`.
+ * makes the operation public — else the document's root `security`. A webhook
+ * takes only its own: the API sends it, so the root requirements, which guard
+ * calls to the API, say nothing about what the receiving endpoint checks.
  */
 export const effectiveSecurity = (
   operation?: SecurityRequirementLike[],
-  document?: SecurityRequirementLike[]
-): SecurityRequirementLike[] => operation ?? document ?? [];
+  document?: SecurityRequirementLike[],
+  webhook = false
+): SecurityRequirementLike[] => operation ?? (webhook ? [] : document) ?? [];
 
 /**
  * Resolve requirement names against `components.securitySchemes`. A name with