@eifi1/ui-kit 0.29.0 → 0.31.0

package/src/auth/auth-errors.ts

@@ -30,16 +30,88 @@ export type AuthErrorCode =
   | "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";
 
-const CODES: ReadonlySet<string> = new Set<AuthErrorCode>([
+/**
+ * 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";
+
+/**
+ * 0.31.0: the demo's coded refusals (docs/landing-demo-harmonization.md §6.2) —
+ * server-kit 0.5's `DemoErrorCode`, value for value, answered as `{detail, code}` like
+ * the others and read by the same {@link authErrorCode}.
+ *
+ * - `demo_disabled` — `404`: the demo switch is off (it is "not there", not forbidden).
+ * - `demo_rate_limited` — `429` with `Retry-After`: the per-IP window of demo starts.
+ * - `demo_capacity` — `429`, no `Retry-After`: the cap of live demo users.
+ * - `demo_not_ready` — `503`: the demo data has not been seeded yet.
+ * - `demo_read_only` — `403`, model R: any write by a demo user. The app's write lock
+ *   already explains it, so it shows no toast (§5.4).
+ * - `demo_refused` — `403`, both models: an action a demo never may — a way in or out,
+ *   mail, uploads, the account export (§6.4).
+ */
+export type DemoErrorCode =
+  | "demo_disabled"
+  | "demo_rate_limited"
+  | "demo_capacity"
+  | "demo_not_ready"
+  | "demo_read_only"
+  | "demo_refused";
+
+/** Every code the kit reads: the sign-in refusals, the account ones (0.30.0) and the
+ *  demo's (0.31.0). */
+export type KitErrorCode = AuthErrorCode | AccountErrorCode | DemoErrorCode;
+
+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",
+  "demo_disabled",
+  "demo_rate_limited",
+  "demo_capacity",
+  "demo_not_ready",
+  "demo_read_only",
+  "demo_refused",
 ]);
 
 type Bag = Record<string, unknown>;
