@segmentstream-cloud/app 0.3.1 → 0.3.2

package/README.md

@@ -56,11 +56,12 @@ export const { GET, POST, PUT, DELETE, PATCH } = segmentstream.authHandlers();
 The route completes emailed sign-in links (`/api/auth/magic-link/verify`) itself: it
 verifies the token through Neon Auth without a callback, sets the session cookies on
 the app's domain and redirects to the link's `callbackURL` path. An expired, used or
-unknown link redirects to `/sign-in?error=sign_in_link_invalid`, where `<SignIn />`
-offers a new code.
+unknown link redirects to `/sign-in?error=sign_in_link_invalid`, where `<SignIn />` (or
+`useSignIn().linkInvalid`) offers a new code.
 
 **`src/app/sign-in/page.tsx`** renders the sign-in form, and the root layout imports
-its stylesheet once:
+its stylesheet once. Apps with their own design system render their own form on
+[`useSignIn()`](#your-own-sign-in-form) instead and skip the stylesheet:
 
 ```tsx
 import { SignIn } from "@segmentstream-cloud/app/ui";
@@ -127,6 +128,7 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 | Export                                 | Does                                                                               |
 | -------------------------------------- | ---------------------------------------------------------------------------------- |
 | `<SignIn />`                           | Email, then the six-digit code; resend after 30 seconds, errors and loading states |
+| `useSignIn()`                          | The same sign-in without markup, for the app's own form                            |
 | `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                   |
 | `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise          |
 | `<UserMenu />`                         | Name, email, roles and sign-out                                                    |
@@ -143,6 +145,85 @@ Server Component may wrap server-rendered children in `<Can>`:
 </Can>
 ```
 
+### Your own sign-in form
+
+`useSignIn({ returnTo, error })` holds everything `<SignIn />` does, without markup: the
+steps, the 30-second resend hold, the six-digit check, error sentences, the return to
+`returnTo` after sign-in and the `not_invited` and `sign_in_link_invalid` states. Both
+options default to the page's query parameters. The workspace starter renders it with
+Tailwind CSS and shadcn/ui in `src/components/sign-in-form.tsx`; `<SignIn />` stays for
+apps without Tailwind.
+
+```tsx
+"use client";
+
+import { useSignIn } from "@segmentstream-cloud/app/ui";
+
+export function SignInForm() {
+  const signIn = useSignIn();
+
+  if (signIn.step === "email") {
+    return (
+      <form
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault();
+          void signIn.submitEmail();
+        }}
+      >
+        <input
+          type="email"
+          value={signIn.email}
+          onChange={(event) => signIn.setEmail(event.target.value)}
+        />
+        {signIn.error !== null && <p role="alert">{signIn.error}</p>}
+        <button disabled={signIn.pending !== null}>Send code</button>
+      </form>
+    );
+  }
+
+  return (
+    <form
+      noValidate
+      onSubmit={(event) => {
+        event.preventDefault();
+        void signIn.submitCode();
+      }}
+    >
+      <input
+        inputMode="numeric"
+        autoComplete="one-time-code"
+        value={signIn.code}
+        onChange={(event) => signIn.setCode(event.target.value)}
+      />
+      {signIn.error !== null && <p role="alert">{signIn.error}</p>}
+      <button disabled={signIn.pending !== null}>Sign in</button>
+      <button type="button" onClick={() => void signIn.resend()} disabled={signIn.resendIn > 0}>
+        Resend code
+      </button>
+    </form>
+  );
+}
+```
+
+| Field                                  | Means                                                                                  |
+| -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `step`                                 | `email`, then `code` once a code is sent                                               |
+| `email`, `setEmail`, `code`, `setCode` | The field values; `submitEmail()` trims the address                                    |
+| `pending`                              | `send`, `verify`, `resend` or `sign-out` while a call runs; disable the form           |
+| `error`, `notice`                      | A sentence for the person, and a confirmation such as a resent code                    |
+| `resendIn`                             | Seconds until `resend()` may be offered; 0 when it may                                 |
+| `submitEmail()`, `submitCode(value?)`  | Send the code; verify `value` or `code`. A wrong code clears `code`; refocus the field |
+| `resend()`, `changeEmail()`            | Another code to the same address; back to the email step                               |
+| `signedIn`, `destination`              | A session already exists: offer a link to `destination`                                |
+| `notInvited`, `sessionEmail`           | The person is signed in as `sessionEmail` without an invitation                        |
+| `switchAccount()`                      | Signs out and returns to the email step                                                |
+| `linkInvalid`                          | An emailed sign-in link was expired or used: say so on the email step                  |
+
+The calls take values, not form events: call `submitEmail()` and `submitCode()` from the
+form's submit handler after `event.preventDefault()`. A second `submitCode()` while one
+runs is ignored, so the last digit and the Enter key may both submit.
+
 ## The ontology
 
 `segmentstream.ontology.<entity>` calls the app's ontology service at `/api/ontology`

package/dist/ui/index.d.ts

@@ -2,8 +2,10 @@ export { Can, SignedIn, SignedOut, UserMenu, signOut } from "./components.js";
 export type { CanProps, ChildrenProps, UserMenuProps } from "./components.js";
 export { usePermissions, useSession, useUser } from "./hooks.js";
 export type { Permissions } from "./hooks.js";
-export { SignIn, signInErrorMessage } from "./sign-in.js";
+export { SignIn } from "./sign-in.js";
 export type { SignInProps } from "./sign-in.js";
+export { signInErrorMessage, useSignIn } from "./use-sign-in.js";
+export type { SignInController, SignInOptions } from "./use-sign-in.js";
 export type { SessionState, SessionUser, UserState } from "./store.js";
 export { isAllowed } from "../permissions.js";
 export type { CurrentUser } from "../me.js";

package/dist/ui/index.js

@@ -1,8 +1,10 @@
 "use client";
 // Client components for apps that sign in with Neon Auth. Import the stylesheet once, in the root
-// layout: `import "@segmentstream-cloud/app/ui/styles.css";`.
+// layout, when rendering the components: `import "@segmentstream-cloud/app/ui/styles.css";`. The
+// hooks, `useSignIn()` among them, need no stylesheet.
 export { Can, SignedIn, SignedOut, UserMenu, signOut } from "./components.js";
 export { usePermissions, useSession, useUser } from "./hooks.js";
-export { SignIn, signInErrorMessage } from "./sign-in.js";
+export { SignIn } from "./sign-in.js";
+export { signInErrorMessage, useSignIn } from "./use-sign-in.js";
 export { isAllowed } from "../permissions.js";
 export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";

package/dist/ui/sign-in.d.ts

@@ -1,20 +1,10 @@
-export interface SignInProps {
-    /** Where to go once signed in. Defaults to the page's `returnTo` parameter, then `/`. */
-    readonly returnTo?: string;
-    /**
-     * Why the page was opened: `not_invited` when `requireUser()` found no invitation,
-     * `sign_in_link_invalid` when an emailed sign-in link was expired, used or unknown. Defaults to
-     * the page's `error` parameter.
-     */
-    readonly error?: string;
+import type { SignInOptions } from "./use-sign-in.js";
+export interface SignInProps extends SignInOptions {
     /** The heading. Defaults to "Sign in". */
     readonly title?: string;
 }
 /**
- * Email code sign-in with Neon Auth: the email address, then the six-digit code sent to it. New
- * addresses get an account on first sign-in; whether they may use the app is the ontology's
- * decision, which `requireUser()` reports as `not_invited`.
+ * Email code sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
+ * with their own design system render `useSignIn()` themselves.
  */
-export declare function SignIn({ returnTo, error: reason, title }: SignInProps): import("react").JSX.Element;
-/** A sentence for a Neon Auth (Better Auth) failure. */
-export declare function signInErrorMessage(error: unknown): string;
+export declare function SignIn({ title, ...options }: SignInProps): import("react").JSX.Element;

package/dist/ui/sign-in.js

@@ -1,158 +1,42 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
-import { SIGN_IN_LINK_INVALID } from "../errors.js";
-import { safeReturnTo } from "../return-to.js";
-import { useSession } from "./hooks.js";
-import { navigate } from "./navigation.js";
-import { NOT_INVITED, authClient, clearSession, refreshSession } from "./store.js";
-/** Seconds before another code may be requested. */
-const RESEND_AFTER_SECONDS = 30;
-const CODE_LENGTH = 6;
-const noSubscription = () => () => { };
-/** The page's own query string; empty during server rendering. */
-function useSearchParameter(name) {
-    const search = useSyncExternalStore(noSubscription, () => window.location.search, () => "");
-    return new URLSearchParams(search).get(name);
-}
+import { useEffect, useId, useRef } from "react";
+import { useSignIn } from "./use-sign-in.js";
 /**
- * Email code sign-in with Neon Auth: the email address, then the six-digit code sent to it. New
- * addresses get an account on first sign-in; whether they may use the app is the ontology's
- * decision, which `requireUser()` reports as `not_invited`.
+ * Email code sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
+ * with their own design system render `useSignIn()` themselves.
  */
-export function SignIn({ returnTo, error: reason, title = "Sign in" }) {
+export function SignIn({ title = "Sign in", ...options }) {
     const ids = useId();
-    const session = useSession();
-    const pageReturnTo = useSearchParameter("returnTo");
-    const pageError = useSearchParameter("error");
-    const [step, setStep] = useState("email");
-    const [email, setEmail] = useState("");
-    const [code, setCode] = useState("");
-    const [pending, setPending] = useState(null);
-    const [error, setError] = useState(null);
-    const [notice, setNotice] = useState(null);
-    /** Seconds until another code may be requested. */
-    const [resendIn, setResendIn] = useState(0);
-    const [switchingAccount, setSwitchingAccount] = useState(false);
+    const { step, email, setEmail, code, setCode, pending, error, notice, resendIn, codeLength, destination, signedIn, notInvited, linkInvalid, sessionEmail, submitEmail, submitCode, resend, changeEmail, switchAccount, } = useSignIn(options);
     const codeInput = useRef(null);
-    const verifying = useRef(false);
-    const resendTimer = useRef(undefined);
-    const destination = safeReturnTo(returnTo ?? pageReturnTo);
-    const notInvited = (reason ?? pageError) === NOT_INVITED && !switchingAccount;
-    const linkInvalid = (reason ?? pageError) === SIGN_IN_LINK_INVALID;
-    useEffect(() => () => clearInterval(resendTimer.current), []);
+    // The code field takes focus when it appears and again after a wrong code.
     useEffect(() => {
-        if (step === "code") {
+        if (step === "code" && pending === null) {
             codeInput.current?.focus();
         }
-    }, [step]);
-    function holdResend() {
-        const deadline = Date.now() + RESEND_AFTER_SECONDS * 1000;
-        clearInterval(resendTimer.current);
-        setResendIn(RESEND_AFTER_SECONDS);
-        resendTimer.current = setInterval(() => {
-            const remaining = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
-            setResendIn(remaining);
-            if (remaining === 0) {
-                clearInterval(resendTimer.current);
-            }
-        }, 1000);
-    }
-    async function sendCode(address) {
-        const result = await attempt(() => authClient().emailOtp.sendVerificationOtp({ email: address, type: "sign-in" }));
-        if (result !== null) {
-            setError(signInErrorMessage(result));
-            return false;
-        }
-        holdResend();
-        return true;
-    }
-    async function submitEmail(event) {
-        event.preventDefault();
-        const address = email.trim();
-        if (address === "") {
-            setError("Enter your email address.");
-            return;
-        }
-        setPending("send");
-        setError(null);
-        setNotice(null);
-        if (await sendCode(address)) {
-            setEmail(address);
-            setCode("");
-            setStep("code");
-        }
-        setPending(null);
-    }
-    async function verify(value) {
-        // The sixth digit and the Enter key may both submit the same code.
-        if (verifying.current) {
-            return;
-        }
-        if (!new RegExp(`^[0-9]{${CODE_LENGTH}}$`).test(value)) {
-            setError(`Enter the ${CODE_LENGTH}-digit code from the email.`);
-            return;
-        }
-        verifying.current = true;
-        setPending("verify");
-        setError(null);
-        setNotice(null);
-        const result = await attempt(() => authClient().signIn.emailOtp({ email, otp: value }));
-        if (result !== null) {
-            verifying.current = false;
-            setError(signInErrorMessage(result));
-            setCode("");
-            setPending(null);
-            codeInput.current?.focus();
-            return;
-        }
-        navigate(destination);
-    }
-    async function resend() {
-        setPending("resend");
-        setError(null);
-        setNotice(null);
-        if (await sendCode(email)) {
-            setCode("");
-            setNotice(`We sent a new code to ${email}.`);
-        }
-        setPending(null);
-    }
-    function changeEmail() {
-        setStep("email");
-        setCode("");
-        setError(null);
-        setNotice(null);
-    }
-    async function switchAccount() {
-        setPending("sign-out");
-        setError(null);
-        await attempt(() => authClient().signOut());
-        clearSession();
-        await refreshSession();
-        setSwitchingAccount(true);
-        setStep("email");
-        setPending(null);
-    }
+    }, [step, pending]);
     const errorId = `${ids}-error`;
-    const sessionEmail = session.status === "signed-in" ? (session.user.email ?? session.user.name) : null;
     if (notInvited) {
         return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "Ask for an invitation" }), _jsxs("p", { className: "ss-text", children: [sessionEmail === null ? "You are signed in" : `You are signed in as ${sessionEmail}`, ", but this app has not invited you. Ask your administrator for an invitation, or sign in with another email address."] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), _jsx("button", { type: "button", className: "ss-button", onClick: () => void switchAccount(), disabled: pending !== null, "aria-busy": pending === "sign-out", children: pending === "sign-out" ? "Signing out…" : "Use another email" })] }));
     }
