authfyio-react 0.3.9

package/README.md

@@ -0,0 +1,83 @@
+# authfyio-react
+
+React SDK for Authfyio. Provides a `<AuthfyioProvider />`, hooks for session state, and a background refresh loop that keeps the short-lived `__session` JWT valid without interrupting your UI.
+
+## Install
+
+```bash
+npm install authfyio-react
+```
+
+Requires React 18 or newer.
+
+## Quick start
+
+```tsx
+// app.tsx
+import { AuthfyioProvider } from 'authfyio-react';
+
+export default function App({ children }: { children: React.ReactNode }) {
+  return (
+    <AuthfyioProvider baseUrl={process.env.REACT_APP_AF_API_URL!}>
+      {children}
+    </AuthfyioProvider>
+  );
+}
+```
+
+```tsx
+// any component
+import { useSession, useUserId } from 'authfyio-react';
+
+export function Avatar() {
+  const session = useSession();
+  const userId = useUserId();
+
+  if (session.status === 'signed_out') return <SignInButton />;
+  return <span>Signed in as {userId}</span>;
+}
+```
+
+## API
+
+### `<AuthfyioProvider />`
+
+| Prop                  | Type      | Default | Description                                                                  |
+| --------------------- | --------- | ------- | ---------------------------------------------------------------------------- |
+| `baseUrl`             | `string`  | —       | Instance API base URL (e.g. `https://auth.example.com`).                     |
+| `autoRefresh`         | `boolean` | `true`  | Runs the refresh loop in the background to keep `__session` fresh.           |
+| `refreshSkewSeconds`  | `number`  | `15`    | How many seconds before JWT expiry to trigger a refresh.                     |
+
+The provider reads the `__session` cookie on mount, decodes its claims, and exposes them to descendants. When `autoRefresh` is on, it schedules a refresh that fires `refreshSkewSeconds` before `exp` and repeats for the lifetime of the session.
+
+### Hooks
+
+- `useSession()` — returns `{ status: 'signed_in', jwt, claims } | { status: 'signed_out' }`.
+- `useUserId()` — returns the `sub` claim when signed in, otherwise `null`.
+- `useAuthfyio()` — returns `{ client, session, refresh }`. `refresh()` lets you trigger a token refresh manually (e.g. after a password change).
+
+### Low-level client
+
+`AuthfyioReactClient` is exposed if you want to skip the provider — useful for scripts or non-React roots. Most apps should not need it.
+
+## How the refresh loop works
+
+Your instance issues two cookies:
+
+- `__client` (httpOnly, long-lived) — held by the browser, used only for the refresh call.
+- `__session` (readable by JS, ~60s) — the JWT your frontend sends to your backend.
+
+The SDK decodes `__session.exp`, schedules `setTimeout(refresh, exp - skew)`, hits the instance's `/v1/auth/refresh` endpoint, and re-reads the new `__session` cookie. The httpOnly `__client` never touches JS memory. If the refresh fails (revoked, network error), state transitions to `signed_out` and children re-render.
+
+## Next.js + Server Components
+
+This package is a **Client SDK** (`'use client'` under the hood). For App Router middleware and server-side session access, use `authfyio-nextjs`.
+
+## Error handling
+
+- `useSession()` never throws — it simply reports `signed_out` when the cookie is missing or invalid.
+- Manual `refresh()` can throw network errors; wrap it in a `try/catch` if you surface retry UI.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,128 @@
+import { type SessionClaims } from './jwt.js';
+export declare const PUBLISHABLE_KEY_HEADER = "x-authfyio-publishable-key";
+export type AuthConfigSnapshot = {
+    signIn: {
+        emailPassword: boolean;
+        usernamePassword: boolean;
+        magicLink: boolean;
+        emailCode: boolean;
+        phoneOtp: boolean;
+        passkey: boolean;
+    };
+    signUp: {
+        enabled: boolean;
+        email: boolean;
+        emailRequired: boolean;
+        username: {
+            required: boolean;
+            minLength: number;
+            maxLength: number;
+        } | null;
+        password: boolean;
+        phone: boolean;
+        firstAndLastName: {
+            required: boolean;
+        } | null;
+        verifyAtSignUp: boolean;
+    };
+    socialProviders: string[];
+    web3Wallets: string[];
+    legal: {
+        termsOfServiceUrl: string | null;
+        privacyPolicyUrl: string | null;
+        requireConsent: boolean;
+    };
+    branding: {
+        primaryColor: string | null;
+        logoUrl: string | null;
+        appName: string | null;
+        removeBranding: boolean;
+    };
+};
+export type AuthfyioReactClientOptions = {
+    baseUrl: string;
+    /**
+     * `pk_live_…` / `pk_test_…` — identifies which environment to route
+     * to on api.authfyio.com. Required when calling the hosted SaaS so
+     * requests don't depend on container-level `AF_ENVIRONMENT_ID`.
+     */
+    publishableKey?: string;
+};
+/**
+ * Minimal browser-side client used by the React hooks. Mirrors the resource
+ * shapes defined in hooks.ts so the type-checker is happy. All methods use
+ * `credentials: 'include'` so the FAPI session cookie travels with the request.
+ */
+export declare class AuthfyioReactClient {
+    readonly baseUrl: string;
+    readonly publishableKey: string | null;
+    constructor(opts: AuthfyioReactClientOptions);
+    private headers;
+    /**
+     * Public auth-method config for this instance — which methods, social
+     * providers and web3 wallets the dashboard has enabled. Safe to call
+     * unauthenticated.
+     */
+    fetchAuthConfig(): Promise<AuthConfigSnapshot | null>;
+    getSessionFromCookies(): {
+        jwt: string;
+        claims: SessionClaims;
+    } | null;
+    refresh(): Promise<{
+        ok: true;
+        jwt: string;
+        claims: SessionClaims;
+    } | {
+        ok: false;
+    }>;
+    fetchCurrentUser(): Promise<{
+        id: string;
+        email: string | null;
+        username: string | null;
+        firstName: string | null;
+        lastName: string | null;
+        publicMetadata: Record<string, unknown>;
+        createdAt: string;
+    } | null>;
+    fetchOrganization(orgId: string): Promise<{
+        id: string;
+        name: string;
+        slug: string;
+    } | null>;
+    fetchPlans(): Promise<Array<{
+        id: string;
+        name: string;
+        description: string | null;
+        monthlyPriceCents: number;
+        annualPriceCents: number | null;
+    }>>;
+    /**
+     * Returns the caller's effective plan + attached features, used by
+     * `useAuth().has({ plan })` / `has({ feature })` and `<Protect>` /
+     * `<Show when>`. Always served by the instance API; returns `null` for
+     * signed-out users.
+     */
+    fetchMyBilling(): Promise<{
+        plan: {
+            id: string;
+            key: string | null;
+            name: string;
+        } | null;
+        features: Array<{
+            key: string;
+            name: string;
+            description?: string;
+        }>;
+        status: string | null;
+    } | null>;
+    fetchSubscription(): Promise<{
+        id: string;
+        status: string;
+        planId: string;
+        currentPeriodEnd: string | null;
+    } | null>;
+    createCheckoutSession(planId: string, billingCycle?: 'monthly' | 'annual'): Promise<{
+        url: string;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,227 @@
+import { decodeJwtPayload, getSessionJwtFromDocumentCookie } from './jwt.js';
+export const PUBLISHABLE_KEY_HEADER = 'x-authfyio-publishable-key';
+/**
+ * Minimal browser-side client used by the React hooks. Mirrors the resource
+ * shapes defined in hooks.ts so the type-checker is happy. All methods use
+ * `credentials: 'include'` so the FAPI session cookie travels with the request.
+ */
+export class AuthfyioReactClient {
+    // Public so UI components (notably <SignIn>) can append the
+    // publishable key to OAuth /authorize anchors as a query string.
+    // Top-level browser navigations don't carry custom headers, so the
+    // header path used by fetch() requests doesn't apply here.
+    baseUrl;
+    publishableKey;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.publishableKey = opts.publishableKey ?? null;
+    }
+    headers(extra = {}) {
+        const out = { ...extra };
+        if (this.publishableKey)
+            out[PUBLISHABLE_KEY_HEADER] = this.publishableKey;
+        return out;
+    }
+    /**
+     * Public auth-method config for this instance — which methods, social
+     * providers and web3 wallets the dashboard has enabled. Safe to call
+     * unauthenticated.
+     */
+    async fetchAuthConfig() {
+        const res = await fetch(`${this.baseUrl}/v1/auth/config`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body || typeof body !== 'object')
+            return null;
+        const si = body.signIn ?? {};
+        const su = body.signUp ?? {};
+        return {
+            signIn: {
+                emailPassword: !!si.emailPassword,
+                usernamePassword: !!si.usernamePassword,
+                magicLink: !!si.magicLink,
+                emailCode: !!si.emailCode,
+                phoneOtp: !!si.phoneOtp,
+                passkey: !!si.passkey,
+            },
+            signUp: {
+                enabled: su.enabled !== false,
+                email: !!su.email,
+                emailRequired: !!su.emailRequired,
+                username: su.username
+                    ? {
+                        required: su.username.required === true,
+                        minLength: Number(su.username.minLength ?? 4),
+                        maxLength: Number(su.username.maxLength ?? 64),
+                    }
+                    : null,
+                password: !!su.password,
+                phone: !!su.phone,
+                firstAndLastName: su.firstAndLastName ? { required: su.firstAndLastName.required === true } : null,
+                verifyAtSignUp: !!su.verifyAtSignUp,
+            },
+            socialProviders: Array.isArray(body.socialProviders) ? body.socialProviders.map(String) : [],
+            web3Wallets: Array.isArray(body.web3Wallets) ? body.web3Wallets.map(String) : [],
+            legal: {
+                termsOfServiceUrl: typeof body.legal?.termsOfServiceUrl === 'string' ? body.legal.termsOfServiceUrl : null,
+                privacyPolicyUrl: typeof body.legal?.privacyPolicyUrl === 'string' ? body.legal.privacyPolicyUrl : null,
+                requireConsent: body.legal?.requireConsent === true,
+            },
+            branding: {
+                primaryColor: typeof body.branding?.primaryColor === 'string' ? body.branding.primaryColor : null,
+                logoUrl: typeof body.branding?.logoUrl === 'string' ? body.branding.logoUrl : null,
+                appName: typeof body.branding?.appName === 'string' ? body.branding.appName : null,
+                removeBranding: body.branding?.removeBranding === true,
+            },
+        };
+    }
+    getSessionFromCookies() {
+        const jwt = getSessionJwtFromDocumentCookie();
+        if (!jwt)
+            return null;
+        const claims = decodeJwtPayload(jwt);
+        return { jwt, claims };
+    }
+    async refresh() {
+        const res = await fetch(`${this.baseUrl}/v1/auth/sessions/refresh`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: this.headers({ 'content-type': 'application/json' }),
+            body: JSON.stringify({}),
+        });
+        if (!res.ok)
+            return { ok: false };
+        const next = this.getSessionFromCookies();
+        if (!next)
+            return { ok: false };
+        return { ok: true, jwt: next.jwt, claims: next.claims };
+    }
+    async fetchCurrentUser() {
+        const res = await fetch(`${this.baseUrl}/v1/auth/sessions/current`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body?.user?.id)
+            return null;
+        const u = body.user;
+        return {
+            id: String(u.id),
+            email: u.email ?? null,
+            username: u.username ?? null,
+            firstName: u.firstName ?? null,
+            lastName: u.lastName ?? null,
+            publicMetadata: (u.publicMetadata ?? {}),
+            createdAt: String(u.createdAt ?? new Date().toISOString()),
+        };
+    }
+    async fetchOrganization(orgId) {
+        const res = await fetch(`${this.baseUrl}/v1/orgs/${encodeURIComponent(orgId)}`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body?.organization?.id)
+            return null;
+        const o = body.organization;
+        return { id: String(o.id), name: String(o.name), slug: String(o.slug) };
+    }
+    async fetchPlans() {
+        const res = await fetch(`${this.baseUrl}/v1/billing/plans`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return [];
+        const body = (await res.json());
+        if (!Array.isArray(body?.plans))
+            return [];
+        return body.plans.map((p) => ({
+            id: String(p.id),
+            name: String(p.name),
+            description: p.description ?? null,
+            monthlyPriceCents: Number(p.monthlyPriceCents ?? 0),
+            annualPriceCents: p.annualPriceCents == null ? null : Number(p.annualPriceCents),
+        }));
+    }
+    /**
+     * Returns the caller's effective plan + attached features, used by
+     * `useAuth().has({ plan })` / `has({ feature })` and `<Protect>` /
+     * `<Show when>`. Always served by the instance API; returns `null` for
+     * signed-out users.
+     */
+    async fetchMyBilling() {
+        const res = await fetch(`${this.baseUrl}/v1/billing/me`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body)
+            return null;
+        return {
+            plan: body.plan
+                ? {
+                    id: String(body.plan.id),
+                    key: body.plan.key ?? null,
+                    name: String(body.plan.name ?? ''),
+                }
+                : null,
+            features: Array.isArray(body.features)
+                ? body.features.map((f) => ({
+                    key: String(f.key),
+                    name: String(f.name ?? f.key),
+                    description: f.description ?? undefined,
+                }))
+                : [],
+            status: body.status ?? null,
+        };
+    }
+    async fetchSubscription() {
+        const res = await fetch(`${this.baseUrl}/v1/billing/subscription`, {
+            method: 'GET',
+            credentials: 'include',
+            headers: this.headers({ accept: 'application/json' }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body?.subscription?.id)
+            return null;
+        const s = body.subscription;
+        return {
+            id: String(s.id),
+            status: String(s.status),
+            planId: String(s.planId),
+            currentPeriodEnd: s.currentPeriodEnd ?? null,
+        };
+    }
+    async createCheckoutSession(planId, billingCycle = 'monthly') {
+        const res = await fetch(`${this.baseUrl}/v1/billing/checkout`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: this.headers({ 'content-type': 'application/json', accept: 'application/json' }),
+            body: JSON.stringify({ planId, billingCycle }),
+        });
+        if (!res.ok)
+            throw new Error(`checkout_failed_${res.status}`);
+        const body = (await res.json());
+        if (!body?.url)
+            throw new Error('checkout_no_url');
+        return { url: body.url };
+    }
+}

package/dist/components.d.ts

@@ -0,0 +1,79 @@
+import React from 'react';
+/**
+ * Renders its children only when there's an active session. Server-side
+ * it renders nothing until the provider hydrates, so wrap it in a client
+ * component tree (the AuthfyioProvider already is).
+ */
+export declare function SignedIn({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement | null;
+/**
+ * Renders its children only when the session is absent or expired.
+ */
+export declare function SignedOut({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement | null;
+export type ProtectProps = {
+    children: React.ReactNode;
+    /** Require an org role (matches the session's `org_role` claim). */
+    role?: string;
+    /** Require an active subscription to a plan by stable key (e.g. "pro"). */
+    plan?: string;
+    /** Require a specific feature attached to the user's active plan. */
+    feature?: string;
+    /** Fallback rendered when the user is signed out or fails the check. */
+    fallback?: React.ReactNode;
+};
+/**
+ * Renders `children` when the user is signed in AND satisfies every provided
+ * check (`role`, `plan`, `feature`). Otherwise renders `fallback`. Use this
+ * for component-level authorization inside larger unprotected pages.
+ */
+export declare function Protect({ children, role, plan, feature, fallback, }: ProtectProps): React.ReactElement | null;
+export type ShowProps = {
+    children: React.ReactNode;
+    /** Conditions; all must match (AND). */
+    when: {
+        plan?: string;
+        feature?: string;
+        role?: string;
+    };
+    /** Rendered when the check fails. */
+    fallback?: React.ReactNode;
+};
+/**
+ * customisable `<Show when={{plan,feature,role}}>`. Thin wrapper over
+ * `auth.has({...})`. Returns nothing while the check is loading so you
+ * don't flash the fallback state.
+ */
+export declare function Show({ children, when, fallback }: ShowProps): React.ReactElement | null;
+export type RedirectToSignInProps = {
+    /** Target path on your app that renders the sign-in form (default: '/sign-in'). */
+    signInUrl?: string;
+    /** Optional query parameter carrying the caller URL so you can return after sign-in. */
+    afterSignInParam?: string;
+};
+/**
+ * Client-side redirect to the sign-in page. Fire-and-forget: it navigates on
+ * mount via `window.location.replace` so it also works inside React trees
+ * without `next/navigation`. Prefer `<SignedOut>` + this for guarded UIs.
+ */
+export declare function RedirectToSignIn({ signInUrl, afterSignInParam, }: RedirectToSignInProps): null;
+export type RedirectToSignUpProps = {
+    signUpUrl?: string;
+    afterSignUpParam?: string;
+};
+export declare function RedirectToSignUp({ signUpUrl, afterSignUpParam, }: RedirectToSignUpProps): null;
+export type SignOutButtonProps = {
+    children?: React.ReactNode;
+    /** Redirect target after sign-out completes. Defaults to '/'. */
+    redirectUrl?: string;
+    className?: string;
+};
+/**
+ * Convenience button — calls `POST /v1/auth/sign-out` on the instance API,
+ * then navigates to `redirectUrl`. Use inside `<SignedIn>` or check `isSignedIn`
+ * yourself. Uses the provider's configured baseUrl.
+ */
+export declare function SignOutButton({ children, redirectUrl, className }: SignOutButtonProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAoB,MAAM,OAAO,CAAC;AAKzC;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAIhG;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,QAAe,GAChB,EAAE,YAAY,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAY1C;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,wCAAwC;IACxC,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAe,EAAE,EAAE,SAAS,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAK9F;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,SAAsB,EACtB,gBAAiC,GAClC,EAAE,qBAAqB,GAAG,IAAI,CAS9B;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAC/B,SAAsB,EACtB,gBAAiC,GAClC,EAAE,qBAAqB,GAAG,IAAI,CAS9B;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,WAAiB,EAAE,SAAS,EAAE,EAAE,kBAAkB,2CAiB3F"}

package/dist/components.js

@@ -0,0 +1,111 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { useSession, useAuthfyio } from './provider.js';
+import { useAuth } from './hooks.js';
+/**
+ * Renders its children only when there's an active session. Server-side
+ * it renders nothing until the provider hydrates, so wrap it in a client
+ * component tree (the AuthfyioProvider already is).
+ */
+export function SignedIn({ children }) {
+    const s = useSession();
+    if (s.status !== 'signed_in')
+        return null;
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Renders its children only when the session is absent or expired.
+ */
+export function SignedOut({ children }) {
+    const s = useSession();
+    if (s.status === 'signed_in')
+        return null;
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Renders `children` when the user is signed in AND satisfies every provided
+ * check (`role`, `plan`, `feature`). Otherwise renders `fallback`. Use this
+ * for component-level authorization inside larger unprotected pages.
+ */
+export function Protect({ children, role, plan, feature, fallback = null, }) {
+    const auth = useAuth();
+    if (!auth.isSignedIn)
+        return _jsx(_Fragment, { children: fallback });
+    const checks = [];
+    if (role)
+        checks.push(auth.has({ role }));
+    if (plan)
+        checks.push(auth.has({ plan }));
+    if (feature)
+        checks.push(auth.has({ feature }));
+    // While any async check is still resolving (`undefined`), render nothing to
+    // avoid a flash of the fallback. Once all checks settle to booleans, render.
+    if (checks.some((c) => c === undefined))
+        return null;
+    if (checks.some((c) => c === false))
+        return _jsx(_Fragment, { children: fallback });
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * customisable `<Show when={{plan,feature,role}}>`. Thin wrapper over
+ * `auth.has({...})`. Returns nothing while the check is loading so you
+ * don't flash the fallback state.
+ */
+export function Show({ children, when, fallback = null }) {
+    const auth = useAuth();
+    const result = auth.has(when);
+    if (result === undefined)
+        return null;
+    return result ? _jsx(_Fragment, { children: children }) : _jsx(_Fragment, { children: fallback });
+}
+/**
+ * Client-side redirect to the sign-in page. Fire-and-forget: it navigates on
+ * mount via `window.location.replace` so it also works inside React trees
+ * without `next/navigation`. Prefer `<SignedOut>` + this for guarded UIs.
+ */
+export function RedirectToSignIn({ signInUrl = '/sign-in', afterSignInParam = 'redirect_url', }) {
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const next = window.location.pathname + window.location.search;
+        const url = new URL(signInUrl, window.location.origin);
+        if (next && next !== '/')
+            url.searchParams.set(afterSignInParam, next);
+        window.location.replace(url.toString());
+    }, [signInUrl, afterSignInParam]);
+    return null;
+}
+export function RedirectToSignUp({ signUpUrl = '/sign-up', afterSignUpParam = 'redirect_url', }) {
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const next = window.location.pathname + window.location.search;
+        const url = new URL(signUpUrl, window.location.origin);
+        if (next && next !== '/')
+            url.searchParams.set(afterSignUpParam, next);
+        window.location.replace(url.toString());
+    }, [signUpUrl, afterSignUpParam]);
+    return null;
+}
+/**
+ * Convenience button — calls `POST /v1/auth/sign-out` on the instance API,
+ * then navigates to `redirectUrl`. Use inside `<SignedIn>` or check `isSignedIn`
+ * yourself. Uses the provider's configured baseUrl.
+ */
+export function SignOutButton({ children, redirectUrl = '/', className }) {
+    const { client } = useAuthfyio();
+    async function onClick() {
+        try {
+            await fetch(`${client.baseUrl ?? ''}/v1/auth/sign-out`, {
+                method: 'POST',
+                credentials: 'include',
+            });
+        }
+        finally {
+            if (typeof window !== 'undefined')
+                window.location.href = redirectUrl;
+        }
+    }
+    return (_jsx("button", { type: "button", onClick: onClick, className: className, children: children ?? 'Sign out' }));
+}