npm - insforge - Versions diffs - 0.3.3 → 1.2.10 - Mend

insforge 0.3.3 → 1.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (507) hide show

package/docs/core-concepts/authentication/ui-components/nextjs.mdx ADDED Viewed

@@ -0,0 +1,221 @@
+---
+title: Next.js
+description: Zero-configuration authentication for Next.js with built-in UI components
+---
+The `@insforge/nextjs` package provides **zero-configuration authentication** for Next.js applications. Authentication pages are hosted on your backend by default—no UI code needed.
+## Quick Start
+### Step 1: Install Package and Set Environment Variables
+```bash
+npm install @insforge/nextjs@latest
+```
+```bash .env.local
+NEXT_PUBLIC_INSFORGE_BASE_URL=https://your-app.region.insforge.app
+```
+### Step 2: Add Middleware
+Create middleware to protect routes:
+```ts middleware.ts
+import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+export default InsforgeMiddleware({
+  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app', // Replace with your InsForge backend URL
+  publicRoutes: ['/'],
+});
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+};
+```
+### Step 3: Create API Route
+Create an API route to enable server-side rendering (SSR) and cookie-based authentication:
+```tsx app/api/auth/route.ts
+import { createAuthRouteHandlers } from '@insforge/nextjs/api';
+const handlers = createAuthRouteHandlers({
+  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app', // Replace with your InsForge backend URL
+});
+export const POST = handlers.POST;
+export const GET = handlers.GET;
+export const DELETE = handlers.DELETE;
+```
+<Info>**Why?** This route syncs auth tokens to HTTP-only cookies for server-side middleware.</Info>
+### Step 4: Add InsforgeProvider
+Wrap your application with the `InsforgeProvider` in your root layout:
+```tsx app/layout.tsx
+import {
+  InsforgeProvider,
+  SignedIn,
+  SignedOut,
+  SignInButton,
+  SignUpButton,
+  UserButton,
+} from '@insforge/nextjs';
+export const metadata: Metadata = {
+  title: 'InsForge Next.js Quickstart',
+  description: 'Generated by create next app',
+};
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <InsforgeProvider
+          baseUrl={
+            process.env.NEXT_PUBLIC_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app' // Replace with your InsForge backend URL
+          }
+        >
+          <nav>
+            <SignedOut>
+              <SignInButton />
+              <SignUpButton />
+            </SignedOut>
+            <SignedIn>
+              <UserButton />
+            </SignedIn>
+          </nav>
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+<Info>
+  **Preventing FOUC**: The CSS import in your root layout ensures styles are loaded during
+  server-side rendering, preventing flash of unstyled content (FOUC). Without this import,
+  components may briefly appear unstyled when the page first loads.
+</Info>
+**That's it!** When users click "Sign In", they'll be redirected to your backend's auth page automatically.
+## Next Steps
+### Client-side Hooks
+#### `useAuth()`
+Access authentication state in client side:
+```tsx
+'use client';
+import { useAuth } from '@insforge/nextjs';
+function LoginButton() {
+  const { isSignedIn, isLoaded } = useAuth();
+  if (!isLoaded) return <div>Loading...</div>;
+  return <div>{isSignedIn ? 'Welcome!' : 'Sign In'}</div>;
+}
+```
+**Returns:**
+- `isSignedIn` - Boolean auth state
+- `isLoaded` - Boolean loading state
+#### `useUser()`
+Access current user data in client side:
+```tsx
+'use client';
+import { useUser } from '@insforge/nextjs';
+function UserProfile() {
+  const { user, isLoaded } = useUser();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+  return (
+    <div>
+      <p>Id: {user.id}</p>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+      <img src={user.avatarUrl} alt="Avatar" />
+    </div>
+  );
+}
+```
+**Returns:**
+- `user` - User object with id, email, name, avatarUrl
+- `isLoaded` - Boolean loading state
+### Server side functions
+#### `auth`
+Access current user data and access token in server side:
+```tsx
+import { auth } from '@insforge/nextjs/server';
+import { createClient } from '@insforge/sdk';
+export async function POST(request: NextRequest) {
+  try {
+    // Authenticate the request and get user info
+    const { user, userId, token } = await auth();
+    // Parse request body to get the prompt
+    const { prompt } = await request.json();
+    // Create InsForge SDK
+    const insforge = createClient({
+      baseUrl: process.env.NEXT_PUBLIC_INSFORGE_BASE_URL || "https://your-app.region.insforge.app",
+      anonKey: token
+    });
+    // Request for AI response
+    const completion = await insforge.ai.chat.completions.create({
+      model: 'anthropic/claude-3.5-haiku',
+      messages: [
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+    });
+    const generatedResponse = completion.choices[0].message.content.trim();
+    // Return success response
+    return NextResponse.json(
+      {
+        success: true,
+        data: generatedResponse,
+      },
+      { status: 201 }
+    );
+  } catch (error) {
+    console.error(error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+```

package/docs/core-concepts/authentication/ui-components/react-router.mdx ADDED Viewed

@@ -0,0 +1,184 @@
+---
+title: React + React Router
+description: Framework-agnostic authentication components for React + React Router application
+---
+The `@insforge/react-router` package provides **complete authentication solution for React applications**. Use deployed auth pages (built-in auth) or custom UI components—works with Vite + React Router.
+## Quick Start
+### Step 1: Create New React Project (Required)
+```bash
+npm install react-router-dom @insforge/react-router@latest
+```
+### Step 2: Set Environment Variables
+```bash .env
+VITE_INSFORGE_BASE_URL=https://your-app.region.insforge.app
+VITE_INSFORGE_ANON_KEY=your-anon-key-here
+```
+### Step 3: Setup Provider
+Wrap your app with `InsforgeProvider` in the root:
+```tsx src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { InsforgeProvider } from '@insforge/react-router';
+import App from './App';
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <InsforgeProvider
+      baseUrl={
+        import.meta.env.VITE_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app' // Replace with your InsForge backend URL
+      }
+    >
+      <App />
+    </InsforgeProvider>
+  </StrictMode>
+);
+```
+### Step 4: Configure Router (Built-in Auth)
+**The fastest way** - Use deployed auth pages with Layout pattern:
+```tsx src/App.tsx
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import { getInsforgeRoutes } from '@insforge/react-router/router';
+import Layout from './components/Layout';
+import Home from './pages/Home';
+import Dashboard from './pages/Dashboard';
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Layout />,
+    children: [
+      { index: true, element: <Home /> },
+      { path: 'dashboard', element: <Dashboard /> },
+    ],
+  },
+  ...getInsforgeRoutes({
+    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app', // Replace with your InsForge backend URL
+    afterSignInUrl: '/dashboard',
+  }),
+]);
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+```tsx src/components/Layout.tsx
+import { Outlet } from 'react-router-dom';
+export default function Layout() {
+  return (
+    <div>
+      <nav>{/* Your navigation */}</nav>
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+```
+**What this does:**
+- Visiting `/sign-in` → Redirects to `your-project.insforge.app/auth/sign-in`
+- Visiting `/sign-up` → Redirects to `your-project.insforge.app/auth/sign-up`
+- Visiting `/forgot-password` → Redirects to `your-project.insforge.app/auth/forgot-password`
+- After auth → Backend redirects with token in URL → SDK auto-detects and stores token → Goes to dashboard
+<Info>
+  **Built-in auth** means using authentication pages hosted in your InsForge App. No UI code needed!
+</Info>
+### Step 5: Use Hooks & Components
+```tsx src/pages/Home.tsx
+import { SignInButton, SignedIn, SignedOut, UserButton } from '@insforge/react-router';
+export default function Home() {
+  return (
+    <div>
+      <SignedOut>
+        <SignInButton />
+      </SignedOut>
+      <SignedIn>
+        <UserButton />
+        <h1>Welcome!</h1>
+      </SignedIn>
+    </div>
+  );
+}
+```
+**That's it!** Your React + React Router app now has production-ready authentication with built-in auth pages.
+## Next Steps
+### Hooks
+#### `useAuth()`
+Access authentication state:
+```tsx
+import { useAuth } from '@insforge/react-router';
+function LoginButton() {
+  const { isSignedIn, isLoaded } = useAuth();
+  if (!isLoaded) return <div>Loading...</div>;
+  return (
+    <div>
+      {isSignedIn ? 'Welcome!' : 'Sign In'}
+    </div>
+  );
+}
+```
+**Returns:**
+- `isSignedIn` - Boolean auth state
+- `isLoaded` - Boolean loading state
+#### `useUser()`
+Access current user data:
+```tsx
+import { useUser } from '@insforge/react-router';
+function UserProfile() {
+  const { user, isLoaded } = useUser();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+  return (
+    <div>
+      <p>Id: {user.id}</p>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+      <img src={user.avatarUrl} alt="Avatar" />
+    </div>
+  );
+}
+```
+**Returns:**
+- `user` - User object with id, email, name, avatarUrl
+- `isLoaded` - Boolean loading state