-    if (session.status === "signed-in" && step === "email" && pending === null && !switchingAccount) {
+    if (signedIn && step === "email" && pending === null) {
         return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "You are signed in" }), _jsx("p", { className: "ss-text", children: sessionEmail === null ? "You already have a session." : `Signed in as ${sessionEmail}.` }), _jsxs("div", { className: "ss-actions", children: [_jsx("a", { className: "ss-button", href: destination, children: "Continue" }), _jsx("button", { type: "button", className: "ss-button ss-button--secondary", onClick: () => void switchAccount(), children: "Use another email" })] })] }));
     }
     if (step === "email") {
-        return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: title }), _jsxs("p", { className: "ss-text", children: ["We will email you a ", CODE_LENGTH, "-digit code to sign in."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => void submitEmail(event), noValidate: true, children: [linkInvalid && (_jsx("p", { className: "ss-notice", role: "status", children: "This sign-in link is not valid anymore. Enter your email to get a new code." })), _jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-email`, children: "Email" }), _jsx("input", { id: `${ids}-email`, className: "ss-input", type: "email", name: "email", autoComplete: "email", inputMode: "email", required: true, value: email, onChange: (event) => setEmail(event.target.value), disabled: pending !== null, "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "send", children: pending === "send" ? "Sending code…" : "Send code" })] })] }));
+        return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: title }), _jsxs("p", { className: "ss-text", children: ["We will email you a ", codeLength, "-digit code to sign in."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
+                        event.preventDefault();
+                        void submitEmail();
+                    }, noValidate: true, children: [linkInvalid && (_jsx("p", { className: "ss-notice", role: "status", children: "This sign-in link is not valid anymore. Enter your email to get a new code." })), _jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-email`, children: "Email" }), _jsx("input", { id: `${ids}-email`, className: "ss-input", type: "email", name: "email", autoComplete: "email", inputMode: "email", required: true, value: email, onChange: (event) => setEmail(event.target.value), disabled: pending !== null, "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "send", children: pending === "send" ? "Sending code…" : "Send code" })] })] }));
     }
-    return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "Check your email" }), _jsxs("p", { className: "ss-text", children: ["Enter the ", CODE_LENGTH, "-digit code we sent to ", _jsx("strong", { children: email }), "."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
+    return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "Check your email" }), _jsxs("p", { className: "ss-text", children: ["Enter the ", codeLength, "-digit code we sent to ", _jsx("strong", { children: email }), "."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
                     event.preventDefault();
-                    void verify(code);
-                }, noValidate: true, children: [_jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-code`, children: "Code" }), _jsx("input", { ref: codeInput, id: `${ids}-code`, className: "ss-input ss-input--code", type: "text", name: "code", inputMode: "numeric", autoComplete: "one-time-code", pattern: "[0-9]*", maxLength: CODE_LENGTH, required: true, value: code, onChange: (event) => {
-                                    const digits = event.target.value.replace(/\D/g, "").slice(0, CODE_LENGTH);
+                    void submitCode();
+                }, noValidate: true, children: [_jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-code`, children: "Code" }), _jsx("input", { ref: codeInput, id: `${ids}-code`, className: "ss-input ss-input--code", type: "text", name: "code", inputMode: "numeric", autoComplete: "one-time-code", pattern: "[0-9]*", maxLength: codeLength, required: true, value: code, onChange: (event) => {
+                                    const digits = event.target.value.replace(/\D/g, "").slice(0, codeLength);
                                     setCode(digits);
-                                    if (digits.length === CODE_LENGTH) {
-                                        void verify(digits);
+                                    if (digits.length === codeLength) {
+                                        void submitCode(digits);
                                     }
                                 }, disabled: pending === "verify", "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), notice !== null && (_jsx("p", { className: "ss-notice", role: "status", children: notice })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "verify", children: pending === "verify" ? "Signing in…" : "Sign in" })] }), _jsxs("div", { className: "ss-actions", children: [_jsx("button", { type: "button", className: "ss-link", onClick: () => void resend(), disabled: pending !== null || resendIn > 0, "aria-busy": pending === "resend", children: pending === "resend"
                             ? "Sending…"
@@ -160,41 +44,3 @@ export function SignIn({ returnTo, error: reason, title = "Sign in" }) {
                                 ? `Resend code in ${resendIn} s`
                                 : "Resend code" }), _jsx("button", { type: "button", className: "ss-link", onClick: changeEmail, disabled: pending !== null, children: "Use another email" })] })] }));
 }
