# IsAgent SDK Documentation

## Overview

The **IsAgent SDK** enables React developers to detect whether a client is likely an AI agent or a human user by leveraging Stytch's agent detection API. It provides both low-level functions and high-level React hooks/components for seamless integration into your application.

## Installation

Install the SDK via npm:

```bash
npm install @stytch/is-agent
```

## Quick Start

1. **Initialize the context** with your Stytch public token:

   ```tsx
   import React from 'react';
   import { createAgentContext } from '@stytch/is-agent';

   const { useIsAgent, IsAgent, IsHuman } = createAgentContext('your-stytch-public-token');
   ```

2. **Use the components** in your app:

   ```tsx
   function App() {
     return (
       <div>
         <IsHuman>
           <p>Welcome, human user!</p>
         </IsHuman>

         <IsAgent>
           <p>Agent detected — showing simplified view.</p>
         </IsAgent>
       </div>
     );
   }
   ```

3. **Or use the hook** directly for custom behavior:

   ```tsx
   function CustomComponent() {
     const { isAgentClientHint, identity, loading, error } = useIsAgent();

     if (loading) return <div>Checking agent status...</div>;
     if (error) return <div>Error: {error.message}</div>;

     return (
       <div>
         Agent detected: {isAgentClientHint ? 'Yes' : 'No'}
         {identity && <div>Identity: {identity}</div>}
       </div>
     );
   }
   ```

## SDK Reference

### `createAgentContext(publicToken: string)`

Initializes the agent-detection context.

- **Parameters:**
  - `publicToken` — Your Stytch public token.
- **Returns:** An object with:
  - `useIsAgent` — React hook for agent detection.
  - `IsAgent` — Component rendering children only for detected agents.
  - `IsHuman` — Component rendering children only for detected humans.

### `useIsAgent(): AgentState`

React hook providing detection state.

- **Returns:** A union type with three specific states:

  **Loading State:**
  ```ts
  { loading: true; error: null; identity: null; isAgentClientHint: null }
  ```

  **Error State:**
  ```ts
  { loading: false; error: Error; identity: null; isAgentClientHint: null }
  ```

  **Success State:**
  ```ts
  { loading: false; error: null; identity: string | null; isAgentClientHint: boolean }
  ```
#### Example `useIsAgent` usage

```
const state = useIsAgent()

if (state.loading) {
  // TypeScript knows: error is null, identity is null, isAgentClientHint is null
  return <div>Loading...</div>
}

if (state.error) {
  // TypeScript knows: loading is false, identity is null, isAgentClientHint is null
  return <div>Error: {state.error.message}</div>
}

// TypeScript knows: loading is false, error is null
// isAgentClientHint is boolean, identity is string | null
return <div>Agent detected: {state.isAgentClientHint}</div>
```

### `<IsAgent>` Component

Renders children only when `isAgentClientHint` is `true`.

- **Props:**
  - `loadingComponent?: React.ReactNode` — Shown during loading.
  - `errorComponent?: React.ReactNode | ((props: { error: Error }) => React.ReactNode)` — Shown on error.
  - `children: React.ReactNode` — Content for agents.

### `<IsHuman>` Component

Renders children only when `isAgentClientHint` is `false`.

- **Props:**
  - `loadingComponent?: React.ReactNode` — Shown during loading.
  - `errorComponent?: React.ReactNode | ((props: { error: Error }) => React.ReactNode)` — Shown on error.
  - `children: React.ReactNode` — Content for humans.

### Low-Level Functions (from `isAgent.ts`)

- `isAgent()` — Checks agent status via Stytch API. Returns a promise resolving to detection result.

### Errors

- `IsAgentError` — Error thrown when the API call fails, containing details:
  - `status_code`, `error_type`, `error_message`, `error_url`, optional `request_id` and `error_details`.

### Exports (`index.ts`)

```ts
export { isAgent, IsAgentError } from './isAgent';
export { createAgentContext } from './useIsAgent';
export type {
  AgentState,
  useIsAgent,
  IsAgent,
  IsAgentProps,
  IsHumanProps,
  IsHuman,
} from './useIsAgent';
```

## Requirements

- React 17.0.0 or higher.
- A valid Stytch `public_token`.