blume 2.2.0 → 2.2.2

package/src/core/schema.ts

@@ -43,6 +43,7 @@ import { isExternalUrl, normalizeBasePath } from "./base-path.ts";
 import { FOOTER_SOCIALS } from "./footer.ts";
 import { PUBLIC_HOST_URL } from "./github.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
+import { isBuiltInMcpClient, mcpClients } from "./mcp-clients.ts";
 import { openInChatProviders } from "./open-in-chat.ts";
 import { PAGE_MODES } from "./page-modes.ts";
 import { redirectPatternError } from "./redirect-patterns.ts";
@@ -487,10 +488,13 @@ const apiConfigSchema = z.strictObject({
 });
 
 /**
- * The site footer: a row of links, and social profile icons. Unset, the site
- * has no footer (a `components.ts` `Footer` still renders).
+ * The site footer: a copyright line, a row of links, and social profile
+ * icons. Unset, the site has no footer (a `components.ts` `Footer` still
+ * renders).
  */
 const footerConfigSchema = z.strictObject({
+  /** A line of plain text between the links and the icons (`© 2026 Acme, Inc.`). */
+  copyright: localizableLabelSchema.optional(),
   /** Links in one row, in the order written. */
   links: z
     .array(z.strictObject({ href: z.string(), label: localizableLabelSchema }))
@@ -891,7 +895,91 @@ const publicJwkSchema = z
     }
   });
 
+// The label is the row button's only accessible name (its icon is
+// decorative), so unlike a header link's it can't be blank in any locale.
+const mcpClientLabelSchema = z.union(
+  [
+    z.string().trim().min(1),
+    z
+      .record(z.string(), z.string().trim().min(1))
+      .refine((value) => Object.keys(value).length > 0, {
+        message: "Provide at least one locale's label.",
+      }),
+  ],
+  { error: "Expected a label, or a map of locale code to label" }
+);
+
+// A "Connect to MCP" row for a client Blume doesn't ship: its `command` is
+// copied with `{name}` and `{url}` filled in.
+const mcpCustomClientSchema = z.strictObject({
+  command: z.string().trim().min(1),
+  icon: iconName.optional(),
+  label: mcpClientLabelSchema,
+});
+
+const ACCEPTED_MCP_CLIENTS = `${mcpClients.map((key) => `"${key}"`).join(", ")}, or a custom client { label, command, icon? }`;
+
+/** A union's issue: every member failed, each with issues of its own. */
+const isUnionIssue = (
+  issue: z.core.$ZodIssue
+): issue is z.core.$ZodIssueInvalidUnion => issue.code === "invalid_union";
+
+// A bad entry fails the list member of `clients`, which zod reports as a bare
+// "Invalid input" on the whole list; that union issue is all this map sees.
+// The entries' issues ride along in `errors`. The culprit is an entry that
+// matches neither a built-in key nor a custom client, which fails as a union
+// at its index (a blank field or an unknown key elsewhere doesn't fail the
+// list on its own). Name that entry, and for a custom client its bad field.
+const mcpClientsError = (issue: z.core.$ZodRawIssue): string => {
+  const entryIssue = (issue.code === "invalid_union" ? issue.errors : [])
+    .flat()
+    .filter(isUnionIssue)
+    .find((nested) => Number.isInteger(nested.path[0]));
+  if (!entryIssue) {
+    return `agents.mcp.clients takes true, false, or a list whose entries are each ${ACCEPTED_MCP_CLIENTS}.`;
+  }
+  const index = Number(entryIssue.path[0]);
+  const at = `agents.mcp.clients.${String(index)}`;
+  const entry = Array.isArray(issue.input) ? issue.input[index] : null;
+  if (isString(entry)) {
+    return `${at} is "${entry}", which isn't a built-in client. Use ${ACCEPTED_MCP_CLIENTS}.`;
+  }
+  const fieldIssue = entryIssue.errors
+    .flat()
+    .find((nested) => nested.path.length > 0);
+  return fieldIssue
+    ? `${at}.${fieldIssue.path.map(String).join(".")}: ${fieldIssue.message}. A custom client is { label, command, icon? }.`
+    : `${at} isn't ${ACCEPTED_MCP_CLIENTS}.`;
+};
+
 const mcpConfigSchema = z.strictObject({
+  /**
+   * The "Connect to MCP" page action's clients. `true` (the default) lists
+   * every built-in client, `false` none (the menu keeps "Copy server URL"),
+   * and an array picks built-in clients by key and adds custom ones, in the
+   * given order. Normalized to the list so consumers read a plain array.
+   */
+  clients: z
+    .union(
+      [
+        z.boolean(),
+        z.array(z.union([z.enum(mcpClients), mcpCustomClientSchema])).refine(
+          (value) => {
+            const keys = value.filter(isBuiltInMcpClient);
+            return new Set(keys).size === keys.length;
+          },
+          { message: "agents.mcp.clients must not repeat a built-in client." }
+        ),
+      ],
+      { error: mcpClientsError }
+    )
+    .default(true)
+    .transform((value) => {
+      if (isBoolean(value)) {
+        return value ? [...mcpClients] : [];
+      }
+      return value;
+    }),
   enabled: z.boolean().default(false),
   /** Optional system hint passed to connecting agents. */
   instructions: z.string().optional(),
@@ -1182,6 +1270,8 @@ export type AssistantConfig = NonNullable<
 >;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";
+export { mcpClients } from "./mcp-clients.ts";
+export type { McpClient, McpCustomClient } from "./mcp-clients.ts";
 
 // Reader-facing "Export" page action (PDF via print, EPUB via client-side
 // generation). Off by default. Accepts a shorthand boolean to toggle both
@@ -2271,7 +2361,7 @@ export const blumeConfigSchema = z
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message:
-          'rateLimit: cloudflare() counts with a Workers binding, so it needs `deployment: cloudflare()` from "blume/deploy". On another host, use upstash() or memory() from "blume/ratelimit".',
+          'rateLimit: cloudflare() counts with a Workers binding, so it needs `deployment: cloudflare()` from "blume/deploy". On another host, use upstash(), unkey(), or memory() from "blume/ratelimit".',
         path: ["rateLimit"],
       });
     }