-/** Runs a Neon Auth client call; its failure, returned or thrown, or `null` on success. */
-async function attempt(call) {
-    try {
-        const result = await call();
-        return result.error ?? null;
-    }
-    catch (error) {
-        return error ?? new Error("Sign-in failed.");
-    }
-}
-/** A sentence for a Neon Auth (Better Auth) failure. */
-export function signInErrorMessage(error) {
-    const details = typeof error === "object" && error !== null ? error : {};
-    const status = typeof details.status === "number" ? details.status : undefined;
-    const text = [details.code, details.message]
-        .filter((part) => typeof part === "string")
-        .join(" ")
-        .toLowerCase();
-    if (status === 429 || text.includes("rate limit") || text.includes("too many requests")) {
-        return "Too many requests. Wait a minute, then try again.";
-    }
-    if (text.includes("too many attempts") || text.includes("too_many_attempts")) {
-        return "Too many wrong codes. Send a new code.";
-    }
-    if (text.includes("expired")) {
-        return "That code has expired. Send a new one.";
-    }
-    if (text.includes("otp") || text.includes("code")) {
-        return "That code is not right. Check the email and try again.";
-    }
-    if (text.includes("email")) {
-        return "Enter a valid email address.";
-    }
-    if (status === undefined || status >= 500 || text.includes("network")) {
-        return "Sign-in is unavailable right now. Try again in a moment.";
-    }
-    return "Sign-in failed. Try again.";
-}

