Installation

Package Installation

Auth-Agent SDK is available as an npm package under the name ai-auth.

npm install ai-auth

yarn add ai-auth

pnpm add ai-auth

bun add ai-auth

Package Exports

The ai-auth package provides multiple entry points for different use cases:

Full SDK (Recommended)

import {
  AuthProvider,
  useAuth,
  SignInWithAuthAgent,
  AuthAgentClient,
} from "ai-auth";

Includes everything: React components, hooks, and core client.

Core Client Only

import { AuthAgentClient } from "ai-auth/client";

Framework-agnostic authentication client for vanilla JS/TS or server-side use.

React Components Only

import { AuthProvider, useAuth, SignInWithAuthAgent } from "ai-auth/react";

Only React-specific exports (components and hooks).

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions.

import type {
  AuthConfig,
  UserInfo,
  TokenResponse,
  AuthState,
  AuthError,
} from "ai-auth";

TypeScript Configuration

Make sure your tsconfig.json includes:

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16" / "nodenext"
    "jsx": "react-jsx", // if using React
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Peer Dependencies

For React Applications

{
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}

React and React DOM are peer dependencies, meaning they must be installed separately if you’re using React components.

For Vanilla JavaScript

No peer dependencies required when using only the core client.

Browser Compatibility

Auth-Agent SDK supports modern browsers with the following APIs:

Crypto API: For PKCE generation (SHA-256 hashing)
Fetch API: For HTTP requests
LocalStorage/SessionStorage: For token storage
ES2020+: For JavaScript features

Minimum Versions

Chrome

>=87

Firefox

>=78

Safari

>=14

Edge

>=88

CDN Installation

For quick prototyping without a build step:

<script type="module">
  import { AuthAgentClient } from "https://cdn.skypack.dev/ai-auth";

  const client = new AuthAgentClient({
    clientId: "your_agent_id",
    redirectUri: window.location.origin + "/callback",
  });
</script>

CDN usage is recommended for prototyping only. For production, use a bundler for better performance and tree-shaking.

Framework-Specific Setup

Next.js
Vite + React
Create React App
Vanilla JS

Next.js App Router

app/providers.tsx

'use client';

import { AuthProvider } from 'ai-auth';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      config={{
        clientId: process.env.NEXT_PUBLIC_CLIENT_ID!,
        redirectUri: `${process.env.NEXT_PUBLIC_APP_URL}/callback`,
      }}
    >
      {children}
    </AuthProvider>
  );
}

app/layout.tsx

import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { AuthProvider } from 'ai-auth';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AuthProvider
      config={{
        clientId: import.meta.env.VITE_CLIENT_ID,
        redirectUri: 'http://localhost:5173/callback',
      }}
    >
      <App />
    </AuthProvider>
  </React.StrictMode>
);

index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { AuthProvider } from 'ai-auth';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root')!);

root.render(
  <React.StrictMode>
    <AuthProvider
      config={{
        clientId: process.env.REACT_APP_CLIENT_ID!,
        redirectUri: 'http://localhost:3000/callback',
      }}
    >
      <App />
    </AuthProvider>
  </React.StrictMode>
);

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Auth-Agent Demo</title>
</head>
<body>
  <div id="app"></div>
  
  <script type="module">
    import { AuthAgentClient } from 'ai-auth';

    const client = new AuthAgentClient({
      clientId: 'your_client_id',
      redirectUri: window.location.origin,
    });

    // Your app logic
  </script>
</body>
</html>

Verify Installation

Create a simple test to verify the SDK is installed correctly:

test.ts

import { AuthAgentClient } from "ai-auth";

const client = new AuthAgentClient({
  clientId: "test",
  redirectUri: "http://localhost:3000",
});

console.log("SDK installed successfully!");
console.log("Client created:", client);

Run with:

node test.ts
# or
tsx test.ts

Get Started

Core Concepts

Components

Guides

Advanced

Package Installation

Package Exports

Full SDK (Recommended)

Core Client Only

React Components Only

TypeScript Support

TypeScript Configuration

Peer Dependencies

For React Applications

For Vanilla JavaScript

Browser Compatibility

Minimum Versions

CDN Installation

Framework-Specific Setup

Next.js App Router

Verify Installation

Next Steps

Quick Start

Configuration

​Package Installation

​Package Exports

​Full SDK (Recommended)

​Core Client Only

​React Components Only

​TypeScript Support

​TypeScript Configuration

​Peer Dependencies

​For React Applications

​For Vanilla JavaScript

​Browser Compatibility

​Minimum Versions

​CDN Installation

​Framework-Specific Setup

​Next.js App Router

​Verify Installation

​Next Steps

Quick Start

Configuration

Package Installation

Package Exports

Full SDK (Recommended)

Core Client Only

React Components Only

TypeScript Support

TypeScript Configuration

Peer Dependencies

For React Applications

For Vanilla JavaScript

Browser Compatibility

Minimum Versions

CDN Installation

Framework-Specific Setup

Next.js App Router

Verify Installation

Next Steps