@graph8/sdk 0.361.0 → 0.370.0

package/blocks/_foundation/lib/g8-cache.ts

@@ -0,0 +1,454 @@
+"use client";
+
+/**
+ * The shared query cache behind `useG8Query(..., { key })`, `usePaginated(..., { key })` and
+ * `useG8Mutation(..., { invalidates })`. No dependencies, framework-agnostic, SSR-safe.
+ *
+ * What a `key` buys you (all opt-in: hooks called WITHOUT a key never touch this file's state):
+ * - Dedupe: any number of components asking for the same key share ONE in-flight request.
+ * - Stale-while-revalidate: cached data renders instantly on mount, then refreshes in the background
+ *   once it is older than `staleTime` (default 0: always revalidate, but never show a skeleton twice).
+ * - Revalidate on window focus / reconnect, throttled per key (default 5 s between refreshes).
+ * - Smart invalidation: `invalidate("contacts")` marks every key that starts with "contacts" stale and
+ *   refetches the ones on screen. Mutations pass `invalidates: ["contacts"]` to do this on success.
+ * - Bounded memory: at most `maxEntries` keys (LRU, default 200); a key nobody watches is dropped
+ *   after `gcTime` (default 5 min). Only unwatched, idle entries are ever evicted.
+ * - Abort: a request is aborted when its LAST subscriber unmounts (or it is superseded), never while
+ *   another component still waits for it.
+ *
+ * Keys are a string or an array whose first item names the area: `["contacts", "list", { page, filters }]`.
+ * Object parts are compared by value (key order does not matter). A key must contain every input the
+ * fetcher reads; prefixes match whole parts: "contacts" matches ["contacts", ...] but not ["contacts-x"].
+ *
+ * On the server nothing is cached: hooks render their initial state and fetch after hydration.
+ */
+
+export type G8QueryKey = string | readonly unknown[];
+
+export interface G8QueryState<T = unknown> {
+  data: T | undefined;
+  error: unknown;
+  /** Epoch ms of the last successful fetch or setQueryData (0 = never). */
+  updatedAt: number;
+  /** A request for this key is in flight. */
+  fetching: boolean;
+  /** Marked stale by `invalidate` (refetched on next use even inside `staleTime`). */
+  invalidated: boolean;
+}
+
+export type G8Fetcher<T> = (signal: AbortSignal) => Promise<T>;
+
+/** What a mounted hook tells the cache about itself. Read lazily, so the latest render's values win. */
+export interface G8QueryObserver {
+  fetcher: () => G8Fetcher<unknown>;
+  /** A disabled hook (for example waiting for an id) is never refetched by invalidation. Default true. */
+  enabled?: () => boolean;
+  staleTime: () => number;
+  refetchOnFocus: () => boolean;
+}
+
+export interface G8QueryCacheOptions {
+  /** Most keys kept at once (LRU). Default 200. */
+  maxEntries?: number;
+  /** How long an unwatched key is kept, ms. Default 5 minutes. */
+  gcTime?: number;
+  /** Least time between two focus/reconnect refreshes of one key, ms. Default 5 s. */
+  focusThrottleMs?: number;
+}
+
+interface Entry {
+  key: readonly unknown[];
+  hash: string;
+  parts: string[];
+  state: G8QueryState;
+  listeners: Set<() => void>;
+  observers: Set<G8QueryObserver>;
+  promise?: Promise<unknown>;
+  controller?: AbortController;
+  /** Bumped by every fetch start and every cancel: only the latest fetch may write. */
+  gen: number;
+  lastFetchAt: number;
+  /** The synchronous run (tick) the request in flight started in. */
+  startedTick: number;
+  gcTimer?: ReturnType<typeof setTimeout>;
+}
+
+const EMPTY_STATE: G8QueryState = Object.freeze({
+  data: undefined,
+  error: undefined,
+  updatedAt: 0,
+  fetching: false,
+  invalidated: false,
+}) as G8QueryState;
+
+const isServer = (): boolean => typeof window === "undefined";
+
+function stable(value: unknown): string {
+  if (value === undefined) return "u";
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? String(value);
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (value instanceof Date) return `D${value.toISOString()}`;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    // A Map, Set, URLSearchParams or class instance has no own keys to hash: two different ones would
+    // collide as {} and share data. Fail loudly instead.
+    throw new TypeError("g8 query keys must be JSON-like: strings, numbers, booleans, null, arrays, plain objects or Dates");
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stable(obj[k])}`).join(",")}}`;
+}
+
+/** A key as an array (a string key is a one-part key). */
+export function normalizeKey(key: G8QueryKey): readonly unknown[] {
+  return typeof key === "string" ? [key] : key;
+}
+
+/** The identity of a key: equal for keys equal by value. */
+export function hashKey(key: G8QueryKey): string {
+  return stable(normalizeKey(key));
+}
+
+function isAbort(err: unknown, signal: AbortSignal): boolean {
+  return signal.aborted || (err as { name?: string } | null)?.name === "AbortError";
+}
+
+/** Same JSON as before = keep the old object, so memoised rows and effects do not churn. */
+function share<T>(prev: unknown, next: T): T {
+  if (prev === undefined || prev === next) return next;
+  try {
+    return JSON.stringify(prev) === JSON.stringify(next) ? (prev as T) : next;
+  } catch {
+    return next;
+  }
+}
+
+export class G8QueryCache {
+  readonly maxEntries: number;
+  readonly gcTime: number;
+  readonly focusThrottleMs: number;
+  private entries = new Map<string, Entry>();
+  private windowBound = false;
+  private tick = 0;
+  private tickScheduled = false;
+
+  constructor(options: G8QueryCacheOptions = {}) {
+    this.maxEntries = Math.max(1, options.maxEntries ?? 200);
+    this.gcTime = options.gcTime ?? 5 * 60_000;
+    this.focusThrottleMs = options.focusThrottleMs ?? 5_000;
+  }
+
+  /** Number of keys held (for tests and debugging). */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** The current state of a key, or an empty state. Never creates an entry. */
+  getState<T = unknown>(key: G8QueryKey): G8QueryState<T> {
+    return (this.entries.get(hashKey(key))?.state ?? EMPTY_STATE) as G8QueryState<T>;
+  }
+
+  getQueryData<T = unknown>(key: G8QueryKey): T | undefined {
+    return this.getState<T>(key).data;
+  }
+
+  /** Watch a key: `listener` runs on every state change. Returns the unsubscribe function. */
+  subscribe(key: G8QueryKey, listener: () => void, observer?: G8QueryObserver): () => void {
+    const entry = this.ensure(key);
+    clearTimeout(entry.gcTimer);
+    entry.gcTimer = undefined;
+    entry.listeners.add(listener);
+    if (observer) entry.observers.add(observer);
+    this.bindWindow();
+    return () => {
+      entry.listeners.delete(listener);
+      if (observer) entry.observers.delete(observer);
+      if (entry.listeners.size > 0) return;
+      // Last one out: nobody needs the answer any more.
+      if (entry.promise) this.cancelEntry(entry);
+      this.scheduleGc(entry);
+    };
+  }
+
+  /**
+   * Fetch a key. Joins the request already in flight unless `force` (which supersedes it: the old
+   * request is aborted and only the new answer is kept). Resolves with the data, or undefined when the
+   * request failed (the error is in the state) or was superseded/aborted.
+   */
+  fetch<T>(
+    key: G8QueryKey,
+    fetcher: G8Fetcher<T>,
+    options: { force?: boolean; share?: boolean } = {},
+  ): Promise<T | undefined> {
+    const entry = this.ensure(key);
+    // A forced fetch still joins a request started in this same synchronous run: it cannot predate the
+    // write that asked for it (a mutation's `invalidates` plus the component's own refetch = one request).
+    if (entry.promise && (!options.force || entry.startedTick === this.tick)) return entry.promise as Promise<T | undefined>;
+    if (entry.promise) this.cancelEntry(entry);
+    const gen = ++entry.gen;
+    entry.startedTick = this.currentTick();
+    const controller = new AbortController();
+    entry.controller = controller;
+    entry.lastFetchAt = Date.now();
+    this.write(entry, { fetching: true });
+    const promise = (async (): Promise<T | undefined> => {
+      try {
+        const data = await fetcher(controller.signal);
+        if (gen !== entry.gen) return undefined;
+        this.write(entry, {
+          // Background refreshes keep the old object when nothing changed (no churn); an explicit refetch always
+          // hands over a new one, as the uncached hook did, so effects keyed on `data` run again.
+          data: options.share === false ? data : share(entry.state.data, data),
+          error: undefined,
+          updatedAt: Date.now(),
+          fetching: false,
+          invalidated: false,
+        });
+        return data;
+      } catch (err) {
+        if (gen !== entry.gen || isAbort(err, controller.signal)) return undefined;
+        this.write(entry, { error: err, fetching: false });
+        return undefined;
+      } finally {
+        if (gen === entry.gen) {
+          entry.promise = undefined;
+          entry.controller = undefined;
+        }
+      }
+    })();
+    entry.promise = promise;
+    return promise;
+  }
+
+  /** Is this key due a refresh for a reader that tolerates `staleTime` ms of age? */
+  isStale(key: G8QueryKey, staleTime: number): boolean {
+    const state = this.getState(key);
+    return state.invalidated || state.updatedAt === 0 || Date.now() - state.updatedAt >= staleTime;
+  }
+
+  /** Fetch only if there is no fresh data and no request in flight. */
+  ensureFresh<T>(key: G8QueryKey, fetcher: G8Fetcher<T>, staleTime: number): Promise<T | undefined> | undefined {
+    const entry = this.ensure(key);
+    if (entry.promise) return entry.promise as Promise<T | undefined>;
+    if (!this.isStale(key, staleTime)) return undefined;
+    return this.fetch(key, fetcher);
+  }
+
+  /**
+   * Mark every key under `prefix` (all keys when omitted) stale. Keys on screen refetch now
+   * (superseding a request that started before the write); the rest refetch when next used.
+   */
+  async invalidate(prefix?: G8QueryKey, options: { refetch?: boolean } = {}): Promise<void> {
+    const runs: Array<Promise<unknown>> = [];
+    for (const entry of this.match(prefix)) {
+      this.write(entry, { invalidated: true });
+      const observer = [...entry.observers].find((o) => o.enabled?.() ?? true);
+      if (options.refetch === false || entry.listeners.size === 0 || !observer) {
+        if (entry.promise) this.cancelEntry(entry);
+        continue;
+      }
+      runs.push(this.fetch(entry.key, observer.fetcher(), { force: true }));
+    }
+    await Promise.all(runs);
+  }
+
+  /** Replace one key's data (a value, or a function of the old data). Cancels a request in flight. */
+  setQueryData<T>(key: G8QueryKey, updater: T | ((old: T | undefined) => T | undefined)): T | undefined {
+    const entry = this.ensure(key);
+    if (entry.promise) this.cancelEntry(entry);
+    const old = entry.state.data as T | undefined;
+    const next =
+      typeof updater === "function" ? (updater as (old: T | undefined) => T | undefined)(old) : updater;
+    this.write(entry, { data: next, error: undefined, updatedAt: Date.now(), fetching: false, invalidated: false });
+    if (entry.listeners.size === 0) this.scheduleGc(entry);
+    return next;
+  }
+
+  /**
+   * Update the data of every key under `prefix` that has data. Returns a snapshot to pass to
+   * `restore` (an optimistic update that failed puts the old data back).
+   */
+  setQueriesData<T>(
+    prefix: G8QueryKey,
+    updater: (old: T, key: readonly unknown[]) => T,
+  ): Array<{ key: readonly unknown[]; data: unknown }> {
+    const snapshot: Array<{ key: readonly unknown[]; data: unknown }> = [];
+    for (const entry of this.match(prefix)) {
+      if (entry.state.data === undefined) continue;
+      if (entry.promise) this.cancelEntry(entry);
+      snapshot.push({ key: entry.key, data: entry.state.data });
+      this.write(entry, { data: updater(entry.state.data as T, entry.key) });
+    }
+    return snapshot;
+  }
+
+  /** Put back the data captured by `setQueriesData`. */
+  restore(snapshot: Array<{ key: readonly unknown[]; data: unknown }>): void {
+    for (const item of snapshot) {
+      const entry = this.entries.get(hashKey(item.key));
+      if (entry) this.write(entry, { data: item.data });
+    }
+  }
+
+  /** Abort the requests in flight under `prefix` (their answers are dropped). */
+  cancel(prefix?: G8QueryKey): void {
+    for (const entry of this.match(prefix)) if (entry.promise) this.cancelEntry(entry);
+  }
+
+  /** Forget keys under `prefix` that nobody is watching (all of them when omitted). */
+  remove(prefix?: G8QueryKey): void {
+    for (const entry of this.match(prefix)) {
+      if (entry.listeners.size > 0) continue;
+      this.drop(entry);
+    }
+  }
+
+  /** Forget everything, watched or not (tests, sign-out). Subscribers see an empty state. */
+  clear(): void {
+    for (const entry of [...this.entries.values()]) {
+      if (entry.promise) this.cancelEntry(entry);
+      clearTimeout(entry.gcTimer);
+      if (entry.listeners.size > 0) {
+        this.write(entry, { ...EMPTY_STATE });
+      } else {
+        this.entries.delete(entry.hash);
+      }
+    }
+  }
+
+  /** Refresh watched keys after the window regains focus or the network returns (throttled per key). */
+  revalidateOnFocus(): void {
+    const now = Date.now();
+    for (const entry of this.entries.values()) {
+      if (entry.listeners.size === 0 || entry.promise) continue;
+      const observers = [...entry.observers].filter((o) => o.enabled?.() ?? true);
+      // An opt-out is a veto: a form seeded from this key must not be refreshed because another view wants it.
+      if (observers.length === 0 || observers.some((o) => !o.refetchOnFocus())) continue;
+      if (now - entry.lastFetchAt < this.focusThrottleMs) continue;
+      const staleTime = Math.min(...observers.map((o) => o.staleTime()));
+      if (!this.isStale(entry.key, staleTime)) continue;
+      void this.fetch(entry.key, observers[0].fetcher());
+    }
+  }
+
+  private ensure(key: G8QueryKey): Entry {
+    const norm = normalizeKey(key);
+    const hash = hashKey(norm);
+    let entry = this.entries.get(hash);
+    if (entry) {
+      // LRU: most recently used goes to the end.
+      this.entries.delete(hash);
+      this.entries.set(hash, entry);
+      return entry;
+    }
+    entry = {
+      key: norm,
+      hash,
+      parts: norm.map(stable),
+      state: EMPTY_STATE,
+      listeners: new Set(),
+      observers: new Set(),
+      gen: 0,
+      lastFetchAt: 0,
+      startedTick: -1,
+    };
+    this.entries.set(hash, entry);
+    this.evict();
+    return entry;
+  }
+
+  private evict(): void {
+    if (this.entries.size <= this.maxEntries) return;
+    for (const entry of [...this.entries.values()]) {
+      if (this.entries.size <= this.maxEntries) return;
+      if (entry.listeners.size > 0 || entry.promise) continue;
+      this.drop(entry);
+    }
+  }
+
+  private drop(entry: Entry): void {
+    clearTimeout(entry.gcTimer);
+    if (entry.promise) this.cancelEntry(entry);
+    this.entries.delete(entry.hash);
+  }
+
+  private scheduleGc(entry: Entry): void {
+    clearTimeout(entry.gcTimer);
+    if (isServer()) {
+      this.drop(entry);
+      return;
+    }
+    entry.gcTimer = setTimeout(() => {
+      if (entry.listeners.size === 0 && !entry.promise) this.drop(entry);
+    }, this.gcTime);
+  }
+
+  private match(prefix?: G8QueryKey): Entry[] {
+    const parts = prefix === undefined ? [] : normalizeKey(prefix).map(stable);
+    return [...this.entries.values()].filter(
+      (entry) => parts.length <= entry.parts.length && parts.every((part, i) => entry.parts[i] === part),
+    );
+  }
+
+  private cancelEntry(entry: Entry): void {
+    entry.gen++;
+    entry.controller?.abort();
+    entry.controller = undefined;
+    entry.promise = undefined;
+    if (entry.state.fetching) this.write(entry, { fetching: false });
+  }
+
+  private write(entry: Entry, patch: Partial<G8QueryState>): void {
+    entry.state = { ...entry.state, ...patch };
+    for (const listener of [...entry.listeners]) listener();
+  }
+
+  /** Ticks advance once per macrotask/microtask boundary after a fetch starts. */
+  private currentTick(): number {
+    if (!this.tickScheduled) {
+      this.tickScheduled = true;
+      void Promise.resolve().then(() => {
+        this.tick++;
+        this.tickScheduled = false;
+      });
+    }
+    return this.tick;
+  }
+
+  private bindWindow(): void {
+    if (this.windowBound || isServer() || typeof window.addEventListener !== "function") return;
+    this.windowBound = true;
+    const onFocus = (): void => this.revalidateOnFocus();
+    window.addEventListener("focus", onFocus);
+    window.addEventListener("online", onFocus);
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "visible") onFocus();
+      });
+    }
+  }
+}
+
+const SINGLETON = Symbol.for("@graph8/blocks/query-cache");
+
+/** The app-wide cache every keyed hook uses (one per page, shared by every copy of this module). */
+export const g8QueryCache: G8QueryCache = ((globalThis as Record<symbol, unknown>)[SINGLETON] as
+  | G8QueryCache
+  | undefined) ?? ((globalThis as Record<symbol, unknown>)[SINGLETON] = new G8QueryCache()) as G8QueryCache;
+
+/** Mark keys under `prefix` stale; the ones on screen refetch now. `invalidate("contacts")`. */
+export const invalidate = (prefix?: G8QueryKey, options?: { refetch?: boolean }): Promise<void> =>
+  g8QueryCache.invalidate(prefix, options);
+
+/** Write one key's data (after a create/update response, or optimistically). */
+export const setQueryData = <T>(key: G8QueryKey, updater: T | ((old: T | undefined) => T | undefined)) =>
+  g8QueryCache.setQueryData<T>(key, updater);
+
+export const getQueryData = <T>(key: G8QueryKey): T | undefined => g8QueryCache.getQueryData<T>(key);
+
+/** Warm a key before it is shown (hover, next page). Joins a request already in flight. */
+export const prefetchQuery = <T>(key: G8QueryKey, fetcher: G8Fetcher<T>, staleTime = 0) =>
+  g8QueryCache.ensureFresh(key, fetcher, staleTime) ?? Promise.resolve(g8QueryCache.getQueryData<T>(key));
+
+/** The empty state hooks render before a key has data (and on the server). */
+export const EMPTY_QUERY_STATE: G8QueryState = EMPTY_STATE;

