@segmentstream-cloud/app 0.17.1 → 0.18.0

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

@@ -1,10 +1,14 @@
+import { type ReactNode } from "react";
+import type { ChannelSignInState } from "./use-channel-sign-in.js";
 import type { SignInOptions } from "./use-sign-in.js";
 export interface SignInProps extends SignInOptions {
     /** The heading. Defaults to "Sign in". */
     readonly title?: string;
+    /** App-owned rendering for channel status/error codes; no SDK error copy is supplied. */
+    readonly renderTelegram?: (state: ChannelSignInState) => ReactNode;
 }
 /**
  * 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({ title, ...options }: SignInProps): import("react").JSX.Element;
+export declare function SignIn({ renderTelegram, ...options }: SignInProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null;

package/dist/ui/sign-in.js

@@ -1,12 +1,26 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef } from "react";
+import { telegramInitData, useTelegramSignIn } from "./telegram-sign-in.js";
 import { useSignIn } from "./use-sign-in.js";
 /**
  * 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({ title = "Sign in", ...options }) {
+export function SignIn({ renderTelegram, ...options }) {
+    const destination = typeof window === "undefined"
+        ? "/"
+        : (new URLSearchParams(window.location.search).get("returnTo") ?? "/");
+    const telegram = useTelegramSignIn({ redirectTo: options.returnTo ?? destination });
+    const active = telegram.status !== "loading" &&
+        typeof window !== "undefined" &&
+        telegramInitData() !== undefined;
+    if (active && telegram.status !== "disabled") {
+        return renderTelegram?.(telegram) ?? null;
+    }
+    return _jsx(EmailSignIn, { ...options });
+}
+function EmailSignIn({ title = "Sign in", ...options }) {
     const ids = useId();
     const { step, segmentstreamSignInUrl, 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);

package/dist/ui/store.d.ts

@@ -16,12 +16,16 @@ export type SessionState = {
     readonly status: "loading";
 } | {
     readonly status: "signed-out";
+    readonly source?: "oidc";
 } | {
     readonly status: "signed-in";
     readonly sessionId: string;
     readonly user: SessionUser;
+    readonly source?: "channel" | "oidc";
+    readonly expiresAt?: string;
 } | {
     readonly status: "unavailable";
+    readonly source?: "oidc";
 };
 /** `useUser()`: the `/api/ontology/me` answer for the session, loaded once per session. */
 export type UserState = {
@@ -48,6 +52,7 @@ interface Snapshot {
 }
 export declare const LOADING_USER: UserState;
 export declare const SIGNED_OUT_USER: UserState;
+export declare function sessionWasEnded(): boolean;
 /** The Neon Auth browser client, created on first use. It talks to the app's `/api/auth`. */
 export declare function authClient(): ReturnType<typeof createAuthClient>;
 export declare function subscribe(listener: () => void): () => void;
@@ -57,5 +62,14 @@ export declare function getServerSnapshot(): Snapshot;
 export declare function refreshSession(): Promise<void>;
 /** Forgets the session and every `/me` answer, after signing out. */
 export declare function clearSession(): void;
+/** Ends the selected authentication session before any browser state is cleared. */
+export declare function endBrowserSession(): Promise<void>;
+export interface AppSignInConfiguration {
+    readonly enabled: boolean;
+    readonly neon: boolean;
+    readonly channels: Readonly<Record<string, boolean>>;
+}
+/** Public, non-secret app opt-ins from the existing SDK handlers. No provider is enabled by default. */
+export declare function appSignInConfiguration(): Promise<AppSignInConfiguration | null>;
 /** Starts loading `/me` for a session unless it is loaded or loading. */
-export declare function ensureUser(sessionId: string): void;
+export declare function ensureUser(sessionId: string, source?: "channel" | "oidc"): void;

package/dist/ui/store.js

@@ -1,5 +1,6 @@
 "use client";
 import { createAuthClient } from "@neondatabase/auth/next";
+import { CHANNEL_LOGOUT_PATH, CHANNEL_SESSION_PATH } from "../channel-protocol.js";
 import { NOT_INVITED, SegmentStreamApiError, apiErrorFrom, readJson } from "../errors.js";
 import { ME_PATH, parseMe } from "../me.js";
 /** The Neon Auth API the app serves from `app/src/app/api/auth/[...path]/route.ts`. */
@@ -12,9 +13,14 @@ export const SIGNED_OUT_USER = { status: "signed-out", user: null, error: null }
 const SERVER_SNAPSHOT = { session: { status: "loading" }, users: new Map() };
 let snapshot = SERVER_SNAPSHOT;
 let sessionLoad = null;
+let sessionGeneration = 0;
 const loadingUsers = new Set();
 const listeners = new Set();
 let client;
+let explicitlySignedOut = false;
+export function sessionWasEnded() {
+    return explicitlySignedOut;
+}
 /** The Neon Auth browser client, created on first use. It talks to the app's `/api/auth`. */
 export function authClient() {
     client ??= createAuthClient();
@@ -41,30 +47,133 @@ export function getServerSnapshot() {
 }
 /** Reads the session again, after signing in or out. */
 export function refreshSession() {
+    if (snapshot.session.status === "unavailable") {
+        configurationLoad = undefined;
+    }
     sessionLoad = loadSession();
     return sessionLoad;
 }
 /** Forgets the session and every `/me` answer, after signing out. */
 export function clearSession() {
+    sessionGeneration++;
+    explicitlySignedOut = true;
     loadingUsers.clear();
     update({ session: { status: "signed-out" }, users: new Map() });
 }
-async function loadSession() {
-    let session;
+/** Ends the selected authentication session before any browser state is cleared. */
+export async function endBrowserSession() {
+    if (snapshot.session.status !== "signed-in" || snapshot.session.source !== "channel") {
+        if (snapshot.session.status === "signed-in" && snapshot.session.source === "oidc") {
+            const response = await fetch("/api/segmentstream/sign-out", {
+                method: "POST",
+                credentials: "same-origin",
+            });
+            if (!response.ok) {
+                throw new Error("logout_failed");
+            }
+        }
+        else {
+            await authClient().signOut();
+        }
+        return;
+    }
+    const response = await fetch(CHANNEL_LOGOUT_PATH, {
+        method: "POST",
+        credentials: "same-origin",
+    });
+    if (!response.ok) {
+        throw new Error("logout_failed");
+    }
+}
+let configurationLoad;
+/** Public, non-secret app opt-ins from the existing SDK handlers. No provider is enabled by default. */
+export function appSignInConfiguration() {
+    configurationLoad ??= (async () => {
+        try {
+            const response = await fetch("/api/segmentstream/configuration", {
+                credentials: "same-origin",
+                cache: "no-store",
+            });
+            const body = response.ok ? await readJson(response) : null;
+            if (!body || typeof body !== "object" || !("enabled" in body)) {
+                return null;
+            }
+            const { enabled } = body;
+            // Older SDK handlers omit this field; keep their existing session discovery precedence.
+            const neon = "neon" in body ? body.neon : true;
+            const channels = "channels" in body ? body.channels : {};
+            if (typeof enabled !== "boolean" ||
+                typeof neon !== "boolean" ||
+                !channels ||
+                typeof channels !== "object" ||
+                Array.isArray(channels) ||
+                Object.values(channels).some((value) => typeof value !== "boolean")) {
+                return null;
+            }
+            return { enabled, neon, channels: channels };
+        }
+        catch {
+            return null;
+        }
+    })();
+    return configurationLoad;
+}
+async function discover(path, source) {
     try {
-        const response = await fetch(`${AUTH_API_PATH}/get-session`, {
+        const response = await fetch(path, {
             credentials: "same-origin",
             cache: "no-store",
             headers: { accept: "application/json" },
         });
-        session = response.ok
-            ? sessionFrom(await readJson(response))
+        const payload = await readJson(response);
+        const session = response.ok
+            ? sessionFrom(payload)
             : response.status === 401
                 ? { status: "signed-out" }
                 : { status: "unavailable" };
+        // Channel/OIDC endpoints confirm absence with 401. A malformed success is an outage,
+        // and must not select a different user from a lower-priority provider.
+        if (source && response.ok && session.status === "signed-out") {
+            return { status: "unavailable" };
+        }
+        if (source === "oidc" &&
+            (session.status === "signed-out" || session.status === "unavailable") &&
+            payload &&
+            typeof payload === "object" &&
+            payload.source === "oidc") {
+            return { ...session, source: "oidc" };
+        }
+        return session.status === "signed-in" && source
+            ? {
+                ...session,
+                sessionId: `${source}:${session.sessionId}`,
+                source,
+            }
+            : session;
     }
     catch {
-        session = { status: "unavailable" };
+        return { status: "unavailable" };
+    }
+}
+async function loadSession() {
+    const generation = ++sessionGeneration;
+    const config = await appSignInConfiguration();
+    let session = { status: config ? "signed-out" : "unavailable" };
+    // Same precedence as ontology cookie authentication and app server helpers: channel, OIDC, Neon.
+    if (config && Object.values(config.channels).some((enabled) => enabled === true)) {
+        session = await discover(CHANNEL_SESSION_PATH, "channel");
+    }
+    if (session.status === "signed-out" && config?.enabled) {
+        session = await discover("/api/segmentstream/session", "oidc");
+    }
+    if (session.status === "signed-out" && session.source !== "oidc" && config?.neon) {
+        session = await discover(`${AUTH_API_PATH}/get-session`);
+    }
+    if (generation !== sessionGeneration) {
+        return;
+    }
+    if (session.status === "signed-in") {
+        explicitlySignedOut = false;
     }
     update({ session });
 }
@@ -79,7 +188,7 @@ function sessionFrom(payload) {
         user === null) {
         return { status: "signed-out" };
     }
-    const { id: sessionId } = session;
+    const { id: sessionId, expires_at } = session;
     const { id, email, name } = user;
     if (typeof sessionId !== "string" || typeof id !== "string") {
         return { status: "signed-out" };
@@ -87,6 +196,9 @@ function sessionFrom(payload) {
     return {
         status: "signed-in",
         sessionId,
+        ...(typeof expires_at === "string" && Number.isFinite(Date.parse(expires_at))
+            ? { expiresAt: expires_at }
+            : {}),
         user: {
             id,
             email: typeof email === "string" ? email : null,
@@ -95,12 +207,12 @@ function sessionFrom(payload) {
     };
 }
 /** Starts loading `/me` for a session unless it is loaded or loading. */
-export function ensureUser(sessionId) {
+export function ensureUser(sessionId, source) {
     if (snapshot.users.has(sessionId) || loadingUsers.has(sessionId)) {
         return;
     }
     loadingUsers.add(sessionId);
-    void loadUser().then((state) => {
+    void loadUser(source).then((state) => {
         if (!loadingUsers.delete(sessionId)) {
             return; // Signed out meanwhile.
         }
@@ -108,26 +220,34 @@ export function ensureUser(sessionId) {
     });
 }
 /** The session's JWT from Neon Auth, then the ontology's account of the user. */
-async function loadUser() {
+async function loadUser(source) {
     try {
-        const tokenResponse = await fetch(`${AUTH_API_PATH}/token`, {
-            credentials: "same-origin",
-            cache: "no-store",
-            headers: { accept: "application/json" },
-        });
-        if (tokenResponse.status === 401) {
-            return SIGNED_OUT_USER;
-        }
-        const tokenPayload = await readJson(tokenResponse);
-        const token = typeof tokenPayload === "object" && tokenPayload !== null
-            ? tokenPayload.token
-            : undefined;
-        if (!tokenResponse.ok || typeof token !== "string" || token === "") {
-            return failed("auth_unavailable", 503, "Neon Auth did not issue a token. Try again.");
+        let token;
+        if (source === undefined) {
+            const tokenResponse = await fetch(`${AUTH_API_PATH}/token`, {
+                credentials: "same-origin",
+                cache: "no-store",
+                headers: { accept: "application/json" },
+            });
+            if (tokenResponse.status === 401) {
+                return SIGNED_OUT_USER;
+            }
+            const tokenPayload = await readJson(tokenResponse);
+            token =
+                typeof tokenPayload === "object" && tokenPayload !== null
+                    ? tokenPayload.token
+                    : undefined;
+            if (!tokenResponse.ok || typeof token !== "string" || token === "") {
+                return failed("auth_unavailable", 503, "Neon Auth did not issue a token. Try again.");
+            }
         }
         const response = await fetch(ME_PATH, {
             cache: "no-store",
-            headers: { accept: "application/json", authorization: `Bearer ${token}` },
+            credentials: "same-origin",
+            headers: {
+                accept: "application/json",
+                ...(typeof token === "string" ? { authorization: `Bearer ${token}` } : {}),
+            },
         });
         const payload = await readJson(response);
         if (!response.ok) {

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

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+import { type ChannelSignInState } from "./use-channel-sign-in.js";
+export interface TelegramSignInOptions {
+    readonly redirectTo?: string;
+    /** Read fresh signed initData from the app's Telegram integration. */
+    readonly initData?: () => string | undefined;
+}
+/** Telegram carries launch data in a URL fragment, which browsers inherit through HTTP redirects. */
+export declare function telegramInitData(): string | undefined;
+/** Works on any app page; the public SDK configuration must explicitly enable Telegram. */
+export declare function useTelegramSignIn(options?: TelegramSignInOptions): ChannelSignInState;
+export interface TelegramSignInProps extends TelegramSignInOptions {
+    readonly children?: (state: ChannelSignInState) => ReactNode;
+}
+/** Headless component: the app owns all labels and error messages. */
+export declare function TelegramSignIn({ children, ...options }: TelegramSignInProps): string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;

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

@@ -0,0 +1,21 @@
+"use client";
+import { useChannelSignIn } from "./use-channel-sign-in.js";
+/** Telegram carries launch data in a URL fragment, which browsers inherit through HTTP redirects. */
+export function telegramInitData() {
+    const telegram = window.Telegram;
+    return (telegram?.WebApp?.initData ||
+        new URLSearchParams(window.location.hash.slice(1)).get("tgWebAppData") ||
+        undefined);
+}
+/** Works on any app page; the public SDK configuration must explicitly enable Telegram. */
+export function useTelegramSignIn(options = {}) {
+    return useChannelSignIn("telegram", {
+        ...options,
+        assertion: options.initData ?? telegramInitData,
+    });
+}
+/** Headless component: the app owns all labels and error messages. */
+export function TelegramSignIn({ children, ...options }) {
+    const state = useTelegramSignIn(options);
+    return children?.(state) ?? null;
+}

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.js

@@ -5,7 +5,7 @@ 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";
+import { 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;
@@ -175,7 +175,15 @@ export function useSignIn({ returnTo, error: reason } = {}) {
     async function switchAccount() {
         setPending("sign-out");
         setErrorCode(null);
-        await attempt(() => authClient().signOut());
+        const result = await attempt(async () => {
+            await endBrowserSession();
+            return { error: null };
+        });
+        if (result !== null) {
+            setErrorCode(signInErrorCode(result));
+            setPending(null);
+            return;
+        }
         clearSession();
         await refreshSession();
         setSwitchingAccount(true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.17.1",
+  "version": "0.18.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",
@@ -46,10 +46,10 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/ui/styles.css dist/ui/styles.css",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint src tests --config ../../eslint.config.mjs",
-    "test": "vitest run",
+    "build": "node scripts/prepare-channel-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 && tsc -p tsconfig.json --noEmit",
+    "lint": "node scripts/prepare-channel-protocol.mjs && eslint src tests --config ../../eslint.config.mjs",
+    "test": "node scripts/prepare-channel-protocol.mjs && vitest run",
     "prepack": "npm run build"
   },
   "dependencies": {