@franklinhelp/sdk-react
Version:
Embeddable AI-native help center for modern SaaS applications
234 lines (180 loc) • 4.92 kB
Markdown
# @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