@mybase-dev/sdk 1.0.0 → 1.0.1

package/src/captcha.ts

@@ -0,0 +1,110 @@
+// mybase's self-hosted captcha: proof of work instead of puzzles. The browser gets a signed
+// challenge from the project, finds the number whose SHA-256 matches (a fraction of a second),
+// and sends the answer with the form; your server checks it once with mybase.
+//
+//   // Browser (or use the script tag: <script src="https://mybase.example.com/captcha.js" data-project="shop">)
+//   const token = await solveCaptcha({ apiUrl, project: "shop" });
+//   await fetch("/signup", { method: "POST", headers: { "x-captcha-response": token }, body });
+//
+//   // Server
+//   const captcha = createCaptchaClient({ apiUrl, project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+//   const { success } = await captcha.verify(token);
+//
+// With Better Auth, use `mybaseCaptcha()` from @mybase-dev/sdk/better-auth instead of verify().
+// No cookies, no third party, nothing to see or click. Tokens work once and expire after 5 minutes.
+import { MybaseApiError } from "./cron";
+
+export { MybaseApiError };
+
+export const CAPTCHA_LIMITS = {
+  /** How long a challenge (and so its token) stays valid. */
+  expiresMs: 5 * 60_000,
+  /** The work: the browser tries up to this many numbers (half on average). */
+  maxNumber: { min: 1_000, max: 1_000_000, default: 50_000 },
+  tokenLength: 2_000,
+} as const;
+
+/** `GET /captcha/:project/challenge`. `salt` carries its expiry (`…?expires=<unix seconds>`). */
+export interface CaptchaChallenge {
+  algorithm: "SHA-256";
+  challenge: string;
+  salt: string;
+  maxnumber: number;
+  signature: string;
+}
+
+/** What `verify` answers. `error` says why a token was refused. */
+export interface CaptchaVerifyResponse {
+  success: boolean;
+  error?: "invalid" | "expired" | "used" | "unavailable";
+}
+
+const hex = (buf: ArrayBuffer) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+
+export async function sha256Hex(text: string): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+}
+
+/** The token for a solved challenge: base64 of the challenge plus the number found. */
+export function encodeToken(c: CaptchaChallenge, number: number): string {
+  const json = JSON.stringify({ algorithm: c.algorithm, challenge: c.challenge, number, salt: c.salt, signature: c.signature });
+  return btoa(json);
+}
+
+/** Finds the number. Rejects if none up to `maxnumber` matches, or when `signal` aborts. */
+export async function solveChallenge(c: CaptchaChallenge, { signal }: { signal?: AbortSignal } = {}): Promise<string> {
+  if (c.algorithm !== "SHA-256") throw new Error(`mybase captcha: unknown algorithm ${c.algorithm}`);
+  for (let n = 0; n <= c.maxnumber; n++) {
+    if ((await sha256Hex(c.salt + n)) === c.challenge) return encodeToken(c, n);
+    if (n % 1000 === 0 && signal?.aborted) throw signal.reason ?? new Error("aborted");
+  }
+  throw new Error("mybase captcha: challenge has no solution");
+}
+
+export interface SolveOptions {
+  /** Where the mybase API is reachable from the browser. */
+  apiUrl: string;
+  project: string;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+/** Fetches a challenge and solves it. Returns the token to send with the form. */
+export async function solveCaptcha(options: SolveOptions): Promise<string> {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const res = await doFetch(`${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/challenge`, { signal: options.signal });
+  const body = (await res.json().catch(() => ({}))) as CaptchaChallenge & { error?: string };
+  if (!res.ok) throw new MybaseApiError(body.error ?? `mybase API answered ${res.status}`, res.status);
+  return solveChallenge(body, { signal: options.signal });
+}
+
+export interface CaptchaClientOptions {
+  apiUrl: string;
+  project: string;
+  /** A mybase API key with `captcha:write` for this project. Server-side only. */
+  apiKey: string;
+  fetch?: typeof fetch;
+}
+
+export interface CaptchaClient {
+  /** Checks a token once. A second check of the same token fails with `used`. */
+  verify(token: string): Promise<CaptchaVerifyResponse>;
+}
+
+export function createCaptchaClient(options: CaptchaClientOptions): CaptchaClient {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/verify`;
+  return {
+    async verify(token) {
+      if (typeof token !== "string" || !token || token.length > CAPTCHA_LIMITS.tokenLength) return { success: false, error: "invalid" };
+      const res = await doFetch(url, {
+        method: "POST",
+        body: JSON.stringify({ token }),
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+      });
+      const body = (await res.json().catch(() => ({}))) as CaptchaVerifyResponse & { error?: string };
+      if (!res.ok) throw new MybaseApiError((body as { error?: string }).error ?? `mybase API answered ${res.status}`, res.status);
+      return body;
+    },
+  };
+}

package/src/config.ts

@@ -1,8 +1,9 @@
-// Cron jobs, rate limit rules, and queues declared in code. `mybase cron sync`, `mybase ratelimit
-// sync`, and `mybase queue sync` import this file (and only this file), so keep app code out of it:
-// handlers live with your routes (see ./cron).
+// Cron jobs, rate limit rules, queues, and vector indexes declared in code. `mybase cron sync`,
+// `mybase ratelimit sync`, `mybase queue sync`, and `mybase vector sync` import this file (and
+// only this file), so keep app code out of it: handlers live with your routes (see ./cron).
 import type { DeadLetterSettings } from "./queue";
 import type { RateLimitAlgorithm } from "./ratelimit";
+import type { VectorIndexInput } from "./vector";
 
 /** One job mybase calls on a schedule. */
 export interface CronJobConfig {
@@ -52,6 +53,9 @@ export interface QueueConfig {
   deadLetter?: DeadLetterSettings;
 }
 
+/** One vector/full-text index. Dimensions, metric, and language can't change after creation. */
+export type VectorIndexConfig = VectorIndexInput;
+
 export interface MybaseConfig {
   /** The mybase project these jobs belong to. */
   project: string;
@@ -66,6 +70,9 @@ export interface MybaseConfig {
   queue?: {
     queues: Record<string, QueueConfig>;
   };
+  vector?: {
+    indexes: Record<string, VectorIndexConfig>;
+  };
 }
 
 /** Identity function that types `mybase.config.ts`. */

package/src/search.ts

@@ -0,0 +1,250 @@
+// Web search through mybase. The API asks its own SearXNG (a metasearch engine over Bing,
+// Mojeek, Yahoo, DuckDuckGo, Brave, …) and reads pages for you, so an agent can search and then
+// read without paying a search API.
+//
+//   const web = createSearchClient({ apiUrl, project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+//   const { results } = await web.search("bun sql postgres");
+//   const page = await web.fetch(results[0].url); // → { title, markdown, … }
+//
+// For an LLM agent, `searchTools(web)` gives `web_search` and `web_fetch` as tool definitions.
+import { MybaseApiError } from "./cron";
+
+export { MybaseApiError };
+
+/** `general`: the web. `news`: recent articles. `it`: GitHub and Stack Overflow. */
+export const SEARCH_CATEGORIES = ["general", "news", "it"] as const;
+export type SearchCategory = (typeof SEARCH_CATEGORIES)[number];
+
+export const SEARCH_TIME_RANGES = ["day", "week", "month", "year"] as const;
+export type SearchTimeRange = (typeof SEARCH_TIME_RANGES)[number];
+
+export const SEARCH_LIMITS = {
+  queryLength: 400,
+  results: { default: 10, max: 20 },
+  page: { max: 10 },
+  urlLength: 2048,
+  maxChars: { default: 20_000, min: 500, max: 100_000 },
+} as const;
+
+/** `en`, `de`, `en-US`, …: what language results should be in. */
+export const SEARCH_LANGUAGE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+export interface SearchOptions {
+  /** Results to return, 1–20. Default 10. */
+  limit?: number;
+  /** Default `general`. */
+  category?: SearchCategory;
+  /** Only results from the last day/week/month/year. Not every engine supports it. */
+  timeRange?: SearchTimeRange;
+  /** `en`, `en-US`, …. Default: any language. */
+  language?: string;
+  /** Results page, 1–10. Default 1. */
+  page?: number;
+}
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  /** The text the engines showed under the link. May be empty. */
+  snippet: string;
+  /** Which engines returned it; more engines usually means more relevant. */
+  engines: string[];
+  /** ISO date, when the engine knows it (mostly news). */
+  publishedAt: string | null;
+}
+
+/** Answer of `GET /search/<project>?q=…`. */
+export interface SearchResponse {
+  query: string;
+  results: SearchResult[];
+  /** True when this answer came from mybase's cache (searches are kept 1 hour). */
+  cached: boolean;
+}
+
+export interface FetchOptions {
+  /** Cut the markdown at this many characters, 500–100000. Default 20000. */
+  maxChars?: number;
+}
+
+/** Answer of `GET /search/<project>/fetch?url=…`. */
+export interface FetchResponse {
+  /** Where the page ended up, after redirects. */
+  url: string;
+  title: string | null;
+  /** The page's main content as markdown (navigation, ads, and scripts left out). */
+  markdown: string;
+  /** True when the markdown was cut at `maxChars`. */
+  truncated: boolean;
+  contentType: string;
+  /** True when this answer came from mybase's cache (pages are kept 1 day). */
+  cached: boolean;
+}
+
+export interface SearchClientOptions {
+  /** Where the mybase API is reachable from your app, e.g. `https://mybase.example.com`. */
+  apiUrl: string;
+  project: string;
+  /** A mybase API key (`mb_…`) with `search:read` for this project. Server-side only. */
+  apiKey: string;
+  /** How long to wait for mybase, in ms. Default 20000 (searches and page reads take seconds). */
+  timeoutMs?: number;
+  /** Default `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+
+export interface SearchClient {
+  /** Searches the web. Throws `MybaseApiError` when mybase answers with an error. */
+  search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+  /** Reads a public web page as markdown. Throws `MybaseApiError` when it can't (blocked address, not HTML, …). */
+  fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
+}
+
+export function createSearchClient(options: SearchClientOptions): SearchClient {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/search/${encodeURIComponent(options.project)}`;
+  const timeoutMs = options.timeoutMs ?? 20_000;
+
+  async function get<T>(url: string): Promise<T> {
+    const res = await doFetch(url, {
+      headers: { Authorization: `Bearer ${options.apiKey}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const data = (await res.json().catch(() => ({}))) as T & { error?: string };
+    if (!res.ok) throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data;
+  }
+
+  return {
+    search(query, { limit, category, timeRange, language, page } = {}) {
+      const params = new URLSearchParams({ q: query });
+      if (limit !== undefined) params.set("limit", String(limit));
+      if (category) params.set("category", category);
+      if (timeRange) params.set("timeRange", timeRange);
+      if (language) params.set("language", language);
+      if (page !== undefined) params.set("page", String(page));
+      return get<SearchResponse>(`${base}?${params}`);
+    },
+    fetch(url, { maxChars } = {}) {
+      const params = new URLSearchParams({ url });
+      if (maxChars !== undefined) params.set("maxChars", String(maxChars));
+      return get<FetchResponse>(`${base}/fetch?${params}`);
+    },
+  };
+}
+
+// ---- agent tools ------------------------------------------------------------
+
+/** JSON Schema for a tool's input (the subset these tools use). */
+export interface ToolInputSchema {
+  type: "object";
+  properties: Record<string, Record<string, unknown>>;
+  required: string[];
+  additionalProperties: false;
+}
+
+/**
+ * A tool for an LLM agent, independent of the provider. Map it to yours:
+ * Anthropic `{ name, description, input_schema: inputSchema }`,
+ * OpenAI `{ type: "function", function: { name, description, parameters: inputSchema } }`.
+ */
+export interface SearchTool {
+  name: "web_search" | "web_fetch";
+  description: string;
+  inputSchema: ToolInputSchema;
+  /**
+   * Runs the tool with the model's input and returns text for the tool result. Problems the
+   * model can work around (a blocked or unreadable page, no results, bad input, rate limits) come
+   * back as text starting with `Error:`; a wrong key or a disabled service throws.
+   */
+  run(input: unknown): Promise<string>;
+}
+
+export interface SearchToolsOptions {
+  /** Most characters `web_fetch` returns per page. Default 20000. Keeps tool results inside your context budget. */
+  maxChars?: number;
+  /** Results `web_search` returns. Default 8. */
+  limit?: number;
+}
+
+/** `web_search` and `web_fetch`, ready for an LLM tool-use loop. */
+export function searchTools(client: SearchClient, options: SearchToolsOptions = {}): SearchTool[] {
+  const maxChars = options.maxChars ?? SEARCH_LIMITS.maxChars.default;
+  const limit = options.limit ?? 8;
+
+  return [
+    {
+      name: "web_search",
+      description:
+        "Search the web. Returns titles, URLs, and snippets. Use web_fetch to read a result in full. " +
+        "Write queries like a search engine query (keywords), not a question to a person.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The search query." },
+          category: {
+            type: "string",
+            enum: [...SEARCH_CATEGORIES],
+            description: "general (default): the web. news: recent articles. it: GitHub and Stack Overflow.",
+          },
+          timeRange: { type: "string", enum: [...SEARCH_TIME_RANGES], description: "Only results from this recent period." },
+        },
+        required: ["query"],
+        additionalProperties: false,
+      },
+      run: (input) =>
+        attempt(async () => {
+          const { query, category, timeRange } = object(input);
+          if (typeof query !== "string" || !query.trim()) return "Error: query is required.";
+          const { results } = await client.search(query, {
+            limit,
+            category: oneOf(category, SEARCH_CATEGORIES),
+            timeRange: oneOf(timeRange, SEARCH_TIME_RANGES),
+          });
+          if (results.length === 0) return `No results for "${query}".`;
+          return results
+            .map((r, i) => {
+              const date = r.publishedAt ? ` (${r.publishedAt.slice(0, 10)})` : "";
+              return `${i + 1}. ${r.title}${date}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ""}`;
+            })
+            .join("\n\n");
+        }),
+    },
+    {
+      name: "web_fetch",
+      description:
+        "Read a public web page and return its main content as markdown. Use it on URLs from web_search " +
+        "or ones the user gave. Long pages are cut off.",
+      inputSchema: {
+        type: "object",
+        properties: { url: { type: "string", description: "The http(s) URL to read." } },
+        required: ["url"],
+        additionalProperties: false,
+      },
+      run: (input) =>
+        attempt(async () => {
+          const { url } = object(input);
+          if (typeof url !== "string" || !url.trim()) return "Error: url is required.";
+          const page = await client.fetch(url, { maxChars });
+          const head = `# ${page.title ?? page.url}\nURL: ${page.url}\n\n`;
+          return head + page.markdown + (page.truncated ? `\n\n[Cut off at ${maxChars} characters.]` : "");
+        }),
+    },
+  ];
+}
+
+const object = (input: unknown): Record<string, unknown> =>
+  typeof input === "object" && input !== null && !Array.isArray(input) ? (input as Record<string, unknown>) : {};
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
+  return allowed.includes(value as T) ? (value as T) : undefined;
+}
+
+// Errors the model can act on go back as text; ones only the developer can fix still throw.
+async function attempt(run: () => Promise<string>): Promise<string> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof MybaseApiError && ![401, 403, 404].includes(error.status)) return `Error: ${error.message}`;
+    throw error;
+  }
+}

