@atlasauth/react 0.1.0

package/dist/AtlasProvider.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from 'react';
+import { type ProviderToken } from '@atlasauth/js';
+import { type Appearance } from './appearance';
+import { type Catalog } from './i18n';
+import type { AtlasOrganizationMembership, AtlasSession, AtlasUser, SessionClaims } from './types';
+/**
+ * §10.1 `<AtlasProvider publishableKey>`.
+ *
+ * Holds exactly one thing that matters: the token, in memory. Not
+ * localStorage, not a cookie this code writes — the refresh token is HttpOnly
+ * so browser script never touches it, and the short-lived JWT lives only as
+ * long as the tab. A provider that persisted either would survive the tab and
+ * become the thing an XSS reads first.
+ */
+export type AuthStatus = 'loading' | 'signed_in' | 'signed_out';
+interface AtlasContextValue {
+    publishableKey: string;
+    frontendApi: string;
+    status: AuthStatus;
+    user: AtlasUser | null;
+    session: AtlasSession | null;
+    claims: SessionClaims | null;
+    memberships: AtlasOrganizationMembership[];
+    appearance?: Appearance;
+    catalog: Catalog;
+    /**
+     * §5.3: a sign-in attempt handed back by an OAuth redirect that still needs a
+     * second factor (no session was issued). Null in the ordinary case. The
+     * <SignIn> flow seeds itself from this so the user resumes at the 2FA step
+     * instead of starting over.
+     */
+    pendingAttempt: {
+        id: string;
+        status: string;
+    } | null;
+    getToken(): Promise<string | null>;
+    /**
+     * §6.6 the signed-in user's OWN live token at a connected provider (Google,
+     * GitHub, …), so the app can call that provider's API. Null when there is no
+     * usable token — no linked account, or the provider granted / kept none. The
+     * server refreshes a stale token on read; the refresh token is never exposed.
+     */
+    getProviderToken(provider: string): Promise<ProviderToken | null>;
+    signOut(): Promise<void>;
+    setActiveOrganization(organizationId: string | null): Promise<void>;
+    reload(): Promise<void>;
+}
+export interface AtlasProviderProps {
+    publishableKey: string;
+    /** The instance's FAPI origin. */
+    frontendApi?: string;
+    appearance?: Appearance;
+    localization?: Catalog;
+    children: ReactNode;
+    fetchImpl?: typeof fetch;
+}
+export declare function AtlasProvider(props: AtlasProviderProps): import("react").JSX.Element;
+export declare function useAtlas(): AtlasContextValue;
+export {};

