@segmentstream/app 0.0.0-stage → 0.38.0

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

@@ -0,0 +1,304 @@
+"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 { appSignInConfiguration, authClient, clearSession, endBrowserSession, 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 fragment, with its `#`; empty during server rendering. */
+function useLocationHash() {
+    return useSyncExternalStore(noSubscription, () => window.location.hash, () => "");
+}
+/** 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);
+}
+/**
+ * The address and code that a sign-in code email's link carries in the sign-in page's fragment, as
+ * the platform writes it for apps that declare `signIn.codeLink`:
+ * `/sign-in#code=482915&email=ada%40example.com`. Browsers never send the fragment to a server.
+ */
+export function signInCodeFromLink(hash) {
+    const fragment = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+    const code = fragment.get("code") ?? "";
+    const email = fragment.get("email")?.trim() ?? "";
+    return new RegExp(`^[0-9]{${CODE_LENGTH}}$`).test(code) && email.includes("@")
+        ? { email, code }
+        : null;
+}
+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 [codeFromLink, setCodeFromLink] = useState(false);
+    const [segmentstreamEnabled, setSegmentstreamEnabled] = useState(false);
+    const [emailEnabled, setEmailEnabled] = useState(true);
+    useEffect(() => {
+        let active = true;
+        void appSignInConfiguration().then((body) => {
+            if (active) {
+                setSegmentstreamEnabled(body?.enabled === true);
+                setEmailEnabled(body?.neon !== false);
+            }
+        });
+        return () => {
+            active = false;
+        };
+    }, []);
+    // A code email's link fills in its address and code once, during the first client render.
+    const linked = signInCodeFromLink(useLocationHash());
+    const [linkRead, setLinkRead] = useState(false);
+    if (linked !== null && !linkRead) {
+        setLinkRead(true);
+        setEmail(linked.email);
+        setCode(linked.code);
+        setStep("code");
+        setCodeFromLink(true);
+    }
+    useEffect(() => {
+        if (linkRead && window.location.hash !== "") {
+            // The code stays out of the history and of the address the person might copy.
+            window.history.replaceState(window.history.state, "", `${window.location.pathname}${window.location.search}`);
+        }
+    }, [linkRead]);
+    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() {
+        if (!emailEnabled) {
+            setErrorCode("unavailable");
+            return;
+        }
+        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("");
+            setCodeFromLink(false);
+            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("");
+            setCodeFromLink(false);
+            setNoticeCode("code_resent");
+        }
+        setPending(null);
+    }
+    function changeEmail() {
+        setStep("email");
+        setCode("");
+        setCodeFromLink(false);
+        clearMessages();
+    }
+    async function switchAccount() {
+        setPending("sign-out");
+        setErrorCode(null);
+        const result = await attempt(async () => {
+            await endBrowserSession();
+            return { error: null };
+        });
+        if (result !== null) {
+            setErrorCode(signInErrorCode(result));
+            setPending(null);
+            return;
+        }
+        clearSession();
+        await refreshSession();
+        setSwitchingAccount(true);
+        setStep("email");
+        setPending(null);
+    }
+    return {
+        emailEnabled,
+        segmentstreamSignInUrl: segmentstreamEnabled
+            ? `/api/segmentstream/sign-in?returnTo=${encodeURIComponent(destination)}`
+            : null,
+        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,
+        codeFromLink,
+        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,97 @@
 {
   "name": "@segmentstream/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.38.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",
+  "homepage": "https://segmentstream.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/segmentstream/segmentstream.git",
+    "directory": "packages/app-sdk"
+  },
+  "keywords": [
+    "segmentstream",
+    "nextjs",
+    "authentication",
+    "neon-auth",
+    "ontology"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js"
+    },
+    "./ui/styles.css": "./dist/ui/styles.css",
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    },
+    "./navigation/build": {
+      "types": "./dist/navigation/build.d.ts",
+      "import": "./dist/navigation/build.js",
+      "default": "./dist/navigation/build.js"
+    },
+    "./navigation/next": {
+      "types": "./dist/navigation/next.d.ts",
+      "import": "./dist/navigation/next.js",
+      "default": "./dist/navigation/next.js"
+    },
+    "./browser-auth-capability": {
+      "types": "./dist/browser-auth-capability.d.ts",
+      "import": "./dist/browser-auth-capability.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/prepare-channel-protocol.mjs && node scripts/prepare-navigation-protocol.mjs && rm -rf dist && tsc -p tsconfig.build.json && cp src/ui/styles.css dist/ui/styles.css",
+    "typecheck": "node scripts/prepare-channel-protocol.mjs && node scripts/prepare-navigation-protocol.mjs && tsc -p tsconfig.json --noEmit",
+    "lint": "node scripts/prepare-channel-protocol.mjs && node scripts/prepare-navigation-protocol.mjs && eslint src tests --config ../../eslint.config.mjs",
+    "test": "node scripts/prepare-channel-protocol.mjs && node scripts/prepare-navigation-protocol.mjs && vitest run",
+    "prepack": "pnpm run build",
+    "test:navigation:integration": "pnpm run build && node --test tests/navigation-build.integration.mjs"
+  },
+  "dependencies": {
+    "@neondatabase/auth": "0.5.0-beta",
+    "jose": "^6.2.12"
+  },
+  "peerDependencies": {
+    "next": ">=16.0.0",
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "effect": "4.0.0-rc.113",
+    "jsdom": "^28.1.0",
+    "next": "16.3.8",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^5.9",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "segmentstream-page-catalog": "./dist/navigation/cli.js"
+  }
+}