@s8lab/sso-client 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# @s8lab/sso-client
+
+React authentication component library — **Login**, **Signup**, **Forgot Password**, **Logout**, and **Profile** — with Google reCAPTCHA v2 and shadcn-style UI built on Radix UI + Tailwind CSS.
+
+---
+
+## Installation
+
+```bash
+npm install @s8lab/sso-client
+```
+
+> **Peer dependencies** — make sure your project has `react` and `react-dom` ≥ 18.
+
+### Tailwind setup (required)
+
+Add this library to your Tailwind `content` so its classes are picked up:
+
+```js
+// tailwind.config.js
+export default {
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@s8lab/sso-client/dist/**/*.js",
+  ],
+  // ...
+};
+```
+
+Then import the bundled CSS once at your app root:
+
+```ts
+import "@s8lab/sso-client/styles.css";
+```
+
+---
+
+## Quick start
+
+### 1 — Wrap your app with `<AuthProvider>`
+
+```tsx
+import { AuthProvider } from "@s8lab/sso-client";
+
+function App() {
+  return (
+    <AuthProvider
+      apiUrl="https://api.yourapp.com"
+      recaptchaSiteKey="6LeXXXXXXXXXXXXXXXXX"
+    >
+      <Router />
+    </AuthProvider>
+  );
+}
+```
+
+#### `AuthProvider` props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiUrl` | `string` | **required** | Base URL of your SSO server |
+| `recaptchaSiteKey` | `string` | **required** | Google reCAPTCHA v2 site key |
+| `storageKeyPrefix` | `string` | `"sso"` | localStorage key prefix for tokens |
+| `fetcher` | `(url, init) => Promise<T>` | built-in fetch | Override for custom headers/interceptors |
+
+---
+
+### 2 — Use the components
+
+```tsx
+import {
+  LoginForm,
+  SignupForm,
+  ForgotPasswordForm,
+  LogoutButton,
+  ProfileComponent,
+} from "@s8lab/sso-client";
+```
+
+#### `<LoginForm>`
+
+```tsx
+<LoginForm
+  className="mx-auto"
+  title="Welcome back"
+  description="Sign in to your account"
+  signupUrl="/signup"
+  forgotPasswordUrl="/forgot-password"
+  onSuccess={(user) => router.push("/dashboard")}
+  onError={(err) => toast.error(err.message)}
+/>
+```
+
+#### `<SignupForm>`
+
+```tsx
+<SignupForm
+  className="mx-auto"
+  loginUrl="/login"
+  onSuccess={(user) => router.push("/dashboard")}
+/>
+```
+
+#### `<ForgotPasswordForm>`
+
+```tsx
+<ForgotPasswordForm
+  loginUrl="/login"
+  onSuccess={() => toast.success("Reset link sent!")}
+/>
+```
+
+#### `<LogoutButton>`
+
+```tsx
+// Default button
+<LogoutButton onSuccess={() => router.push("/login")} />
+
+// Custom render
+<LogoutButton onSuccess={() => router.push("/login")}>
+  {({ isLoading }) => (
+    <button disabled={isLoading}>
+      {isLoading ? "Logging out…" : "Log out"}
+    </button>
+  )}
+</LogoutButton>
+```
+
+#### `<ProfileComponent>`
+
+```tsx
+<ProfileComponent
+  showLogout
+  onLogoutSuccess={() => router.push("/login")}
+  onEditProfile={(user) => router.push("/settings")}
+/>
+```
+
+---
+
+### 3 — `useAuth` hook
+
+Access auth state and actions anywhere inside `<AuthProvider>`:
+
+```tsx
+import { useAuth } from "@s8lab/sso-client";
+
+function Dashboard() {
+  const { user, isAuthenticated, isLoading, logout } = useAuth();
+
+  if (isLoading) return <Spinner />;
+  if (!isAuthenticated) return <Redirect to="/login" />;
+
+  return <h1>Hello, {user.firstName}!</h1>;
+}
+```
+
+---
+
+## API server contract
+
+The `AuthProvider` expects the following endpoints on your `apiUrl`:
+
+| Method | Path | Request body | Response |
+|---|---|---|---|
+| `POST` | `/auth/login` | `{ email, password, recaptchaToken }` | `{ user, tokens }` |
+| `POST` | `/auth/signup` | `{ firstName, lastName, email, password, whatsappNumber?, recaptchaToken }` | `{ user, tokens }` |
+| `POST` | `/auth/logout` | *(none)* | `204` |
+| `POST` | `/auth/forgot-password` | `{ email, recaptchaToken }` | `200` |
+| `GET` | `/auth/me` | *(Authorization header)* | `User` |
+
+`tokens` shape: `{ accessToken: string; refreshToken?: string }`
+
+---
+
+## Customising styles
+
+Every component accepts a `className` prop that is merged onto the outer `Card` via `tailwind-merge`, so you can freely override any Tailwind class:
+
+```tsx
+<LoginForm className="border-2 border-indigo-500 shadow-xl rounded-2xl" />
+```
+
+CSS variables for the design tokens (colors, radius, etc.) follow the standard shadcn/ui convention and can be overridden globally in your CSS.
+
+---
+
+## Publishing to npm
+
+```bash
+npm run build
+npm publish --access public
+```