package/dist/AtlasProvider.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlasProvider = AtlasProvider;
+exports.useAtlas = useAtlas;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const js_1 = require("@atlasauth/js");
+const appearance_1 = require("./appearance");
+const i18n_1 = require("./i18n");
+const AtlasContext = (0, react_1.createContext)(null);
+function AtlasProvider(props) {
+    const { publishableKey, children, appearance, localization } = props;
+    const baseUrl = props.frontendApi ?? '';
+    const doFetch = props.fetchImpl ?? fetch;
+    const [status, setStatus] = (0, react_1.useState)('loading');
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [session, setSession] = (0, react_1.useState)(null);
+    const [claims, setClaims] = (0, react_1.useState)(null);
+    const [memberships, setMemberships] = (0, react_1.useState)([]);
+    const cache = (0, react_1.useRef)(new js_1.TokenCache());
+    const timer = (0, react_1.useRef)(null);
+    /**
+     * Captured synchronously during the first render (not in an effect) so it is
+     * already in context before <SignIn> reads it — a needs_second_factor redirect
+     * carries a status but no ticket, and that is what the 2FA resume seeds from.
+     */
+    const [pendingAttempt] = (0, react_1.useState)(() => {
+        if (typeof window === 'undefined')
+            return null;
+        const result = (0, js_1.readRedirectResult)(window.location.search);
+        return result?.status && !result.ticket
+            ? { id: result.attemptId, status: result.status }
+            : null;
+    });
+    const call = (0, react_1.useCallback)(async (path, init) => {
+        return doFetch(`${baseUrl}${path}`, {
+            ...init,
+            // Cookies carry the session; a fetch without this looks identical to
+            // being signed out.
+            credentials: 'include',
+            headers: {
+                'x-publishable-key': publishableKey,
+                ...(init?.body ? { 'content-type': 'application/json' } : {}),
+                ...init?.headers,
+            },
+        });
+    }, [baseUrl, doFetch, publishableKey]);
+    const applyToken = (0, react_1.useCallback)((jwt, sessionId) => {
+        const expiresAt = (0, js_1.readExpiry)(jwt);
+        if (!expiresAt)
+            return;
+        cache.current.set({ jwt, expiresAt, sessionId });
+        setClaims(decodeClaims(jwt));
+    }, []);
+    const reload = (0, react_1.useCallback)(async () => {
+        try {
+            const response = await call('/v1/client');
+            if (!response.ok)
+                throw new Error('boot failed');
+            const body = (await response.json());
+            if (!body.session || !body.user) {
+                cache.current.clear();
+                setStatus('signed_out');
+                setUser(null);
+                setSession(null);
+                setClaims(null);
+                setMemberships([]);
+                return;
+            }
+            setUser(body.user);
+            setSession(body.session);
+            setMemberships(body.organization_memberships ?? []);
+            if (body.jwt)
+                applyToken(body.jwt, body.session.id);
+            setStatus('signed_in');
+        }
+        catch {
+            /**
+             * A failed boot is NOT signed-out. Rendering a sign-in form because the
+             * network hiccuped throws away a perfectly good session and makes the
+             * user re-authenticate for no reason.
+             */
+            setStatus((current) => (current === 'loading' ? 'signed_out' : current));
+        }
+    }, [applyToken, call]);
+    const refresh = (0, react_1.useCallback)(async () => {
+        const current = cache.current.peek();
+        if (!current)
+            return;
+        try {
+            const response = await call(`/v1/client/sessions/${current.sessionId}/tokens`, {
+                method: 'POST',
+            });
+            if (!response.ok)
+                throw new Error('refresh failed');
+            const body = (await response.json());
+            applyToken(body.jwt, body.session_id);
+        }
+        catch {
+            // The session may genuinely be gone. Re-boot rather than guess.
+            await reload();
+        }
+    }, [applyToken, call, reload]);
+    /** §7.4: proactive, jittered refresh scheduled from the token's own expiry. */
+    (0, react_1.useEffect)(() => {
+        if (status !== 'signed_in')
+            return;
+        const token = cache.current.peek();
+        if (!token)
+            return;
+        const delay = (0, js_1.msUntilRefresh)({ token, now: Date.now() });
+        timer.current = setTimeout(() => void refresh(), delay);
+        return () => {
+            if (timer.current)
+                clearTimeout(timer.current);
+        };
+    }, [status, claims, refresh]);
+    /**
+     * §6.3 step 3: complete a redirect-based sign-in. An OAuth or hosted-page flow
+     * lands back here with a one-time ticket in the URL; exchange it for cookies,
+     * scrub the URL so a reload can't replay it, THEN boot. A redirect that only
+     * carries a `__atlas_status` (a second factor is still owed) has no ticket, so
+     * nothing is exchanged and the app boots signed-out — exactly as intended.
+     */
+    (0, react_1.useEffect)(() => {
+        const result = typeof window !== 'undefined' ? (0, js_1.readRedirectResult)(window.location.search) : null;
+        void (async () => {
+            if (result?.ticket) {
+                await call('/v1/client/tickets/exchange', {
+                    method: 'POST',
+                    body: JSON.stringify({ attempt_id: result.attemptId, ticket: result.ticket }),
+                }).catch(() => undefined);
+            }
+            if (result && typeof window !== 'undefined') {
+                window.history.replaceState({}, document.title, (0, js_1.stripRedirectParams)(window.location.href));
+            }
+            await reload();
+        })();
+        // Runs once on mount (empty deps): the redirect is handled exactly once, and
+        // re-running would only re-read an already-scrubbed URL. `reload`/`call` are
+        // stable across renders.
+    }, []);
+    const getToken = (0, react_1.useCallback)(async () => {
+        // A 5s skew so a token that would die inside the caller's request is
+        // refreshed first rather than handed over.
+        const usable = cache.current.get(5_000);
+        if (usable)
+            return usable.jwt;
+        await refresh();
+        return cache.current.get(5_000)?.jwt ?? null;
+    }, [refresh]);
+    /**
+     * The FAPI client for the token-vault read. Reuses the exact same
+     * credentials-and-publishable-key request `call` makes, so the browser sends
+     * one consistent shape and the framework-agnostic `@atlasauth/js` helper is the
+     * single implementation the React SDK surfaces.
+     */
+    const fapiClient = (0, react_1.useMemo)(() => new js_1.FapiClient({ publishableKey, baseUrl, fetchImpl: doFetch }), [publishableKey, baseUrl, doFetch]);
+    const getProviderToken = (0, react_1.useCallback)((provider) => (0, js_1.getProviderToken)(fapiClient, provider), [fapiClient]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        const current = cache.current.peek();
+        if (current) {
+            await call(`/v1/client/sessions/${current.sessionId}/revoke`, { method: 'POST' }).catch(() => undefined);
+        }
+        cache.current.clear();
+        setStatus('signed_out');
+        setUser(null);
+        setSession(null);
+        setClaims(null);
+        setMemberships([]);
+    }, [call]);
+    const setActiveOrganization = (0, react_1.useCallback)(async (organizationId) => {
+        const current = cache.current.peek();
+        if (!current)
+            return;
+        const response = await call(`/v1/client/sessions/${current.sessionId}/touch`, {
+            method: 'POST',
+            body: JSON.stringify({ active_organization_id: organizationId }),
+        });
+        if (!response.ok)
+            return;
+        const body = (await response.json());
+        // The new token carries the new org claims; re-boot would work too but
+        // costs a round trip for information already in hand.
+        applyToken(body.jwt, current.sessionId);
+        await reload();
+    }, [applyToken, call, reload]);
+    const catalog = (0, react_1.useMemo)(() => (localization ? (0, i18n_1.withFallback)(localization) : i18n_1.EN_US), [localization]);
+    const value = (0, react_1.useMemo)(() => ({
+        publishableKey,
+        frontendApi: baseUrl,
+        status,
+        user,
+        session,
+        claims,
+        memberships,
+        appearance,
+        catalog,
+        pendingAttempt,
+        getToken,
+        getProviderToken,
+        signOut,
+        setActiveOrganization,
+        reload,
+    }), [
+        appearance,
+        baseUrl,
+        publishableKey,
+        catalog,
+        claims,
+        getToken,
+        getProviderToken,
+        memberships,
+        pendingAttempt,
+        reload,
+        session,
+        setActiveOrganization,
+        signOut,
+        status,
+        user,
+    ]);
+    const style = (0, react_1.useMemo)(() => (0, appearance_1.cssVariables)((0, appearance_1.resolveTokens)(appearance)), [appearance]);
+    return ((0, jsx_runtime_1.jsx)(AtlasContext.Provider, { value: value, children: (0, jsx_runtime_1.jsx)("div", { className: "atlas-root", style: style, children: children }) }));
+}
+function useAtlas() {
+    const value = (0, react_1.useContext)(AtlasContext);
+    if (!value) {
+        /**
+         * A thrown error rather than a null-ish default. A hook returning
+         * `{ user: null }` outside the provider is indistinguishable from a
+         * signed-out user, and the developer spends an afternoon on it.
+         */
+        throw new Error('Atlas hooks must be used inside <AtlasProvider>.');
+    }
+    return value;
+}
+function decodeClaims(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        return JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=AtlasProvider.js.map

package/dist/AtlasProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtlasProvider.js","sourceRoot":"","sources":["../src/AtlasProvider.tsx"],"names":[],"mappings":"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"}

package/dist/appearance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * §10.3 theming.
+ *
+ * "appearance prop: design tokens (colors, radius, font, spacing) + per-element
+ * class overrides (elements: { formButtonPrimary: "…" }). No iframe — components
+ * render in the host DOM so Tailwind/CSS just works."
+ *
+ * Rendering in the host DOM is the decision everything else follows from. An
+ * iframe would isolate styles perfectly and be unusable: it cannot be sized to
+ * its content reliably, it breaks password managers, it breaks autofill, and a
+ * Tailwind class the customer writes has no effect inside it. Sharing the DOM
+ * means the customer's CSS reaches our markup, which is exactly what they want
+ * and what makes an override system necessary rather than decorative.
+ *
+ * Element classes are APPENDED to ours, never replacing them. A customer adding
+ * `className="rounded-xl"` wants a rounder button, not an unstyled one — and
+ * replacement is a support burden where every override starts by rebuilding the
+ * component's base styles from scratch.
+ */
+export interface DesignTokens {
+    colorPrimary?: string;
+    colorText?: string;
+    colorBackground?: string;
+    colorDanger?: string;
+    colorBorder?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    spacingUnit?: string;
+}
+/** Every element a customer may target. Named for what it IS, not where it sits. */
+export type ElementKey = 'root' | 'card' | 'headerTitle' | 'headerSubtitle' | 'formField' | 'formFieldLabel' | 'formFieldInput' | 'formFieldError' | 'formButtonPrimary' | 'formButtonSecondary' | 'socialButton' | 'dividerText' | 'footerAction' | 'avatar' | 'menu' | 'menuItem' | 'badge';
+export interface Appearance {
+    /** A prebuilt theme to start from. */
+    baseTheme?: keyof typeof THEMES;
+    variables?: DesignTokens;
+    elements?: Partial<Record<ElementKey, string>>;
+}
+export declare const DEFAULT_TOKENS: Required<DesignTokens>;
+/**
+ * §10.3: "prebuilt themes shipped (default, dark, neobrutalist as a demo of the
+ * override system)". Neobrutalist exists to prove the token set is expressive
+ * enough for a theme that looks nothing like the default — a theming system
+ * that only produces tasteful variations of itself is not a theming system.
+ */
+export declare const THEMES: {
+    readonly default: Required<DesignTokens>;
+    readonly dark: {
+        readonly colorText: "#e6e9ef";
+        readonly colorBackground: "#14171c";
+        readonly colorBorder: "#242932";
+        readonly colorPrimary: "#6ea8fe";
+        readonly colorDanger: string;
+        readonly borderRadius: string;
+        readonly fontFamily: string;
+        readonly spacingUnit: string;
+    };
+    readonly neobrutalist: {
+        readonly colorPrimary: "#ffe600";
+        readonly colorText: "#000000";
+        readonly colorBackground: "#ffffff";
+        readonly colorBorder: "#000000";
+        readonly borderRadius: "0px";
+        readonly fontFamily: "\"Courier New\", ui-monospace, monospace";
+        readonly colorDanger: string;
+        readonly spacingUnit: string;
+    };
+};
+/**
+ * Resolve tokens: defaults, then the base theme, then explicit variables.
+ *
+ * Later wins, and `undefined` never overwrites. A customer setting one variable
+ * on the dark theme expects the other eleven to stay dark, not silently revert
+ * to the light defaults.
+ */
+export declare function resolveTokens(appearance?: Appearance): Required<DesignTokens>;
+/** Tokens as CSS custom properties, for the host DOM to inherit. */
+export declare function cssVariables(tokens: Required<DesignTokens>): Record<string, string>;
+/**
+ * Combine our base class with the customer's override.
+ *
+ * Appended, never replaced — a customer adding `rounded-xl` wants a rounder
+ * button, not an unstyled one. Theirs comes last so it wins on equal
+ * specificity, which is the behaviour anyone writing Tailwind expects.
+ */
+export declare function classFor(element: ElementKey, appearance: Appearance | undefined, base: string): string;

package/dist/appearance.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * §10.3 theming.
+ *
+ * "appearance prop: design tokens (colors, radius, font, spacing) + per-element
+ * class overrides (elements: { formButtonPrimary: "…" }). No iframe — components
+ * render in the host DOM so Tailwind/CSS just works."
+ *
+ * Rendering in the host DOM is the decision everything else follows from. An
+ * iframe would isolate styles perfectly and be unusable: it cannot be sized to
+ * its content reliably, it breaks password managers, it breaks autofill, and a
+ * Tailwind class the customer writes has no effect inside it. Sharing the DOM
+ * means the customer's CSS reaches our markup, which is exactly what they want
+ * and what makes an override system necessary rather than decorative.
+ *
+ * Element classes are APPENDED to ours, never replacing them. A customer adding
+ * `className="rounded-xl"` wants a rounder button, not an unstyled one — and
+ * replacement is a support burden where every override starts by rebuilding the
+ * component's base styles from scratch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THEMES = exports.DEFAULT_TOKENS = void 0;
+exports.resolveTokens = resolveTokens;
+exports.cssVariables = cssVariables;
+exports.classFor = classFor;
+exports.DEFAULT_TOKENS = {
+    colorPrimary: '#5b5bd6',
+    colorText: '#1c1c1f',
+    colorBackground: '#ffffff',
+    colorDanger: '#d64545',
+    colorBorder: '#e4e4e9',
+    borderRadius: '8px',
+    fontFamily: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+    spacingUnit: '4px',
+};
+/**
+ * §10.3: "prebuilt themes shipped (default, dark, neobrutalist as a demo of the
+ * override system)". Neobrutalist exists to prove the token set is expressive
+ * enough for a theme that looks nothing like the default — a theming system
+ * that only produces tasteful variations of itself is not a theming system.
+ */
+exports.THEMES = {
+    default: exports.DEFAULT_TOKENS,
+    dark: {
+        ...exports.DEFAULT_TOKENS,
+        colorText: '#e6e9ef',
+        colorBackground: '#14171c',
+        colorBorder: '#242932',
+        colorPrimary: '#6ea8fe',
+    },
+    neobrutalist: {
+        ...exports.DEFAULT_TOKENS,
+        colorPrimary: '#ffe600',
+        colorText: '#000000',
+        colorBackground: '#ffffff',
+        colorBorder: '#000000',
+        borderRadius: '0px',
+        fontFamily: '"Courier New", ui-monospace, monospace',
+    },
+};
+/**
+ * Resolve tokens: defaults, then the base theme, then explicit variables.
+ *
+ * Later wins, and `undefined` never overwrites. A customer setting one variable
+ * on the dark theme expects the other eleven to stay dark, not silently revert
+ * to the light defaults.
+ */
+function resolveTokens(appearance) {
+    const base = appearance?.baseTheme ? exports.THEMES[appearance.baseTheme] : exports.DEFAULT_TOKENS;
+    const overrides = appearance?.variables ?? {};
+    const resolved = { ...exports.DEFAULT_TOKENS, ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    return resolved;
+}
+/** Tokens as CSS custom properties, for the host DOM to inherit. */
+function cssVariables(tokens) {
+    const vars = {};
+    for (const [key, value] of Object.entries(tokens)) {
+        // camelCase → --atlas-kebab-case, which is what a customer writes in CSS.
+        vars[`--atlas-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`] = value;
+    }
+    return vars;
+}
+/**
+ * Combine our base class with the customer's override.
+ *
+ * Appended, never replaced — a customer adding `rounded-xl` wants a rounder
+ * button, not an unstyled one. Theirs comes last so it wins on equal
+ * specificity, which is the behaviour anyone writing Tailwind expects.
+ */
+function classFor(element, appearance, base) {
+    const override = appearance?.elements?.[element];
+    return override ? `${base} ${override}` : base;
+}
+//# sourceMappingURL=appearance.js.map

package/dist/appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.js","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAoFH,sCASC;AAGD,oCAOC;AASD,4BAOC;AA/EY,QAAA,cAAc,GAA2B;IACpD,YAAY,EAAE,SAAS;IACvB,SAAS,EAAE,SAAS;IACpB,eAAe,EAAE,SAAS;IAC1B,WAAW,EAAE,SAAS;IACtB,WAAW,EAAE,SAAS;IACtB,YAAY,EAAE,KAAK;IACnB,UAAU,EAAE,iEAAiE;IAC7E,WAAW,EAAE,KAAK;CACnB,CAAC;AAEF;;;;;GAKG;AACU,QAAA,MAAM,GAAG;IACpB,OAAO,EAAE,sBAAc;IACvB,IAAI,EAAE;QACJ,GAAG,sBAAc;QACjB,SAAS,EAAE,SAAS;QACpB,eAAe,EAAE,SAAS;QAC1B,WAAW,EAAE,SAAS;QACtB,YAAY,EAAE,SAAS;KACxB;IACD,YAAY,EAAE;QACZ,GAAG,sBAAc;QACjB,YAAY,EAAE,SAAS;QACvB,SAAS,EAAE,SAAS;QACpB,eAAe,EAAE,SAAS;QAC1B,WAAW,EAAE,SAAS;QACtB,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,wCAAwC;KACrD;CACwD,CAAC;AAE5D;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,UAAuB;IACnD,MAAM,IAAI,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,cAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,sBAAc,CAAC;IACnF,MAAM,SAAS,GAAG,UAAU,EAAE,SAAS,IAAI,EAAE,CAAC;IAE9C,MAAM,QAAQ,GAAG,EAAE,GAAG,sBAAc,EAAE,GAAG,IAAI,EAAE,CAAC;IAChD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,GAAyB,CAAC,GAAG,KAAK,CAAC;IACvE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,oEAAoE;AACpE,SAAgB,YAAY,CAAC,MAA8B;IACzD,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,0EAA0E;QAC1E,IAAI,CAAC,WAAW,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,OAAmB,EACnB,UAAkC,EAClC,IAAY;IAEZ,MAAM,QAAQ,GAAG,UAAU,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/dist/components.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from 'react';
+import { type ProtectCondition } from './protect';
+export declare function SignedIn({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+export declare function SignedOut({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** §10.2: render children only while the SDK is still loading. */
+export declare function AtlasLoading({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** §10.2: render children only once the SDK has finished loading — the
+ * symmetric partner of {@link AtlasLoading}, so a consumer can show a spinner
+ * and its resolved content without hand-rolling the inverse condition. */
+export declare function AtlasLoaded({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/**
+ * §10.2 `<Protect permission="…">`.
+ *
+ * A rendering helper, never an authorization boundary — anyone can flip the
+ * condition in devtools. The server checking the same permission is what
+ * actually stops them, and this component's job is only to avoid showing a
+ * button that would fail.
+ */
+export declare function Protect({ children, fallback, ...condition }: ProtectCondition & {
+    children: ReactNode;
+    fallback?: ReactNode;
+}): import("react").JSX.Element | null;
+export interface FlowProps {
+    /** Where to send the user once the flow completes. */
+    afterUrl?: string;
+}
+export declare function SignIn(_props?: FlowProps): import("react").JSX.Element;
+export declare function SignUp(_props?: FlowProps): import("react").JSX.Element;
+export declare function UserButton(): import("react").JSX.Element | null;
+export declare function OrganizationSwitcher(): import("react").JSX.Element;
+export declare function UserProfile(): import("react").JSX.Element | null;
+export declare function OrganizationProfile(): import("react").JSX.Element | null;