@eifi1/ui-kit 0.28.1 → 0.30.0

package/src/auth/accept-invitation.tsx

@@ -0,0 +1,227 @@
+import { useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { CheckCircle2, LogIn, TimerOff, XCircle } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { useAnnounce } from "../hooks/use-announce";
+import { LoadingState } from "../components/loading-state";
+import { Button, EmptyState } from "../components/ui";
+import { authErrorCode } from "./auth-errors";
+import { OUTCOME_CLASS, STATUS_HEADING_CLASS, useOncePerKey } from "./status-parts";
+import type { AuthHeadingLevel } from "./status-parts";
+
+/* ── Labels ──────────────────────────────────────────────────────────────── */
+
+/** Every string the page renders — the `acceptInvitation` namespace. keksdose's words
+ *  where its `/join` page has them (`budget_share.join*`). */
+export interface AcceptInvitationLabels {
+  /** The heading. */
+  title: string;
+  /** While the invitation is accepted. */
+  accepting: string;
+  /** Accepted, when the app did not say into what. */
+  accepted: string;
+  /** Accepted, given what it attached the account to — a company, a team, a budget. */
+  joined: (name: string) => string;
+  /** Into the app, from every outcome but "sign in first". */
+  continue: string;
+  /** The token is unknown, spent, or for another address. */
+  invalid: string;
+  expired: string;
+  /** The page was opened without a `token`. */
+  noToken: string;
+  /** Under `invalid` and `expired`: an invitation is re-sent as a new one (§4.4). */
+  askAgain: string;
+  /** Nobody is signed in: an existing account accepts after sign-in (§4.4). */
+  signInFirst: string;
+  /** Under it. */
+  signInHint: string;
+  signIn: string;
+  /** Beside "Sign in", with `registerHref`. */
+  register: string;
+}
+
+export const DEFAULT_ACCEPT_INVITATION_LABELS: AcceptInvitationLabels = {
+  title: "Accept invitation",
+  accepting: "Joining…",
+  accepted: "Invitation accepted.",
+  joined: (name) => `You’ve joined ${name}.`,
+  continue: "Continue",
+  invalid: "Could not join with this link",
+  expired: "This invitation has expired",
+  noToken: "This link is missing its invite token.",
+  askAgain: "Ask the person who invited you to send a new invitation.",
+  signInFirst: "Sign in to accept this invitation",
+  signInHint: "Use the account the invitation was sent to.",
+  signIn: "Sign in",
+  register: "Create account",
+};
+
+/* ── Types ───────────────────────────────────────────────────────────────── */
+
+/** What `onAccept` may resolve with. */
+export interface AcceptInvitationResult {
+  /** What the invitation attached the account to, by name — "Example Property Ltd",
+   *  "Team North", a budget. Said in the confirmation. */
+  name?: string;
+}
+
+/** What became of an invitation that was not accepted. `signIn`: the server wants a
+ *  session first (a `401`), which `signedIn` did not know about. */
+export type AcceptInvitationFailure = "invalid" | "expired" | "signIn";
+
+type Outcome = "accepted" | AcceptInvitationFailure;
+
+export interface AcceptInvitationProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "title"> {
+  /** The invitation's token — the app's `?invite=` / `?token=`. Empty: the link was cut
+   *  short, and the page says so without asking anyone. */
+  token: string;
+  /** Someone is signed in on this device. Until then the page asks for a sign-in and
+   *  sends nothing: accepting attaches the invitation to the SIGNED-IN account. */
+  signedIn: boolean;
+  /**
+   * Accept it — `POST /auth/invitations/accept {token}`, once per token, as soon as
+   * someone is signed in. Resolve (with what it attached the account to, if the app
+   * knows); reject with the client's error.
+   */
+  onAccept: (token: string) => Promise<AcceptInvitationResult | void | undefined>;
+  /** Which dead end a rejection is. Default: `invitation_expired` is `expired`,
+   *  anything else `invalid` (§5.2's codes). Map a `401` to `signIn` here. */
+  classifyError?: (error: unknown) => AcceptInvitationFailure;
+  /** "Continue" — into the app. Default `/`. */
+  continueHref?: string;
+  /** "Sign in" — the app's `/login`, with a way back here (`?next=…`). Default
+   *  `/login`. */
+  signInHref?: string;
+  /** "Create account" beside "Sign in", for an invitation that may lead to a new
+   *  account — the app's `/register?invite=…`. Left out, none. */
+  registerHref?: string;
+  /** The heading. Default `labels.title`; `null` draws none, for a page that puts it in
+   *  `AuthLayout`'s `title` instead. */
+  title?: ReactNode;
+  /** The heading's level. Default `h2`, under the page's `h1`. */
+  headingAs?: AuthHeadingLevel;
+  labels?: Partial<AcceptInvitationLabels>;
+}
+
+/**
+ * Accept an invitation with an EXISTING account (docs/auth-harmonization.md §4.4): the
+ * link leads here, the person signs in if they are not, and the app attaches the
+ * invitation — a kastlan user joining a second company, a Kurvenschmiede member a team,
+ * a keksdose user a shared budget. A new address never needs this page: its link opens
+ * the sign-up form, which spends the invitation itself.
+ *
+ * keksdose's `JoinSharePage` (features/budgets/join-page.tsx) is the model: it accepts
+ * on load, once (the token is single-use, and StrictMode's double effect would send it
+ * twice), and shows the outcome where its spinner was. The outcomes: accepted, with the
+ * way into the app; not valid; expired (both say to ask for a new invitation, since
+ * "resend" mints a new token); or "sign in first", with nothing sent. "Continue" REPLACES
+ * this page in the history: the token is spent, so Back must not land here again.
+ */
+export function AcceptInvitation({
+  token,
+  signedIn,
+  onAccept,
+  classifyError,
+  continueHref = "/",
+  signInHref = "/login",
+  registerHref,
+  title,
+  headingAs: Heading = "h2",
+  labels: labelsProp,
+  className,
+  ...rest
+}: AcceptInvitationProps) {
+  const labels = useKitLabels("acceptInvitation", DEFAULT_ACCEPT_INVITATION_LABELS, labelsProp);
+  const [settled, setSettled] = useState<{ token: string; outcome: Outcome; name?: string } | null>(null);
+  const { announce, regionProps } = useAnnounce();
+
+  useOncePerKey(token !== "" && signedIn ? token : null, onAccept, (key, result) => {
+    if (result.ok) {
+      const name = result.value?.name?.trim() || undefined;
+      setSettled({ token: key, outcome: "accepted", name });
+      announce(name ? labels.joined(name) : labels.accepted);
+      return;
+    }
+    const failure: AcceptInvitationFailure =
+      classifyError?.(result.error) ?? (authErrorCode(result.error) === "invitation_expired" ? "expired" : "invalid");
+    setSettled({ token: key, outcome: failure });
+    announce(failure === "signIn" ? labels.signInFirst : labels[failure]);
+  });
+
+  const outcome: Outcome | "accepting" =
+    token === ""
+      ? "invalid"
+      : settled?.token === token
+        ? settled.outcome
+        : signedIn
+          ? "accepting"
+          : "signIn";
+
+  const continueButton = (variant: "brand" | "secondary") => (
+    <Button href={continueHref} replace variant={variant}>
+      {labels.continue}
+    </Button>
+  );
+
+  let body: ReactNode;
+  if (outcome === "accepting") {
+    body = <LoadingState size="sm" label={labels.accepting} />;
+  } else if (outcome === "accepted") {
+    body = (
+      <EmptyState
+        tone="success"
+        icon={<CheckCircle2 />}
+        title={settled?.name ? labels.joined(settled.name) : labels.accepted}
+        action={continueButton("brand")}
+        className={OUTCOME_CLASS}
+      />
+    );
+  } else if (outcome === "signIn") {
+    body = (
+      <EmptyState
+        icon={<LogIn />}
+        title={labels.signInFirst}
+        hint={labels.signInHint}
+        action={
+          <>
+            <Button href={signInHref} variant="brand">
+              {labels.signIn}
+            </Button>
+            {registerHref !== undefined && (
+              <Button href={registerHref} variant="secondary">
+                {labels.register}
+              </Button>
+            )}
+          </>
+        }
+        className={OUTCOME_CLASS}
+      />
+    );
+  } else {
+    body = (
+      <EmptyState
+        tone="danger"
+        icon={outcome === "expired" ? <TimerOff /> : <XCircle />}
+        title={token === "" ? labels.noToken : labels[outcome]}
+        hint={labels.askAgain}
+        action={signedIn ? continueButton("secondary") : undefined}
+        className={OUTCOME_CLASS}
+      />
+    );
+  }
+
+  return (
+    <div
+      {...rest}
+      data-state={outcome}
+      aria-busy={outcome === "accepting" || undefined}
+      className={cn("space-y-3", className)}
+    >
+      {title === null ? null : <Heading className={STATUS_HEADING_CLASS}>{title ?? labels.title}</Heading>}
+      {body}
+      {/* Rendered from the start, so the outcome is read when it arrives. */}
+      <div {...regionProps} />
+    </div>
+  );
+}

package/src/auth/auth-errors.ts

@@ -0,0 +1,262 @@
+/**
+ * The coded refusals of sign-in and sign-up (docs/auth-harmonization.md §5.2): every
+ * refusal the auth routes answer carries a machine-readable `code`, and the pages
+ * recognise the CODE, never the server's sentence.
+ *
+ * Today each app's pages print the server's `detail` string (keksdose's
+ * `extractApiErrorMessage`), which is English on every locale and, on a credential
+ * check, would be an account-enumeration oracle if it ever said more than one thing.
+ * keksdose already keys one refusal on a code (`features/budgets/plan-limit.ts`,
+ * `402 {detail, code: "plan_budget_limit"}`); §5.2 makes that the rule for auth. Each
+ * app switches its server and its pages together (§9).
+ *
+ * - `invalid_credentials` — unknown address, wrong password AND deactivated account:
+ *   one answer, in the same time (§2.10). `401`.
+ * - `registration_closed` — the sign-up gate refused the address. `403`.
+ * - `email_taken` — an account with this address exists. `409`.
+ * - `invitation_invalid`, `invitation_expired` — the `invite` token of a sign-up or an
+ *   accept (§4.4).
+ * - `token_invalid` — a one-time token (reset, verification, a sign-in challenge) is
+ *   unknown, spent or expired.
+ * - `account_inactive` — **no server answers it.** §2.10 decided that a deactivated
+ *   account gets `invalid_credentials`, because a separate answer after a correct
+ *   password would confirm a leaked one. It stays in the union only for a future server
+ *   step that is past the password (an admin view, a signed-in refresh) and may say so.
+ */
+export type AuthErrorCode =
+  | "invalid_credentials"
+  | "registration_closed"
+  | "email_taken"
+  | "invitation_invalid"
+  | "invitation_expired"
+  | "token_invalid"
+  /** 0.29.1: a link that WAS valid and ran out (verification, reset) — keksdose's step-3
+   *  refusals tell it from `token_invalid`, so a page can say "expired, ask for a new one". */
+  | "token_expired"
+  | "account_inactive";
+
+/**
+ * 0.30.0: the coded refusals of user administration and the account's own settings
+ * (docs/user-admin-harmonization.md §4, §6) — server-kit 0.4.0's `AccountErrorCode`,
+ * value for value. The same family of answer as the sign-in codes (`{detail, code}`,
+ * plus `companies` on kastlan's `last_admin`), read by the same {@link authErrorCode}.
+ *
+ * - `last_admin` — the action would leave no active admin: deactivating, demoting or
+ *   deleting the last one (in kastlan, of a company; the answer names the `companies`).
+ * - `self_action` — an admin acting on their own account where that is never allowed.
+ * - `other_companies` — kastlan: the account belongs to other companies too, so a
+ *   company admin may not deactivate it; "Remove from company" instead (§9.6).
+ * - `household_has_members` — keksdose's guard on a deletion request (§6.4).
+ * - `confirmation_required`, `confirmation_mismatch` — the action's confirmation level
+ *   asked for a typed address (or a tick), and the request carried none, or another
+ *   address (§4.2).
+ * - `password_incorrect` — the CURRENT password is wrong on a signed-in route (the email
+ *   change, the deletion request). `400`, not `401`: an app's client reads a 401 as an
+ *   ended session and signs the user out, the wrong answer to a typo. Every other one
+ *   is a `409`.
+ */
+export type AccountErrorCode =
+  | "last_admin"
+  | "self_action"
+  | "other_companies"
+  | "household_has_members"
+  | "confirmation_required"
+  | "confirmation_mismatch"
+  | "password_incorrect";
+
+/** Every code the kit reads: the sign-in refusals and the account ones (0.30.0). */
+export type KitErrorCode = AuthErrorCode | AccountErrorCode;
+
+const CODES: ReadonlySet<string> = new Set<KitErrorCode>([
+  "invalid_credentials",
+  "registration_closed",
+  "email_taken",
+  "invitation_invalid",
+  "invitation_expired",
+  "token_invalid",
+  "token_expired",
+  "account_inactive",
+  "last_admin",
+  "self_action",
+  "other_companies",
+  "household_has_members",
+  "confirmation_required",
+  "confirmation_mismatch",
+  "password_incorrect",
+]);
+
+type Bag = Record<string, unknown>;
+
+const isBag = (value: unknown): value is Bag => typeof value === "object" && value !== null;
+
+/** A known code, or undefined. */
+function known(value: unknown): KitErrorCode | undefined {
+  return typeof value === "string" && CODES.has(value) ? (value as KitErrorCode) : undefined;
+}
+
+/** `{code}` on a parsed body, or FastAPI's `{detail: {code}}` — what an
+ *  `HTTPException(detail={"code": …})` serialises to. */
+function codeOfBody(body: unknown): KitErrorCode | undefined {
+  if (!isBag(body)) return undefined;
+  return known(body.code) ?? (isBag(body.detail) ? known(body.detail.code) : undefined);
+}
+
+/**
+ * The code an error carries — an {@link AuthErrorCode}, or since 0.30.0 an
+ * {@link AccountErrorCode} — or `undefined` when it carries none.
+ *
+ * Reads the parsed response body wherever the apps' HTTP clients put it, without
+ * depending on any of them:
+ *
+ *  1. `err.response.data` — axios (keksdose's, kastlan's and Kurvenschmiede's clients;
+ *     keksdose's `isPlanBudgetLimitRefusal` reads the same path);
+ *  2. `err.data` — ofetch's `FetchError`, and most `fetch` wrappers that parse the body;
+ *  3. `err.body` — the generated OpenAPI clients' `ApiError`;
+ *  4. `err` itself — a body thrown as it came (`throw await res.json()`).
+ *
+ * In each, `code` or FastAPI's nested `detail.code`. Last, `err.code` — but only when
+ * it is one of the codes above: axios writes its OWN codes there (`ERR_NETWORK`,
+ * `ECONNABORTED`, `ERR_BAD_REQUEST`), and so does Node, so an unknown value is never
+ * read as a refusal. The HTTP status is not checked: the code is the contract, and the
+ * status differs per refusal (401, 403, 409, 410).
+ */
+export function authErrorCode(err: unknown): KitErrorCode | undefined {
+  if (!isBag(err)) return undefined;
+  const response = err.response;
+  return (
+    (isBag(response) ? codeOfBody(response.data) : undefined) ??
+    codeOfBody(err.data) ??
+    codeOfBody(err.body) ??
+    codeOfBody(err)
+  );
+}
+
+/**
+ * Whether `err` is a coded auth refusal — any of them, or the one named:
+ *
+ * ```ts
+ * try { await api.register(values) }
+ * catch (err) { if (isAuthError(err, "email_taken")) … }
+ * ```
+ *
+ * The kit's `SignInForm` and `RegisterForm` call it on what their callbacks reject
+ * with, so an app's `onSubmit` can simply let its client's error through. See
+ * {@link authErrorCode} for the shapes it reads. Since 0.30.0 it knows the account codes
+ * too: `isAuthError(err, "last_admin")`.
+ */
+export function isAuthError(err: unknown, code?: KitErrorCode): boolean {
+  const found = authErrorCode(err);
+  return found !== undefined && (code === undefined || found === code);
+}
+
+/** An HTTP status as a number, or undefined. */
+function statusOf(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) ? value : undefined;
+}
+
+/**
+ * Whether `err` is a throttled request — HTTP `429 Too Many Requests` (0.30.0, from the
+ * apps' 0.29 adoption: every app answered a throttled sign-in, sign-up or reset through
+ * its own `describeError`, with three wordings of one sentence).
+ *
+ * A throttle carries no `code` in the contract — the STATUS is the answer, set by the
+ * apps' limiters (server-kit's `AuthLimiters`, keksdose's per-IP limit) — so this reads
+ * the status, wherever the apps' HTTP clients put it, without depending on any of them:
+ *
+ *  1. `err.response.status` — axios (all three apps' clients);
+ *  2. `err.status` — ofetch's `FetchError`, the generated OpenAPI clients' `ApiError`, and
+ *     a `Response` thrown as it came;
+ *  3. `err.statusCode` — ofetch's alias, and Node-style errors.
+ *
+ * There is no `rate_limited` code: keksdose answers its 429s uncoded, with a
+ * `Retry-After` header, and the status is the one signal every limiter gives.
+ *
+ * The kit's `SignInForm`, `RegisterForm`, `ForgotPasswordForm` and `ResetPasswordForm`
+ * call it AFTER the app's `describeError` — an app with words of its own keeps them —
+ * and before their generic failure, so "Too many attempts. Try again in 30 s." (with
+ * {@link retryAfterSeconds}) or "… Wait a moment and try again." needs no app code.
+ */
+export function isRateLimited(err: unknown): boolean {
+  if (!isBag(err)) return false;
+  const response = err.response;
+  const status =
+    (isBag(response) ? statusOf(response.status) : undefined) ?? statusOf(err.status) ?? statusOf(err.statusCode);
+  return status === 429;
+}
+
+/** A header's value from a `Headers` (fetch, ofetch's `response`), axios' `AxiosHeaders`
+ *  or a plain record — whose keys may come in any case. */
+function headerOf(headers: unknown, name: string): unknown {
+  if (!isBag(headers)) return undefined;
+  if (typeof headers.get === "function") {
+    try {
+      const value: unknown = (headers.get as (key: string) => unknown).call(headers, name);
+      if (value !== undefined && value !== null) return value;
+    } catch {
+      // A `get` that is not a header lookup; the record below is.
+    }
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) return value;
+  }
+  return undefined;
+}
+
+/** `Retry-After` as seconds from `now`: delta-seconds ("30"), or an HTTP date
+ *  ("Wed, 07 Oct 2026 10:00:00 GMT") counted from now, never below 0 (RFC 9110 §10.2.3). */
+function parseRetryAfter(value: unknown, now: number): number | undefined {
+  const raw = Array.isArray(value) ? (value as unknown[])[0] : value;
+  if (typeof raw === "number") return Number.isFinite(raw) && raw >= 0 ? Math.ceil(raw) : undefined;
+  if (typeof raw !== "string") return undefined;
+  const text = raw.trim();
+  if (/^\d+$/.test(text)) return Number(text);
+  // An HTTP date names its day and month ("Wed, 07 Oct 2026 …"). Without a letter it is
+  // a malformed number ("-5", "1.5"), which `Date.parse` would happily read as a year.
+  if (!/[a-z]/i.test(text)) return undefined;
+  const at = Date.parse(text);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, Math.ceil((at - now) / 1000));
+}
+
+/**
+ * How long a throttled request asks to wait, in whole seconds — its `Retry-After`
+ * header (0.30.0, keksdose: its 429s carry no code, only the header) — or `undefined`
+ * when there is none, or none that parses.
+ *
+ * Read where the apps' clients keep the response headers, without depending on any of
+ * them: `err.response.headers` (axios' `AxiosHeaders` or a plain record; ofetch's
+ * `FetchError.response`, a fetch `Headers`), then `err.headers` (a `Response` thrown as
+ * it came). The value is delta-seconds, or an HTTP date turned into seconds from `now`
+ * (default: the present moment) — never below 0.
+ *
+ * The forms hand it to their `rateLimited` label when {@link isRateLimited} is true:
+ * "Too many attempts. Try again in 30 s." — and, without one, "… Wait a moment and try
+ * again." A browser only exposes `Retry-After` to a cross-origin page when the server
+ * lists it in `Access-Control-Expose-Headers`.
+ */
+export function retryAfterSeconds(err: unknown, now: number | Date = Date.now()): number | undefined {
+  if (!isBag(err)) return undefined;
+  const at = typeof now === "number" ? now : now.getTime();
+  const response = err.response;
+  const value =
+    (isBag(response) ? headerOf(response.headers, "retry-after") : undefined) ?? headerOf(err.headers, "retry-after");
+  return value === undefined ? undefined : parseRetryAfter(value, at);
+}
+
+/**
+ * The English of every `rateLimited` label (0.30.0): "Too many attempts. Try again in
+ * 30 s." with a wait under a minute, in whole minutes from one minute up (keksdose's
+ * reset throttle answers in hours, and "3600 s" is a number nobody reads), and "Wait a
+ * moment and try again." without one — or with a `0`.
+ *
+ * @internal The namespaces' English; not part of the barrel.
+ */
+export function englishRateLimited(seconds?: number): string {
+  if (!seconds || seconds <= 0) return "Too many attempts. Wait a moment and try again.";
+  return `Too many attempts. Try again in ${englishWait(seconds)}.`;
+}
+
+/** "30 s", "2 min" — a wait in English, rounded up. @internal */
+export function englishWait(seconds: number): string {
+  return seconds < 60 ? `${Math.ceil(seconds)} s` : `${Math.ceil(seconds / 60)} min`;
+}