package/docs/core-concepts/authentication/ui-components/react.mdx ADDED Viewed

@@ -0,0 +1,129 @@
+---
+title: React
+description: Framework-agnostic authentication components for any React application
+---
+The `@insforge/react` package provides **complete authentication solution for React applications**. Use deployed auth pages (built-in auth) or custom UI components—works with Vite.
+## Quick start
+### Step 1: Create New React Project (Required)
+```bash
+npm install @insforge/react@latest
+```
+### Step 2: Set Environment Variables
+```bash .env
+VITE_INSFORGE_BASE_URL=https://your-app.region.insforge.app
+VITE_INSFORGE_ANON_KEY=your-anon-key-here
+```
+### Step 3: Setup Provider
+Wrap your app with `InsforgeProvider` in the root:
+```tsx src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { InsforgeProvider } from '@insforge/react';
+import App from './App';
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <InsforgeProvider
+      baseUrl={
+        import.meta.env.VITE_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app' // Replace with your InsForge backend URL
+      }
+    >
+      <App />
+    </InsforgeProvider>
+  </StrictMode>
+);
+```
+### Step 4: Use Hooks & Components
+```tsx src/pages/Home.tsx
+import { SignInButton, SignUpButton, SignedIn, SignedOut, UserButton, useUser } from '@insforge/react';
+export default function Home() {
+  const { user } = useUser();
+  return (
+    <div>
+      <SignedOut>
+        <SignInButton />
+        <SignUpButton />
+      </SignedOut>
+      <SignedIn>
+        <UserButton />
+        <h1>Welcome, {user?.email}!</h1>
+      </SignedIn>
+    </div>
+  );
+}
+```
+**That's it!** Your React app now has production-ready authentication with built-in auth pages.
+## Next Steps
+### Hooks
+#### `useAuth()`
+Access authentication state:
+```tsx
+import { useAuth } from '@insforge/react';
+function LoginButton() {
+  const { isSignedIn, isLoaded } = useAuth();
+  if (!isLoaded) return <div>Loading...</div>;
+  return (
+    <div>
+      {isSignedIn ? 'Welcome!' : 'Sign In'}
+    </div>
+  );
+}
+```
+**Returns:**
+- `isSignedIn` - Boolean auth state
+- `isLoaded` - Boolean loading state
+#### `useUser()`
+Access current user data:
+```tsx
+import { useUser } from '@insforge/react';
+function UserProfile() {
+  const { user, isLoaded } = useUser();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+  return (
+    <div>
+      <p>Id: {user.id}</p>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+      <img src={user.avatarUrl} alt="Avatar" />
+    </div>
+  );
+}
+```
+**Returns:**
+- `user` - User object with id, email, name, avatarUrl
+- `isLoaded` - Boolean loading state