@segmentstream/app 0.0.0-stage → 0.38.0

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

@@ -0,0 +1,169 @@
+"use client";
+import { useEffect, useState } from "react";
+import { safeReturnTo } from "../return-to.js";
+import { appSignInConfiguration, authClient } from "./store.js";
+/** Headless browser-method discovery. The workspace supplies every message and control. */
+export function useBrowserSignIn(options = {}) {
+    const [configuration, setConfiguration] = useState();
+    useEffect(() => {
+        let active = true;
+        void appSignInConfiguration().then((value) => {
+            if (active)
+                setConfiguration(value);
+        });
+        return () => {
+            active = false;
+        };
+    }, []);
+    const query = typeof window === "undefined" ? undefined : new URLSearchParams(window.location.search);
+    const returnTo = safeReturnTo(options.returnTo ?? query?.get("returnTo"));
+    const error = options.error ?? query?.get("error") ?? null;
+    const methods = configuration?.browser?.methods ?? [
+        ...(configuration?.neon ? ["email"] : []),
+        ...(configuration?.enabled ? ["segmentstream"] : []),
+    ];
+    return {
+        status: configuration === undefined
+            ? "loading"
+            : configuration === null
+                ? "unavailable"
+                : "ready",
+        methods,
+        primary: configuration?.browser?.primary ?? (configuration?.neon ? "email" : "segmentstream"),
+        returnTo,
+        error,
+        segmentstreamSignInUrl: methods.includes("segmentstream")
+            ? `/api/segmentstream/sign-in?returnTo=${encodeURIComponent(returnTo)}`
+            : null,
+        connectAccountUrl: methods.includes("email") && methods.includes("segmentstream")
+            ? `/api/segmentstream/connect?returnTo=${encodeURIComponent(returnTo)}`
+            : null,
+        accountSwitchUrl: methods.includes("segmentstream")
+            ? `/api/segmentstream/sign-in?account=select&returnTo=${encodeURIComponent(returnTo)}`
+            : null,
+        emailSignInUrl: methods.includes("email")
+            ? `/sign-in?method=email&returnTo=${encodeURIComponent(returnTo)}`
+            : null,
+    };
+}
+/** Linking never confirms during a GET. Post the form to confirmationUrl after explicit consent. */
+export function useIdentityLink() {
+    const [state, setState] = useState({
+        status: "loading",
+        pending: false,
+        proofReady: false,
+        emailEnabled: false,
+        identity: null,
+        workspaceUser: null,
+        expiresAt: null,
+        returnTo: null,
+    });
+    useEffect(() => {
+        let active = true;
+        void fetch("/api/segmentstream/link", { credentials: "same-origin", cache: "no-store" })
+            .then(async (response) => {
+            if (!response.ok)
+                throw new Error("identity_link_unavailable");
+            const value = (await response.json());
+            if (active)
+                setState({
+                    status: "ready",
+                    pending: value.pending === true,
+                    proofReady: value.proof_ready === true,
+                    emailEnabled: value.email_enabled === true,
+                    identity: typeof value.identity?.id === "string" ? value.identity : null,
+                    workspaceUser: typeof value.workspaceUser?.id === "string" ? value.workspaceUser : null,
+                    expiresAt: typeof value.expiresAt === "number" ? value.expiresAt : null,
+                    returnTo: typeof value.returnTo === "string" ? safeReturnTo(value.returnTo) : null,
+                });
+        })
+            .catch(() => {
+            if (active)
+                setState({
+                    status: "unavailable",
+                    pending: false,
+                    proofReady: false,
+                    emailEnabled: false,
+                    identity: null,
+                    workspaceUser: null,
+                    expiresAt: null,
+                    returnTo: null,
+                });
+        });
+        return () => {
+            active = false;
+        };
+    }, []);
+    useEffect(() => {
+        if (state.expiresAt === null)
+            return;
+        const deadline = state.expiresAt;
+        const timer = window.setTimeout(() => setState((current) => current.expiresAt === deadline
+            ? { ...current, pending: false, proofReady: false, identity: null, workspaceUser: null }
+            : current), Math.max(0, deadline - Date.now()));
+        return () => window.clearTimeout(timer);
+    }, [state.expiresAt]);
+    return {
+        ...state,
+        confirmationUrl: "/api/segmentstream/link",
+        emailProofUrl: `/sign-in?method=email&returnTo=${encodeURIComponent(`/sign-in/link?returnTo=${encodeURIComponent(state.returnTo ?? "/")}`)}`,
+    };
+}
+/** Explicit reverse linking. Email possession is proof only; the OIDC session selects the user. */
+export function useEmailIdentityLink() {
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(null);
+    async function confirm() {
+        setStatus("pending");
+        setError(null);
+        try {
+            const response = await fetch("/api/segmentstream/link-email", {
+                method: "POST",
+                credentials: "same-origin",
+                cache: "no-store",
+            });
+            const body = (await response.json());
+            if (!response.ok) {
+                setError(typeof body.error === "string" ? body.error : "identity_link_failed");
+                setStatus("error");
+                return false;
+            }
+            setStatus("linked");
+            return true;
+        }
+        catch {
+            setError("identity_link_unavailable");
+            setStatus("error");
+            return false;
+        }
+    }
+    async function requestProof(email, returnTo = "/sign-in/link-email") {
+        setStatus("pending");
+        setError(null);
+        try {
+            const configuration = await appSignInConfiguration();
+            if (!configuration?.neon || !configuration.enabled) {
+                setError("identity_method_unavailable");
+                setStatus("error");
+                return false;
+            }
+            const result = await authClient().signIn.magicLink({
+                email,
+                callbackURL: new URL(safeReturnTo(returnTo), window.location.origin).href,
+            });
+            if (result.error) {
+                setError("identity_proof_failed");
+                setStatus("error");
+                return false;
+            }
+            setStatus("idle");
+            return true;
+        }
+        catch {
+            setError("identity_proof_unavailable");
+            setStatus("error");
+            return false;
+        }
+    }
+    return { status, error, confirm, requestProof };
+}

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