@@ -47,19 +119,21 @@ 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): AuthErrorCode | undefined {
-  return typeof value === "string" && CODES.has(value) ? (value as AuthErrorCode) : 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): AuthErrorCode | undefined {
+function codeOfBody(body: unknown): KitErrorCode | undefined {
   if (!isBag(body)) return undefined;
   return known(body.code) ?? (isBag(body.detail) ? known(body.detail.code) : undefined);
 }
 
 /**
- * The {@link AuthErrorCode} an error carries, or `undefined` when it carries none.
+ * The code an error carries — an {@link AuthErrorCode}, since 0.30.0 an
+ * {@link AccountErrorCode}, since 0.31.0 a {@link DemoErrorCode} — or `undefined` when it
+ * carries none.
  *
  * Reads the parsed response body wherever the apps' HTTP clients put it, without
  * depending on any of them:
@@ -76,7 +150,7 @@ function codeOfBody(body: unknown): AuthErrorCode | undefined {
  * 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): AuthErrorCode | undefined {
+export function authErrorCode(err: unknown): KitErrorCode | undefined {
   if (!isBag(err)) return undefined;
   const response = err.response;
   return (
@@ -97,9 +171,123 @@ export function authErrorCode(err: unknown): AuthErrorCode | undefined {
  *
  * 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.
+ * {@link authErrorCode} for the shapes it reads. Since 0.30.0 it knows the account codes
+ * too: `isAuthError(err, "last_admin")`; since 0.31.0 the demo's:
+ * `isAuthError(err, "demo_read_only")`.
  */
-export function isAuthError(err: unknown, code?: AuthErrorCode): boolean {
+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`;
+}

package/src/auth/forgot-password-form.tsx

@@ -6,6 +6,7 @@ import { useKitLabels } from "../i18n/kit-labels";
 import { AlertBanner } from "../components/alert-banner";
 import { TextLink } from "../components/text-link";
 import { Button, Input } from "../components/ui";
+import { englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
 import { FORM_HEADING_CLASS, INTRO_CLASS, OutcomeMessage, isThenable, useFocusWhen } from "./status-parts";
 import type { AuthHeadingLevel } from "./status-parts";
 
@@ -30,9 +31,15 @@ export interface ForgotPasswordLabels {
   /** A request that did not go through: a throttle, an outage. Never "unknown
    *  address" — the endpoint does not say. */
   error: string;
+  /** 0.30.0: the request was throttled — HTTP 429 ({@link isRateLimited}) — given the
+   *  `Retry-After` wait in seconds, or `undefined` without one. OPTIONAL, like every key
+   *  added to a shipped interface; the provider's `forgotPassword`, then English, fill
+   *  it. */
+  rateLimited?: (seconds?: number) => string;
 }
 
-export const DEFAULT_FORGOT_PASSWORD_LABELS: ForgotPasswordLabels = {
+/** `Required`: every key, the 0.30 one included, has its English here. */
+export const DEFAULT_FORGOT_PASSWORD_LABELS: Required<ForgotPasswordLabels> = {
   title: "Forgot password",
   intro: "Enter your account’s email address. We’ll send you a link to choose a new password.",
   email: "Email",
@@ -41,6 +48,7 @@ export const DEFAULT_FORGOT_PASSWORD_LABELS: ForgotPasswordLabels = {
   sentHint: "The link is valid for one hour and works exactly once. Check your spam folder too.",
   backToSignIn: "Back to sign in",
   error: "The request failed. Please try again later.",
+  rateLimited: englishRateLimited,
 };
 
 /* ── The form ────────────────────────────────────────────────────────────── */
@@ -61,8 +69,9 @@ export interface ForgotPasswordFormProps
    *  whose password just failed need not type it twice. */
   defaultEmail?: string;
   /**
-   * The app's words for a failed request (a `429`: "Too many requests — try again in
-   * an hour"), or `undefined` for the kit's `error`. The same hook as `SignInForm`'s.
+   * The app's words for a failed request ("Too many requests — try again in an hour"),
+   * or `undefined` for the kit's: `rateLimited` for a bare `429` (0.30.0), else `error`.
+   * The same hook as `SignInForm`'s.
    */
   describeError?: (error: unknown) => ReactNode | undefined;
   /** App content under the intro — a notice, a support address. */
@@ -146,6 +155,13 @@ export function ForgotPasswordForm({
     );
   }
 
+  // The app's words first, then the throttle's, then the kit's catch-all.
+  const failureFor = (error: unknown): ReactNode =>
+    describeError?.(error) ??
+    (isRateLimited(error)
+      ? (labels.rateLimited ?? DEFAULT_FORGOT_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))
+      : labels.error);
+
   const submit = (e: FormEvent) => {
     e.preventDefault();
     const address = email.trim();
@@ -155,7 +171,7 @@ export function ForgotPasswordForm({
     try {
       result = onSubmit(address);
     } catch (error) {
-      setFailure(describeError?.(error) ?? labels.error);
+      setFailure(failureFor(error));
       return;
     }
     if (!isThenable(result)) {
@@ -170,7 +186,7 @@ export function ForgotPasswordForm({
       },
       (error: unknown) => {
         setPending(false);
-        setFailure(describeError?.(error) ?? labels.error);
+        setFailure(failureFor(error));
       },
     );
   };

package/src/auth/register-form.tsx

@@ -11,7 +11,7 @@ import { LanguageSelect } from "../components/language-select";
 import { LegalAcceptCheckbox } from "../components/legal-page";
 import { TextLink } from "../components/text-link";
 import { Button, Input } from "../components/ui";
-import { authErrorCode } from "./auth-errors";
+import { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
 import { emailParts, taggedEmail } from "./email-tag";
 import { newPasswordProblem, personNameOk, PERSON_NAME_MAX_LENGTH } from "./form-rules";
 import { NewPasswordFields } from "./new-password-fields";
@@ -71,9 +71,15 @@ export interface RegisterLabels {
   invitationExpired: string;
   /** Any other failure. */
   failed: string;
+  /** 0.30.0: the request was throttled — HTTP 429 ({@link isRateLimited}) — given the
+   *  `Retry-After` wait in seconds, or `undefined` without one. OPTIONAL, like every key
+   *  added to a shipped interface (an annotated call site must keep compiling); the
+   *  provider's `register`, then English, fill it. */
+  rateLimited?: (seconds?: number) => string;
 }
 
-export const DEFAULT_REGISTER_LABELS: RegisterLabels = {
+/** `Required`: every key, the 0.30 one included, has its English here. */
+export const DEFAULT_REGISTER_LABELS: Required<RegisterLabels> = {
   firstName: "First name",
   lastName: "Last name",
   email: "Email",
@@ -94,6 +100,7 @@ export const DEFAULT_REGISTER_LABELS: RegisterLabels = {
   invitationInvalid: "This invitation link is not valid.",
   invitationExpired: "This invitation has expired. Ask for a new one.",
   failed: "Registration failed. Please try again.",
+  rateLimited: englishRateLimited,
 };
 
 export interface RegisterFormProps extends Omit<ComponentPropsWithoutRef<"div">, "onSubmit" | "children"> {
@@ -119,6 +126,13 @@ export interface RegisterFormProps extends Omit<ComponentPropsWithoutRef<"div">,
    * it — the server accepts exactly that variant — and go back.
    */
   invitedEmail?: string;
+  /**
+   * 0.29.1: an address to start with that stays EDITABLE, with the `+tag` suggestion still
+   * offered — for a link anyone can build (keksdose's token-free `/register?email=…`
+   * beta link, kept while an app moves to invitations). Unlike `invitedEmail` it proves
+   * nothing, so it locks nothing. `invitedEmail` wins when both are given.
+   */
+  defaultEmail?: string;
   /**
    * The language field's value — controlled. Pass the app's UI language
    * (`i18n.resolvedLanguage`) with `onLocaleChange` switching it, and the field IS the
@@ -158,8 +172,9 @@ export interface RegisterFormProps extends Omit<ComponentPropsWithoutRef<"div">,
   privacyHref?: string;
   /** "Already have an account? Sign in" goes here — `/login`. Left out, no line. */
   signInHref?: string;
-  /** The app's own words for a failure the kit cannot know (a throttled attempt), or
-   *  `undefined` for the kit's. Asked first, for every failure. */
+  /** The app's own words for a failure the kit cannot know (the device offline, a
+   *  throttle with its wait), or `undefined` for the kit's. Asked first, for every
+   *  failure; a bare `429` needs none since 0.30.0 — the kit says `rateLimited`. */
   describeError?: (error: unknown) => ReactNode | undefined;
   labels?: Partial<RegisterLabels>;
 }
@@ -211,6 +226,7 @@ export function RegisterForm({
   onSubmit,
   emailTag,
   invitedEmail,
+  defaultEmail,
   locale: localeProp,
   defaultLocale,
   onLocaleChange,
@@ -234,7 +250,7 @@ export function RegisterForm({
   const invited = invitedEmail !== undefined;
   const [firstName, setFirstName] = useState("");
   const [lastName, setLastName] = useState("");
-  const [email, setEmail] = useState(invitedEmail ?? "");
+  const [email, setEmail] = useState(invitedEmail ?? defaultEmail ?? "");
   const [password, setPassword] = useState("");
   const [confirm, setConfirm] = useState("");
   const [ownLocale, setOwnLocale] = useState<string>(
@@ -312,7 +328,9 @@ export function RegisterForm({
         setFailure(
           hasMessage(own)
             ? own
-            : code === "registration_closed"
+            : isRateLimited(error)
+              ? (labels.rateLimited ?? DEFAULT_REGISTER_LABELS.rateLimited)(retryAfterSeconds(error))
+              : code === "registration_closed"
               ? labels.registrationClosed
               : code === "invitation_invalid"
                 ? labels.invitationInvalid

package/src/auth/reset-password-form.tsx

@@ -6,7 +6,7 @@ import { useKitLabels } from "../i18n/kit-labels";
 import { AlertBanner } from "../components/alert-banner";
 import { LoadingState } from "../components/loading-state";
 import { Button, EmptyState } from "../components/ui";
-import { authErrorCode } from "./auth-errors";
+import { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
 import { newPasswordProblem } from "./form-rules";
 import { NewPasswordFields } from "./new-password-fields";
 import {
@@ -53,9 +53,15 @@ export interface ResetPasswordLabels {
   sessionsEnded: string;
   /** The button out — to sign-in, with the address filled in. */
   signIn: string;
+  /** 0.30.0: the save was throttled — HTTP 429 ({@link isRateLimited}) — given the
+   *  `Retry-After` wait in seconds, or `undefined` without one. OPTIONAL, like every key
+   *  added to a shipped interface; the provider's `resetPassword`, then English, fill
+   *  it. */
+  rateLimited?: (seconds?: number) => string;
 }
 
-export const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordLabels = {
+/** `Required`: every key, the 0.30 one included, has its English here. */
+export const DEFAULT_RESET_PASSWORD_LABELS: Required<ResetPasswordLabels> = {
   title: "Choose a new password",
   checking: "Checking the link…",
   intro: (email) => `You’re setting a new password for ${email}.`,
@@ -71,6 +77,7 @@ export const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordLabels = {
   success: "Your password has been changed. You can sign in with it now.",
   sessionsEnded: "Signed-in devices were signed out — you’ll need to sign in again there.",
   signIn: "Go to sign in",
+  rateLimited: englishRateLimited,
 };
 
 /* ── Types ───────────────────────────────────────────────────────────────── */
@@ -135,8 +142,9 @@ export interface ResetPasswordFormProps
   /** "Request a new link" — the app's "Forgot password" page. Default
    *  `/forgot-password`. */
   forgotHref?: string;
-  /** The app's words for a failed save (a `429`, the device offline), or `undefined`
-   *  for the kit's `failed`. Not asked for `token_invalid`, which is a state. */
+  /** The app's words for a failed save (the device offline), or `undefined` for the
+   *  kit's: `rateLimited` for a bare `429` (0.30.0), else `failed`. Not asked for
+   *  `token_invalid`, which is a state. */
   describeError?: (error: unknown) => ReactNode | undefined;
   /** The heading. Default `labels.title`; `null` draws none, for a page that puts it
    *  in `AuthLayout`'s `title` instead. */
@@ -297,7 +305,13 @@ export function ResetPasswordForm({
             setPhase({ token, phase: { kind: "invalid" } });
             return;
           }
-          setFailure(describeError?.(error) ?? labels.failed);
+          // The app's words first, then the throttle's, then the kit's catch-all.
+          setFailure(
+            describeError?.(error) ??
+              (isRateLimited(error)
+                ? (labels.rateLimited ?? DEFAULT_RESET_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))
+                : labels.failed),
+          );
         },
       );
   };