blume 1.5.0 → 1.5.2

package/src/components/openapi/request.ts

@@ -0,0 +1,287 @@
+import type { RequestSample } from "./snippets.ts";
+
+/**
+ * Framework-free request model for the "Try it" playground. This module ships
+ * in the client bundle, so it must stay dependency-free: parameter and body
+ * examples are precomputed server-side (`operation-model.ts`) and embedded in
+ * the model JSON — nothing here touches openapi-sampler or the spec document.
+ * `buildRequest` is THE one request builder: the code samples, the copy
+ * buttons, and the live fetch all consume its output, so what readers see is
+ * byte-for-byte what gets sent.
+ */
+
+export interface PlaygroundParam {
+  name: string;
+  in: "path" | "query" | "header";
+  required: boolean;
+  description?: string;
+  /** Short type label for the input: "string" | "number" | "integer" | "boolean" | ... */
+  type: string;
+  /** Enum members stringified, when the schema declares them. */
+  enum?: string[];
+  /** Precomputed default from spec example/sampler; "" when none (optional params default ""). */
+  value: string;
+}
+
+export interface PlaygroundBodyField {
+  name: string;
+  required: boolean;
+  description?: string;
+  /** Primitive type name; the client coerces number/integer/boolean. */
+  type: string;
+  enum?: string[];
+  /** Stringified default, "" when none. */
+  value: string;
+}
+
+/** A pruned, cycle-free JSON-schema subset `validate-json.ts` understands. */
+export interface ValidationSchema {
+  type?: string;
+  properties?: Record<string, ValidationSchema>;
+  required?: string[];
+  items?: ValidationSchema;
+  enum?: unknown[];
+}
+
+export interface PlaygroundBody {
+  contentType: string;
+  /** Present when the schema is a flat object of primitives -> typed fields UI. */
+  fields?: PlaygroundBodyField[];
+  /** Pretty-printed example JSON prefill for the raw editor; "" when none. */
+  example: string;
+  schema?: ValidationSchema;
+}
+
+export type AuthKind = "bearer" | "basic" | "apiKey" | "oauth2";
+
+export interface PlaygroundAuthInput {
+  /** SecurityScheme component key. */
+  id: string;
+  kind: AuthKind;
+  /** `schemeLabel()` output. */
+  label: string;
+  carrier: { in: "header" | "query" | "cookie"; name: string };
+  /** Placeholder credential used in redacted samples, e.g. "YOUR_TOKEN". */
+  placeholder: string;
+  /** Header value prefix, e.g. "Bearer " ("" for apiKey). Basic uses "Basic ". */
+  prefix: string;
+}
+
+export interface PlaygroundModel {
+  /** Upper-case HTTP method. */
+  method: string;
+  /** Templated path, e.g. `/pets/{id}`. */
+  path: string;
+  /** Spec servers in order; first is the default base. */
+  servers: string[];
+  params: PlaygroundParam[];
+  body?: PlaygroundBody;
+  /** First security alternative (AND set). */
+  auth: PlaygroundAuthInput[];
+  authOptional: boolean;
+}
+
+export interface AuthValue {
+  value: string;
+  username?: string;
+  password?: string;
+}
+
+export interface RequestValues {
+  /** Resolved base URL (custom override already applied). */
+  server: string;
+  /** Key: `paramKey(param)`. */
+  params: Record<string, string>;
+  /** Raw JSON text; undefined = no body. */
+  body?: string;
+  /** Key: `PlaygroundAuthInput.id`. */
+  auth: Record<string, AuthValue>;
+}
+
+export const paramKey = (p: { in: string; name: string }): string =>
+  `${p.in}:${p.name}`;
+
+/** Values pre-filled from the model's precomputed examples; auth entries empty. */
+export const defaultValues = (model: PlaygroundModel): RequestValues => ({
+  auth: Object.fromEntries(
+    model.auth.map((input) => [input.id, { value: "" }])
+  ),
+  body: model.body ? model.body.example : undefined,
+  params: Object.fromEntries(
+    model.params.map((param) => [paramKey(param), param.value])
+  ),
+  server: model.servers[0] ?? "",
+});
+
+/** Copy of `values` with every auth value emptied (redacted) so samples show placeholders. */
+export const redactAuth = (
+  model: PlaygroundModel,
+  values: RequestValues
+): RequestValues => ({
+  ...values,
+  auth: Object.fromEntries(
+    model.auth.map((input) => [input.id, { value: "" }])
+  ),
+});
+
+const TRAILING_SLASH = /\/+$/u;
+
+/**
+ * Base64 of `text`'s UTF-8 bytes. `btoa` alone throws on any code point above
+ * U+00FF, so a credential with non-Latin-1 characters (a Cyrillic username, an
+ * emoji in a password) would take down every sample render; RFC 7617 names
+ * UTF-8 as the charset to encode a `user:password` pair in.
+ */
+const base64Utf8 = (text: string): string => {
+  let binary = "";
+  for (const byte of new TextEncoder().encode(text)) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary);
+};
+
+/**
+ * The credential a request carries for one auth input: the user's value when
+ * present, else the redaction placeholder. Basic auth encodes user:password
+ * per RFC 7617 — the placeholder stands in until either field is filled.
+ */
+const credentialFor = (
+  input: PlaygroundAuthInput,
+  auth: AuthValue | undefined
+): string => {
+  if (input.kind === "basic") {
+    const username = auth?.username ?? "";
+    const password = auth?.password ?? "";
+    return username !== "" || password !== ""
+      ? base64Utf8(`${username}:${password}`)
+      : input.placeholder;
+  }
+  const value = auth?.value ?? "";
+  return value === "" ? input.placeholder : value;
+};
+
+/**
+ * Apply the model's auth inputs to the outgoing query/headers. Query-borne
+ * credentials skip names an explicit query parameter already contributed (the
+ * spec's example wins); cookie-borne ones collapse into a single `Cookie`
+ * header, matching how browsers send them.
+ */
+const applyAuth = (
+  model: PlaygroundModel,
+  values: RequestValues,
+  seen: ReadonlySet<string>,
+  query: string[],
+  headers: Record<string, string>
+): void => {
+  const cookies: string[] = [];
+  for (const input of model.auth) {
+    const credential = credentialFor(input, values.auth[input.id]);
+    if (input.carrier.in === "query") {
+      if (!seen.has(input.carrier.name)) {
+        query.push(
+          `${encodeURIComponent(input.carrier.name)}=${encodeURIComponent(
+            credential
+          )}`
+        );
+      }
+    } else if (input.carrier.in === "cookie") {
+      cookies.push(`${input.carrier.name}=${credential}`);
+    } else {
+      headers[input.carrier.name] = `${input.prefix}${credential}`;
+    }
+  }
+  if (cookies.length > 0) {
+    headers.Cookie = cookies.join("; ");
+  }
+};
+
+/** The raw editor text to send, with a parsed mirror when it is valid JSON. */
+const bodyFor = (
+  text: string | undefined
+): Pick<RequestSample, "body" | "bodyValue"> => {
+  if (text === undefined || text === "") {
+    return {};
+  }
+  try {
+    return { body: text, bodyValue: JSON.parse(text) };
+  } catch {
+    // Not valid JSON (mid-edit or intentionally raw): still send it — the
+    // structured mirror is only a nicety for consumers of `bodyValue`.
+    return { body: text };
+  }
+};
+
+/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
+export const buildRequest = (
+  model: PlaygroundModel,
+  values: RequestValues
+): RequestSample => {
+  const base = values.server.replace(TRAILING_SLASH, "");
+
+  // Path params: an empty value substitutes the raw param name, so a blank
+  // form still renders a readable templated URL instead of `//`.
+  let resolvedPath = model.path;
+  for (const param of model.params) {
+    if (param.in !== "path") {
+      continue;
+    }
+    const value = values.params[paramKey(param)] ?? "";
+    resolvedPath = resolvedPath.replace(
+      `{${param.name}}`,
+      value === "" ? param.name : encodeURIComponent(value)
+    );
+  }
+
+  // Query params with a value contribute in model order; a query-borne auth
+  // credential appends after — unless the spec also declares that name as an
+  // explicit query parameter, whose (better) example wins.
+  const query: string[] = [];
+  const seen = new Set<string>();
+  for (const param of model.params) {
+    if (param.in !== "query") {
+      continue;
+    }
+    const value = values.params[paramKey(param)] ?? "";
+    // A required param stays visible even when blank (`filter=`) — silently
+    // dropping it would make the samples deny the parameter exists. Optional
+    // blanks drop out entirely.
+    if (value === "" && !param.required) {
+      continue;
+    }
+    seen.add(param.name);
+    query.push(
+      `${encodeURIComponent(param.name)}=${encodeURIComponent(value)}`
+    );
+  }
+
+  // Auth first, so a spec that also declares the credential as an explicit
+  // header parameter overrides it below with its own (better) example.
+  const headers: Record<string, string> = {};
+  applyAuth(model, values, seen, query, headers);
+  for (const param of model.params) {
+    if (param.in !== "header") {
+      continue;
+    }
+    const value = values.params[paramKey(param)] ?? "";
+    // Required headers emit even when blank, mirroring the query rule above —
+    // except a blank one never clobbers a credential auth already placed
+    // under the same name.
+    if (value !== "" || (param.required && headers[param.name] === undefined)) {
+      headers[param.name] = value;
+    }
+  }
+
+  const { body, bodyValue } = model.body ? bodyFor(values.body) : {};
+  if (body !== undefined && model.body) {
+    headers["Content-Type"] = model.body.contentType;
+  }
+
+  const search = query.length > 0 ? `?${query.join("&")}` : "";
+  return {
+    body,
+    bodyValue,
+    headers,
+    method: model.method.toUpperCase(),
+    url: `${base}${resolvedPath}${search}`,
+  };
+};