package/src/openapi/proxy.ts

@@ -196,7 +196,11 @@ const followUpstream = async (args: {
   signal: AbortSignal;
   url: URL;
 }): Promise<Response> => {
-  const response = await args.fetchImpl(args.url, {
+  // Called bare, never as `args.fetchImpl(...)`: that would run the global
+  // `fetch` with `this` set to `args`, which Node allows and workerd rejects
+  // as an "Illegal invocation".
+  const { fetchImpl } = args;
+  const response = await fetchImpl(args.url, {
     body: args.body,
     headers: args.headers,
     method: args.method,

package/src/ratelimit/index.ts

@@ -28,3 +28,5 @@ export type { MemoryAdapter, RateLimitOptions } from "./memory.ts";
 export type { RateLimitAdapter } from "./schema.ts";
 export { upstash } from "./upstash.ts";
 export type { UpstashAdapter, UpstashOptions } from "./upstash.ts";
+export { unkey } from "./unkey.ts";
+export type { UnkeyAdapter, UnkeyOptions } from "./unkey.ts";

package/src/ratelimit/memory.ts

@@ -35,7 +35,7 @@ export const memoryAdapterSchema = adapterDescriptorSchema(
  * platform that runs many short-lived instances (Vercel, Netlify,
  * Cloudflare) each instance keeps its own, so it stops a burst from one
  * reader rather than enforcing the limit exactly. For that, share the count
- * with `upstash()` or `cloudflare()`.
+ * with `upstash()`, `cloudflare()`, or `unkey()`.
  */
 export const memory = (options: RateLimitOptions = {}): MemoryAdapter => ({
   kind: "memory",

package/src/ratelimit/runtime.ts

@@ -11,11 +11,14 @@
  * the shared store fails to count (logged, not blocked). A shared store
  * without its secrets or binding falls back to counting in memory.
  */
+import { z } from "zod";
+
 import { clientAddressOf } from "../core/client-address.ts";
 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 { UNKEY_MAX_WINDOW, UNKEY_NAMESPACE, unkeySecrets } from "./unkey.ts";
 import { upstashSecrets } from "./upstash.ts";
 
 /** What a limiter says about one request. */
@@ -152,6 +155,68 @@ export const upstashLimiter = (
   };
 };
 
+/** Unkey's rate limit endpoint. */
+const UNKEY_LIMIT_URL = "https://api.unkey.com/v2/ratelimit.limit";
+
+/**
+ * How long Unkey gets to count a request, in milliseconds, before the
+ * request is let through without it.
+ */
+export const UNKEY_TIMEOUT = 2000;
+
+/** The part of Unkey's reply the limiter reads. */
+const unkeyReplySchema = z.object({
+  data: z.object({
+    overrideId: z.string().optional(),
+    reset: z.number(),
+    success: z.boolean(),
+  }),
+});
+
+/**
+ * Count with Unkey's rate limit API. Unkey takes identifiers of letters,
+ * digits, and `_.:/-`, so anything else in the key (an IPv6 host's brackets,
+ * an address's `%` zone) becomes `_`. Its `reset` is a timestamp on Unkey's
+ * clock, which this server's may not match, so `retryAfter` is kept between
+ * one second and the window: the configured one, or Unkey's longest when an
+ * override set in Unkey replaced it.
+ */
+export const unkeyLimiter =
+  (
+    requests: number,
+    window: number,
+    namespace: string,
+    rootKey: string,
+    { fetch: fetchImpl = fetch, now = Date.now }: LimiterRuntime = {}
+  ): Limiter =>
+  async (key) => {
+    const response = await fetchImpl(UNKEY_LIMIT_URL, {
+      body: JSON.stringify({
+        duration: window * 1000,
+        identifier: key.replaceAll(/[^\w.:/-]/gu, "_"),
+        limit: requests,
+        namespace,
+      }),
+      headers: {
+        authorization: `Bearer ${rootKey}`,
+        "content-type": "application/json",
+      },
+      method: "POST",
+      signal: AbortSignal.timeout(UNKEY_TIMEOUT),
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(`Unkey answered ${response.status}.`);
+    }
+    const { data } = unkeyReplySchema.parse(await response.json());
+    const seconds = Math.ceil((data.reset - now()) / 1000);
+    const longest = data.overrideId ? UNKEY_MAX_WINDOW : window;
+    return {
+      allowed: data.success,
+      retryAfter: Math.min(longest, Math.max(1, seconds)),
+    };
+  };
+
 /** Count with a Workers rate limiting binding. */
 export const bindingLimiter =
   (binding: RateLimitBinding, window: number): Limiter =>
@@ -185,6 +250,22 @@ export const createLimiter = (
     return null;
   }
   const { requests, window } = limitOf(adapter);
+  if (adapter.kind === "unkey") {
+    const [secret] = unkeySecrets(adapter.options);
+    const rootKey = runtime.secret?.(secret);
+    if (rootKey) {
+      return unkeyLimiter(
+        requests,
+        window,
+        adapter.options.namespace ?? UNKEY_NAMESPACE,
+        rootKey,
+        runtime
+      );
+    }
+    console.warn(
+      `Rate limiting counts in memory: set ${secret} to share the count through Unkey.`
+    );
+  }
   if (adapter.kind === "cloudflare") {
     if (runtime.binding) {
       return bindingLimiter(runtime.binding, window);

package/src/ratelimit/schema.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { cloudflareRateLimitAdapterSchema } from "./cloudflare.ts";
 import { memory, memoryAdapterSchema } from "./memory.ts";
+import { unkeyAdapterSchema } from "./unkey.ts";
 import { upstashAdapterSchema } from "./upstash.ts";
 
 const ADAPTER_HINT =
@@ -12,6 +13,7 @@ export const rateLimitAdapterSchema = z.discriminatedUnion("kind", [
   cloudflareRateLimitAdapterSchema,
   memoryAdapterSchema,
   upstashAdapterSchema,
+  unkeyAdapterSchema,
 ]);
 
 export type RateLimitAdapter = z.output<typeof rateLimitAdapterSchema>;

package/src/ratelimit/unkey.ts

@@ -0,0 +1,61 @@
+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 var holding the Unkey root key, unless set. */
+const UNKEY_ROOT_KEY_ENV = "UNKEY_ROOT_KEY";
+
+/** The Unkey rate limit namespace the count is kept in, unless set. */
+export const UNKEY_NAMESPACE = "docs";
+
+/** The longest window Unkey takes, in seconds (30 days). */
+export const UNKEY_MAX_WINDOW = 2_592_000;
+
+/** Options for {@link unkey}. */
+export interface UnkeyOptions extends RateLimitOptions {
+  /**
+   * The Unkey rate limit namespace, up to 512 characters. Defaults to `docs`;
+   * Unkey creates it on the first request.
+   */
+  namespace?: string;
+  /** Name of the env var holding the root key. Defaults to `UNKEY_ROOT_KEY`. */
+  rootKeyEnv?: string;
+  /** The window, in seconds: Unkey takes up to 30 days. */
+  window?: number;
+}
+
+export const unkeyOptionsSchema = rateLimitOptionsSchema.extend({
+  namespace: z.string().min(1).max(512).optional(),
+  rootKeyEnv: z.string().min(1).optional(),
+  window: z.number().int().positive().max(UNKEY_MAX_WINDOW).optional(),
+});
+
+export type UnkeyAdapter = AdapterDescriptor<"unkey", UnkeyOptions>;
+
+export const unkeyAdapterSchema = adapterDescriptorSchema(
+  "unkey",
+  unkeyOptionsSchema
+);
+
+/** The env var the root key is read from. */
+export const unkeySecrets = (options: UnkeyOptions): [string] => [
+  options.rootKeyEnv ?? UNKEY_ROOT_KEY_ENV,
+];
+
+/**
+ * Counts with Unkey's rate limiting, which every instance on every host
+ * shares. Unkey counts in each region and shares the counts between them
+ * within moments, so a short burst split across regions can pass more than
+ * the limit. It talks to Unkey's REST API, so there is nothing to install;
+ * the root key comes from `UNKEY_ROOT_KEY`, or the env var `rootKeyEnv`
+ * names.
+ */
+export const unkey = (options: UnkeyOptions = {}): UnkeyAdapter => ({
+  kind: "unkey",
+  options,
+  requiredSecrets: unkeySecrets(options),
+  runtimeDeps: [],
+});

package/src/registry/registry.ts

@@ -264,7 +264,7 @@ export const registry: RegistryItem[] = [
   }),
   layoutComponent({
     description:
-      "The site footer: a row of links, social icons, the theme toggle, and the Cookie settings link.",
+      "The site footer: a copyright line, a row of links, social icons, and the Cookie settings link.",
     file: "SiteFooter.astro",
     name: "footer",
     slot: "Footer",