package/src/secrets.ts

@@ -0,0 +1,234 @@
+// Secrets and config per environment, stored encrypted on mybase. Locally and in CI, the
+// CLI injects them into your process (`mybase run -- bun start`); this client is for reading
+// them at runtime instead, e.g. to pick up a rotated value without a restart.
+//
+//   const secrets = createSecretsClient({ apiUrl, project: "shop", env: "prod", apiKey: process.env.MYBASE_API_KEY! });
+//   await secrets.load();                  // into process.env (existing vars win)
+//   const stripe = await secrets.get("STRIPE_KEY");
+import { MybaseApiError } from "./cron";
+
+export { MybaseApiError };
+
+/** `dev`, `staging`, `prod`, `prod_eu`, … */
+export const SECRETS_ENV_PATTERN = /^[a-z][a-z0-9_-]{0,39}$/;
+export const SECRETS_ENV_RULES = "1–40 characters: lowercase letters, digits, _ or -, starting with a letter";
+
+/** Env var names: `STRIPE_KEY`, `databaseUrl`, … */
+export const SECRET_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+export const SECRET_KEY_RULES = "1–128 characters: letters, digits, or _, not starting with a digit";
+
+export const SECRETS_LIMITS = {
+  /** Per value, UTF-8. */
+  valueBytes: 64 * 1024,
+  keysPerEnv: 1000,
+  envsPerProject: 50,
+  /** Older revisions are pruned. */
+  revisionsKept: 200,
+  messageLength: 200,
+} as const;
+
+/** Every project starts with these (they can be renamed or deleted). */
+export const DEFAULT_SECRETS_ENVS = ["dev", "staging", "prod"] as const;
+
+/**
+ * Keys `mybase secrets link` writes and keeps up to date. Read-only elsewhere: running link
+ * again rotates them.
+ */
+export const MANAGED_SECRET_KEYS = [
+  "DATABASE_URL",
+  "S3_ENDPOINT",
+  "S3_REGION",
+  "S3_BUCKET",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY",
+  "REDIS_URL",
+  "MYBASE_URL",
+  "MYBASE_PROJECT",
+] as const;
+
+// ---- wire types -------------------------------------------------------------
+
+export interface SecretsEnv {
+  name: string;
+  /** Branch envs inherit every key of their parent (a root env) and override some. */
+  parent: string | null;
+  /** Bumped on every change. */
+  revision: number;
+  /** Own keys, not counting inherited ones. */
+  keys: number;
+  /** Holds the project's credentials (`mybase secrets link`). */
+  linked: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `GET /projects/<project>/secrets`. Only envs the caller's key may read are listed. */
+export interface SecretsOverview {
+  envs: SecretsEnv[];
+  apiUrl: string;
+  enabledAt: string;
+}
+
+export interface SecretEntry {
+  key: string;
+  /** Only when values were asked for. */
+  value?: string;
+  /** Written by `mybase secrets link`. */
+  managed: boolean;
+  /** From the parent env (a branch env hasn't overridden it). */
+  inherited: boolean;
+  updatedAt: string;
+}
+
+export interface SecretsEnvDetail {
+  env: SecretsEnv;
+  secrets: SecretEntry[];
+}
+
+export interface CreateSecretsEnvRequest {
+  name: string;
+  /** Makes a branch env of this root env. */
+  parent?: string | null;
+}
+
+export interface UpdateSecretsRequest {
+  set?: Record<string, string>;
+  unset?: string[];
+  /** Shown in the history. */
+  message?: string;
+}
+
+export interface UpdateSecretsResponse {
+  /** The env's revision after the change (unchanged when nothing changed). */
+  revision: number;
+  changed: number;
+}
+
+export type SecretChangeAction = "added" | "changed" | "removed";
+
+export interface SecretChange {
+  key: string;
+  action: SecretChangeAction;
+  managed: boolean;
+  /** Only when values were asked for. */
+  oldValue?: string | null;
+  newValue?: string | null;
+}
+
+export interface SecretsRevision {
+  revision: number;
+  /** `admin`, `key:<name>`, or `link`. */
+  actor: string;
+  message: string | null;
+  createdAt: string;
+  changes: SecretChange[];
+}
+
+/** `GET /secrets/<project>/<env>`: every key resolved, branch overrides applied. */
+export interface SecretsResponse {
+  env: string;
+  /** Changes whenever any value (own or inherited) may have changed. Also sent as the ETag. */
+  version: string;
+  secrets: Record<string, string>;
+}
+
+export interface LinkCredentialsRequest {
+  envs: string[];
+}
+
+export interface LinkCredentialsResponse {
+  /** Every env now holding the credentials (earlier links included). */
+  envs: string[];
+  keys: string[];
+}
+
+// ---- client -----------------------------------------------------------------
+
+export interface SecretsClientOptions {
+  /** Where the mybase API is reachable from your app, e.g. `https://mybase.example.com`. */
+  apiUrl: string;
+  project: string;
+  /** `dev`, `prod`, a branch env, … */
+  env: string;
+  /** A mybase API key (`mb_…`) with `secrets:read` for this project (and env, if it's env-scoped). Server-side only. */
+  apiKey: string;
+  /** Reuse fetched secrets this long without asking mybase, in ms. Default 0: every read revalidates (a 304 when nothing changed). */
+  maxAgeMs?: number;
+  /** Default 10000. */
+  timeoutMs?: number;
+  /** Default `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+
+export interface SecretsClient {
+  /** Every key in the env, inherited ones included. */
+  all(): Promise<Record<string, string>>;
+  /** One value, or undefined when the key isn't set. */
+  get(key: string): Promise<string | undefined>;
+  /** Copies the secrets into `process.env`. Existing vars win unless `override`. Returns the keys set. */
+  load(options?: { override?: boolean }): Promise<string[]>;
+  /** Needs `secrets:write`. One revision in the history. */
+  set(values: Record<string, string>, options?: { message?: string }): Promise<UpdateSecretsResponse>;
+  unset(keys: string | string[], options?: { message?: string }): Promise<UpdateSecretsResponse>;
+}
+
+export function createSecretsClient(options: SecretsClientOptions): SecretsClient {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/secrets/${encodeURIComponent(options.project)}/${encodeURIComponent(options.env)}`;
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const maxAgeMs = options.maxAgeMs ?? 0;
+  const headers = { Authorization: `Bearer ${options.apiKey}` };
+  let cached: { etag: string | null; secrets: Record<string, string>; at: number } | undefined;
+
+  async function fail(res: Response): Promise<never> {
+    const data = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+  }
+
+  async function all(): Promise<Record<string, string>> {
+    if (cached && Date.now() - cached.at < maxAgeMs) return { ...cached.secrets };
+    const res = await doFetch(url, {
+      headers: cached?.etag ? { ...headers, "If-None-Match": cached.etag } : headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status === 304 && cached) {
+      cached.at = Date.now();
+      return { ...cached.secrets };
+    }
+    if (!res.ok) return fail(res);
+    const data = (await res.json()) as SecretsResponse;
+    cached = { etag: res.headers.get("ETag"), secrets: data.secrets, at: Date.now() };
+    return { ...data.secrets };
+  }
+
+  async function update(body: UpdateSecretsRequest): Promise<UpdateSecretsResponse> {
+    const res = await doFetch(url, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+      headers: { ...headers, "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return fail(res);
+    cached = undefined;
+    return (await res.json()) as UpdateSecretsResponse;
+  }
+
+  return {
+    all,
+    get: async (key) => (await all())[key],
+    async load({ override = false } = {}) {
+      const secrets = await all();
+      const env = (globalThis as { process?: { env: Record<string, string | undefined> } }).process?.env;
+      if (!env) throw new Error("load() needs process.env (Node, Bun, Deno); use all() elsewhere");
+      const set: string[] = [];
+      for (const [key, value] of Object.entries(secrets)) {
+        if (!override && env[key] !== undefined) continue;
+        env[key] = value;
+        set.push(key);
+      }
+      return set;
+    },
+    set: (values, opts = {}) => update({ set: values, message: opts.message }),
+    unset: (keys, opts = {}) => update({ unset: [keys].flat(), message: opts.message }),
+  };
+}