package/src/components/openapi/security.ts

@@ -152,9 +152,6 @@ export const resolveAsyncApiSecurity = (
   return { alternatives, optional: false };
 };
 
-const capitalize = (text: string): string =>
-  text.charAt(0).toUpperCase() + text.slice(1);
-
 /**
  * Fixed labels for scheme types with no per-scheme variation. Covers both
  * OpenAPI's types and the broker-auth types AsyncAPI adds; `http` is handled
@@ -219,56 +216,3 @@ export const schemeCarrier = (
     }
   }
 };
-
-/** Placeholder credentials the request samples send. */
-export interface SampleAuth {
-  headers: Record<string, string>;
-  query: Record<string, string>;
-}
-
-/**
- * Placeholder credentials for an operation's request samples, from its first
- * alternative (the spec's preferred way to authorize). Schemes that don't
- * travel in the request (mutual TLS) and unknown refs contribute nothing.
- */
-export const sampleAuth = (security: OperationSecurity): SampleAuth => {
-  const headers: Record<string, string> = {};
-  const query: Record<string, string> = {};
-  const cookies: string[] = [];
-  for (const resolved of security.alternatives[0] ?? []) {
-    const { scheme } = resolved;
-    switch (scheme?.type) {
-      case "http": {
-        const kind = (scheme.scheme ?? "bearer").toLowerCase();
-        headers.Authorization =
-          kind === "bearer"
-            ? "Bearer YOUR_TOKEN"
-            : `${capitalize(kind)} YOUR_CREDENTIALS`;
-        break;
-      }
-      case "oauth2":
-      case "openIdConnect": {
-        headers.Authorization = "Bearer YOUR_ACCESS_TOKEN";
-        break;
-      }
-      case "apiKey": {
-        const name = scheme.name ?? resolved.key;
-        if (scheme.in === "query") {
-          query[name] = "YOUR_API_KEY";
-        } else if (scheme.in === "cookie") {
-          cookies.push(`${name}=YOUR_API_KEY`);
-        } else {
-          headers[name] = "YOUR_API_KEY";
-        }
-        break;
-      }
-      default: {
-        break;
-      }
-    }
-  }
-  if (cookies.length > 0) {
-    headers.Cookie = cookies.join("; ");
-  }
-  return { headers, query };
-};