package/dist/components/CaptchaWidget.d.ts

@@ -0,0 +1,20 @@
+import { CaptchaConfig } from '../types';
+export interface CaptchaHandle {
+    reset: () => void;
+}
+interface CaptchaWidgetProps {
+    config: CaptchaConfig;
+    onVerify: (token: string) => void;
+    onExpire: () => void;
+}
+/**
+ * Renders the appropriate captcha widget based on config:
+ * - recaptcha v2 → Google checkbox widget
+ * - hcaptcha     → hCaptcha checkbox widget
+ * - recaptcha v3 → nothing (invisible; execute via executeRecaptchaV3 util)
+ * - disabled     → nothing
+ *
+ * Expose .reset() via ref to reset the widget after submission.
+ */
+export declare const CaptchaWidget: import('react').ForwardRefExoticComponent<CaptchaWidgetProps & import('react').RefAttributes<CaptchaHandle>>;
+export {};

package/dist/components/ForgotPasswordForm.d.ts

@@ -0,0 +1,2 @@
+import { ForgotPasswordFormProps } from '../types';
+export declare function ForgotPasswordForm({ className, onSuccess, onError, loginUrl, title, }: ForgotPasswordFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/LoginForm.d.ts

@@ -0,0 +1,2 @@
+import { LoginFormProps } from '../types';
+export declare function LoginForm({ className, onSuccess, onError, forgotPasswordUrl, signupUrl, title, }: LoginFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/LogoutButton.d.ts

@@ -0,0 +1,2 @@
+import { LogoutButtonProps } from '../types';
+export declare function LogoutButton({ className, onSuccess, onError, label, children, }: LogoutButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ProfileComponent.d.ts

@@ -0,0 +1,2 @@
+import { ProfileComponentProps } from '../types';
+export declare function ProfileComponent({ className, onEditProfile, showLogout, onLogoutSuccess, }: ProfileComponentProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/SignupForm.d.ts

@@ -0,0 +1,2 @@
+import { SignupFormProps } from '../types';
+export declare function SignupForm({ className, onSuccess, onError, loginUrl, title, }: SignupFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/avatar.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React.RefAttributes<HTMLImageElement>, "ref"> & React.RefAttributes<HTMLImageElement>>;
+declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarFallbackProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export { Avatar, AvatarImage, AvatarFallback };

package/dist/components/ui/button.d.ts

@@ -0,0 +1,11 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/dist/components/ui/card.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/dist/components/ui/checkbox.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export { Checkbox };

package/dist/components/ui/input.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export { Input };

package/dist/components/ui/label.d.ts

@@ -0,0 +1,5 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+declare const Label: React.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref"> & VariantProps<(props?: import('class-variance-authority/types').ClassProp | undefined) => string> & React.RefAttributes<HTMLLabelElement>>;
+export { Label };

package/dist/components/ui/separator.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
+declare const Separator: React.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export { Separator };

package/dist/context/AuthContext.d.ts

@@ -0,0 +1,4 @@
+import { AuthConfigContextValue, AuthContextValue, AuthProviderProps } from '../types';
+export declare function AuthProvider({ children, apiUrl, projectId, storageKeyPrefix, fetcher, }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAuth(): AuthContextValue;
+export declare function useAuthConfig(): AuthConfigContextValue;