package/dist/ui/use-sign-in.d.ts

@@ -0,0 +1,63 @@
+export interface SignInOptions {
+    /** Where to go once signed in. Defaults to the page's `returnTo` parameter, then `/`. */
+    readonly returnTo?: string;
+    /**
+     * Why the page was opened: `not_invited` when `requireUser()` found no invitation,
+     * `sign_in_link_invalid` when an emailed sign-in link was expired, used or unknown. Defaults to
+     * the page's `error` parameter.
+     */
+    readonly error?: string;
+}
+/** Email code sign-in for a form the app renders itself. The calls take values, not form events. */
+export interface SignInController {
+    readonly step: "email" | "code";
+    readonly email: string;
+    readonly setEmail: (value: string) => void;
+    readonly code: string;
+    readonly setCode: (value: string) => void;
+    /** The call in flight; disable the form while it is not `null`. */
+    readonly pending: "send" | "verify" | "resend" | "sign-out" | null;
+    /** A sentence for the person, from the last failed call. */
+    readonly error: string | null;
+    /** A confirmation, such as a new code having been sent. */
+    readonly notice: string | null;
+    /** Seconds until another code may be requested; 0 when it may. */
+    readonly resendIn: number;
+    /** Digits in a code: 6. */
+    readonly codeLength: number;
+    /** The same-origin path the person returns to after signing in. */
+    readonly destination: string;
+    /**
+     * A session exists in this browser and the person has not chosen another account: offer to
+     * continue to `destination` instead of the email step.
+     */
+    readonly signedIn: boolean;
+    /** The page was opened for a signed-in person the app has not invited. */
+    readonly notInvited: boolean;
+    /** The emailed sign-in link was expired, used or unknown: say so on the email step. */
+    readonly linkInvalid: boolean;
+    /** The signed-in address or name, for the not-invited state; null when signed out. */
+    readonly sessionEmail: string | null;
+    /** Sends a code to `email` and moves to the code step. Call it from the form's submit handler. */
+    readonly submitEmail: () => Promise<void>;
+    /**
+     * Verifies `value`, or the current `code`, and opens `destination`. A wrong code clears `code`;
+     * a second call while one is verifying is ignored, so the last digit and Enter may both submit.
+     */
+    readonly submitCode: (value?: string) => Promise<void>;
+    /** Sends another code to the same address. */
+    readonly resend: () => Promise<void>;
+    /** Returns to the email step. */
+    readonly changeEmail: () => void;
+    /** Signs the current session out and returns to the email step. */
+    readonly switchAccount: () => Promise<void>;
+}
+/**
+ * Email code sign-in with Neon Auth, without markup: the email address, then the six-digit code
+ * sent to it. New addresses get an account on first sign-in; whether they may use the app is the
+ * ontology's decision, which `requireUser()` reports as `not_invited`. `<SignIn />` renders it with
+ * the SDK's own styles; apps with their own design system render the controller themselves.
+ */
+export declare function useSignIn({ returnTo, error: reason }?: SignInOptions): SignInController;
+/** A sentence for a Neon Auth (Better Auth) failure. */
+export declare function signInErrorMessage(error: unknown): string;

