@segmentstream-cloud/app 0.3.0 → 0.3.2

package/README.md

@@ -53,8 +53,15 @@ import { segmentstream } from "@/segmentstream";
 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 />` (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";
@@ -121,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                                                    |
@@ -137,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/errors.d.ts

@@ -31,6 +31,8 @@ export declare class SegmentStreamApiError extends Error {
 }
 /** The person signed in, but the ontology has no member row for them. */
 export declare const NOT_INVITED = "not_invited";
+/** An emailed sign-in link that Neon Auth rejected: expired, already used or unknown. */
+export declare const SIGN_IN_LINK_INVALID = "sign_in_link_invalid";
 /** The error body of a failed response: `{ error, detail, requestId, issues? }`. */
 export declare function apiErrorFrom(status: number, payload: unknown, fallbackDetail: string): SegmentStreamApiError;
 export declare function readJson(response: Response): Promise<unknown>;

package/dist/errors.js

@@ -26,6 +26,8 @@ export class SegmentStreamApiError extends Error {
 }
 /** The person signed in, but the ontology has no member row for them. */
 export const NOT_INVITED = "not_invited";
+/** An emailed sign-in link that Neon Auth rejected: expired, already used or unknown. */
+export const SIGN_IN_LINK_INVALID = "sign_in_link_invalid";
 /** The error body of a failed response: `{ error, detail, requestId, issues? }`. */
 export function apiErrorFrom(status, payload, fallbackDetail) {
     const body = typeof payload === "object" && payload !== null ? payload : {};

package/dist/index.d.ts

@@ -15,7 +15,7 @@ import type { SegmentStreamAppConfig } from "./config.js";
  * from the ontology. Without it, members sign in with their SegmentStream account, as in 0.2.
  */
 export declare function createSegmentStreamApp<O = unknown>(config: SegmentStreamAppConfig): SegmentStreamApp<O>;
-export { NOT_INVITED, SegmentStreamApiError } from "./errors.js";
+export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
 export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";

package/dist/index.js

@@ -16,6 +16,6 @@ import { createApp } from "./app.js";
 export function createSegmentStreamApp(config) {
     return createApp(config);
 }
-export { NOT_INVITED, SegmentStreamApiError } from "./errors.js";
+export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";

package/dist/neon.js

@@ -4,7 +4,7 @@ import { cookies } from "next/headers";
 import { redirect } from "next/navigation";
 import { NextResponse } from "next/server";
 import { replaceRequestCookies, safeReturnTo } from "./cookies.js";
-import { NOT_INVITED, SegmentStreamApiError, apiErrorFrom, readJson } from "./errors.js";
+import { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError, apiErrorFrom, readJson, } from "./errors.js";
 import { parseMe } from "./me.js";
 import { createOntologyTransport } from "./ontology-transport.js";
 import { isAllowed } from "./permissions.js";
@@ -28,6 +28,12 @@ export const OPEN_PATHS = [
     "/sitemap.xml",
     "/manifest.webmanifest",
 ];
+/**
+ * Better Auth answers a magic link that names a callback with a redirect to that path on Neon
+ * Auth's own origin; Neon's proxy follows it and loses the session cookie. Without them it answers
+ * JSON with the cookies, and the app's auth route redirects itself.
+ */
+const MAGIC_LINK_CALLBACK_PARAMETERS = ["callbackURL", "errorCallbackURL", "newUserCallbackURL"];
 /** How long a user's roles and permissions are reused before `/api/ontology/me` is asked again. */
 const USER_TTL_MS = 60_000;
 /** Neon Auth JWTs live 15 minutes; a cached one is replaced a minute before it expires. */
@@ -281,7 +287,12 @@ export function createNeonSession(dependencies) {
     function authHandlers() {
         const handlers = () => (routeHandlers ??= neonAuth().handler());
         return {
-            GET: (request, context) => handlers().GET(request, context),
+            GET: async (request, context) => {
+                const { path } = await context.params;
+                return path.length === 2 && path[0] === "magic-link" && path[1] === "verify"
+                    ? completeMagicLink(request, context, () => handlers().GET)
+                    : handlers().GET(request, context);
+            },
             POST: (request, context) => handlers().POST(request, context),
             PUT: (request, context) => handlers().PUT(request, context),
             DELETE: (request, context) => handlers().DELETE(request, context),
@@ -375,6 +386,52 @@ function forwardSessionCookies(request, response) {
     }
     return forwarded;
 }
+/**
+ * Signs in with an emailed magic link on the app's own domain: Neon Auth verifies the token
+ * without a callback and sets the session cookies, which go to the browser with a redirect to the
+ * link's `callbackURL` path. A link Neon Auth rejects leads to the sign-in page instead.
+ */
+async function completeMagicLink(request, context, verify) {
+    const url = new URL(request.url);
+    const destination = safeReturnTo(url.searchParams.get("callbackURL"));
+    const token = url.searchParams.get("token");
+    if (token === null || token === "") {
+        return invalidSignInLink(url.origin, destination);
+    }
+    for (const name of MAGIC_LINK_CALLBACK_PARAMETERS) {
+        url.searchParams.delete(name);
+    }
+    const handler = verify();
+    let response;
+    try {
+        response = await handler(new Request(url, request), context);
+    }
+    catch {
+        return invalidSignInLink(url.origin, destination);
+    }
+    // The body holds the session token; only the cookies go on to the browser.
+    void response.body?.cancel().catch(() => undefined);
+    if (!response.ok) {
+        return invalidSignInLink(url.origin, destination);
+    }
+    const redirect = NextResponse.redirect(new URL(destination, url.origin), 303);
+    for (const cookie of response.headers.getSetCookie()) {
+        redirect.headers.append("set-cookie", cookie);
+    }
+    redirect.headers.set("cache-control", "no-store");
+    return redirect;
+}
+/** An expired, used or unknown sign-in link: the sign-in page explains it and sends a code. */
+function invalidSignInLink(origin, destination) {
+    const url = new URL(SIGN_IN_PAGE, origin);
+    url.searchParams.set("error", SIGN_IN_LINK_INVALID);
+    if (destination !== "/") {
+        url.searchParams.set("returnTo", destination);
+    }
+    const response = NextResponse.redirect(url, 303);
+    response.headers.set("cache-control", "no-store");
+    return response;
+}
 /** Page navigations go to the sign-in page and come back to where they started. */
 function signInPageRedirect(request) {
     const url = new URL(SIGN_IN_PAGE, request.nextUrl.origin);

package/dist/ui/index.d.ts

@@ -2,9 +2,11 @@ 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";
-export { SegmentStreamApiError, NOT_INVITED } from "../errors.js";
+export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.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 } from "../errors.js";
+export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";

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

@@ -1,19 +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. 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,156 +1,42 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
-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;
-    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: [_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…"
@@ -158,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.0",
+  "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",