authvital-sdk 0.1.1-dev.3.cefb119.0

package/dist/index.d.ts

@@ -0,0 +1,615 @@
+import { ReactNode, CSSProperties } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { o as AppAccessDeactivatedEvent, D as AppAccessEventHandler, A as AppAccessGrantedEvent, n as AppAccessRevokedEvent, p as AppAccessRoleChangedEvent, y as AuthVitalEventHandler, K as IAppAccessEventHandler, F as IAuthVitalEventHandler, G as IInviteEventHandler, N as ILicenseEventHandler, J as IMemberEventHandler, H as ISubjectEventHandler, b as InviteAcceptedEvent, I as InviteCreatedEvent, c as InviteDeletedEvent, z as InviteEventHandler, d as InviteExpiredEvent, L as LicenseAssignedEvent, r as LicenseChangedEvent, E as LicenseEventHandler, q as LicenseRevokedEvent, m as MemberActivatedEvent, C as MemberEventHandler, M as MemberJoinedEvent, j as MemberLeftEvent, k as MemberRoleChangedEvent, l as MemberSuspendedEvent, x as SYNC_EVENT_TYPES, f as SubjectCreatedEvent, e as SubjectData, i as SubjectDeactivatedEvent, h as SubjectDeletedEvent, B as SubjectEventHandler, g as SubjectUpdatedEvent, S as SyncEvent, a as SyncEventType, W as WebhookRouter, O as WebhookRouterOptions, P as WebhookVerifier, Q as WebhookVerifierOptions, v as isAppAccessEvent, s as isInviteEvent, w as isLicenseEvent, u as isMemberEvent, t as isSubjectEvent } from './webhook-router-DdfXLtHa.js';
+
+/**
+ * @authvital/sdk - Client-Side Types
+ *
+ * Type definitions for React components and browser-side SDK.
+ */
+
+interface AuthVitalProviderProps {
+    /** OAuth Client ID from AuthVital admin panel */
+    clientId: string;
+    /** AuthVital server URL (e.g., http://localhost:3000) */
+    authVitalHost: string;
+    /** Redirect after successful sign-in */
+    afterSignInUrl?: string;
+    /** Redirect after successful sign-up */
+    afterSignUpUrl?: string;
+    /**
+     * Initial user data (from your server after JWT verification).
+     * Your server should use `getCurrentUser()` from the server SDK to verify the JWT,
+     * then pass the user data here.
+     */
+    initialUser?: AuthVitalUser | null;
+    /**
+     * Initial tenants data (from your server after JWT verification).
+     */
+    initialTenants?: AuthVitalTenant[];
+    /** Children */
+    children: ReactNode;
+}
+interface AuthVitalUser {
+    id: string;
+    email: string | null;
+    givenName: string | null;
+    familyName: string | null;
+    fullName: string | null;
+    imageUrl?: string | null;
+    isAnonymous: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface AuthVitalTenant {
+    id: string;
+    name: string;
+    slug: string;
+    imageUrl?: string | null;
+    role: string;
+}
+interface AuthVitalMembership {
+    id: string;
+    tenant: AuthVitalTenant;
+    role: string;
+    joinedAt: string;
+}
+interface AuthContextValue {
+    /** Whether user is authenticated */
+    isAuthenticated: boolean;
+    /** Whether auth state is loading */
+    isLoading: boolean;
+    /** Whether sign-in is in progress */
+    isSigningIn: boolean;
+    /** Whether sign-up is in progress */
+    isSigningUp: boolean;
+    /** Current user (null if not authenticated) */
+    user: AuthVitalUser | null;
+    /** User's tenants */
+    tenants: AuthVitalTenant[];
+    /** Currently active tenant */
+    currentTenant: AuthVitalTenant | null;
+    /** Last error message */
+    error: string | null;
+    login: (email: string, password: string) => Promise<LoginResult>;
+    signIn: (email: string, password: string) => Promise<LoginResult>;
+    signUp: (data: SignUpData) => Promise<SignUpResult>;
+    signOut: () => Promise<void>;
+    logout: () => Promise<void>;
+    setActiveTenant: (tenantId: string) => void;
+    switchTenant: (tenantId: string) => void;
+    refreshToken: () => Promise<void>;
+    /** Check if user is authenticated */
+    checkAuth: () => Promise<boolean>;
+    /**
+     * Set the authenticated user and tenants.
+     * Call this after your server verifies the JWT using getCurrentUser().
+     */
+    setAuthState: (user: AuthVitalUser | null, tenants?: AuthVitalTenant[]) => void;
+    /**
+     * Clear auth state (call on logout)
+     */
+    clearAuthState: () => void;
+}
+interface LoginResult {
+    user: AuthVitalUser;
+    tenants: AuthVitalTenant[];
+    redirectToken?: string;
+    redirectUrl?: string;
+}
+interface SignUpData {
+    email: string;
+    password: string;
+    givenName?: string;
+    familyName?: string;
+    phone?: string;
+}
+interface SignUpResult {
+    user: AuthVitalUser;
+    tenant?: AuthVitalTenant;
+    needsEmailVerification?: boolean;
+}
+interface SignInProps {
+    /** Callback on successful sign-in */
+    onSuccess?: (user: AuthVitalUser, tenants: AuthVitalTenant[]) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Show social login buttons (Google, GitHub, etc.) */
+    showSocialLogins?: boolean;
+    /** Show "Create account" link */
+    showSignupLink?: boolean;
+    /** Show "Forgot password" link */
+    showForgotPassword?: boolean;
+    /** Custom redirect after sign-in */
+    redirectUrl?: string;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+interface SignUpProps {
+    /** Callback on successful sign-up initiation (email sent) */
+    onSuccess?: (data: any) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Show social login buttons */
+    showSocialLogins?: boolean;
+    /** Show "Sign in" link */
+    showSignInLink?: boolean;
+    /** Show terms checkbox */
+    showTerms?: boolean;
+    /** Terms of service URL */
+    termsUrl?: string;
+    /** Privacy policy URL */
+    privacyUrl?: string;
+    /** Custom redirect after sign-up */
+    redirectUrl?: string;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+interface UserButtonProps {
+    /** Show user's name next to avatar */
+    showName?: boolean;
+    /** URL to redirect after sign-out */
+    afterSignOutUrl?: string;
+    /** Custom menu items */
+    menuItems?: UserMenuItemProps[];
+}
+interface UserMenuItemProps {
+    label: string;
+    onClick?: () => void;
+    href?: string;
+    icon?: ReactNode;
+}
+interface ProtectedRouteProps {
+    children: ReactNode;
+    /** URL to redirect if not authenticated */
+    redirectTo?: string;
+    /** Show loading spinner while checking auth */
+    showLoading?: boolean;
+    /** Custom loading component */
+    loadingComponent?: ReactNode;
+}
+interface TenantSwitcherProps {
+    /** Callback when tenant changes */
+    onChange?: (tenant: AuthVitalTenant) => void;
+    /** Show "Create tenant" option */
+    showCreateTenant?: boolean;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+interface AppearanceProps {
+    theme?: 'light' | 'dark' | 'auto';
+    variables?: AppearanceVariables;
+    elements?: AppearanceElements;
+}
+interface AppearanceVariables {
+    colorPrimary?: string;
+    colorBackground?: string;
+    colorText?: string;
+    colorTextSecondary?: string;
+    colorDanger?: string;
+    colorSuccess?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    fontSize?: string;
+}
+interface AppearanceElements {
+    card?: CSSProperties;
+    form?: CSSProperties;
+    input?: CSSProperties;
+    button?: CSSProperties;
+    primaryButton?: CSSProperties;
+    secondaryButton?: CSSProperties;
+    socialButton?: CSSProperties;
+    link?: CSSProperties;
+    error?: CSSProperties;
+    header?: CSSProperties;
+    footer?: CSSProperties;
+}
+interface OAuthConfig {
+    authVitalHost: string;
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+}
+/**
+ * Token response from OAuth token endpoint.
+ * Note: In cookie-based auth, these tokens are set as httpOnly cookies
+ * and are NOT accessible to JavaScript. This type is mainly for
+ * server-side SDK use or for understanding the response structure.
+ */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface StandaloneAuthOptions {
+    authVitalHost: string;
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+}
+interface LoginToAuthVitalOptions {
+    screen?: 'login' | 'signup';
+    clientId?: string;
+}
+interface InvitationDetails {
+    id: string;
+    email: string;
+    role: string;
+    expiresAt: string;
+    tenant: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    invitedBy: {
+        name: string;
+    } | null;
+}
+interface CreateInvitationParams {
+    email: string;
+    tenantId: string;
+    role?: string;
+    expiresInDays?: number;
+    clientId?: string;
+}
+interface CreateInvitationResult {
+    id: string;
+    email: string;
+    token: string;
+    role: string;
+    expiresAt: string;
+    tenant: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    inviteUrl: string;
+}
+interface ConsumeInvitationResult {
+    success: boolean;
+    membership: {
+        id: string;
+        tenantId: string;
+        tenant: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+    };
+    alreadyMember: boolean;
+}
+interface UseInvitationOptions {
+    autoConsume?: boolean;
+    onConsumed?: (result: ConsumeInvitationResult) => void;
+    onError?: (error: Error) => void;
+}
+
+declare function AuthVitalProvider({ clientId, authVitalHost, initialUser, initialTenants, children, }: AuthVitalProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAuth(): AuthContextValue;
+declare function useUser(): AuthVitalUser | null;
+declare function useTenant(): AuthVitalTenant | null;
+declare function useTenants(): AuthVitalTenant[];
+declare function useAuthVitalConfig(): {
+    authVitalHost: string;
+    clientId: string;
+};
+declare function useOAuth(options?: {
+    redirectUri?: string;
+}): {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    startLogin: (opts?: {
+        state?: string;
+        scope?: string;
+    }) => Promise<void>;
+    startSignup: (opts?: {
+        state?: string;
+        scope?: string;
+    }) => Promise<void>;
+    logout: (logoutOptions?: {
+        postLogoutRedirectUri?: string;
+    }) => Promise<void>;
+};
+declare function useInvitation(options?: UseInvitationOptions): {
+    invitation: InvitationDetails | null;
+    isLoading: boolean;
+    error: Error | null;
+    consumed: boolean;
+    hasPendingInvite: boolean;
+    fetchInvitation: (token: string) => Promise<InvitationDetails>;
+    acceptAndLogin: (token: string, loginOptions?: {
+        state?: string;
+    }) => Promise<void>;
+    consumeInvite: (token: string) => Promise<ConsumeInvitationResult>;
+};
+
+/**
+ * @authvital/sdk - Browser OAuth Utilities
+ *
+ * Handles PKCE, authorization flow, and token exchange for browser-based apps.
+ *
+ * IMPORTANT: Auth state is managed via httpOnly cookies, NOT localStorage.
+ * This protects against XSS attacks - JavaScript cannot access the tokens.
+ *
+ * The PKCE code_verifier is encoded in the OAuth `state` parameter to enable
+ * cross-domain flows without storing secrets in the browser.
+ *
+ * State format: `{csrf_nonce}:{base64url_verifier}`
+ */
+
+/**
+ * Encode PKCE verifier into OAuth state parameter
+ */
+declare function encodeState(csrf: string, codeVerifier: string): string;
+/**
+ * Decode state parameter to extract CSRF and verifier
+ */
+declare function decodeState(state: string): {
+    csrf: string;
+    codeVerifier: string;
+} | null;
+/**
+ * Simple redirect to AuthVital login/signup page.
+ * Use this on landing pages where you just want to send users to login.
+ *
+ * @example
+ * ```tsx
+ * import { loginToAuthVital } from '@authvital/sdk';
+ *
+ * <button onClick={() => loginToAuthVital('http://auth.myapp.com', { clientId: 'my-app' })}>
+ *   Sign In
+ * </button>
+ * ```
+ */
+declare function loginToAuthVital(authVitalHost: string, options?: LoginToAuthVitalOptions): void;
+/**
+ * Convenience function for signup redirect.
+ */
+declare function signupAtAuthVital(authVitalHost: string, options?: Omit<LoginToAuthVitalOptions, 'screen'>): void;
+/**
+ * Generate a cryptographically random code verifier
+ */
+declare function generateCodeVerifier(): string;
+/**
+ * Generate code challenge from verifier (S256 method)
+ */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+interface AuthorizeParams {
+    state?: string;
+    nonce?: string;
+    screen?: 'login' | 'signup';
+}
+/**
+ * Start the OAuth authorization flow with PKCE
+ *
+ * After successful auth, AuthVital sets httpOnly cookies.
+ * Use checkAuthStatus() to verify if user is authenticated.
+ */
+declare function startAuthorizationFlow(config: OAuthConfig, params?: AuthorizeParams): Promise<void>;
+/**
+ * Start the login flow (standalone function)
+ */
+declare function startLogin(options: StandaloneAuthOptions): Promise<void>;
+/**
+ * Start the signup flow (standalone function)
+ */
+declare function startSignup(options: StandaloneAuthOptions): Promise<void>;
+/**
+ * Handle the OAuth callback - exchange code for tokens
+ *
+ * The tokens are set as httpOnly cookies by the server.
+ * This function completes the PKCE flow and clears the URL params.
+ */
+declare function handleCallback(config: OAuthConfig): Promise<void>;
+/**
+ * Extract callback parameters for trampoline/backend handling
+ */
+declare function extractCallbackParams(): {
+    code: string | null;
+    codeVerifier: string | null;
+    csrf: string | null;
+    error: string | null;
+    errorDescription: string | null;
+};
+/**
+ * Exchange authorization code for tokens.
+ * The server sets httpOnly cookies - tokens are NOT returned to JS.
+ */
+declare function exchangeCodeForTokens(config: OAuthConfig, code: string, codeVerifier: string): Promise<TokenResponse>;
+interface AuthStatus {
+    authenticated: boolean;
+    user?: {
+        id: string;
+        email: string;
+        givenName?: string;
+        familyName?: string;
+    };
+}
+/**
+ * Check if user is authenticated by calling the auth status endpoint.
+ * Auth state is in httpOnly cookies, so we must ask the server.
+ */
+declare function checkAuthStatus(authVitalHost: string): Promise<AuthStatus>;
+/**
+ * Logout - clears the httpOnly session cookie via server redirect
+ */
+declare function logout(authVitalHost: string, options?: {
+    postLogoutRedirectUri?: string;
+}): Promise<void>;
+/**
+ * Decode JWT payload (without verification - for display purposes only)
+ *
+ * WARNING: Do NOT use this to make auth decisions!
+ * Auth state should be verified via checkAuthStatus() which checks cookies.
+ */
+declare function decodeJwt<T = Record<string, unknown>>(token: string): T | null;
+
+/**
+ * @authvital/sdk - Client-Side Invitation Helpers
+ *
+ * Handles the invite flow: get invite details, store token, consume after login.
+ * Auth is via httpOnly cookies - no Authorization header needed for authenticated requests.
+ */
+
+/**
+ * Store invite token in sessionStorage (temporary, for the signup flow)
+ */
+declare function storeInviteToken(token: string): void;
+/**
+ * Get stored invite token
+ */
+declare function getStoredInviteToken(): string | null;
+/**
+ * Clear stored invite token
+ */
+declare function clearStoredInviteToken(): void;
+/**
+ * Check URL for invite token and store it
+ */
+declare function captureInviteTokenFromUrl(): string | null;
+/**
+ * Get invitation details by token (public endpoint - no auth required)
+ */
+declare function getInvitation(authVitalHost: string, token: string): Promise<InvitationDetails>;
+/**
+ * Create an invitation (requires authentication via cookie)
+ */
+declare function createInvitation(authVitalHost: string, _accessToken: string, // Ignored - auth is via cookie
+params: CreateInvitationParams): Promise<CreateInvitationResult>;
+/**
+ * Consume an invitation - adds current user to the tenant
+ */
+declare function consumeInvitation(authVitalHost: string, _accessToken: string, // Ignored - auth is via cookie
+token: string): Promise<ConsumeInvitationResult>;
+/**
+ * List pending invitations for a tenant
+ */
+declare function listTenantInvitations(authVitalHost: string, _accessToken: string, // Ignored - auth is via cookie
+tenantId: string): Promise<Array<{
+    id: string;
+    email: string;
+    role: string;
+    expiresAt: string;
+    createdAt: string;
+    invitedBy: {
+        id: string;
+        email: string;
+        givenName: string;
+        familyName: string;
+    } | null;
+}>>;
+/**
+ * Revoke an invitation
+ */
+declare function revokeInvitation(authVitalHost: string, _accessToken: string, // Ignored - auth is via cookie
+invitationId: string): Promise<{
+    success: boolean;
+}>;
+
+declare function ProtectedRoute({ children, redirectTo, showLoading, loadingComponent, }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
+
+interface SignUpFormProps {
+    /** Callback when verification email is sent */
+    onSuccess?: (data: {
+        email: string;
+        message: string;
+    }) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Show "Sign in" link */
+    showSignInLink?: boolean;
+    /** Callback when user clicks sign in link */
+    onSignInClick?: () => void;
+    /** Redirect URI after signup completion */
+    redirectUri?: string;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+declare function SignUpForm({ onSuccess, onError, showSignInLink, onSignInClick, redirectUri, appearance, }: SignUpFormProps): react_jsx_runtime.JSX.Element;
+
+type VerifyStatus = 'loading' | 'success' | 'error' | 'expired' | 'already_completed';
+interface VerifyEmailProps {
+    /** Verification token from URL */
+    token: string;
+    /** Callback on successful verification */
+    onSuccess?: (data: VerifiedData) => void;
+    /** Callback on error */
+    onError?: (error: Error, status: VerifyStatus) => void;
+    /** Callback to continue to complete signup */
+    onContinueSignup?: (data: VerifiedData) => void;
+    /** Callback to go to login */
+    onLogin?: () => void;
+    /** Callback to start over (signup again) */
+    onStartOver?: () => void;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+/**
+ * Data returned after successful email verification.
+ *
+ * IMPORTANT: When redirecting to complete-signup, only pass the `token` in the URL.
+ * All other data (email, name) should be loaded from the token on the backend to
+ * prevent PII from being exposed in URLs.
+ */
+interface VerifiedData {
+    /** The verification token - use this (and ONLY this) in redirect URLs */
+    token: string;
+    /** Email (for display only - do NOT include in URLs) */
+    email?: string;
+    /** Given name (for display only - do NOT include in URLs) */
+    givenName?: string;
+    /** Family name (for display only - do NOT include in URLs) */
+    familyName?: string;
+    /** Tenant name (for display only - do NOT include in URLs) */
+    tenantName?: string;
+}
+declare function VerifyEmail({ token, onSuccess, onError, onContinueSignup, onLogin, onStartOver, appearance, }: VerifyEmailProps): react_jsx_runtime.JSX.Element;
+
+interface CompleteSignupFormProps {
+    /** Verification token */
+    token: string;
+    /** Email from verification */
+    email: string;
+    /** Pre-filled given name */
+    givenName?: string;
+    /** Pre-filled family name */
+    familyName?: string;
+    /** Pre-filled tenant name */
+    tenantName?: string;
+    /** Redirect URI after completion */
+    redirectUri?: string;
+    /** Callback on successful signup */
+    onSuccess?: (result: CompleteSignupResult) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Appearance customization */
+    appearance?: AppearanceProps;
+}
+interface CompleteSignupResult {
+    user: {
+        id: string;
+        email: string;
+        givenName?: string;
+        familyName?: string;
+    };
+    tenant?: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    initiateLoginUri?: string;
+}
+declare function CompleteSignupForm({ token, email, givenName: initialGivenName, familyName: initialFamilyName, tenantName: initialOrgName, redirectUri, onSuccess, onError, appearance, }: CompleteSignupFormProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shared styles for components
+ */
+
+declare function getStyles(appearance?: AppearanceProps): Record<string, CSSProperties>;
+
+export { type AppearanceElements, type AppearanceProps, type AppearanceVariables, type AuthContextValue, type AuthStatus, type AuthVitalMembership, AuthVitalProvider, type AuthVitalProviderProps, type AuthVitalTenant, type AuthVitalUser, CompleteSignupForm, type CompleteSignupFormProps, type CompleteSignupResult, type ConsumeInvitationResult, type CreateInvitationParams, type CreateInvitationResult, type InvitationDetails, type LoginResult, type LoginToAuthVitalOptions, type OAuthConfig, ProtectedRoute, type ProtectedRouteProps, type SignInProps, type SignUpData, SignUpForm, type SignUpFormProps, type SignUpProps, type SignUpResult, type StandaloneAuthOptions, type TenantSwitcherProps, type TokenResponse, type UseInvitationOptions, type UserButtonProps, type UserMenuItemProps, type VerifiedData, VerifyEmail, type VerifyEmailProps, captureInviteTokenFromUrl, checkAuthStatus, clearStoredInviteToken, consumeInvitation, createInvitation, decodeJwt, decodeState, encodeState, exchangeCodeForTokens, extractCallbackParams, generateCodeChallenge, generateCodeVerifier, getInvitation, getStoredInviteToken, getStyles, handleCallback, listTenantInvitations, loginToAuthVital, logout, revokeInvitation, signupAtAuthVital, startAuthorizationFlow, startLogin, startSignup, storeInviteToken, useAuth, useAuthVitalConfig, useInvitation, useOAuth, useTenant, useTenants, useUser };