@segmentstream-cloud/app 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,8 @@
 
 Sign-in, users, permissions, the ontology client and warehouse data access for
 SegmentStream workspace apps built with Next.js (App Router, version 16 or later) and
-React 19. The app's users sign in with an email code through Neon Auth (Managed
+React 19. The app's users sign in with an email code, or a sign-in link the first time,
+through Neon Auth (Managed
 Better Auth) on the workspace's Neon project; the workspace's ontology decides who may
 use the app and what they may do. The SDK wraps `@neondatabase/auth`, so the app never
 configures Neon Auth itself.
@@ -56,11 +57,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 one.
 
 **`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";
@@ -124,15 +126,16 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 (no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
 `:root` set colours, radius and font.
 
-| Export                                 | Does                                                                               |
-| -------------------------------------- | ---------------------------------------------------------------------------------- |
-| `<SignIn />`                           | Email, then the six-digit code; resend after 30 seconds, errors and loading states |
-| `<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                                                    |
-| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session         |
-| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                               |
-| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                    |
+| Export                                 | Does                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `<SignIn />`                           | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
+| `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                                                 |
+| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
+| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
+| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                 |
 
 `<Can>` only hides controls: the ontology service checks every read and action. A
 Server Component may wrap server-rendered children in `<Can>`:
@@ -143,6 +146,105 @@ 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
+sign-in check, the steps, the 30-second resend hold, the six-digit check, error sentences
+and their codes, 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.
+
+`submitEmail()` first asks the ontology's `POST /api/ontology/sign-in/check` whether the
+address may sign in. A member who has signed in with Neon Auth before gets a six-digit
+code (`step: "code"`). A first sign-in gets a sign-in link instead (`step: "link"`),
+because Neon Auth sends codes only to existing accounts and the link creates the
+account. An address the ontology refuses gets `errorCode: "not_invited"`, and nothing
+is sent. Without an ontology that answers the check (none, or one deployed with
+`@segmentstream-cloud/ontology` before 0.4), every address gets a code. 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}>Continue</button>
+      </form>
+    );
+  }
+
+  if (signIn.step === "link") {
+    return (
+      <p>
+        We sent a sign-in link to {signIn.email}. Open it to sign in.
+        <button type="button" onClick={() => void signIn.resend()} disabled={signIn.resendIn > 0}>
+          Resend link
+        </button>
+      </p>
+    );
+  }
+
+  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, or `link` once a sign-in link 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                   |
+| `errorCode`, `noticeCode`              | Why the call failed (`not_invited`, `code_invalid`, …) and what was resent, to reword |
+| `resendIn`                             | Seconds until `resend()` may be offered; 0 when it may                                |
+| `submitEmail()`, `submitCode(value?)`  | Check, then send a code or link; verify `value` or `code`. A wrong code clears `code` |
+| `resend()`, `changeEmail()`            | Another code, or link, 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`
@@ -297,6 +399,14 @@ Add the auth route, the sign-in page and the stylesheet import; keep the legacy
 `AppUser` gained `roles` and `permissions`. Under Neon Auth, people sign in again with
 an email code, and the ontology must have invited them.
 
+## Upgrading to 0.4
+
+`useSignIn().step` may now be `link`: render it, or a form written for 0.3 shows the code
+step after a link was sent. The `<SignIn />` button reads "Continue". Deploy the
+ontology with `@segmentstream-cloud/ontology` 0.4 or later to answer the sign-in check;
+until then every address gets a code, as in 0.3. `errorCode` and `noticeCode` let an
+app word messages in its own language without matching the English sentences.
+
 ## License
 
 Apache-2.0

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 { SIGN_IN_ERROR_MESSAGES, signInErrorCode, signInErrorMessage, useSignIn, } from "./use-sign-in.js";
+export type { SignInController, SignInErrorCode, SignInNoticeCode, 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 { SIGN_IN_ERROR_MESSAGES, signInErrorCode, 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-check.d.ts

@@ -0,0 +1,14 @@
+/** The ontology's sign-in check, which the deployment serves beside the app. */
+export declare const SIGN_IN_CHECK_PATH = "/api/ontology/sign-in/check";
+/**
+ * How an address signs in, or why it may not: `code` for a member with a Neon Auth account, `link`
+ * for a first sign-in, which the link's account creation needs; `not_invited`, `email_invalid` or
+ * `rate_limited` when the ontology refuses before any email is sent.
+ */
+export type SignInCheckOutcome = "code" | "link" | "not_invited" | "email_invalid" | "rate_limited";
+/**
+ * Asks the ontology how this address signs in, before any email is sent. An app without an
+ * ontology, an ontology deployed with an SDK before 0.4, an answer the SDK cannot read and a failed
+ * request all get `code`: the sign-in works as it did before the check existed.
+ */
+export declare function checkSignIn(email: string): Promise<SignInCheckOutcome>;

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

@@ -0,0 +1,41 @@
+import { readJson } from "../errors.js";
+/** The ontology's sign-in check, which the deployment serves beside the app. */
+export const SIGN_IN_CHECK_PATH = "/api/ontology/sign-in/check";
+/**
+ * Asks the ontology how this address signs in, before any email is sent. An app without an
+ * ontology, an ontology deployed with an SDK before 0.4, an answer the SDK cannot read and a failed
+ * request all get `code`: the sign-in works as it did before the check existed.
+ */
+export async function checkSignIn(email) {
+    let response;
+    try {
+        response = await fetch(SIGN_IN_CHECK_PATH, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ email }),
+            credentials: "same-origin",
+            cache: "no-store",
+        });
+    }
+    catch {
+        return "code";
+    }
+    if (response.status === 429) {
+        return "rate_limited";
+    }
+    if (response.status === 400) {
+        return "email_invalid";
+    }
+    if (!response.ok) {
+        return "code";
+    }
+    const body = await readJson(response);
+    if (typeof body !== "object" || body === null) {
+        return "code";
+    }
+    const { allowed, method } = body;
+    if (allowed === false) {
+        return "not_invited";
+    }
+    return allowed === true && method === "link" ? "link" : "code";
+}

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 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,200 +1,47 @@
 "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 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") {
-            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);
+        if (step === "code" && pending === 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 }), _jsx("p", { className: "ss-text", children: "We will email you a code or a link 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…" : "Continue" })] })] }));
     }
