@kaappu/react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaappu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @kaappu/react
+
+> Drop-in React components for [Kaappu Identity](https://kaappu.org) — authentication, authorization, and AI-aware access control.
+
+[![npm version](https://img.shields.io/npm/v/@kaappu/react.svg?style=flat-square)](https://www.npmjs.com/package/@kaappu/react)
+[![license](https://img.shields.io/npm/l/@kaappu/react.svg?style=flat-square)](./LICENSE)
+
+## What's in the box
+
+- **`<KaappuProvider />`** — wraps your app, manages session state, handles silent token refresh
+- **`<LoginPanel />`** — full sign-in UI: OAuth (Google / GitHub / Microsoft / Apple), passkey, email + password, magic link, OTP, phone
+- **`<RegisterPanel />`** — full sign-up UI: OAuth providers, password rules, confirm password, friendly error messages, optional email verification
+- **`<Authorize />`** — conditionally render based on permission or role
+- **`<LoggedIn />` / `<LoggedOut />`** — conditional render based on session state
+- **`<ProfileBadge />`** — user avatar with sign-out menu
+- **`<AccountView />`** — drop-in account settings page
+- **`useKaappu()`** — hook returning `{ isLoaded, isSignedIn, user, hasPermission, signOut, getToken, ... }`
+
+All components are theme-aware, accessible, and work with both light and dark color schemes out of the box.
+
+## Install
+
+```bash
+npm install @kaappu/react
+# or
+pnpm add @kaappu/react
+# or
+yarn add @kaappu/react
+```
+
+Peer dependencies: `react >= 18`, `react-dom >= 18`.
+
+## Quick start
+
+```jsx
+import { KaappuProvider, LoginPanel, LoggedIn, LoggedOut, useKaappu } from '@kaappu/react'
+
+// 1. Wrap your app
+function App() {
+  return (
+    <KaappuProvider
+      publishableKey="pk_live_..."
+      baseUrl="https://id.your-domain.com/igai"
+    >
+      <YourApp />
+    </KaappuProvider>
+  )
+}
+
+// 2. Use the components anywhere
+function Header() {
+  const { user, signOut } = useKaappu()
+  return (
+    <header>
+      <LoggedOut>
+        <a href="/sign-in">Sign in</a>
+      </LoggedOut>
+      <LoggedIn>
+        <span>Hi, {user?.email}</span>
+        <button onClick={signOut}>Sign out</button>
+      </LoggedIn>
+    </header>
+  )
+}
+
+// 3. Drop the auth panels onto a page
+function SignInPage() {
+  return <LoginPanel onSuccess={(token, user) => window.location.href = '/'} />
+}
+```
+
+## Authorization
+
+```jsx
+import { Authorize } from '@kaappu/react'
+
+// Permission-gated content
+<Authorize
+  permission="billing:manage"
+  fallback={<p>Upgrade to access billing.</p>}
+>
+  <BillingPanel />
+</Authorize>
+
+// Role-gated content
+<Authorize role="admin">
+  <AdminTools />
+</Authorize>
+
+// Wildcard permission "*" grants access to everything (built-in admin shortcut)
+```
+
+## Standalone mode (no provider)
+
+If you don't want to wrap your app in `<KaappuProvider>`, you can use `<LoginPanel />` and `<RegisterPanel />` as standalone components:
+
+```jsx
+<LoginPanel
+  authUrl="https://id.your-domain.com/api/auth"
+  accountId="your-tenant-id"
+  onSuccess={(token, user) => { /* persist token, redirect */ }}
+/>
+```
+
+## Theming
+
+Pass an `appearance` prop to any component to override colors and typography:
+
+```jsx
+import { LoginPanel, createTheme } from '@kaappu/react'
+
+const theme = createTheme({
+  colorScheme: 'light',
+  variables: {
+    primaryColor: '#0ea5e9',
+    borderRadius: '0.5rem',
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+})
+
+<LoginPanel appearance={theme} />
+```
+
+Themes use CSS custom properties under the hood (`--k-primary`, `--k-card-bg`, `--k-text`, etc.) so you can also override them directly with stylesheets.
+
+## What this SDK is for
+
+`@kaappu/react` is the React client for the Kaappu Identity platform — a closed-loop security control plane for AI-era applications. The SDK lets you drop production-grade authentication, authorization, and identity management into a React app in minutes, with the same primitives Kaappu uses on its own website (kaappu.org).
+
+Learn more at [kaappu.org](https://kaappu.org) — including the Security Control Loop white paper and customer case studies.
+
+## License
+
+[MIT](./LICENSE) © Kaappu

package/dist/index.d.mts

@@ -0,0 +1,354 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+export { AuthResponse, KaappuApiClient, KaappuSession, KaappuTenantConfig, KaappuUser, checkAllPermissions, checkAnyPermission, checkPermission, isPermission } from '@kaappu/core';
+
+/** Tenant config returned by GET /api/v1/accounts/config?pk=... */
+interface KaappuTenantConfig {
+    accountId: string;
+    authMethods: {
+        password: boolean;
+        magicLink: boolean;
+        emailOtp: boolean;
+        phoneOtp: boolean;
+        passkeys: boolean;
+        google: boolean;
+        github: boolean;
+        microsoft: boolean;
+    };
+    customProviders: Array<{
+        id: string;
+        name: string;
+        discoveryUrl: string;
+    }>;
+    branding: {
+        logoUrl: string;
+        primaryColor: string;
+        name: string;
+    };
+    botProtection: {
+        enabled: boolean;
+        siteKey: string;
+    };
+    policy: {
+        mfaRequired: boolean;
+        requireEmailVerification: boolean;
+    };
+}
+/** Authenticated user shape */
+interface KaappuUser {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    avatarUrl?: string;
+    emailVerified?: boolean;
+    mfaEnabled?: boolean;
+    accountId: string;
+    sessionId: string;
+    roles?: string[];
+    permissions?: string[];
+}
+/** Auth state exposed via useKaappu() */
+interface KaappuContextValue {
+    /** Whether the provider has finished loading (config + session check) */
+    isLoaded: boolean;
+    /** Whether a user is signed in */
+    isSignedIn: boolean;
+    /** The signed-in user, or null */
+    user: KaappuUser | null;
+    /** Current access token (may be refreshed transparently) */
+    accessToken: string | null;
+    /** Tenant configuration fetched at init */
+    tenantConfig: KaappuTenantConfig | null;
+    /** Sign out — clears session + tokens */
+    signOut: () => Promise<void>;
+    /** Get the current access token (refreshes if needed) */
+    getToken: () => Promise<string | null>;
+    /** Check if user has a permission (client-side, from token claims) */
+    hasPermission: (permission: string) => boolean;
+}
+/** KaappuProvider props */
+interface KaappuProviderProps {
+    /** The publishable key for your Kaappu account (pk_live_xxx) */
+    publishableKey: string;
+    /** Base URL of the Kaappu API (e.g. https://api.kaappu.com or http://localhost:9091) */
+    baseUrl?: string;
+    /** Default: '/sign-in' */
+    signInUrl?: string;
+    /** Default: '/sign-up' */
+    signUpUrl?: string;
+    children: React.ReactNode;
+}
+/** Appearance customization — passed to any SDK component */
+interface KaappuAppearance {
+    /**
+     * Color scheme. 'auto' follows the OS prefers-color-scheme setting.
+     * Default: 'dark'
+     */
+    colorScheme?: 'dark' | 'light' | 'auto';
+    /** Override CSS custom properties */
+    variables?: {
+        primaryColor?: string;
+        primaryForeground?: string;
+        backgroundColor?: string;
+        cardBackground?: string;
+        textColor?: string;
+        mutedColor?: string;
+        borderColor?: string;
+        borderRadius?: string;
+        fontFamily?: string;
+    };
+    /** Class names for individual elements (slots) */
+    elements?: {
+        card?: string;
+        title?: string;
+        subtitle?: string;
+        input?: string;
+        button?: string;
+        divider?: string;
+        oauthButton?: string;
+        footer?: string;
+        badge?: string;
+        dropdown?: string;
+        dropdownItem?: string;
+    };
+}
+/** ProfileBadge props */
+interface ProfileBadgeProps$1 {
+    afterSignOutUrl?: string;
+    userProfileUrl?: string;
+    appearance?: KaappuAppearance;
+    className?: string;
+}
+/** AccountView props */
+interface AccountViewProps$1 {
+    appearance?: KaappuAppearance;
+    className?: string;
+}
+/** LoginPanel props */
+interface LoginPanelProps {
+    /** Called with accessToken on successful sign-in */
+    onSuccess?: (token: string, user: KaappuUser) => void;
+    /** Redirect URL after sign-in (used by kaappuPipeline integration) */
+    redirectUrl?: string;
+    /** Override the logo displayed inside the card (URL or React node) */
+    logoUrl?: string;
+    /** Appearance overrides */
+    appearance?: KaappuAppearance;
+    /** Custom CSS class for the card wrapper */
+    className?: string;
+    /** Override OAuth redirect base URL (e.g., for WordPress proxy). If set, OAuth goes to {oauthProxyUrl}/{provider} instead of {baseUrl}/oauth/{provider} */
+    oauthProxyUrl?: string;
+    /** List of OAuth providers to show (e.g., ['google']). If set, only these are shown. */
+    allowedProviders?: string[];
+}
+/** RegisterPanel props */
+interface RegisterPanelProps {
+    /** Called with accessToken on successful registration */
+    onSuccess?: (token: string, user: KaappuUser) => void;
+    /** Redirect URL after registration */
+    redirectUrl?: string;
+    /** Override the logo displayed inside the card (URL or data URI) */
+    logoUrl?: string;
+    /** Appearance overrides */
+    appearance?: KaappuAppearance;
+    className?: string;
+}
+
+declare function KaappuProvider({ publishableKey, baseUrl, signInUrl, signUpUrl, children, }: KaappuProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useKaappu(): KaappuContextValue;
+
+/**
+ * <LoginPanel /> — Drop-in sign-in component.
+ *
+ * Renders the full Kaappu authentication UI: OAuth providers, passkey,
+ * email/password, magic link, OTP, and phone tabs.
+ *
+ * All auth calls go through the configured middleware (Next.js API routes
+ * at /api/auth/*) — never directly to igai-connector.
+ *
+ * @example
+ * // Inside <KaappuProvider baseUrl="/api/auth">
+ * <LoginPanel onSuccess={(token, user) => router.push('/')} />
+ *
+ * // Or standalone without KaappuProvider:
+ * <LoginPanel
+ *   authUrl="https://myapp.com/api/auth"
+ *   accountId="kaappu_org"
+ *   onSuccess={(token, user) => { ... }}
+ * />
+ */
+declare function LoginPanel({ onSuccess, redirectUrl, logoUrl, appearance, className, oauthProxyUrl, allowedProviders, authUrl: authUrlProp, accountId: accountIdProp, signUpPath, signUpLabel, signUpPrompt, }: LoginPanelProps & {
+    authUrl?: string;
+    accountId?: string;
+    signUpPath?: string;
+    signUpLabel?: string;
+    signUpPrompt?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * <RegisterPanel /> — Drop-in sign-up component.
+ *
+ * Renders the full Kaappu registration UI: OAuth providers, name/email/
+ * password form with confirm-password and live password rule indicators,
+ * friendly error messages, and an optional email-verification step.
+ *
+ * Designed for visual parity with <LoginPanel /> so apps can wire both
+ * components into a single onboarding flow.
+ *
+ * @example
+ * // Inside <KaappuProvider baseUrl="/api/auth">
+ * <RegisterPanel onSuccess={(token, user) => router.push('/')} />
+ *
+ * // Standalone (no provider needed):
+ * <RegisterPanel
+ *   authUrl="https://myapp.com/api/auth"
+ *   accountId="acme"
+ *   onSuccess={(token, user) => { ... }}
+ * />
+ */
+declare function RegisterPanel({ onSuccess, redirectUrl, logoUrl, appearance, className, authUrl: authUrlProp, accountId: accountIdProp, signInPath, signInLabel, signInPrompt, allowedProviders, oauthProxyUrl, }: RegisterPanelProps & {
+    authUrl?: string;
+    accountId?: string;
+    signInPath?: string;
+    signInLabel?: string;
+    signInPrompt?: string;
+    allowedProviders?: string[];
+    oauthProxyUrl?: string;
+}): react_jsx_runtime.JSX.Element;
+
+interface ProfileBadgeProps {
+    /** URL to redirect after sign-out (default: '/sign-in') */
+    afterSignOutUrl?: string;
+    /** URL for "Manage account" link (default: '/account') */
+    userProfileUrl?: string;
+    /** Appearance overrides */
+    appearance?: KaappuAppearance;
+    /** Custom CSS class for the trigger button */
+    className?: string;
+}
+/**
+ * <ProfileBadge /> — compact avatar + dropdown menu.
+ * Shows user's initials (or avatar image) and name.
+ * Click opens a dropdown: Manage account, Sign out.
+ *
+ * @example
+ * <ProfileBadge afterSignOutUrl="/sign-in" userProfileUrl="/dashboard/profile" />
+ */
+declare function ProfileBadge({ afterSignOutUrl, userProfileUrl, appearance, className, }: ProfileBadgeProps): react_jsx_runtime.JSX.Element | null;
+
+interface AccountViewProps {
+    /** Appearance overrides */
+    appearance?: KaappuAppearance;
+    /** Custom CSS class for the wrapper */
+    className?: string;
+}
+/**
+ * <AccountView /> — full embeddable profile + security management component.
+ *
+ * Tabs:
+ * - Profile   — display name editing
+ * - Security  — TOTP MFA enrollment/status, password change
+ * - Sessions  — active session list with individual revoke
+ * - Passkeys  — registered passkey list with delete
+ *
+ * @example
+ * // app/account/page.tsx
+ * import { AccountView } from '@kaappu/react'
+ * export default function AccountPage() {
+ *   return <AccountView />
+ * }
+ */
+declare function AccountView({ appearance, className }: AccountViewProps): react_jsx_runtime.JSX.Element | null;
+
+interface LoggedInProps {
+    children: React$1.ReactNode;
+    /** Rendered while auth state is loading */
+    fallback?: React$1.ReactNode;
+}
+/**
+ * Renders children only when the user is signed in.
+ *
+ * @example
+ * <LoggedIn fallback={<Spinner />}>
+ *   <UserMenu />
+ * </LoggedIn>
+ */
+declare function LoggedIn({ children, fallback }: LoggedInProps): react_jsx_runtime.JSX.Element | null;
+interface LoggedOutProps {
+    children: React$1.ReactNode;
+    /** Rendered while auth state is loading */
+    fallback?: React$1.ReactNode;
+}
+/**
+ * Renders children only when the user is NOT signed in.
+ *
+ * @example
+ * <LoggedOut>
+ *   <a href="/sign-in">Sign in</a>
+ * </LoggedOut>
+ */
+declare function LoggedOut({ children, fallback }: LoggedOutProps): react_jsx_runtime.JSX.Element | null;
+interface AuthorizeProps {
+    children: React$1.ReactNode;
+    /**
+     * Required permission string (e.g. "billing:manage", "users:read").
+     * Uses client-side permission list from the user's session.
+     * The wildcard permission "*" grants access to everything.
+     */
+    permission?: string;
+    /**
+     * Required role name (e.g. "admin", "owner").
+     * Checked against user.roles[].
+     */
+    role?: string;
+    /** Rendered when the user lacks the required permission/role */
+    fallback?: React$1.ReactNode;
+    /** Rendered while auth state is loading */
+    loading?: React$1.ReactNode;
+}
+/**
+ * Conditionally renders children based on the user's permissions or role.
+ * Combines with <LoggedIn> semantics — unauthenticated users see fallback.
+ *
+ * @example
+ * // Permission-gated
+ * <Authorize permission="billing:manage" fallback={<p>Upgrade to access billing.</p>}>
+ *   <BillingPanel />
+ * </Authorize>
+ *
+ * // Role-gated
+ * <Authorize role="admin">
+ *   <AdminTools />
+ * </Authorize>
+ *
+ * // Combine both (user must have BOTH)
+ * <Authorize role="admin" permission="users:delete">
+ *   <DangerZone />
+ * </Authorize>
+ */
+declare function Authorize({ children, permission, role, fallback, loading, }: AuthorizeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Resolves the active color scheme.
+ * 'auto' reads prefers-color-scheme at call time (SSR-safe — defaults to dark).
+ */
+declare function resolveColorScheme(scheme?: 'dark' | 'light' | 'auto'): 'dark' | 'light';
+/**
+ * Build the CSS variables object to apply as `style` on the root element.
+ * Merges theme defaults → branding primaryColor → appearance overrides.
+ */
+declare function buildThemeVars(appearance?: KaappuAppearance, brandingColor?: string): React.CSSProperties;
+/**
+ * createTheme() — convenience helper for customers who want to define a
+ * theme object once and reuse it across multiple components.
+ *
+ * @example
+ * const theme = createTheme({ colorScheme: 'light', variables: { primaryColor: '#0ea5e9' } })
+ * <LoginPanel appearance={theme} />
+ * <ProfileBadge appearance={theme} />
+ */
+declare function createTheme(appearance: KaappuAppearance): KaappuAppearance;
+
+export { AccountView, type AccountViewProps$1 as AccountViewProps, Authorize, type KaappuAppearance, type KaappuContextValue, KaappuProvider, type KaappuProviderProps, LoggedIn, LoggedOut, LoginPanel, type LoginPanelProps, ProfileBadge, type ProfileBadgeProps$1 as ProfileBadgeProps, RegisterPanel, type RegisterPanelProps, buildThemeVars, createTheme, resolveColorScheme, useKaappu };