@gusnips/react 0.9.30 → 0.9.32

package/README.md

@@ -696,10 +696,19 @@ your scripts signs in on a machine with no browser, it prints a short code, and
 it on your device page. `@gusnips/server/oauth` is the server half. These two hooks are the
 logic for the two pages. The pages themselves are yours.
 
+```ts
+import { createOAuthConsoleApi } from "@gusnips/react/oauth";
+
+export const oauthApi = createOAuthConsoleApi(api, "/auth/oauth");
+```
+
+That is both pages' calls to the server's `oauthConsoleRoutes`, mounted at `/auth/oauth` behind
+your sign-in. `api` is your `createApiClient` client, or any object with its `get` and `post`.
+
 ```tsx
 import { useConsentRequest } from "@gusnips/react/oauth";
 
-const consent = useConsentRequest(api.oauth, useLocation().search);
+const consent = useConsentRequest(oauthApi.consent, useLocation().search);
 
 if (consent.state.status === "ready")
   return (
@@ -709,9 +718,16 @@ if (consent.state.status === "ready")
   );
 ```
 
-`api.oauth` is two calls to your own API: `describe(query)` and `approve(query, choice)`. They
-reach the server's `describe` and `approve` through routes behind your sign-in. `state.status` is
-`loading`, `refused`, `failed` or `ready`:
+If your routes are your own, pass your own two calls instead: `describe(query)` and
+`approve(query, choice)`. The choice is anything your page adds, such as a workspace, and it reaches
+the server's approver. With no choice, call `approve()`.
+
+When your server adds fields to the view, type them after the choice:
+`createOAuthConsoleApi<string, { spaces: Space[] }>(api, "/auth/oauth")`, and
+`state.view.spaces` is typed on the consent page. A third type does the same for the device page.
+With your own calls, it is `ConsentApi<Choice, { spaces: Space[] }>`.
+
+`state.status` is `loading`, `refused`, `failed` or `ready`:
 
 - **`refused`** means the request is not one to answer: an unknown app, or a return address it
   never registered. Show `refusal.message` (or your own words for `refusal.reason`) and a link
@@ -726,13 +742,23 @@ for a second press. Approve sends the browser on with `window.location.assign`,
 an app's own scheme such as `cursor://`.
 
 ```tsx
-import { useDeviceApproval } from "@gusnips/react/oauth";
+import { useDeviceApproval, useDeviceCodeField } from "@gusnips/react/oauth";
 
-const device = useDeviceApproval(api.device, useLocation().search);
+const device = useDeviceApproval(oauthApi.device, useLocation().search);
+const field = useDeviceCodeField(device);
 
-<input value={device.code} onChange={(event) => device.setCode(event.target.value)} />;
+<label htmlFor={field.inputProps.id}>Code</label>
+<input {...field.inputProps} />
+<p {...field.statusProps}>{device.invalidLetter ? "Codes have no vowels." : null}</p>
 ```
 
+`useDeviceCodeField` is the field's wiring: the input's id, value and change handler, the
+attributes a typed code needs (no autocomplete, capitals, no spell check), `aria-invalid`, and the
+status line as the input's description, read out when it changes. It focuses the field only when it
+starts empty. It also keeps the code in the address as `?code=`, so a reload or a shared link comes
+back to the same code. It replaces the address and never pushes, so Back still leaves the page.
+Once the person decides, the code leaves the address, because the server no longer knows it.
+
 The link the script prints carries `?code=`, so the field usually starts full. The field shows
 what was typed as `WDJB-MJHT`, however it was typed. `invalidLetter` turns on as soon as a letter
 no code uses (a vowel) is typed, so you can say so before all eight are in. `state.status` adds
@@ -743,6 +769,10 @@ and send a stranger the link, and that sentence is the only guard against it. On
 page stays decided: it never asks the server again, because the server no longer knows the code,
 and asking on the next focus would tell someone who just said yes that their code is wrong.
 