-    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) => {
+    const resendButton = (label) => (_jsx("button", { type: "button", className: "ss-link", onClick: () => void resend(), disabled: pending !== null || resendIn > 0, "aria-busy": pending === "resend", children: pending === "resend" ? "Sending…" : resendIn > 0 ? `${label} in ${resendIn} s` : label }));
+    const anotherEmail = (_jsx("button", { type: "button", className: "ss-link", onClick: changeEmail, disabled: pending !== null, children: "Use another email" }));
+    if (step === "link") {
+        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: ["We sent a sign-in link to ", _jsx("strong", { children: email }), ". Open it on this device to sign in."] }), error !== null && (_jsx("p", { className: "ss-error", role: "alert", children: error })), notice !== null && (_jsx("p", { className: "ss-notice", role: "status", children: notice })), _jsxs("div", { className: "ss-actions", children: [resendButton("Resend link"), anotherEmail] })] }));
+    }
+    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…"
-                            : resendIn > 0
-                                ? `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.";
+                                }, 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: [resendButton("Resend code"), anotherEmail] })] }));
 }

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

@@ -0,0 +1,89 @@
+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;
+}
+/**
+ * Why the last call failed. `not_invited`: the ontology allows no sign-in with this address, so no
+ * email was sent. Apps that show another language word their message from it.
+ */
+export type SignInErrorCode = "email_required" | "email_invalid" | "not_invited" | "code_incomplete" | "code_invalid" | "code_expired" | "too_many_attempts" | "rate_limited" | "unavailable" | "failed";
+/** What the last call confirmed: another code, or another sign-in link, was sent. */
+export type SignInNoticeCode = "code_resent" | "link_resent";
+/** The SDK's sentence for each {@link SignInErrorCode}. */
+export declare const SIGN_IN_ERROR_MESSAGES: Readonly<Record<SignInErrorCode, string>>;
+/** Email sign-in for a form the app renders itself. The calls take values, not form events. */
+export interface SignInController {
+    /**
+     * `email`, then `code` for a member with a Neon Auth account, or `link` when a sign-in link was
+     * emailed instead: a first sign-in, whose link creates the account. The link step has nothing to
+     * submit; the person opens the link from the email.
+     */
+    readonly step: "email" | "code" | "link";
+    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;
+    /** Why the last call failed, for apps that word `error` themselves. */
+    readonly errorCode: SignInErrorCode | null;
+    /** A confirmation, such as a new code having been sent. */
+    readonly notice: string | null;
+    /** What `notice` confirms, for apps that word it themselves. */
+    readonly noticeCode: SignInNoticeCode | null;
+    /** Seconds until another code or link 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;
+    /**
+     * Asks the ontology whether `email` may sign in, then emails a code or a sign-in link and moves to
+     * `code` or `link`. An address the ontology refuses gets `not_invited`, and no email is sent. 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, or another link on the link step, 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 sign-in with Neon Auth, without markup. The ontology first says whether the address may
+ * sign in (`POST /api/ontology/sign-in/check`): a member with a Neon Auth account gets a six-digit
+ * code, a first sign-in gets a sign-in link, which creates the account, and an address the ontology
+ * refuses gets `not_invited` without an email. Without an ontology to ask, every address gets a
+ * code. `<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;
+/** Why a Neon Auth (Better Auth) call failed. */
+export declare function signInErrorCode(error: unknown): SignInErrorCode;
+/** 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,236 @@
+"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 { checkSignIn } from "./sign-in-check.js";
+import { authClient, clearSession, refreshSession } from "./store.js";
+/** Seconds before another code or link may be requested. */
+const RESEND_AFTER_SECONDS = 30;
+const CODE_LENGTH = 6;
+/** The SDK's sentence for each {@link SignInErrorCode}. */
+export const SIGN_IN_ERROR_MESSAGES = {
+    email_required: "Enter your email address.",
+    email_invalid: "Enter a valid email address.",
+    not_invited: "This app has not invited this address. Check it, or ask your administrator for an invitation.",
+    code_incomplete: `Enter the ${CODE_LENGTH}-digit code from the email.`,
+    code_invalid: "That code is not right. Check the email and try again.",
+    code_expired: "That code has expired. Send a new one.",
+    too_many_attempts: "Too many wrong codes. Send a new code.",
+    rate_limited: "Too many requests. Wait a minute, then try again.",
+    unavailable: "Sign-in is unavailable right now. Try again in a moment.",
+    failed: "Sign-in failed. Try again.",
+};
+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);
+}
+function noticeFor(notice, email) {
+    switch (notice) {
+        case "code_resent":
+            return `We sent a new code to ${email}.`;
+        case "link_resent":
+            return `We sent a new sign-in link to ${email}.`;
+        case null:
+            return null;
+    }
+}
+/**
+ * Email sign-in with Neon Auth, without markup. The ontology first says whether the address may
+ * sign in (`POST /api/ontology/sign-in/check`): a member with a Neon Auth account gets a six-digit
+ * code, a first sign-in gets a sign-in link, which creates the account, and an address the ontology
+ * refuses gets `not_invited` without an email. Without an ontology to ask, every address gets a
+ * code. `<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 [errorCode, setErrorCode] = useState(null);
+    const [noticeCode, setNoticeCode] = 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);
+    }
+    function clearMessages() {
+        setErrorCode(null);
+        setNoticeCode(null);
+    }
+    /** Runs a Neon Auth call that emails the person; on success it holds the next one back. */
+    async function send(call) {
+        const result = await attempt(call);
+        if (result !== null) {
+            setErrorCode(signInErrorCode(result));
+            return false;
+        }
+        holdResend();
+        return true;
+    }
+    function sendCode(address) {
+        return send(() => authClient().emailOtp.sendVerificationOtp({ email: address, type: "sign-in" }));
+    }
+    function sendLink(address) {
+        // Neon Auth checks the callback against the app's trusted origins, so it is absolute.
+        const callbackURL = new URL(destination, window.location.origin).href;
+        return send(() => authClient().signIn.magicLink({ email: address, callbackURL }));
+    }
+    async function submitEmail() {
+        const address = email.trim();
+        if (address === "") {
+            setErrorCode("email_required");
+            return;
+        }
+        setPending("send");
+        clearMessages();
+        const outcome = await checkSignIn(address);
+        if (outcome !== "code" && outcome !== "link") {
+            setErrorCode(outcome);
+        }
+        else if (await (outcome === "code" ? sendCode(address) : sendLink(address))) {
+            setEmail(address);
+            setCode("");
+            setStep(outcome);
+        }
+        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)) {
+            setErrorCode("code_incomplete");
+            return;
+        }
+        verifying.current = true;
+        setPending("verify");
+        clearMessages();
+        const result = await attempt(() => authClient().signIn.emailOtp({ email, otp: value }));
+        if (result !== null) {
+            verifying.current = false;
+            setErrorCode(signInErrorCode(result));
+            setCode("");
+            setPending(null);
+            return;
+        }
+        navigate(destination);
+    }
+    async function resend() {
+        setPending("resend");
+        clearMessages();
+        if (step === "link") {
+            if (await sendLink(email)) {
+                setNoticeCode("link_resent");
+            }
+        }
+        else if (await sendCode(email)) {
+            setCode("");
+            setNoticeCode("code_resent");
+        }
+        setPending(null);
+    }
+    function changeEmail() {
+        setStep("email");
+        setCode("");
+        clearMessages();
+    }
+    async function switchAccount() {
+        setPending("sign-out");
+        setErrorCode(null);
+        await attempt(() => authClient().signOut());
+        clearSession();
+        await refreshSession();
+        setSwitchingAccount(true);
+        setStep("email");
+        setPending(null);
+    }
+    return {
+        step,
+        email,
+        setEmail,
+        code,
+        setCode,
+        pending,
+        error: errorCode === null ? null : SIGN_IN_ERROR_MESSAGES[errorCode],
+        errorCode,
+        notice: noticeFor(noticeCode, email),
+        noticeCode,
+        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.");
+    }
+}
+/** Why a Neon Auth (Better Auth) call failed. */
+export function signInErrorCode(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 "rate_limited";
+    }
+    if (text.includes("too many attempts") || text.includes("too_many_attempts")) {
+        return "too_many_attempts";
+    }
+    if (text.includes("expired")) {
+        return "code_expired";
+    }
+    if (text.includes("otp") || text.includes("code")) {
+        return "code_invalid";
+    }
+    if (text.includes("email")) {
+        return "email_invalid";
+    }
+    if (status === undefined || status >= 500 || text.includes("network")) {
+        return "unavailable";
+    }
+    return "failed";
+}
+/** A sentence for a Neon Auth (Better Auth) failure. */
+export function signInErrorMessage(error) {
+    return SIGN_IN_ERROR_MESSAGES[signInErrorCode(error)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",