azirid-react 0.6.0

package/README.md

@@ -0,0 +1,1311 @@
+# azirid-react
+
+Authentication components and hooks for React and Next.js — powered by [TanStack Query](https://tanstack.com/query) and [Zod](https://zod.dev).
+
+Drop-in `<LoginForm>`, `<SignupForm>` and more, **or** use the headless hooks to build fully custom UIs.
+
+## Installation
+
+```bash
+npm install azirid-react
+# or
+pnpm add azirid-react
+# or
+yarn add azirid-react
+```
+
+### Peer dependencies
+
+```bash
+npm install react react-dom @tanstack/react-query
+# Tailwind CSS is optional – only needed if you use the built-in components
+```
+
+---
+
+## Architecture: Proxy vs Direct Mode
+
+`azirid-react` supports two connection modes to the Azirid API. Choose the one that fits your stack:
+
+| | Proxy mode | Direct mode |
+| --- | --- | --- |
+| **Best for** | Next.js (App Router) | React SPA (Vite, CRA, Remix) |
+| **Security** | First-party cookies, no CORS | Requires CORS on API |
+| **Setup** | Route handler + Provider | Provider only |
+| **How it works** | Browser → your app `/api/auth/*` → Azirid API | Browser → Azirid API directly |
+
+### Proxy mode (recommended for Next.js)
+
+Requests go to your Next.js app's `/api/auth/*` route handler, which securely proxies them to the Azirid API. Cookies are first-party (same domain), so no CORS configuration is needed.
+
+```tsx
+// No apiUrl prop → proxy mode is activated automatically
+<AziridProvider publishableKey="pk_live_...">
+```
+
+### Direct mode (for React SPA / Vite)
+
+Requests go directly to the Azirid API. Requires CORS to be configured on the API server.
+
+```tsx
+// apiUrl prop → direct mode
+<AziridProvider apiUrl="https://api.azirid.com" publishableKey="pk_live_...">
+```
+
+---
+
+## Quick Start — Next.js (Proxy Mode)
+
+### 1. Create the route handler
+
+```ts
+// app/api/auth/[...path]/route.ts
+export { GET, POST, PUT, PATCH, DELETE } from 'azirid-react/next'
+```
+
+That's it. The SDK handles proxy logic, cookie fixing, and header forwarding internally. Works with Next.js 14, 15, and 16+ automatically.
+
+### 2. Set the API URL (optional)
+
+```env
+# .env (server-side only — never exposed to the browser)
+# Default: https://api.azirid.com
+# For local development with the API running locally:
+AZIRID_API_URL=http://localhost:3000
+```
+
+### 3. Wrap your app with `<AziridProvider>`
+
+```tsx
+// app/layout.tsx
+import { AziridProvider } from 'azirid-react'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <AziridProvider
+      publishableKey={process.env.NEXT_PUBLIC_AZIRID_PK!}
+      onLoginSuccess={(data) => console.log('Logged in:', data.user)}
+      onLogoutSuccess={() => console.log('Logged out')}
+      onSessionExpired={() => (window.location.href = '/login')}
+    >
+      {children}
+    </AziridProvider>
+  )
+}
+```
+
+### 4. Add the login page
+
+```tsx
+// app/login/page.tsx
+import { LoginForm } from 'azirid-react'
+
+export default function LoginPage() {
+  return <LoginForm />
+}
+```
+
+---
+
+## Quick Start — React SPA (Direct Mode)
+
+### 1. Wrap your app with `<AziridProvider>`
+
+```tsx
+// main.tsx (Vite / CRA)
+import { AziridProvider } from 'azirid-react'
+
+createRoot(document.getElementById('root')!).render(
+  <AziridProvider
+    apiUrl={import.meta.env.VITE_AZIRID_API_URL || 'https://api.azirid.com'}
+    publishableKey={import.meta.env.VITE_AZIRID_PK}
+    onLoginSuccess={(data) => console.log('Logged in:', data.user)}
+  >
+    <App />
+  </AziridProvider>,
+)
+```
+
+### 2. Configure your environment
+
+```env
+# .env
+VITE_AZIRID_API_URL=https://api.azirid.com
+VITE_AZIRID_PK=pk_live_...
+```
+
+### 3. Use the forms or hooks
+
+```tsx
+import { LoginForm } from 'azirid-react'
+
+export default function LoginPage() {
+  return <LoginForm />
+}
+```
+
+No route handler or proxy needed — requests go directly to the API.
+
+---
+
+## Headless hooks
+
+All hooks require `<AziridProvider>` in the tree.
+
+### `useAzirid` — session state
+
+```tsx
+import { useAzirid } from 'azirid-react'
+
+function Navbar() {
+  const { user, isAuthenticated, isLoading, login, logout } = useAzirid()
+
+  if (isLoading) return <Spinner />
+
+  return isAuthenticated ? (
+    <div>
+      <span>Hello, {user!.email}</span>
+      <button onClick={logout}>Sign out</button>
+    </div>
+  ) : (
+    <button onClick={() => login({ email: '...', password: '...' })}>Sign in</button>
+  )
+}
+```
+
+### `useLogin`
+
+```tsx
+import { useLogin } from 'azirid-react'
+
+function CustomLoginForm() {
+  const { login, isLoading, error } = useLogin({
+    onSuccess: (data) => console.log(data.user),
+    onError: (msg) => console.error(msg),
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        const fd = new FormData(e.currentTarget)
+        login({
+          email: fd.get('email') as string,
+          password: fd.get('password') as string,
+        })
+      }}
+    >
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      {error && <p>{error}</p>}
+      <button disabled={isLoading}>Sign in</button>
+    </form>
+  )
+}
+```
+
+### `useSignup`
+
+```tsx
+import { useSignup } from 'azirid-react'
+
+const { signup, isLoading, error } = useSignup({
+  onSuccess: (data) => console.log('Registered:', data.user),
+})
+
+signup({ email: 'user@example.com', password: 'secret' })
+```
+
+### `useLogout`
+
+```tsx
+import { useLogout } from 'azirid-react'
+
+const { logout, isLoading } = useLogout({
+  onSuccess: () => router.push('/login'),
+})
+```
+
+### `useSession`
+
+```tsx
+import { useSession } from 'azirid-react'
+
+const { user, accessToken, isAuthenticated } = useSession()
+```
+
+### `useMagicLink`
+
+```tsx
+import { useMagicLink } from 'azirid-react'
+
+const { requestMagicLink, verifyMagicLink, isLoading } = useMagicLink()
+
+requestMagicLink({ email: 'user@example.com' })
+verifyMagicLink({ token: '...' })
+```
+
+### `useSocialLogin`
+
+```tsx
+import { useSocialLogin } from 'azirid-react'
+
+const { loginWithProvider, isLoading } = useSocialLogin()
+
+loginWithProvider({ provider: 'google' }) // "google" | "github"
+```
+
+### `usePasskeys`
+
+```tsx
+import { usePasskeys } from 'azirid-react'
+
+const { passkeys, registerPasskey, removePasskey, isLoading } = usePasskeys()
+```
+
+### `useChangePassword`
+
+```tsx
+import { useChangePassword } from 'azirid-react'
+
+const { changePassword, isLoading, error } = useChangePassword()
+
+changePassword({ currentPassword: 'old', newPassword: 'new' })
+```
+
+### `useBootstrap`
+
+Manually re-run the session bootstrap (useful after SSO redirects).
+
+```tsx
+import { useBootstrap } from 'azirid-react'
+
+const { bootstrap, isBootstrapping } = useBootstrap()
+```
+
+### `useRefresh`
+
+Manually refresh the access token.
+
+```tsx
+import { useRefresh } from 'azirid-react'
+
+const { refresh } = useRefresh()
+```
+
+### `useAziridClient`
+
+Access the raw `AccessClient` instance for custom API calls.
+
+```tsx
+import { useAziridClient } from 'azirid-react'
+
+function CustomAction() {
+  const client = useAziridClient()
+
+  async function fetchCustomData() {
+    const data = await client.get('/v1/custom-endpoint')
+    console.log(data)
+  }
+
+  return <button onClick={fetchCustomData}>Fetch</button>
+}
+```
+
+### `useFormState`
+
+Headless form hook with Zod validation. Powers the built-in form components — use it to build fully custom forms.
+
+```tsx
+import { useFormState, loginSchema } from 'azirid-react'
+
+function CustomForm() {
+  const { values, errors, isSubmitting, handleChange, handleSubmit, reset } = useFormState(
+    { email: '', password: '' },
+    loginSchema,
+    async (values) => {
+      // Submit logic
+    },
+  )
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={values.email} onChange={handleChange('email')} />
+      {errors.find((e) => e.field === 'email')?.message}
+      <button disabled={isSubmitting}>Submit</button>
+    </form>
+  )
+}
+```
+
+### `usePasswordToggle`
+
+Simple toggle between `"password"` and `"text"` input types.
+
+```tsx
+import { usePasswordToggle } from 'azirid-react'
+
+function PasswordInput() {
+  const { visible, toggle, type } = usePasswordToggle()
+
+  return (
+    <div>
+      <input type={type} name="password" />
+      <button type="button" onClick={toggle}>
+        {visible ? 'Hide' : 'Show'}
+      </button>
+    </div>
+  )
+}
+```
+
+### Zod Schemas
+
+The SDK exports pre-built Zod schemas with Spanish validation messages, plus factory functions for custom messages.
+
+```tsx
+import {
+  loginSchema,
+  signupSchema,
+  changePasswordSchema,
+  magicLinkRequestSchema,
+  magicLinkVerifySchema,
+  socialLoginSchema,
+  passkeyRegisterStartSchema,
+} from 'azirid-react'
+
+// Default schemas (Spanish messages)
+loginSchema.parse({ email: 'user@example.com', password: 'secret' })
+
+// Factory functions for custom messages
+import { createLoginSchema, createSignupSchema } from 'azirid-react'
+
+const customSchema = createLoginSchema({
+  emailRequired: 'Email is required',
+  emailInvalid: 'Must be a valid email',
+  passwordRequired: 'Password is required',
+  passwordMinLength: 'At least 10 characters',
+})
+```
+
+| Schema | Fields |
+| --- | --- |
+| `loginSchema` | `email`, `password` |
+| `signupSchema` | `email`, `password`, `acceptedTosVersion?`, `acceptedPrivacyVersion?` |
+| `changePasswordSchema` | `currentPassword`, `newPassword` |
+| `magicLinkRequestSchema` | `email` |
+| `magicLinkVerifySchema` | `token` |
+| `socialLoginSchema` | `provider`, `providerAccountId`, `email`, `emailVerified?`, ... |
+| `passkeyRegisterStartSchema` | `deviceName?` |
+
+---
+
+## Billing & Payments
+
+All billing hooks require `<AziridProvider>` in the tree and an authenticated user.
+
+### `usePlans`
+
+Fetch all available billing plans for the current app.
+
+```tsx
+import { usePlans } from 'azirid-react'
+
+function PricingPage() {
+  const { data: plans, isLoading } = usePlans()
+
+  if (isLoading) return <Spinner />
+
+  return (
+    <ul>
+      {plans?.map((plan) => (
+        <li key={plan.id}>
+          {plan.name} — ${(plan.amount / 100).toFixed(2)}/{plan.interval.toLowerCase()}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### `useSubscription`
+
+Get the current user's active subscription.
+
+```tsx
+import { useSubscription } from 'azirid-react'
+
+function SubscriptionStatus() {
+  const { data: sub } = useSubscription()
+
+  if (!sub) return <p>No active subscription</p>
+
+  return (
+    <p>
+      {sub.plan.name} — {sub.status}
+      {sub.cancelAtPeriodEnd && ' (cancels at period end)'}
+    </p>
+  )
+}
+```
+
+### `useCheckout`
+
+Initiate a checkout session. Auto-redirects to the payment provider on success (unless the provider is `MANUAL_TRANSFER` or `PAYPHONE`).
+
+```tsx
+import { useCheckout } from 'azirid-react'
+
+function UpgradeButton({ planId }: { planId: string }) {
+  const { checkout, isPending } = useCheckout({
+    onSuccess: (data) => console.log('Checkout created:', data),
+    onError: (err) => console.error(err),
+  })
+
+  return (
+    <button
+      disabled={isPending}
+      onClick={() =>
+        checkout({
+          planId,
+          successUrl: `${window.location.origin}/billing?success=true`,
+          cancelUrl: `${window.location.origin}/billing`,
+        })
+      }
+    >
+      Upgrade
+    </button>
+  )
+}
+```
+
+### `useInvoices`
+
+List all invoices for the authenticated user.
+
+```tsx
+import { useInvoices } from 'azirid-react'
+
+function InvoiceHistory() {
+  const { data: invoices } = useInvoices()
+
+  return (
+    <ul>
+      {invoices?.map((inv) => (
+        <li key={inv.id}>
+          ${(inv.amount / 100).toFixed(2)} — {inv.status}
+          {inv.invoiceUrl && <a href={inv.invoiceUrl}>View</a>}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### `usePaymentProviders`
+
+Fetch available payment providers for the app (e.g., Stripe, PayPal, manual transfer).
+
+```tsx
+import { usePaymentProviders } from 'azirid-react'
+
+const { data: providers } = usePaymentProviders()
+// [{ provider: 'STRIPE', checkout: true, subscriptions: true }, ...]
+```
+
+### `useSubmitTransferProof`
+
+Submit proof of a manual bank transfer payment.
+
+```tsx
+import { useSubmitTransferProof } from 'azirid-react'
+
+const { submit, isPending } = useSubmitTransferProof({
+  onSuccess: (proof) => console.log('Proof submitted:', proof.id),
+})
+
+submit({
+  planId: 'plan_123',
+  fileUrl: 'https://storage.example.com/receipt.pdf',
+  amount: 9999,
+  currency: 'USD',
+  notes: 'Bank transfer from Account #1234',
+})
+```
+
+### `useTransferProofs`
+
+List submitted transfer proofs and their review status.
+
+```tsx
+import { useTransferProofs } from 'azirid-react'
+
+const { data: proofs } = useTransferProofs()
+// [{ id, status: 'PENDING_REVIEW' | 'APPROVED' | 'REJECTED', ... }]
+```
+
+### `usePayphoneConfirm`
+
+Confirm a Payphone payment callback. Used on the Payphone return URL page.
+
+```tsx
+import { usePayphoneConfirm } from 'azirid-react'
+
+const confirm = usePayphoneConfirm({
+  onSuccess: (data) => console.log('Payment confirmed:', data.status),
+})
+
+confirm.mutate({ id: 12345, clientTransactionId: 'txn_abc' })
+```
+
+### Billing Components
+
+#### `PricingTable`
+
+Drop-in pricing grid with checkout flow integrated.
+
+```tsx
+import { PricingTable } from 'azirid-react'
+
+<PricingTable
+  successUrl={`${window.location.origin}/billing?success=true`}
+  cancelUrl={`${window.location.origin}/billing`}
+  columns={3}
+  onPlanSelect={(plan) => console.log('Selected:', plan.name)}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `successUrl` | `string` | — | **Required.** Redirect URL after successful payment |
+| `cancelUrl` | `string` | — | **Required.** Redirect URL on cancel |
+| `columns` | `number` | `3` | Number of columns in the grid |
+| `onPlanSelect` | `(plan) => void` | — | Called when a plan is selected |
+| `className` | `string` | — | Additional CSS classes |
+
+#### `PayButton`
+
+Flexible payment button with provider selection modal. Supports both plans and payment intents.
+
+```tsx
+import { PayButton } from 'azirid-react'
+
+<PayButton
+  planId="plan_123"
+  successUrl="/billing?success=true"
+  cancelUrl="/billing"
+  onSuccess={(data) => console.log('Payment success:', data)}
+>
+  Subscribe Now
+</PayButton>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `planId` | `string` | — | Plan to purchase (use `planId` or `intentId`) |
+| `intentId` | `string` | — | Payment intent ID (alternative to `planId`) |
+| `successUrl` | `string` | — | **Required.** Redirect URL after success |
+| `cancelUrl` | `string` | — | **Required.** Redirect URL on cancel |
+| `onSuccess` | `(data) => void` | — | Called on successful checkout |
+| `onError` | `(error) => void` | — | Called on error |
+| `children` | `ReactNode` | — | Button label |
+| `disabled` | `boolean` | — | Disable the button |
+
+#### `CheckoutButton`
+
+Simple checkout button for a specific plan.
+
+```tsx
+import { CheckoutButton } from 'azirid-react'
+
+<CheckoutButton
+  planId="plan_123"
+  successUrl="/billing?success=true"
+  cancelUrl="/billing"
+>
+  Subscribe
+</CheckoutButton>
+```
+
+#### `SubscriptionBadge`
+
+Color-coded badge showing the current subscription status.
+
+```tsx
+import { SubscriptionBadge } from 'azirid-react'
+
+<SubscriptionBadge />
+// Renders: "Pro · Active" (green), "Free · Trialing" (blue), etc.
+```
+
+Status colors: ACTIVE (green), TRIALING (blue), PAST_DUE (yellow), CANCELED/UNPAID (red), INCOMPLETE (gray).
+
+#### `InvoiceList`
+
+Table of invoices with status badges and download links.
+
+```tsx
+import { InvoiceList } from 'azirid-react'
+
+<InvoiceList />
+```
+
+#### `PayphoneCallback`
+
+Page component for handling Payphone payment callbacks. Reads `id` and `clientTransactionId` from URL query params automatically.
+
+```tsx
+// app/payphone/callback/page.tsx
+import { PayphoneCallback } from 'azirid-react'
+
+export default function PayphoneCallbackPage() {
+  return (
+    <PayphoneCallback
+      onSuccess={(data) => console.log('Confirmed:', data.status)}
+      onError={(err) => console.error(err)}
+    />
+  )
+}
+```
+
+---
+
+## Referrals
+
+All referral hooks require `<AziridProvider>` in the tree and an authenticated user.
+
+### `useReferral`
+
+Fetch the current user's referral info and copy referral link to clipboard.
+
+```tsx
+import { useReferral } from 'azirid-react'
+
+function ReferralSection() {
+  const { data, copyToClipboard } = useReferral()
+
+  if (!data) return null
+
+  return (
+    <div>
+      <p>Your referral code: {data.referralCode}</p>
+      <input readOnly value={data.referralUrl} />
+      <button onClick={copyToClipboard}>Copy Link</button>
+      <p>
+        {data.completedReferrals} completed / {data.totalReferred} total
+      </p>
+    </div>
+  )
+}
+```
+
+### `useReferralStats`
+
+Fetch detailed referral history with rewards.
+
+```tsx
+import { useReferralStats } from 'azirid-react'
+
+function ReferralHistory() {
+  const { data } = useReferralStats()
+
+  return (
+    <ul>
+      {data?.referrals.map((ref) => (
+        <li key={ref.id}>
+          {ref.referredEmail} — {ref.status}
+          {ref.rewardAmount && ` ($${ref.rewardAmount})`}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Referral Components
+
+#### `ReferralCard`
+
+Card displaying the referral link with copy button and stats.
+
+```tsx
+import { ReferralCard } from 'azirid-react'
+
+<ReferralCard
+  title="Refer a Friend"
+  description="Share your link and earn rewards for each signup."
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"Refer a Friend"` | Card title |
+| `description` | `string` | — | Card description |
+| `className` | `string` | — | Additional CSS classes |
+
+#### `ReferralStats`
+
+Table showing referral history with status and reward badges.
+
+```tsx
+import { ReferralStats } from 'azirid-react'
+
+<ReferralStats />
+```
+
+---
+
+## Internationalization (i18n)
+
+Built-in support for **English** and **Spanish**. The SDK ships two complete dictionaries; pass a `locale` prop to switch languages.
+
+```tsx
+import { AziridProvider } from 'azirid-react'
+;<AziridProvider publishableKey="pk_live_..." locale="en">
+  {/* All form labels, validation messages, and UI text render in English */}
+  {children}
+</AziridProvider>
+```
+
+### Supported locales
+
+| Locale | Language          |
+| ------ | ----------------- |
+| `"es"` | Spanish (default) |
+| `"en"` | English           |
+
+### Custom messages
+
+Override any string by passing a partial `messages` object:
+
+```tsx
+<AziridProvider
+  publishableKey="pk_live_..."
+  locale="en"
+  messages={{
+    login: { title: 'Welcome back!', submit: 'Sign in' },
+    validation: { emailRequired: 'Please enter your email' },
+  }}
+>
+  {children}
+</AziridProvider>
+```
+
+### Using i18n hooks directly
+
+```tsx
+import { useMessages, useBranding } from 'azirid-react'
+
+function CustomForm() {
+  const msg = useMessages() // resolved messages for current locale
+  return <label>{msg.login.emailLabel}</label>
+}
+```
+
+### Locale-aware Zod schemas
+
+```tsx
+import { createLoginSchema, createSignupSchema } from 'azirid-react'
+
+// Pass custom validation messages
+const schema = createLoginSchema({
+  emailRequired: 'Email is required',
+  emailInvalid: 'Must be a valid email',
+  passwordRequired: 'Password is required',
+  passwordMin: 'At least 8 characters',
+})
+```
+
+---
+
+## Branding
+
+The bootstrap endpoint returns branding data configured in the Azirid dashboard (Settings > Branding). The built-in form components automatically apply branding.
+
+### Auto-branding from bootstrap
+
+If branding is configured for your app, the forms will automatically:
+
+- Show your **logo** (from `branding.logoUrl`) above the form
+- Use your **display name** as the form title
+- Apply your **primary color** to the submit button
+- Show/hide the **"Secured by Azirid"** badge
+
+No extra code needed — just configure branding in the dashboard.
+
+### Overriding branding with props
+
+Per-component props always take priority over branding context:
+
+```tsx
+<LoginForm
+  logo={<MyCustomLogo />} // overrides branding.logoUrl
+  title="Sign in to Acme" // overrides branding.displayName
+  submitText="Continue"
+/>
+```
+
+### Using branding hooks
+
+```tsx
+import { useBranding } from 'azirid-react'
+
+function CustomHeader() {
+  const branding = useBranding() // AppBranding | null
+
+  return (
+    <div>
+      {branding?.logoUrl && <img src={branding.logoUrl} alt="Logo" />}
+      <h1 style={{ color: branding?.primaryColor ?? '#000' }}>
+        {branding?.displayName ?? 'My App'}
+      </h1>
+    </div>
+  )
+}
+```
+
+### "Secured by Azirid" badge
+
+The `<SecuredByBadge />` component renders below each form. It's hidden when `branding.removeBranding` is `true` (configurable in the dashboard).
+
+```tsx
+import { SecuredByBadge } from "azirid-react";
+
+// Use in custom form layouts
+<form>
+  {/* ... your form fields ... */}
+</form>
+<SecuredByBadge />
+```
+
+---
+
+## createAccessClient
+
+Under the hood `AziridProvider` creates an `AccessClient` via `createAccessClient`. You can also create a client directly to make raw API calls.
+
+```ts
+import { createAccessClient, BASE_PATHS } from 'azirid-react'
+import type { AccessClientConfig } from 'azirid-react'
+
+// Direct mode — point to the API
+const client = createAccessClient(
+  {
+    baseUrl: 'https://api.azirid.com',
+    basePath: BASE_PATHS.direct, // '/v1/users/auth'
+  },
+  { publishableKey: 'pk_live_...' },
+)
+
+// Set tokens after login
+client.setAccessToken('eyJ...')
+client.setRefreshToken('...')
+
+// Make arbitrary authenticated calls
+const data = await client.get(client.paths.me)
+const result = await client.post('/v1/custom-endpoint', { foo: 'bar' })
+```
+
+### `createAccessClient` signature
+
+```ts
+function createAccessClient(
+  config: AccessClientConfig,
+  appContext?: { publishableKey: string; tenantId?: string },
+): AccessClient
+```
+
+| Param       | Type                 | Description                                                      |
+| ----------- | -------------------- | ---------------------------------------------------------------- |
+| `config`    | `AccessClientConfig` | `{ baseUrl, basePath?, headers? }`                               |
+| `appContext` | `object`            | Optional. `publishableKey` and `tenantId`                        |
+
+---
+
+## AziridProvider props
+
+| Prop               | Type                      | Default  | Description                                                                                    |
+| ------------------ | ------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `children`         | `ReactNode`               | —        | **Required.** Your app tree                                                                    |
+| `apiUrl`           | `string`                  | —        | API URL for direct mode. Omit for proxy mode (recommended in Next.js)                          |
+| `publishableKey`   | `string`                  | —        | Publishable key (e.g. `pk_live_...`)                                                           |
+| `tenantId`         | `string`                  | —        | Tenant ID for multi-tenant apps                                                                |
+| `fetchOptions`     | `Record<string, string>`  | —        | Extra headers to send with every request                                                       |
+| `autoBootstrap`    | `boolean`                 | `true`   | Auto-restore session on mount                                                                  |
+| `refreshInterval`  | `number`                  | `50000`  | Token refresh interval in ms. `0` to disable                                                   |
+| `sessionSyncUrl`   | `string \| false`         | auto     | URL for session cookie sync. Auto-activates in dev mode. Pass `false` to disable               |
+| `onLoginSuccess`   | `(data) => void`          | —        | Called after successful login                                                                  |
+| `onSignupSuccess`  | `(data) => void`          | —        | Called after successful signup                                                                 |
+| `onLogoutSuccess`  | `() => void`              | —        | Called after logout                                                                            |
+| `onSessionExpired` | `() => void`              | —        | Called when refresh fails                                                                      |
+| `onError`          | `(msg: string) => void`   | —        | Called on any auth error                                                                       |
+| `locale`           | `"es" \| "en"`            | `"es"`   | UI language for built-in forms and validation messages                                         |
+| `messages`         | `Partial<AccessMessages>` | —        | Override any i18n string (merged on top of the locale dictionary)                              |
+
+---
+
+## Next.js Integration
+
+`azirid-react` supports **Next.js 14, 15, and 16+** with full compatibility for each version's API conventions.
+
+### Proxy Route Handler (all versions)
+
+Create the file `app/api/auth/[...path]/route.ts` — one line is all you need:
+
+```ts
+// app/api/auth/[...path]/route.ts
+export { GET, POST, PUT, PATCH, DELETE } from 'azirid-react/next'
+```
+
+That's it. The SDK handles all the proxy logic, cookie fixing, and header forwarding internally.
+It works with Next.js 14, 15, and 16+ automatically.
+
+### Custom API URL or debug logging
+
+```ts
+// app/api/auth/[...path]/route.ts
+import { createAziridRouteHandlers } from 'azirid-react/next'
+
+export const { GET, POST, PUT, PATCH, DELETE } = createAziridRouteHandlers({
+  apiUrl: 'https://my-custom-api.com',
+  debug: true, // logs proxy requests to console
+})
+```
+
+### Environment variable
+
+The proxy reads `AZIRID_API_URL` (server-side only) to know where to forward requests:
+
+```env
+# .env
+# Default: https://api.azirid.com
+# For local development:
+AZIRID_API_URL=http://localhost:3000
+```
+
+> **Important:** Use `AZIRID_API_URL` (without `NEXT_PUBLIC_` prefix) — the API URL should never be exposed to the browser. The proxy runs server-side only.
+
+### Next.js Config
+
+#### Next.js 16+ (`next.config.ts`)
+
+Turbopack is the default bundler — `transpilePackages` is no longer needed:
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {}
+
+export default nextConfig
+```
+
+#### Next.js 14/15 (`next.config.js`)
+
+```js
+// next.config.js
+const { withAziridProxy } = require('azirid-react/next')
+
+/** @type {import('next').NextConfig} */
+module.exports = withAziridProxy()({
+  transpilePackages: ['azirid-react'],
+})
+```
+
+### Route Protection (optional)
+
+> **Not required for basic usage.** Only add this if you need to protect specific routes from unauthenticated users.
+
+#### Next.js 16+ (`proxy.ts`)
+
+```ts
+// proxy.ts — only needed if you want route protection
+import { createAziridProxy } from 'azirid-react/next'
+
+export const proxy = createAziridProxy({
+  protectedRoutes: ['/dashboard', '/settings'],
+  loginUrl: '/login',
+  publicRoutes: ['/login', '/signup', '/forgot-password'],
+})
+
+export const config = {
+  matcher: ['/((?!_next|favicon.ico|api/).*)'],
+}
+```
+
+#### Next.js 14/15 (`middleware.ts`)
+
+```ts
+// middleware.ts — only needed if you want route protection
+import { createAziridMiddleware } from 'azirid-react/next'
+
+export default createAziridMiddleware({
+  protectedRoutes: ['/dashboard', '/settings'],
+  loginUrl: '/login',
+  publicRoutes: ['/login', '/signup', '/forgot-password'],
+})
+
+export const config = {
+  matcher: ['/((?!_next|favicon.ico|api/).*)'],
+}
+```
+
+---
+
+## Server-side (Next.js App Router)
+
+For **Server Components**, **Server Actions**, and **Route Handlers**, use the `azirid-react/server` entry point to read the session token from the httpOnly `__session` cookie.
+
+### Setup
+
+```ts
+// lib/access-server.ts
+import { cookies } from 'next/headers'
+import { createServerAccess } from 'azirid-react/server'
+
+// Works with all Next.js versions:
+// - Next.js 14: cookies() returns a sync cookie store
+// - Next.js 15/16+: cookies() returns a Promise — handled automatically
+export const { getSessionToken, getAccessToken } = createServerAccess({ cookies })
+```
+
+### Server Action example
+
+```ts
+// app/actions/profile.ts
+'use server'
+import { getSessionToken } from '@/lib/access-server'
+
+export async function getProfile() {
+  const token = await getSessionToken()
+  if (!token) throw new Error('Not authenticated')
+
+  const res = await fetch(`${process.env.AZIRID_API_URL}/v1/users/auth/me`, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+  return res.json()
+}
+```
+
+### Server Component example
+
+```tsx
+// app/dashboard/page.tsx
+import { redirect } from 'next/navigation'
+import { getSessionToken } from '@/lib/access-server'
+
+export default async function DashboardPage() {
+  const token = await getSessionToken()
+  if (!token) redirect('/login')
+
+  const res = await fetch(`${process.env.AZIRID_API_URL}/v1/users/auth/me`, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+  const user = await res.json()
+
+  return <h1>Hello, {user.email}</h1>
+}
+```
+
+### Options
+
+| Option       | Type     | Default       | Description                                |
+| ------------ | -------- | ------------- | ------------------------------------------ |
+| `cookieName` | `string` | `"__session"` | Name of the httpOnly cookie with the token |
+
+### `createSessionSyncHandler`
+
+Creates a route handler that syncs the access token to a local httpOnly cookie. Useful for cross-origin development setups where the API is on a different domain.
+
+```ts
+// app/api/auth/session/route.ts
+import { createSessionSyncHandler } from 'azirid-react/server'
+
+export const { POST, DELETE } = createSessionSyncHandler()
+```
+
+With custom options:
+
+```ts
+export const { POST, DELETE } = createSessionSyncHandler({
+  cookieName: '__session', // default
+  secure: true, // set Secure flag on cookie
+  maxAge: 3600, // cookie max age in seconds (default: 1h)
+})
+```
+
+| Option       | Type      | Default       | Description                         |
+| ------------ | --------- | ------------- | ----------------------------------- |
+| `cookieName` | `string`  | `"__session"` | Name of the httpOnly cookie         |
+| `secure`     | `boolean` | `false`       | Set the `Secure` flag on the cookie |
+| `maxAge`     | `number`  | `3600`        | Cookie max age in seconds           |
+
+---
+
+## Version Compatibility
+
+| Feature             | Next.js 14       | Next.js 15          | Next.js 16+         |
+| ------------------- | ---------------- | ------------------- | ------------------- |
+| React               | 18.x             | 18.x / 19.x         | 19.x+               |
+| Node.js             | >= 18.0.0        | >= 18.17.0          | >= 20.9.0           |
+| Config file         | `next.config.js` | `next.config.js/ts` | `next.config.ts`    |
+| Request interceptor | `middleware.ts`  | `middleware.ts`     | `proxy.ts`          |
+| `cookies()`         | sync             | async (with compat) | async only          |
+| `params`            | sync             | async (with compat) | async only          |
+| Bundler             | Webpack          | Webpack/Turbopack   | Turbopack (default) |
+| `transpilePackages` | Required         | Required            | Not needed          |
+
+---
+
+## Tailwind CSS (optional)
+
+The built-in form components (`LoginForm`, `SignupForm`, etc.) use Tailwind utility classes. Add `azirid-react` to your `content` glob so Tailwind picks them up.
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: ['./src/**/*.{ts,tsx}', './node_modules/azirid-react/dist/**/*.{js,mjs}'],
+}
+```
+
+---
+
+## Utilities
+
+### `SDK_VERSION`
+
+```tsx
+import { SDK_VERSION } from 'azirid-react'
+
+console.log(`azirid-react v${SDK_VERSION}`)
+```
+
+### `isAuthError`
+
+Check if an error is an authentication error (401 or 403).
+
+```tsx
+import { isAuthError } from 'azirid-react'
+
+try {
+  await someApiCall()
+} catch (err) {
+  if (isAuthError(err)) {
+    // redirect to login
+  }
+}
+```
+
+### `removeStyles`
+
+Remove CSS styles injected by SDK components. Useful when unmounting the provider.
+
+```tsx
+import { removeStyles } from 'azirid-react'
+
+useEffect(() => {
+  return () => removeStyles()
+}, [])
+```
+
+### `cn`
+
+Tailwind class merge utility (powered by `clsx` + `tailwind-merge`).
+
+```tsx
+import { cn } from 'azirid-react'
+
+<div className={cn('p-4 bg-white', isActive && 'bg-blue-500')} />
+```
+
+### `BASE_PATHS` and `buildPaths`
+
+```tsx
+import { BASE_PATHS, buildPaths } from 'azirid-react'
+
+BASE_PATHS.proxy  // '/api/auth'
+BASE_PATHS.direct // '/v1/users/auth'
+
+// Build custom path map from a base path
+const paths = buildPaths('/custom/auth')
+// paths.login → '/custom/auth/login'
+// paths.signup → '/custom/auth/signup'
+// etc.
+```
+
+---
+
+## Types Reference
+
+All types are exported from `azirid-react` and can be imported directly:
+
+```tsx
+import type {
+  AuthUser,
+  AuthSuccessResponse,
+  AppBranding,
+  SignupData,
+  BillingPlan,
+  UserSubscription,
+  // ...
+} from 'azirid-react'
+```
+
+### Auth Types
+
+| Type | Description |
+| --- | --- |
+| `AuthUser` | Authenticated user object (`id`, `email`, `firstName`, `emailVerified`, `mfaEnabled`, `appId`, `tenantId`, ...) |
+| `AuthSuccessResponse` | Login/signup response (`accessToken`, `user`) |
+| `AuthState` | Full auth state (`user`, `accessToken`, `isAuthenticated`, `isLoading`, `error`) |
+| `SignupData` | Signup payload (`email`, `password`, `acceptedTosVersion?`, `referralCode?`, ...) |
+| `AppBranding` | Branding config (`displayName`, `logoUrl`, `primaryColor`, `removeBranding`, ...) |
+| `BootstrapResponse` | Bootstrap result (authenticated/unauthenticated + branding) |
+| `AziridProviderProps` | All provider props (see table above) |
+| `AziridContextValue` | Context value returned by `useAzirid()` |
+
+### Billing Types
+
+| Type | Description |
+| --- | --- |
+| `BillingPlan` | Plan object (`id`, `name`, `amount`, `currency`, `interval`, `features`, ...) |
+| `UserSubscription` | Subscription (`planId`, `plan`, `status`, `currentPeriodEnd`, `cancelAtPeriodEnd`, ...) |
+| `CheckoutResponse` | Checkout result (`url`, `sessionId`, `provider`, `plan`, `widgetConfig`, `bankDetails`, ...) |
+| `BillingInvoice` | Invoice (`amount`, `currency`, `status`, `paidAt`, `invoiceUrl`, ...) |
+| `PaymentProviderType` | `'STRIPE' \| 'PAYPAL' \| 'PAYPHONE' \| 'NUVEI' \| 'MANUAL_TRANSFER'` |
+| `AvailableProvider` | Provider info (`provider`, `checkout`, `subscriptions`) |
+| `SubmitTransferProofData` | Transfer proof payload (`planId`, `fileUrl`, `amount`, ...) |
+| `TransferProof` | Transfer proof object (`status`: `PENDING_REVIEW \| APPROVED \| REJECTED`, ...) |
+| `PayphoneWidgetConfig` | Payphone widget config (`token`, `storeId`, `amount`, ...) |
+
+### Referral Types
+
+| Type | Description |
+| --- | --- |
+| `ReferralInfo` | Referral info (`referralCode`, `referralUrl`, `totalReferred`, `completedReferrals`, ...) |
+| `ReferralStatsData` | Stats + referral list (`totalRewards`, `referrals[]`) |
+| `ReferralItem` | Single referral (`referredEmail`, `status`, `rewardStatus`, `rewardAmount`, ...) |
+
+### Form Types
+
+| Type | Description |
+| --- | --- |
+| `LoginFormProps` | LoginForm component props (`title`, `logo`, `labels`, `showSocialButtons`, ...) |
+| `SignupFormProps` | SignupForm component props |
+| `FieldError` | Validation error (`{ field: string, message: string }`) |
+| `UseFormReturn<T>` | Return type of `useFormState()` |
+
+### Passkey Types
+
+| Type | Description |
+| --- | --- |
+| `PasskeyItem` | Passkey entry (`id`, `deviceName`, `credentialId`, `lastUsedAt`) |
+| `PasskeyRegisterStartData` | Registration start payload (`deviceName?`) |
+| `PasskeyRegisterStartResponse` | Registration challenge (`challengeId`, `options`) |
+| `PasskeyLoginStartResponse` | Login challenge (`challengeId`, `options`) |
+
+---
+
+## License
+
+MIT