package/blocks/_foundation/lib/g8-client.ts

@@ -14,7 +14,7 @@
  * thing in the browser.
  */
 
-import { G8Error } from "@graph8/sdk";
+import { G8Error } from "@graph8/sdk/errors";
 import type { PaginatedResponse } from "@graph8/sdk";
 
 /** The envelope every graph8 list/read call returns. */

package/blocks/_foundation/lib/plural.ts

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Plurals done once, correctly: `plural(1, "contact")` -> "1 contact", `plural(2, "contact")` -> "2 contacts",
+ * `plural(3, "company", "companies")` -> "3 companies". The count is formatted with thousands separators.
+ * Use it instead of a hand-rolled `n === 1 ? "" : "s"`.
+ *
+ * SDK operations: none.
+ */
+
+/** The word alone, singular for exactly 1: `pluralWord(2, "city", "cities")` -> "cities". */
+export function pluralWord(count: number, singular: string, pluralForm?: string): string {
+  if (count === 1) return singular;
+  if (pluralForm) return pluralForm;
+  if (/[^aeiou]y$/i.test(singular)) return `${singular.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/i.test(singular)) return `${singular}es`;
+  return `${singular}s`;
+}
+
+/** The count and the word: "1 contact", "1,200 contacts". */
+export function plural(count: number, singular: string, pluralForm?: string): string {
+  return `${count.toLocaleString("en-US")} ${pluralWord(count, singular, pluralForm)}`;
+}

package/blocks/_foundation/server/connect-route.ts

@@ -0,0 +1,15 @@
+/**
+ * Install as `app/api/g8-connect/route.ts` (the CLI copies it there). It backs the Connect graph8 screen that
+ * a created app shows in local preview when the server has no graph8 API key yet: the pasted key is checked
+ * against graph8 and stored server-side in `.g8/local-key` (never in the browser). See g8/server/connect.ts.
+ *
+ * It only answers `next dev` requests from this machine; in a production build every method is 404. Delete
+ * this file (and the gate in app/layout.tsx) if you never want the screen.
+ */
+
+import { createG8ConnectRoute } from "@/g8/server/connect";
+
+export const { GET, POST, DELETE } = createG8ConnectRoute();
+
+// The answer depends on the key on disk: never cache it.
+export const dynamic = "force-dynamic";

package/blocks/_foundation/server/connect.ts

@@ -0,0 +1,127 @@
+/**
+ * Server side of the Connect graph8 screen (local preview only), mounted at `app/api/g8-connect/route.ts`:
+ *
+ *   GET    -> { localPreview: true, connected, source: "env" | "file" | null, keyHint, account }
+ *   POST   { key } -> validates the key with a cheap read (GET /api/v1/me) and stores it in .g8/local-key
+ *   DELETE -> removes the stored key
+ *
+ * It answers ONLY `next dev` requests from this machine (same check as the proxy's local preview). In a
+ * production build every method is 404, as if the route did not exist. The key is never echoed back: the
+ * answer carries only a hint (`...wxyz`) and the key's account (name, workspace, scopes) from /me.
+ * When G8_API_KEY is set in the environment it wins, so POST and DELETE refuse (409) and say where to change it.
+ */
+
+import { DEFAULT_API_URL, isLocalPreviewRequest } from "./proxy";
+import { currentKey, keyHint, removeLocalKey, writeLocalKey, LOCAL_KEY_FILE } from "./local-key";
+
+export interface G8ConnectConfig {
+  /** Replace `fetch` (tests). */
+  fetch?: typeof fetch;
+  /** Project root holding `.g8/` (tests). Default: process.cwd(). */
+  root?: string;
+}
+
+export interface ConnectedAccount {
+  name?: string;
+  workspace?: string;
+  scopes?: string[];
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store" } });
+}
+
+const str = (v: unknown): string | undefined => (typeof v === "string" && v ? v : undefined);
+
+/** The safe, human facts about a key from GET /me (never the key itself). */
+export function accountFromMe(body: unknown): ConnectedAccount {
+  const root = (body ?? {}) as Record<string, unknown>;
+  const d = ((root.data as Record<string, unknown> | undefined) ?? root) as Record<string, unknown>;
+  const org = d.organization as Record<string, unknown> | undefined;
+  const scopes = Array.isArray(d.scopes) ? d.scopes.filter((s): s is string => typeof s === "string") : undefined;
+  return { name: str(d.name) ?? str(d.key_name) ?? str(d.label), workspace: str(org?.name) ?? str(d.org_name) ?? str(d.organization_name), scopes };
+}
+
+/** A pasted key that is plausibly a key: printable, no spaces, 8 to 512 characters. */
+export function plausibleKey(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const key = value.trim();
+  return key.length >= 8 && key.length <= 512 && /^[\x21-\x7e]+$/.test(key) ? key : null;
+}
+
+type Checked = { ok: true; account: ConnectedAccount } | { ok: false; status: number; error: string; message: string };
+
+/** Ask graph8 who the key is: GET /api/v1/me (free, read-only). */
+export async function checkKey(key: string, doFetch: typeof fetch): Promise<Checked> {
+  const base = (process.env.G8_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  let res: Response;
+  try {
+    res = await doFetch(`${base}/api/v1/me`, { headers: { authorization: `Bearer ${key}`, accept: "application/json" }, cache: "no-store", redirect: "manual" });
+  } catch {
+    return { ok: false, status: 502, error: "upstream_unreachable", message: "Could not reach the graph8 API to check the key." };
+  }
+  const body = await res.json().catch(() => ({}));
+  if (res.ok) return { ok: true, account: accountFromMe(body) };
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, status: 400, error: "key_rejected", message: "graph8 did not accept this key. Copy it again from graph8 (Settings > Developers > API keys)." };
+  }
+  return { ok: false, status: 502, error: "upstream_error", message: `graph8 answered HTTP ${res.status} while checking the key. Try again.` };
+}
+
+/** Build the GET/POST/DELETE handlers for `app/api/g8-connect/route.ts`. */
+export function createG8ConnectRoute(config: G8ConnectConfig = {}) {
+  const doFetch = (): typeof fetch => config.fetch ?? globalThis.fetch;
+
+  function refuse(request: Request): Response | null {
+    if (process.env.NODE_ENV === "production") return json(404, { error: "not_found" });
+    if (!isLocalPreviewRequest(request)) {
+      return json(403, { error: "local_preview_only", message: "The Connect graph8 screen only works from this machine (http://localhost)." });
+    }
+    return null;
+  }
+
+  async function status(): Promise<Record<string, unknown>> {
+    const current = await currentKey(config.root);
+    if (!current) return { localPreview: true, connected: false, source: null, keyFile: LOCAL_KEY_FILE };
+    const checked = await checkKey(current.key, doFetch());
+    return {
+      localPreview: true,
+      connected: checked.ok,
+      source: current.source,
+      keyHint: keyHint(current.key),
+      keyFile: LOCAL_KEY_FILE,
+      ...(checked.ok ? { account: checked.account } : { problem: checked.message }),
+    };
+  }
+
+  async function GET(request: Request): Promise<Response> {
+    return refuse(request) ?? json(200, await status());
+  }
+
+  async function POST(request: Request): Promise<Response> {
+    const refused = refuse(request);
+    if (refused) return refused;
+    if ((await currentKey(config.root))?.source === "env") {
+      return json(409, { error: "key_in_environment", message: "G8_API_KEY is set in the server environment (.env.local), and it wins. Change it there, then restart `npm run dev`." });
+    }
+    const body = (await request.json().catch(() => ({}))) as { key?: unknown };
+    const key = plausibleKey(body.key);
+    if (!key) return json(400, { error: "invalid_key", message: "Paste a graph8 API key: one line, no spaces." });
+    const checked = await checkKey(key, doFetch());
+    if (!checked.ok) return json(checked.status, { error: checked.error, message: checked.message });
+    await writeLocalKey(key, config.root);
+    return json(200, { localPreview: true, connected: true, source: "file", keyHint: keyHint(key), keyFile: LOCAL_KEY_FILE, account: checked.account });
+  }
+
+  async function DELETE(request: Request): Promise<Response> {
+    const refused = refuse(request);
+    if (refused) return refused;
+    if ((await currentKey(config.root))?.source === "env") {
+      return json(409, { error: "key_in_environment", message: "G8_API_KEY is set in the server environment (.env.local). Remove it there, then restart `npm run dev`." });
+    }
+    await removeLocalKey(config.root);
+    return json(200, { localPreview: true, connected: false, source: null, keyFile: LOCAL_KEY_FILE });
+  }
+
+  return { GET, POST, DELETE };
+}