package/dist/ui/use-sign-in.js

@@ -0,0 +1,186 @@
+"use client";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";
+import { safeReturnTo } from "../return-to.js";
+import { useSession } from "./hooks.js";
+import { navigate } from "./navigation.js";
+import { authClient, clearSession, refreshSession } from "./store.js";
+/** Seconds before another code may be requested. */
+const RESEND_AFTER_SECONDS = 30;
+const CODE_LENGTH = 6;
+const noSubscription = () => () => { };
+/** The page's own query string; empty during server rendering. */
+function useSearchParameter(name) {
+    const search = useSyncExternalStore(noSubscription, () => window.location.search, () => "");
+    return new URLSearchParams(search).get(name);
+}
+/**
+ * Email code sign-in with Neon Auth, without markup: the email address, then the six-digit code
+ * sent to it. New addresses get an account on first sign-in; whether they may use the app is the
+ * ontology's decision, which `requireUser()` reports as `not_invited`. `<SignIn />` renders it with
+ * the SDK's own styles; apps with their own design system render the controller themselves.
+ */
+export function useSignIn({ returnTo, error: reason } = {}) {
+    const session = useSession();
+    const pageReturnTo = useSearchParameter("returnTo");
+    const pageError = useSearchParameter("error");
+    const [step, setStep] = useState("email");
+    const [email, setEmail] = useState("");
+    const [code, setCode] = useState("");
+    const [pending, setPending] = useState(null);
+    const [error, setError] = useState(null);
+    const [notice, setNotice] = useState(null);
+    const [resendIn, setResendIn] = useState(0);
+    const [switchingAccount, setSwitchingAccount] = useState(false);
+    const verifying = useRef(false);
+    const resendTimer = useRef(undefined);
+    const destination = safeReturnTo(returnTo ?? pageReturnTo);
+    const why = reason ?? pageError;
+    useEffect(() => () => clearInterval(resendTimer.current), []);
+    function holdResend() {
+        const deadline = Date.now() + RESEND_AFTER_SECONDS * 1000;
+        clearInterval(resendTimer.current);
+        setResendIn(RESEND_AFTER_SECONDS);
+        resendTimer.current = setInterval(() => {
+            const remaining = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
+            setResendIn(remaining);
+            if (remaining === 0) {
+                clearInterval(resendTimer.current);
+            }
+        }, 1000);
+    }
+    async function sendCode(address) {
+        const result = await attempt(() => authClient().emailOtp.sendVerificationOtp({ email: address, type: "sign-in" }));
+        if (result !== null) {
+            setError(signInErrorMessage(result));
+            return false;
+        }
+        holdResend();
+        return true;
+    }
+    async function submitEmail() {
+        const address = email.trim();
+        if (address === "") {
+            setError("Enter your email address.");
+            return;
+        }
+        setPending("send");
+        setError(null);
+        setNotice(null);
+        if (await sendCode(address)) {
+            setEmail(address);
+            setCode("");
+            setStep("code");
+        }
+        setPending(null);
+    }
+    async function submitCode(value = code) {
+        // The last digit and the Enter key may both submit the same code.
+        if (verifying.current) {
+            return;
+        }
+        if (!new RegExp(`^[0-9]{${CODE_LENGTH}}$`).test(value)) {
+            setError(`Enter the ${CODE_LENGTH}-digit code from the email.`);
+            return;
+        }
+        verifying.current = true;
+        setPending("verify");
+        setError(null);
+        setNotice(null);
+        const result = await attempt(() => authClient().signIn.emailOtp({ email, otp: value }));
+        if (result !== null) {
+            verifying.current = false;
+            setError(signInErrorMessage(result));
+            setCode("");
+            setPending(null);
+            return;
+        }
+        navigate(destination);
+    }
+    async function resend() {
+        setPending("resend");
+        setError(null);
+        setNotice(null);
+        if (await sendCode(email)) {
+            setCode("");
+            setNotice(`We sent a new code to ${email}.`);
+        }
+        setPending(null);
+    }
+    function changeEmail() {
+        setStep("email");
+        setCode("");
+        setError(null);
+        setNotice(null);
+    }
+    async function switchAccount() {
+        setPending("sign-out");
+        setError(null);
+        await attempt(() => authClient().signOut());
+        clearSession();
+        await refreshSession();
+        setSwitchingAccount(true);
+        setStep("email");
+        setPending(null);
+    }
+    return {
+        step,
+        email,
+        setEmail,
+        code,
+        setCode,
+        pending,
+        error,
+        notice,
+        resendIn,
+        codeLength: CODE_LENGTH,
+        destination,
+        signedIn: session.status === "signed-in" && !switchingAccount,
+        notInvited: why === NOT_INVITED && !switchingAccount,
+        linkInvalid: why === SIGN_IN_LINK_INVALID,
+        sessionEmail: session.status === "signed-in" ? (session.user.email ?? session.user.name) : null,
+        submitEmail,
+        submitCode,
+        resend,
+        changeEmail,
+        switchAccount,
+    };
+}
+/** Runs a Neon Auth client call; its failure, returned or thrown, or `null` on success. */
+async function attempt(call) {
+    try {
+        const result = await call();
+        return result.error ?? null;
+    }
+    catch (error) {
+        return error ?? new Error("Sign-in failed.");
+    }
+}
+/** A sentence for a Neon Auth (Better Auth) failure. */
+export function signInErrorMessage(error) {
+    const details = typeof error === "object" && error !== null ? error : {};
+    const status = typeof details.status === "number" ? details.status : undefined;
+    const text = [details.code, details.message]
+        .filter((part) => typeof part === "string")
+        .join(" ")
+        .toLowerCase();
+    if (status === 429 || text.includes("rate limit") || text.includes("too many requests")) {
+        return "Too many requests. Wait a minute, then try again.";
+    }
+    if (text.includes("too many attempts") || text.includes("too_many_attempts")) {
+        return "Too many wrong codes. Send a new code.";
+    }
+    if (text.includes("expired")) {
+        return "That code has expired. Send a new one.";
+    }
+    if (text.includes("otp") || text.includes("code")) {
+        return "That code is not right. Check the email and try again.";
+    }
+    if (text.includes("email")) {
+        return "Enter a valid email address.";
+    }
+    if (status === undefined || status >= 500 || text.includes("network")) {
+        return "Sign-in is unavailable right now. Try again in a moment.";
+    }
+    return "Sign-in failed. Try again.";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",