npm package: @franklinhelp/sdk-react
Description: Embeddable AI-native help center for modern SaaS applications
Author: Franklin Platform
Latest version: 0.1.0-alpha.6

# @franklinhelp/sdk-react

Embeddable AI-powered help center sidebar for React applications.

## Installation

### Alpha Release
```bash
npm install @franklinhelp/sdk-react@alpha
# or
pnpm add @franklinhelp/sdk-react@alpha
# or
yarn add @franklinhelp/sdk-react@alpha
```

**Note:** This is an alpha release. The API may change in future versions.

## Quick Start

### 1. Import the component and styles

```tsx
import { FranklinHelpCenter, useFranklin } from "@franklinhelp/sdk-react";
import "@franklinhelp/sdk-react/styles";
```

### 2. Add the component to your app

```tsx
function App() {
  const franklin = useFranklin();

  return (
    <div id="app-root">
      <YourApp />
      
      <FranklinHelpCenter
        ref={franklin.ref}
        orgId={process.env.NEXT_PUBLIC_FRANKLIN_ORG_ID}
        sdkKey={process.env.NEXT_PUBLIC_FRANKLIN_SDK_KEY}
        shiftTargetSelector="#app-root"
        defaultTab="ai"
        theme={{
          accent: "#3B82F6",
          mode: "light"
        }}
        onOpen={() => console.log("Franklin opened")}
        onClose={() => console.log("Franklin closed")}
      />
    </div>
  );
}
```

### 3. Control the sidebar programmatically

```tsx
// Open the sidebar
franklin.open();

// Close the sidebar
franklin.close();

// Toggle the sidebar
franklin.toggle();

// Push context to Franklin
franklin.pushContext({
  route: window.location.pathname,
  userId: user.id,
  metadata: {
    plan: "enterprise",
    role: "admin"
  }
});

// Switch the active tab before opening
franklin.setTab("knowledge");
franklin.open();
```

## Props

### FranklinHelpCenterProps

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `orgId` | `string` | ✅ | - | Your Franklin organization ID |
| `sdkKey` | `string` | ✅ | - | Your Franklin SDK key |
| `shiftTargetSelector` | `string` | ❌ | - | CSS selector for the element to shift when sidebar opens |
| `defaultTab` | `"ai" \| "knowledge" \| "cases"` | ❌ | `"ai"` | Default tab to show when sidebar opens |
| `theme` | `FranklinThemeConfig` | ❌ | `{}` | Theme customization options |
| `onOpen` | `() => void` | ❌ | - | Callback when sidebar opens |
| `onClose` | `() => void` | ❌ | - | Callback when sidebar closes |
| `apiEndpoint` | `string` | ❌ | `"/api/franklin"` | API endpoint for Franklin backend |

### FranklinThemeConfig

```typescript
interface FranklinThemeConfig {
  mode?: "light" | "dark" | "auto";
  accent?: string;
  surface?: string;
  border?: string;
  radius?: number;
  fontFamily?: string;
}
```

## Hooks

### useFranklin()

Returns imperative controls for the Franklin sidebar:

```typescript
const franklin = useFranklin();

franklin.open();        // Open sidebar
franklin.close();       // Close sidebar
franklin.toggle();      // Toggle sidebar
franklin.pushContext({ /* context */ }); // Update context
franklin.setTab("knowledge"); // Choose active tab
franklin.isOpen;        // Current open state
franklin.activeTab;     // Current active tab
```

### useFranklinContext()

Access the Franklin context directly (must be used within FranklinProvider):

```typescript
const { 
  isOpen, 
  activeTab, 
  context, 
  theme, 
  orgId, 
  sdkKey 
} = useFranklinContext();
```

## Features

### AI Chat
- Powered by Vercel AI SDK
- Real-time streaming responses
- Quick action suggestions
- Context-aware answers

### Knowledge Base
- Browse articles by category
- Search functionality
- Article detail view
- Markdown content support

### Cases Management
- View open support cases
- Case status tracking
- Message history
- Priority indicators

## Customization

### Theme

```tsx
<FranklinHelpCenter
  theme={{
    mode: "dark",
    accent: "#7C3AED",
    radius: 12,
    fontFamily: "'Inter', sans-serif"
  }}
/>
```

> Setting `theme.mode` to `"light"` or `"dark"` toggles a `data-franklin-theme`
> attribute on the host `<body>`, so you can scope additional overrides if needed.

### CSS Variables

You can override Franklin's CSS variables:

```css
:root {
  --franklin-width: 480px;
  --franklin-accent: #7C3AED;
  --franklin-surface: #ffffff;
  --franklin-border: rgba(0, 0, 0, 0.1);
  --franklin-radius: 12px;
  --franklin-font: 'Inter', sans-serif;
  --franklin-z-index: 9999;
}
```

## API Integration

Franklin SDK expects the following API endpoints:

### Chat Endpoint
`POST /api/franklin/chat`

### Knowledge Base
`GET /api/franklin/knowledge-base`

### Cases
`GET /api/franklin/cases`
`GET /api/franklin/cases/:id/messages`

See the [API documentation](https://developers.franklin.ai) for full details.

## TypeScript

The SDK is fully typed. Import types as needed:

```typescript
import type {
  FranklinHelpCenterProps,
  FranklinHelpCenterHandle,
  FranklinThemeConfig,
  FranklinContextPayload,
  Article,
  Category,
  Case,
  Message
} from "@franklin/sdk-react";
```

## License

Proprietary - Franklin Platform