@@ -0,0 +1,10 @@
+export type ChannelSignInState = {
+    readonly status: "loading" | "disabled" | "idle" | "pending" | "signed_in" | "error";
+    readonly error: string | null;
+};
+export interface ChannelSignInOptions {
+    readonly assertion: () => string | undefined;
+    readonly redirectTo?: string;
+}
+/** One exchange per assertion, with an absolute expiry timer. Errors are app-rendered codes. */
+export declare function useChannelSignIn(provider: string, options: ChannelSignInOptions): ChannelSignInState;

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

@@ -0,0 +1,118 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { channelSignInPath } from "../channel-protocol.js";
+import { safeReturnTo } from "../return-to.js";
+import { useSession } from "./hooks.js";
+import { navigate } from "./navigation.js";
+import { appSignInConfiguration, getSnapshot, refreshSession, sessionWasEnded } from "./store.js";
+// A layout and the SDK sign-in page may mount together. Retain only the latest attempt per provider,
+// in memory, so both share one exchange/discovery and never retry the same launch assertion.
+const attempts = new Map();
+function exchange(provider, assertion) {
+    const previous = attempts.get(provider);
+    if (previous?.assertion === assertion) {
+        return previous.result;
+    }
+    const result = (async () => {
+        try {
+            const response = await fetch(channelSignInPath(provider), {
+                method: "POST",
+                credentials: "same-origin",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ assertion }),
+            });
+            if (!response.ok) {
+                const body = (await response.json());
+                return typeof body.error === "string" ? body.error : "sign_in_failed";
+            }
+            await refreshSession();
+            return getSnapshot().session.status === "signed-in" ? null : "session_unavailable";
+        }
+        catch {
+            return "sign_in_unavailable";
+        }
+    })();
+    attempts.set(provider, { assertion, result });
+    return result;
+}
+/** One exchange per assertion, with an absolute expiry timer. Errors are app-rendered codes. */
+export function useChannelSignIn(provider, options) {
+    const session = useSession();
+    const [enabled, setEnabled] = useState(undefined);
+    const [settled, setSettled] = useState();
+    const [expired, setExpired] = useState();
+    const redirected = useRef(false);
+    const raw = enabled && typeof window !== "undefined" ? options.assertion() : undefined;
+    const redirectTo = options.redirectTo;
+    useEffect(() => {
+        let mounted = true;
+        void appSignInConfiguration().then((config) => {
+            if (mounted) {
+                setEnabled(config === null ? null : config.channels[provider] === true);
+            }
+        });
+        return () => {
+            mounted = false;
+        };
+    }, [provider, session]);
+    useEffect(() => {
+        if (!enabled ||
+            session.status !== "signed-in" ||
+            session.source !== "channel" ||
+            !session.expiresAt ||
+            expired === session.sessionId) {
+            return;
+        }
+        const timer = window.setTimeout(() => {
+            setExpired(session.sessionId);
+            void refreshSession();
+        }, Math.max(0, Date.parse(session.expiresAt) - Date.now()));
+        return () => window.clearTimeout(timer);
+    }, [session, enabled, expired]);
+    useEffect(() => {
+        if (!enabled || session.status === "loading" || session.status === "unavailable") {
+            return;
+        }
+        if (session.status === "signed-in" && expired !== session.sessionId) {
+            if (raw && redirectTo !== undefined && !redirected.current) {
+                redirected.current = true;
+                navigate(safeReturnTo(redirectTo));
+            }
+            return;
+        }
+        if (sessionWasEnded() || !raw) {
+            return;
+        }
+        let mounted = true;
+        void exchange(provider, raw).then((error) => {
+            if (mounted) {
+                setSettled({ assertion: raw, error });
+            }
+        });
+        return () => {
+            mounted = false;
+        };
+    }, [session, enabled, provider, raw, redirectTo, expired]);
+    if (enabled === undefined || session.status === "loading") {
+        return { status: "loading", error: null };
+    }
+    if (enabled === null) {
+        return { status: "error", error: "configuration_unavailable" };
+    }
+    if (!enabled) {
+        return { status: "disabled", error: null };
+    }
+    if (session.status === "unavailable") {
+        return { status: "error", error: "session_unavailable" };
+    }
+    if (session.status === "signed-in" && expired !== session.sessionId) {
+        return { status: "signed_in", error: null };
+    }
+    if (sessionWasEnded() || !raw) {
+        return { status: "idle", error: null };
+    }
+    if (settled?.assertion === raw) {
+        return { status: "error", error: settled.error ?? "fresh_assertion_required" };
+    }
+    return { status: "pending", error: null };
+}

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

@@ -0,0 +1,109 @@
+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 {
+    readonly segmentstreamSignInUrl: string | null;
+    readonly emailEnabled: boolean;
+    /**
+     * `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 page was opened from the link in a sign-in code email, for apps that declare
+     * `signIn.codeLink`: the hook is on the `code` step with that email's address and code. The hook
+     * never submits it. Calling `submitCode()` once when this turns true signs in with one click; a
+     * mail scanner that runs the page's scripts can then spend the code first, and the person asks
+     * for a new one. An app that would rather avoid that asks the person to confirm instead. It turns
+     * false once the code is cleared.
+     */
+    readonly codeFromLink: 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>;
+}
+/**
+ * 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 declare function signInCodeFromLink(hash: string): {
+    readonly email: string;
+    readonly code: string;
+} | 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 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;