package/src/components/openapi/snippets.ts

@@ -1,31 +1,12 @@
-import { exampleValue, toJson } from "./helpers.ts";
-import type { SchemaLike } from "./helpers.ts";
-import type { SampleAuth } from "./security.ts";
-
 /**
- * Request example + code-sample generation for an operation. Kept separate from
- * `helpers.ts` so the schema renderers don't pull in the sample builders. Output
- * is intentionally simple, copy-pasteable starter code — not an exhaustive SDK.
+ * Code-sample generation for an operation. Deliberately dependency-free: the
+ * playground client renders samples live in the browser, so this module must
+ * stay out of the server-only dependency graph (no helpers.ts, no
+ * openapi-sampler). Requests are assembled once by `buildRequest` in
+ * `request.ts`; the builders here only render a finished `RequestSample` as
+ * simple, copy-pasteable starter code — not an exhaustive SDK.
  */
 
-interface ParamLike {
-  name?: string;
-  in?: string;
-  required?: boolean;
-  schema?: SchemaLike;
-  example?: unknown;
-}
-
-interface MediaTypeLike {
-  schema?: SchemaLike;
-  example?: unknown;
-}
-
-export interface OperationLike {
-  parameters?: ParamLike[];
-  requestBody?: { content?: Record<string, MediaTypeLike> };
-}
-
 export interface RequestSample {
   method: string;
   url: string;
@@ -35,115 +16,6 @@ export interface RequestSample {
   bodyValue?: unknown;
 }
 
-const TRAILING_SLASH = /\/+$/u;
-
-const jsonContentType = (
-  content: Record<string, MediaTypeLike> | undefined
-): [string, MediaTypeLike] | undefined => {
-  const entries = Object.entries(content ?? {});
-  return entries.find(([type]) => type.includes("json")) ?? entries[0];
-};
-
-/**
- * The `?a=1&b=2` query string from an operation's required query params, plus
- * any extra entries (a query-borne API key from the security requirements).
- */
-const queryString = (
-  params: ParamLike[],
-  schemas: Record<string, SchemaLike>,
-  extra: Record<string, string>
-): string => {
-  const query: string[] = [];
-  const seen = new Set<string>();
-  for (const param of params) {
-    if (!(param.in === "query" && param.required && param.name)) {
-      continue;
-    }
-    seen.add(param.name);
-    const value = param.example ?? exampleValue(param.schema, schemas);
-    query.push(
-      `${encodeURIComponent(param.name)}=${encodeURIComponent(
-        String(value ?? "")
-      )}`
-    );
-  }
-  for (const [name, value] of Object.entries(extra)) {
-    // A spec may declare the credential as an explicit query parameter too;
-    // its (better) example wins over the auth placeholder, as in headers.
-    if (seen.has(name)) {
-      continue;
-    }
-    query.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
-  }
-  return query.length > 0 ? `?${query.join("&")}` : "";
-};
-
-/**
- * The sample's headers: auth placeholders first, so a spec that also declares
- * the credential as an explicit header parameter overrides them with its own
- * (better) example.
- */
-const headerValues = (
-  params: ParamLike[],
-  schemas: Record<string, SchemaLike>,
-  auth: SampleAuth | undefined
-) => {
-  const headers = { ...auth?.headers };
-  for (const param of params) {
-    if (param.in === "header" && param.required && param.name) {
-      headers[param.name] = String(
-        param.example ?? exampleValue(param.schema, schemas) ?? ""
-      );
-    }
-  }
-  return headers;
-};
-
-/** Assemble a representative request from an operation and the spec servers. */
-export const buildRequestSample = (
-  operation: OperationLike,
-  method: string,
-  path: string,
-  servers: { url?: string }[],
-  schemas: Record<string, SchemaLike>,
-  auth?: SampleAuth
-): RequestSample => {
-  const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
-  const params = operation.parameters ?? [];
-
-  let resolvedPath = path;
-  for (const param of params) {
-    if (param.in === "path" && param.name) {
-      const value = param.example ?? exampleValue(param.schema, schemas);
-      resolvedPath = resolvedPath.replace(
-        `{${param.name}}`,
-        encodeURIComponent(String(value ?? param.name))
-      );
-    }
-  }
-
-  const search = queryString(params, schemas, auth?.query ?? {});
-  const headers = headerValues(params, schemas, auth);
-
-  const media = jsonContentType(operation.requestBody?.content);
-  let body: string | undefined;
-  let bodyValue: unknown;
-  if (media) {
-    const [type, mediaType] = media;
-    headers["Content-Type"] = type;
-    bodyValue = mediaType.example ?? exampleValue(mediaType.schema, schemas);
-    body = toJson(bodyValue);
-  }
-
-  return {
-    body,
-    bodyValue,
-    headers,
-    method: method.toUpperCase(),
-    url: `${base}${resolvedPath}${search}`,
-  };
-};
-
 const headerLines = (
   headers: Record<string, string>,
   format: (key: string, value: string) => string
@@ -174,7 +46,15 @@ const fetchSnippet = (sample: RequestSample): string => {
     options.push(`  headers: {\n${headers}\n  }`);
   }
   if (sample.body) {
-    options.push(`  body: JSON.stringify(${sample.body})`);
+    // `bodyValue` mirrors the body only when it parses as JSON. Mid-edit text
+    // that doesn't can't be inlined as a JS expression — a string literal of
+    // the raw text keeps the snippet syntactically valid and byte-identical
+    // to what the live send transmits.
+    options.push(
+      sample.bodyValue === undefined
+        ? `  body: ${JSON.stringify(sample.body)}`
+        : `  body: JSON.stringify(${sample.body})`
+    );
   }
   return `const response = await fetch("${sample.url}", {\n${options.join(
     ",\n"
@@ -209,7 +89,14 @@ const pythonSnippet = (sample: RequestSample): string => {
     args.push(`    headers={\n${headers}\n    }`);
   }
   if (sample.body) {
-    args.push(`    json=${toPython(sample.body)}`);
+    // Same rule as the fetch snippet: only valid JSON rewrites into a Python
+    // literal for `json=`; anything else travels as a raw string via `data=`
+    // (JSON string escapes are a subset of Python's, so the literal is valid).
+    args.push(
+      sample.bodyValue === undefined
+        ? `    data=${JSON.stringify(sample.body)}`
+        : `    json=${toPython(sample.body)}`
+    );
   }
   return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
     ",\n"

package/src/components/openapi/validate-json.ts

@@ -0,0 +1,144 @@
+import type { ValidationSchema } from "./request.ts";
+
+/**
+ * Minimal JSON-schema validation for the playground body editor. Client-safe
+ * and dependency-free by design: the server prunes the operation's schema into
+ * the tiny `ValidationSchema` subset (`operation-model.ts`), so a full
+ * draft-2020 validator would be dead weight in the browser bundle. Checks are
+ * advisory — they catch the common "typo'd a required field" mistakes, they do
+ * not gate the Send button.
+ */
+
+/** An already-parsed JSON object — string keys, parsed-JSON values. */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** Already-parsed JSON — everything `JSON.parse` can produce. */
+type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+
+// `typeof` checks live in named predicates (the form the oxlint anti-slop
+// config sanctions); each narrows the parsed-JSON union at its call site.
+const isString = (value: JsonValue): value is string =>
+  typeof value === "string";
+
+const isNumber = (value: JsonValue): value is number =>
+  typeof value === "number";
+
+const isBoolean = (value: JsonValue): value is boolean =>
+  typeof value === "boolean";
+
+const isJsonObject = (value: JsonValue): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A human-readable name for a value's actual type, for mismatch messages. */
+const describeValue = (value: JsonValue): string => {
+  if (value === null) {
+    return "null";
+  }
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- typeof's result string is itself the human-readable label here, not a narrowing check
+  return Array.isArray(value) ? "array" : typeof value;
+};
+
+/** Whether `value` satisfies a schema `type` keyword; unknown keywords pass. */
+const matchesType = (value: JsonValue, type: string): boolean => {
+  switch (type) {
+    case "object": {
+      return isJsonObject(value);
+    }
+    case "array": {
+      return Array.isArray(value);
+    }
+    case "string": {
+      return isString(value);
+    }
+    case "number": {
+      return isNumber(value);
+    }
+    case "integer": {
+      return isNumber(value) && Number.isInteger(value);
+    }
+    case "boolean": {
+      return isBoolean(value);
+    }
+    default: {
+      // A keyword the pruned subset doesn't model (e.g. "null"): no opinion.
+      return true;
+    }
+  }
+};
+
+const walk = (
+  value: JsonValue,
+  schema: ValidationSchema | undefined,
+  path: string,
+  errors: string[]
+): void => {
+  if (!schema) {
+    return;
+  }
+  if (schema.type !== undefined && !matchesType(value, schema.type)) {
+    // Deeper checks against a wrong-shaped value would only produce noise.
+    errors.push(
+      `${path} should be ${schema.type}, got ${describeValue(value)}`
+    );
+    return;
+  }
+  if (
+    schema.enum !== undefined &&
+    !schema.enum.some(
+      (member) => JSON.stringify(member) === JSON.stringify(value)
+    )
+  ) {
+    errors.push(
+      `${path} must be one of: ${schema.enum
+        .map((member) => JSON.stringify(member))
+        .join(", ")}`
+    );
+  }
+  if (isJsonObject(value)) {
+    for (const name of schema.required ?? []) {
+      if (!(name in value)) {
+        errors.push(`${path}.${name} is required`);
+      }
+    }
+    for (const [name, property] of Object.entries(schema.properties ?? {})) {
+      if (name in value) {
+        // SAFETY: `name in value` above proves the key exists, and parsed
+        // JSON never holds `undefined` — the lookup is always a `JsonValue`
+        // that `noUncheckedIndexedAccess` alone cannot see.
+        walk(value[name] as JsonValue, property, `${path}.${name}`, errors);
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    for (const [index, item] of value.entries()) {
+      walk(item, schema.items, `${path}[${index}]`, errors);
+    }
+  }
+};
+
+/**
+ * Validate raw JSON text against a pruned schema. Returns human-readable
+ * error messages; an empty array means valid. With no schema, only syntax is
+ * checked. `root` names the value in those messages — the HTTP panel edits a
+ * `body`, the event composer a `payload`.
+ */
+export const validateJson = (
+  text: string,
+  schema?: ValidationSchema,
+  root = "body"
+): string[] => {
+  // `JSON.parse` returns `any`; `JsonValue` is exactly its possible outputs.
+  let value: JsonValue;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    return [
+      `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    ];
+  }
+  const errors: string[] = [];
+  walk(value, schema, root, errors);
+  return errors;
+};