+`approve(choice)` sends a choice with the yes, as on the consent page; `deny()` sends none.
+`pending` is `"approve"` or `"deny"` from the press until the server answers, so the spinner goes
+on the button that was pressed.
+
 ## A new API key, shown once
 
 ```ts
@@ -891,7 +921,7 @@ lives behind a subpath, so you install a dependency only if you import the thing
 | `@gusnips/react/contract` | two prerender names                      | nothing               |
 | `@gusnips/react/theme`    | `createTheme`, `startTheme`              | react                 |
 | `@gusnips/react/commands` | slash matching and `useSlashCommands`    | react                 |
-| `@gusnips/react/oauth`    | `useConsentRequest`, `useDeviceApproval` | @tanstack/react-query |
+| `@gusnips/react/oauth`    | the consent and device page hooks        | @tanstack/react-query |
 | `@gusnips/react/keys`     | `createKeyLifecycle`, `useKeyReveals`    | react                 |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
@@ -902,4 +932,4 @@ about it.
 `@tanstack/react-query`, `i18next` and `react-i18next` are optional and stay in the main entry,
 because only their types are used and types erase.
 
-MIT · part of [frontkit](https://github.com/gusnips/frontkit)
+MIT · part of [kit](https://github.com/gusnips/kit)

package/dist/oauth.d.ts

@@ -1,10 +1,13 @@
+import { type ChangeEvent } from "react";
+import type { ApiClient } from "./api-client.ts";
 /**
  * The two pages behind an agent's sign-in: the consent page, where Claude or ChatGPT sends a
  * person to connect, and the device page, where a script's short code is typed and approved.
  * `@gusnips/server/oauth` is the server half. Logic only: the pages are the product's.
  *
  * Each hook takes your two API calls, so your client, your session and your envelope stay yours,
- * and returns one state to draw. What they settle once:
+ * and returns one state to draw. `createOAuthConsoleApi` writes those calls for the server's
+ * `oauthConsoleRoutes`. What they settle once:
  *
  * - A refusal (an unknown app, a return address it never registered) is a STATE, never a
  *   redirect: sending the browser anywhere on a bad request is how an open redirect is built.
@@ -22,7 +25,8 @@ export interface OAuthRefusal {
     /** An English fallback a person can read. */
     message: string;
 }
-export interface ConsentView {
+/** `Extra` is anything your server adds to the view, such as the workspaces a person may pick. */
+export type ConsentView<Extra extends object = object> = Extra & {
     ok: true;
     /** What the app calls itself. Anyone may pick any name, so show `redirectHost` beside it. */
     clientName: string;
@@ -32,8 +36,8 @@ export interface ConsentView {
     keyName: string;
     /** Where "Cancel" goes: back to the app, which is told the person said no. */
     cancelUrl: string;
-}
-export interface DeviceView {
+};
+export type DeviceView<Extra extends object = object> = Extra & {
     ok: true;
     clientName: string;
     /** As the script printed it: `WDJB-MJHT`. */
@@ -41,17 +45,17 @@ export interface DeviceView {
     keyName: string;
     /** ISO time: JSON carries the server's `Date` as a string. */
     expiresAt: string;
-}
-export interface ConsentApi<Choice> {
+};
+export interface ConsentApi<Choice = void, Extra extends object = object> {
     /** Your API's call to the server's `describe`, with the query string as it came. */
-    describe(query: string): Promise<ConsentView | OAuthRefusal>;
+    describe(query: string): Promise<ConsentView<Extra> | OAuthRefusal>;
     /** Your API's call to `approve`. `choice` is anything your page adds, such as a workspace. */
     approve(query: string, choice: Choice): Promise<{
         ok: true;
         redirectTo: string;
     } | OAuthRefusal>;
 }
-export type ConsentState = {
+export type ConsentState<Extra extends object = object> = {
     status: "loading";
 }
 /** Show `refusal` and a way home. Never a link back to the app. */
@@ -66,10 +70,10 @@ export type ConsentState = {
     retry: () => void;
 } | {
     status: "ready";
-    view: ConsentView;
+    view: ConsentView<Extra>;
 };
-export interface ConsentRequest<Choice> {
-    state: ConsentState;
+export interface ConsentRequest<Choice = void, Extra extends object = object> {
+    state: ConsentState<Extra>;
     approve(choice: Choice): void;
     /** From the press until the browser has left. Keep the button busy the whole time. */
     leaving: boolean;
@@ -80,16 +84,16 @@ export interface ConsentRequest<Choice> {
  *     const consent = useConsentRequest(api.oauth, useLocation().search);
  *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
  */
-export declare function useConsentRequest<Choice = void>(api: ConsentApi<Choice>, search: string): ConsentRequest<Choice>;
-export interface DeviceApi {
+export declare function useConsentRequest<Choice = void, Extra extends object = object>(api: ConsentApi<Choice, Extra>, search: string): ConsentRequest<Choice, Extra>;
+export interface DeviceApi<Choice = void, Extra extends object = object> {
     /** Your API's call to the server's `describeDevice`. */
-    describe(code: string): Promise<DeviceView | OAuthRefusal>;
-    /** Your API's call to `decideDevice`. */
-    decide(code: string, decision: "approve" | "deny"): Promise<{
+    describe(code: string): Promise<DeviceView<Extra> | OAuthRefusal>;
+    /** Your API's call to `decideDevice`. `choice` comes with a yes only, as on the consent page. */
+    decide(code: string, decision: "approve" | "deny", choice?: Choice): Promise<{
         ok: true;
     } | OAuthRefusal>;
 }
-export type DeviceState = 
+export type DeviceState<Extra extends object = object> = 
 /** Fewer than 8 letters so far, or one a code never uses (see `invalidLetter`). */
 {
     status: "typing";
@@ -112,7 +116,7 @@ export type DeviceState =
  */
  | {
     status: "ready";
-    view: DeviceView;
+    view: DeviceView<Extra>;
 }
 /** Done. Tell them to go back to the app, which carries on by itself. */
  | {
@@ -120,16 +124,18 @@ export type DeviceState =
 } | {
     status: "denied";
 };
-export interface DeviceApproval {
-    state: DeviceState;
+export interface DeviceApproval<Choice = void, Extra extends object = object> {
+    state: DeviceState<Extra>;
     /** What the field shows, formatted as they type: `WDJB-MJ`. */
     code: string;
     setCode(input: string): void;
     /** A typed letter no code uses: a vowel. Say so now, not after eight letters. */
     invalidLetter: boolean;
-    approve(): void;
+    approve(choice: Choice): void;
     deny(): void;
     deciding: boolean;
+    /** Which button was pressed, until the server answers: put the spinner on that one. */
+    pending: "approve" | "deny" | null;
     /** The decision did not answer. Show it beside the buttons; pressing again retries. */
     decideError: unknown;
 }
@@ -141,5 +147,54 @@ export declare function formatUserCode(input: string): string;
  *
  * The link the script prints carries `?code=`, so the field usually starts full.
  */
-export declare function useDeviceApproval(api: DeviceApi, search: string): DeviceApproval;
+export declare function useDeviceApproval<Choice = void, Extra extends object = object>(api: DeviceApi<Choice, Extra>, search: string): DeviceApproval<Choice, Extra>;
+export interface DeviceCodeField {
+    /** Spread on the code's `<input>`. Point your `<label htmlFor>` at its `id`. */
+    inputProps: {
+        id: string;
+        value: string;
+        onChange(event: ChangeEvent<HTMLInputElement>): void;
+        placeholder: string;
+        autoComplete: "off";
+        autoCapitalize: "characters";
+        spellCheck: false;
+        /** Only when the field starts empty: a code from the link is there to be read first. */
+        autoFocus: boolean;
+        disabled: boolean;
+        "aria-invalid": boolean;
+        "aria-describedby": string;
+    };
+    /** Spread on the line under the field that says what is happening: a vowel, checking, refused. */
+    statusProps: {
+        id: string;
+        "aria-live": "polite";
+    };
+}
+/**
+ *     const field = useDeviceCodeField(device);
+ *     <label htmlFor={field.inputProps.id}>Code</label>
+ *     <input {...field.inputProps} />
+ *     <p {...field.statusProps}>{device.invalidLetter ? "Codes have no vowels." : null}</p>
+ *
+ * The field's wiring, and the code kept in the address as `?code=`, so a reload or a shared link
+ * comes back to the same code. The address is replaced, never pushed, so Back still leaves the
+ * page, and the router's own state rides along. Once decided the code leaves the address: the
+ * server no longer knows it, and a reload would only tell the person it is wrong.
+ */
+export declare function useDeviceCodeField<Choice, Extra extends object>(device: DeviceApproval<Choice, Extra>): DeviceCodeField;
+/** The calls the console API makes. `createApiClient`'s client fits as it is. */
+export type OAuthConsoleHttp = Pick<ApiClient, "get" | "post">;
+/**
+ *     export const oauthApi = createOAuthConsoleApi(api, "/auth/oauth");
+ *     useConsentRequest(oauthApi.consent, search);
+ *     useDeviceApproval(oauthApi.device, search);
+ *
+ * Both pages' calls to the server's `oauthConsoleRoutes`, mounted at `basePath` behind your
+ * sign-in. A choice travels as `choice`, which is where those routes hand it to your approver.
+ * `ConsentExtra` and `DeviceExtra` are the fields your server adds to each page's view.
+ */
+export declare function createOAuthConsoleApi<Choice = void, ConsentExtra extends object = object, DeviceExtra extends object = object>(http: OAuthConsoleHttp, basePath: string): {
+    consent: ConsentApi<Choice, ConsentExtra>;
+    device: DeviceApi<Choice, DeviceExtra>;
+};
 //# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/oauth.js

@@ -1,5 +1,5 @@
 import { useMutation, useQuery } from "@tanstack/react-query";
-import { useState } from "react";
+import { useEffect, useId, useState } from "react";
 /**
  *     const consent = useConsentRequest(api.oauth, useLocation().search);
  *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
@@ -59,9 +59,9 @@ export function useDeviceApproval(api, search) {
     const invalidLetter = [...letters].some((letter) => !ALPHABET.includes(letter));
     const complete = letters.length === LENGTH && !invalidLetter;
     const decision = useMutation({
-        mutationFn: (choice) => api.decide(letters, choice),
+        mutationFn: (pressed) => api.decide(letters, pressed.decision, pressed.choice),
     });
-    const decided = decision.data?.ok === true ? decision.variables : undefined;
+    const decided = decision.isSuccess && decision.data.ok ? decision.variables.decision : undefined;
     const request = useQuery({
         queryKey: ["@gusnips/react/oauth", "device", letters],
         queryFn: () => api.describe(letters),
@@ -90,10 +90,74 @@ export function useDeviceApproval(api, search) {
             setTyped(formatUserCode(input));
         },
         invalidLetter,
-        approve: () => decision.mutate("approve"),
-        deny: () => decision.mutate("deny"),
+        approve: (choice) => decision.mutate({ decision: "approve", choice }),
+        deny: () => decision.mutate({ decision: "deny" }),
         deciding: decision.isPending,
+        pending: decision.isPending ? decision.variables.decision : null,
         decideError: decision.error,
     };
 }
+/**
+ *     const field = useDeviceCodeField(device);
+ *     <label htmlFor={field.inputProps.id}>Code</label>
+ *     <input {...field.inputProps} />
+ *     <p {...field.statusProps}>{device.invalidLetter ? "Codes have no vowels." : null}</p>
+ *
+ * The field's wiring, and the code kept in the address as `?code=`, so a reload or a shared link
+ * comes back to the same code. The address is replaced, never pushed, so Back still leaves the
+ * page, and the router's own state rides along. Once decided the code leaves the address: the
+ * server no longer knows it, and a reload would only tell the person it is wrong.
+ */
+export function useDeviceCodeField(device) {
+    const id = useId();
+    const statusId = `${id}-status`;
+    const { status } = device.state;
+    const inAddress = status === "approved" || status === "denied" ? "" : device.code;
+    useEffect(() => {
+        const url = new URL(window.location.href);
+        if (inAddress)
+            url.searchParams.set("code", inAddress);
+        else
+            url.searchParams.delete("code");
+        if (url.href !== window.location.href)
+            window.history.replaceState(window.history.state, "", url);
+    }, [inAddress]);
+    return {
+        inputProps: {
+            id,
+            value: device.code,
+            onChange: (event) => device.setCode(event.target.value),
+            placeholder: "WDJB-MJHT",
+            autoComplete: "off",
+            autoCapitalize: "characters",
+            spellCheck: false,
+            autoFocus: device.code === "",
+            disabled: device.deciding,
+            "aria-invalid": device.invalidLetter || status === "refused",
+            "aria-describedby": statusId,
+        },
+        statusProps: { id: statusId, "aria-live": "polite" },
+    };
+}
+/**
+ *     export const oauthApi = createOAuthConsoleApi(api, "/auth/oauth");
+ *     useConsentRequest(oauthApi.consent, search);
+ *     useDeviceApproval(oauthApi.device, search);
+ *
+ * Both pages' calls to the server's `oauthConsoleRoutes`, mounted at `basePath` behind your
+ * sign-in. A choice travels as `choice`, which is where those routes hand it to your approver.
+ * `ConsentExtra` and `DeviceExtra` are the fields your server adds to each page's view.
+ */
+export function createOAuthConsoleApi(http, basePath) {
+    return {
+        consent: {
+            describe: (query) => http.get(`${basePath}/request?${query}`),
+            approve: (query, choice) => http.post(`${basePath}/approve`, { query, choice }),
+        },
+        device: {
+            describe: (code) => http.get(`${basePath}/device?code=${encodeURIComponent(code)}`),
+            decide: (code, decision, choice) => http.post(`${basePath}/device`, { code, decision, choice }),
+        },
+    };
+}
 //# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.30",
+  "version": "0.9.32",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
   "author": "Gustavo Salomé",
-  "homepage": "https://github.com/gusnips/frontkit/tree/main/react#readme",
+  "homepage": "https://github.com/gusnips/kit/tree/main/react#readme",
   "bugs": {
-    "url": "https://github.com/gusnips/frontkit/issues"
+    "url": "https://github.com/gusnips/kit/issues"
   },
   "exports": {
     ".": {
@@ -153,7 +153,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gusnips/frontkit.git",
+    "url": "git+https://github.com/gusnips/kit.git",
     "directory": "react"
   }
 }

package/src/oauth.test.ts

@@ -1,12 +1,15 @@
 // @vitest-environment happy-dom
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { act, createElement } from "react";
+import { act, createElement, type ChangeEvent } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApiClient } from "./api-client.ts";
 import {
+  createOAuthConsoleApi,
   formatUserCode,
   useConsentRequest,
   useDeviceApproval,
+  useDeviceCodeField,
   type ConsentApi,
   type ConsentView,
   type DeviceApi,
@@ -97,6 +100,17 @@ describe("useConsentRequest", () => {
     expect(page.current.leaving).toBe(true);
   });
 
+  it("hands the page whatever its server adds to the view, typed", async () => {
+    const api: ConsentApi<string, { spaces: string[] }> = {
+      describe: async () => ({ ...VIEW, spaces: ["ws-1", "ws-2"] }),
+      approve: async () => ({ ok: true, redirectTo: "https://claude.ai/cb" }),
+    };
+    const page = mount(() => useConsentRequest(api, "?client_id=x"));
+    await settle();
+    const { state } = page.current;
+    expect(state.status === "ready" ? state.view.spaces : null).toEqual(["ws-1", "ws-2"]);
+  });
+
   it("shows a refusal as a state and never redirects on it", async () => {
     const assign = vi.spyOn(window.location, "assign").mockImplementation(() => {});
     const page = mount(() =>
@@ -173,14 +187,14 @@ const DEVICE: DeviceView = {
   expiresAt: "2026-10-16T12:10:00.000Z",
 };
 
-describe("useDeviceApproval", () => {
-  function deviceApi(overrides: Partial<DeviceApi> = {}) {
-    return {
-      describe: vi.fn<DeviceApi["describe"]>(overrides.describe ?? (async () => DEVICE)),
-      decide: vi.fn<DeviceApi["decide"]>(overrides.decide ?? (async () => ({ ok: true }))),
-    };
-  }
+function deviceApi(overrides: Partial<DeviceApi> = {}) {
+  return {
+    describe: vi.fn<DeviceApi["describe"]>(overrides.describe ?? (async () => DEVICE)),
+    decide: vi.fn<DeviceApi["decide"]>(overrides.decide ?? (async () => ({ ok: true }))),
+  };
+}
 
+describe("useDeviceApproval", () => {
   it("starts from the link's code, asks the server, and stays approved after the yes", async () => {
     const api = deviceApi();
     const page = mount(() => useDeviceApproval(api, "?code=wdjb-mjht"));
@@ -191,7 +205,7 @@ describe("useDeviceApproval", () => {
 
     act(() => page.current.approve());
     await settle();
-    expect(api.decide).toHaveBeenCalledWith("WDJBMJHT", "approve");
+    expect(api.decide).toHaveBeenCalledWith("WDJBMJHT", "approve", undefined);
     expect(page.current.state).toEqual({ status: "approved" });
 
     // A refetch on focus would now hear "unknown code". It must not be asked.
@@ -218,11 +232,13 @@ describe("useDeviceApproval", () => {
   });
 
   it("says no, and shows a code the server does not know as refused", async () => {
-    const said = mount(() => useDeviceApproval(deviceApi(), "?code=WDJBMJHT"));
+    const api = deviceApi();
+    const said = mount(() => useDeviceApproval(api, "?code=WDJBMJHT"));
     await settle();
     act(() => said.current.deny());
     await settle();
     expect(said.current.state).toEqual({ status: "denied" });
+    expect(api.decide).toHaveBeenCalledWith("WDJBMJHT", "deny", undefined);
 
     const unknown: OAuthRefusal = { ok: false, reason: "unknown-code", message: "expired" };
     const gone = mount(() =>
@@ -246,6 +262,163 @@ describe("useDeviceApproval", () => {
   });
 });
 
+describe("useDeviceApproval with a choice", () => {
+  it("sends the page's choice with the yes, and names the pressed button until it answers", async () => {
+    let release!: () => void;
+    const decide = vi.fn<DeviceApi<string>["decide"]>(
+      () =>
+        new Promise((resolve) => {
+          release = () => resolve({ ok: true });
+        }),
+    );
+    const page = mount(() =>
+      useDeviceApproval({ describe: async () => DEVICE, decide }, "?code=WDJBMJHT"),
+    );
+    await settle();
+    expect(page.current.pending).toBeNull();
+
+    act(() => page.current.approve("ws-1"));
+    await settle();
+    expect(decide).toHaveBeenCalledWith("WDJBMJHT", "approve", "ws-1");
+    expect(page.current.pending).toBe("approve");
+
+    release();
+    await settle();
+    expect(page.current.pending).toBeNull();
+    expect(page.current.state).toEqual({ status: "approved" });
+  });
+});
+
+/** The one part of a change event the field reads. A test-only cast: the hook takes React's own. */
+const changeTo = (value: string) => ({ target: { value } }) as ChangeEvent<HTMLInputElement>;
+
+describe("useDeviceCodeField", () => {
+  it("wires the field to its status line and keeps the code in the address until decided", async () => {
+    window.history.replaceState({ idx: 3 }, "", "/device?from=mail&code=wdjbmjht");
+    const api = deviceApi();
+    const page = mount(() => {
+      const device = useDeviceApproval(api, window.location.search);
+      return { device, field: useDeviceCodeField(device) };
+    });
+    await settle();
+    const { inputProps, statusProps } = page.current.field;
+    expect(inputProps).toMatchObject({
+      value: "WDJB-MJHT",
+      autoFocus: false,
+      disabled: false,
+      "aria-invalid": false,
+      "aria-describedby": statusProps.id,
+    });
+    expect(inputProps.id).not.toBe(statusProps.id);
+    expect(window.location.search).toBe("?from=mail&code=WDJB-MJHT");
+    // Replaced with the router's own entry state, or its next Back lands on the wrong page.
+    expect(window.history.state).toEqual({ idx: 3 });
+    expect(window.history.length).toBe(1);
+
+    act(() => page.current.field.inputProps.onChange(changeTo("bcda")));
+    expect(page.current.field.inputProps["aria-invalid"]).toBe(true);
+    expect(window.location.search).toBe("?from=mail&code=BCDA");
+
+    act(() => page.current.field.inputProps.onChange(changeTo("wdjb mjht")));
+    await settle();
+    act(() => page.current.device.approve());
+    await settle();
+    expect(page.current.device.state).toEqual({ status: "approved" });
+    // The server no longer knows the code: a reload must not ask about it and say it is wrong.
+    expect(window.location.search).toBe("?from=mail");
+  });
+
+  it("focuses the field only when it starts empty", () => {
+    window.history.replaceState(null, "", "/device");
+    const page = mount(() => useDeviceCodeField(useDeviceApproval(deviceApi(), "")));
+    expect(page.current.inputProps.autoFocus).toBe(true);
+    expect(window.location.search).toBe("");
+  });
+});
+
+describe("createOAuthConsoleApi", () => {
+  function client(answer: (url: string) => unknown = () => ({ ok: true })) {
+    const sent: { url: string; method?: string; body?: BodyInit | null }[] = [];
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (url, init) => {
+      sent.push({ url: String(url), method: init?.method, body: init?.body });
+      return new Response(JSON.stringify({ data: answer(String(url)) }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+    const http = createApiClient({
+      baseUrl: "https://api.test",
+      session: {
+        getToken: async () => "token",
+        refresh: async () => ({ token: "token", reachedAuth: true }),
+        signOut: async () => {},
+      },
+      onSessionDead: () => {},
+    });
+    return { http, sent };
+  }
+
+  it("calls the server's console routes through the app's own client", async () => {
+    const { http, sent } = client();
+    const api = createOAuthConsoleApi<string>(http, "/auth/oauth");
+    await api.consent.describe("client_id=x&state=s");
+    await api.consent.approve("client_id=x&state=s", "ws-1");
+    await api.device.describe("WDJBMJHT");
+    await api.device.decide("WDJBMJHT", "approve", "ws-1");
+    await api.device.decide("WDJBMJHT", "deny");
+    expect(sent).toEqual([
+      { url: "https://api.test/auth/oauth/request?client_id=x&state=s", method: "GET" },
+      {
+        url: "https://api.test/auth/oauth/approve",
+        method: "POST",
+        body: '{"query":"client_id=x&state=s","choice":"ws-1"}',
+      },
+      { url: "https://api.test/auth/oauth/device?code=WDJBMJHT", method: "GET" },
+      {
+        url: "https://api.test/auth/oauth/device",
+        method: "POST",
+        body: '{"code":"WDJBMJHT","decision":"approve","choice":"ws-1"}',
+      },
+      {
+        url: "https://api.test/auth/oauth/device",
+        method: "POST",
+        body: '{"code":"WDJBMJHT","decision":"deny"}',
+      },
+    ]);
+  });
+
+  it("sends no choice when the page has none", async () => {
+    const { http, sent } = client();
+    await createOAuthConsoleApi(http, "/app/oauth").consent.approve("client_id=x");
+    expect(sent[0]?.body).toBe('{"query":"client_id=x"}');
+  });
+
+  it("keeps the fields your server adds to each page's view", async () => {
+    type Workspaces = { workspaces: { id: string; name: string }[] };
+    type Account = { accountEmail: string };
+    const { http } = client((url) =>
+      url.includes("/request")
+        ? { ...VIEW, workspaces: [{ id: "ws-1", name: "Acme" }] }
+        : { ...DEVICE, accountEmail: "ana@example.com" },
+    );
+    const api = createOAuthConsoleApi<string, Workspaces, Account>(http, "/auth/oauth");
+    const consent = mount(() => useConsentRequest(api.consent, "?client_id=x"));
+    const device = mount(() => useDeviceApproval(api.device, "?code=WDJB-MJHT"));
+    await settle();
+    const consentState = consent.current.state;
+    const deviceState = device.current.state;
+    if (consentState.status !== "ready" || deviceState.status !== "ready")
+      throw new Error("A view never loaded");
+
+    // These read with no cast: the page keeps the types its server adds.
+    expect(consentState.view.workspaces[0]?.name).toBe("Acme");
+    expect(deviceState.view.accountEmail).toBe("ana@example.com");
+    // @ts-expect-error: the server sends no such field.
+    expect(consentState.view.plan).toBeUndefined();
+    // @ts-expect-error: the consent page's fields are not the device page's.
+    expect(deviceState.view.workspaces).toBeUndefined();
+  });
+});
+
 describe("formatUserCode", () => {
   it("writes what the field shows", () => {
     expect(formatUserCode("")).toBe("");

package/src/oauth.ts

@@ -1,5 +1,6 @@
 import { useMutation, useQuery } from "@tanstack/react-query";
-import { useState } from "react";
+import { useEffect, useId, useState, type ChangeEvent } from "react";
+import type { ApiClient } from "./api-client.ts";
 
 /**
  * The two pages behind an agent's sign-in: the consent page, where Claude or ChatGPT sends a
@@ -7,7 +8,8 @@ import { useState } from "react";
  * `@gusnips/server/oauth` is the server half. Logic only: the pages are the product's.
  *
  * Each hook takes your two API calls, so your client, your session and your envelope stay yours,
- * and returns one state to draw. What they settle once:
+ * and returns one state to draw. `createOAuthConsoleApi` writes those calls for the server's
+ * `oauthConsoleRoutes`. What they settle once:
  *
  * - A refusal (an unknown app, a return address it never registered) is a STATE, never a
  *   redirect: sending the browser anywhere on a bad request is how an open redirect is built.
@@ -29,7 +31,8 @@ export interface OAuthRefusal {
   message: string;
 }
 
-export interface ConsentView {
+/** `Extra` is anything your server adds to the view, such as the workspaces a person may pick. */
+export type ConsentView<Extra extends object = object> = Extra & {
   ok: true;
   /** What the app calls itself. Anyone may pick any name, so show `redirectHost` beside it. */
   clientName: string;
@@ -39,9 +42,9 @@ export interface ConsentView {
   keyName: string;
   /** Where "Cancel" goes: back to the app, which is told the person said no. */
   cancelUrl: string;
-}
+};
 
-export interface DeviceView {
+export type DeviceView<Extra extends object = object> = Extra & {
   ok: true;
   clientName: string;
   /** As the script printed it: `WDJB-MJHT`. */
@@ -49,25 +52,25 @@ export interface DeviceView {
   keyName: string;
   /** ISO time: JSON carries the server's `Date` as a string. */
   expiresAt: string;
-}
+};
 
-export interface ConsentApi<Choice> {
+export interface ConsentApi<Choice = void, Extra extends object = object> {
   /** Your API's call to the server's `describe`, with the query string as it came. */
-  describe(query: string): Promise<ConsentView | OAuthRefusal>;
+  describe(query: string): Promise<ConsentView<Extra> | OAuthRefusal>;
   /** Your API's call to `approve`. `choice` is anything your page adds, such as a workspace. */
   approve(query: string, choice: Choice): Promise<{ ok: true; redirectTo: string } | OAuthRefusal>;
 }
 
-export type ConsentState =
+export type ConsentState<Extra extends object = object> =
   | { status: "loading" }
   /** Show `refusal` and a way home. Never a link back to the app. */
   | { status: "refused"; refusal: OAuthRefusal }
   /** The request failed to arrive or answer. Show what failed, and `retry`. */
   | { status: "failed"; error: unknown; retry: () => void }
-  | { status: "ready"; view: ConsentView };
+  | { status: "ready"; view: ConsentView<Extra> };
 
-export interface ConsentRequest<Choice> {
-  state: ConsentState;
+export interface ConsentRequest<Choice = void, Extra extends object = object> {
+  state: ConsentState<Extra>;
   approve(choice: Choice): void;
   /** From the press until the browser has left. Keep the button busy the whole time. */
   leaving: boolean;
@@ -79,10 +82,10 @@ export interface ConsentRequest<Choice> {
  *     const consent = useConsentRequest(api.oauth, useLocation().search);
  *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
  */
-export function useConsentRequest<Choice = void>(
-  api: ConsentApi<Choice>,
+export function useConsentRequest<Choice = void, Extra extends object = object>(
+  api: ConsentApi<Choice, Extra>,
   search: string,
-): ConsentRequest<Choice> {
+): ConsentRequest<Choice, Extra> {
   const query = search.replace(/^\?/, "");
   const request = useQuery({
     queryKey: ["@gusnips/react/oauth", "consent", query],
@@ -99,7 +102,7 @@ export function useConsentRequest<Choice = void>(
   const answer = request.data;
   const refusal =
     approval.data?.ok === false ? approval.data : answer?.ok === false ? answer : null;
-  let state: ConsentState;
+  let state: ConsentState<Extra>;
   if (refusal) state = { status: "refused", refusal };
   else if (answer?.ok === true) state = { status: "ready", view: answer };
   else if (request.isError)
@@ -114,14 +117,18 @@ export function useConsentRequest<Choice = void>(
   };
 }
 
-export interface DeviceApi {
+export interface DeviceApi<Choice = void, Extra extends object = object> {
   /** Your API's call to the server's `describeDevice`. */
-  describe(code: string): Promise<DeviceView | OAuthRefusal>;
-  /** Your API's call to `decideDevice`. */
-  decide(code: string, decision: "approve" | "deny"): Promise<{ ok: true } | OAuthRefusal>;
+  describe(code: string): Promise<DeviceView<Extra> | OAuthRefusal>;
+  /** Your API's call to `decideDevice`. `choice` comes with a yes only, as on the consent page. */
+  decide(
+    code: string,
+    decision: "approve" | "deny",
+    choice?: Choice,
+  ): Promise<{ ok: true } | OAuthRefusal>;
 }
 
-export type DeviceState =
+export type DeviceState<Extra extends object = object> =
   /** Fewer than 8 letters so far, or one a code never uses (see `invalidLetter`). */
   | { status: "typing" }
   | { status: "loading" }
@@ -133,21 +140,23 @@ export type DeviceState =
    * this is the code on your screen. Somebody can run the real script and send a stranger the
    * link, and that sentence is the only guard against it (RFC 8628 §5.4).
    */
-  | { status: "ready"; view: DeviceView }
+  | { status: "ready"; view: DeviceView<Extra> }
   /** Done. Tell them to go back to the app, which carries on by itself. */
   | { status: "approved" }
   | { status: "denied" };
 
-export interface DeviceApproval {
-  state: DeviceState;
+export interface DeviceApproval<Choice = void, Extra extends object = object> {
+  state: DeviceState<Extra>;
   /** What the field shows, formatted as they type: `WDJB-MJ`. */
   code: string;
   setCode(input: string): void;
   /** A typed letter no code uses: a vowel. Say so now, not after eight letters. */
   invalidLetter: boolean;
-  approve(): void;
+  approve(choice: Choice): void;
   deny(): void;
   deciding: boolean;
+  /** Which button was pressed, until the server answers: put the spinner on that one. */
+  pending: "approve" | "deny" | null;
   /** The decision did not answer. Show it beside the buttons; pressing again retries. */
   decideError: unknown;
 }
@@ -171,7 +180,10 @@ export function formatUserCode(input: string): string {
  *
  * The link the script prints carries `?code=`, so the field usually starts full.
  */
-export function useDeviceApproval(api: DeviceApi, search: string): DeviceApproval {
+export function useDeviceApproval<Choice = void, Extra extends object = object>(
+  api: DeviceApi<Choice, Extra>,
+  search: string,
+): DeviceApproval<Choice, Extra> {
   const [code, setTyped] = useState(() =>
     formatUserCode(new URLSearchParams(search).get("code") ?? ""),
   );
@@ -180,9 +192,10 @@ export function useDeviceApproval(api: DeviceApi, search: string): DeviceApprova
   const complete = letters.length === LENGTH && !invalidLetter;
 
   const decision = useMutation({
-    mutationFn: (choice: "approve" | "deny") => api.decide(letters, choice),
+    mutationFn: (pressed: { decision: "approve" | "deny"; choice?: Choice }) =>
+      api.decide(letters, pressed.decision, pressed.choice),
   });
-  const decided = decision.data?.ok === true ? decision.variables : undefined;
+  const decided = decision.isSuccess && decision.data.ok ? decision.variables.decision : undefined;
   const request = useQuery({
     queryKey: ["@gusnips/react/oauth", "device", letters],
     queryFn: () => api.describe(letters),
@@ -192,7 +205,7 @@ export function useDeviceApproval(api: DeviceApi, search: string): DeviceApprova
   const answer = request.data;
   const refusal =
     decision.data?.ok === false ? decision.data : answer?.ok === false ? answer : null;
-  let state: DeviceState;
+  let state: DeviceState<Extra>;
   if (decided !== undefined) state = { status: decided === "approve" ? "approved" : "denied" };
   else if (!complete) state = { status: "typing" };
   else if (refusal) state = { status: "refused", refusal };
@@ -209,9 +222,107 @@ export function useDeviceApproval(api: DeviceApi, search: string): DeviceApprova
       setTyped(formatUserCode(input));
     },
     invalidLetter,
-    approve: () => decision.mutate("approve"),
-    deny: () => decision.mutate("deny"),
+    approve: (choice) => decision.mutate({ decision: "approve", choice }),
+    deny: () => decision.mutate({ decision: "deny" }),
     deciding: decision.isPending,
+    pending: decision.isPending ? decision.variables.decision : null,
     decideError: decision.error,
   };
 }
+
+export interface DeviceCodeField {
+  /** Spread on the code's `<input>`. Point your `<label htmlFor>` at its `id`. */
+  inputProps: {
+    id: string;
+    value: string;
+    onChange(event: ChangeEvent<HTMLInputElement>): void;
+    placeholder: string;
+    autoComplete: "off";
+    autoCapitalize: "characters";
+    spellCheck: false;
+    /** Only when the field starts empty: a code from the link is there to be read first. */
+    autoFocus: boolean;
+    disabled: boolean;
+    "aria-invalid": boolean;
+    "aria-describedby": string;
+  };
+  /** Spread on the line under the field that says what is happening: a vowel, checking, refused. */
+  statusProps: { id: string; "aria-live": "polite" };
+}
+
+/**
+ *     const field = useDeviceCodeField(device);
+ *     <label htmlFor={field.inputProps.id}>Code</label>
+ *     <input {...field.inputProps} />
+ *     <p {...field.statusProps}>{device.invalidLetter ? "Codes have no vowels." : null}</p>
+ *
+ * The field's wiring, and the code kept in the address as `?code=`, so a reload or a shared link
+ * comes back to the same code. The address is replaced, never pushed, so Back still leaves the
+ * page, and the router's own state rides along. Once decided the code leaves the address: the
+ * server no longer knows it, and a reload would only tell the person it is wrong.
+ */
+export function useDeviceCodeField<Choice, Extra extends object>(
+  device: DeviceApproval<Choice, Extra>,
+): DeviceCodeField {
+  const id = useId();
+  const statusId = `${id}-status`;
+  const { status } = device.state;
+  const inAddress = status === "approved" || status === "denied" ? "" : device.code;
+  useEffect(() => {
+    const url = new URL(window.location.href);
+    if (inAddress) url.searchParams.set("code", inAddress);
+    else url.searchParams.delete("code");
+    if (url.href !== window.location.href)
+      window.history.replaceState(window.history.state, "", url);
+  }, [inAddress]);
+
+  return {
+    inputProps: {
+      id,
+      value: device.code,
+      onChange: (event) => device.setCode(event.target.value),
+      placeholder: "WDJB-MJHT",
+      autoComplete: "off",
+      autoCapitalize: "characters",
+      spellCheck: false,
+      autoFocus: device.code === "",
+      disabled: device.deciding,
+      "aria-invalid": device.invalidLetter || status === "refused",
+      "aria-describedby": statusId,
+    },
+    statusProps: { id: statusId, "aria-live": "polite" },
+  };
+}
+
+/** The calls the console API makes. `createApiClient`'s client fits as it is. */
+export type OAuthConsoleHttp = Pick<ApiClient, "get" | "post">;
+
+/**
+ *     export const oauthApi = createOAuthConsoleApi(api, "/auth/oauth");
+ *     useConsentRequest(oauthApi.consent, search);
+ *     useDeviceApproval(oauthApi.device, search);
+ *
+ * Both pages' calls to the server's `oauthConsoleRoutes`, mounted at `basePath` behind your
+ * sign-in. A choice travels as `choice`, which is where those routes hand it to your approver.
+ * `ConsentExtra` and `DeviceExtra` are the fields your server adds to each page's view.
+ */
+export function createOAuthConsoleApi<
+  Choice = void,
+  ConsentExtra extends object = object,
+  DeviceExtra extends object = object,
+>(
+  http: OAuthConsoleHttp,
+  basePath: string,
+): { consent: ConsentApi<Choice, ConsentExtra>; device: DeviceApi<Choice, DeviceExtra> } {
+  return {
+    consent: {
+      describe: (query) => http.get(`${basePath}/request?${query}`),
+      approve: (query, choice) => http.post(`${basePath}/approve`, { query, choice }),
+    },
+    device: {
+      describe: (code) => http.get(`${basePath}/device?code=${encodeURIComponent(code)}`),
+      decide: (code, decision, choice) =>
+        http.post(`${basePath}/device`, { code, decision, choice }),
+    },
+  };
+}