@intentai/react 1.0.1 → 2.0.0

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 (7) hide show
  1. package/README.md +160 -315
  2. package/dist/index.d.mts +85 -334
  3. package/dist/index.d.ts +85 -334
  4. package/dist/index.js +1503 -2
  5. package/dist/index.mjs +1485 -2
  6. package/dist/styles.css +1047 -0
  7. package/package.json +22 -21
package/README.md CHANGED
@@ -1,407 +1,252 @@
1
- # @intentai/react
1
+ # @intent-ai/react
2
2
 
3
- Official React SDK for [Intent AI](https://intent-ai.com) - AI-powered feedback collection widget.
3
+ React component for [Intent AI](https://intent-ai.com) - the AI-powered feedback widget that helps you collect and analyze user feedback effortlessly.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
- npm install @intentai/react
8
+ npm install @intent-ai/react
9
9
  # or
10
- yarn add @intentai/react
10
+ yarn add @intent-ai/react
11
11
  # or
12
- pnpm add @intentai/react
12
+ pnpm add @intent-ai/react
13
13
  ```
14
14
 
15
15
  ## Quick Start
16
16
 
17
- ### 1. Get your Public Key
18
-
19
- Get your public key (`pk_live_*` or `pk_test_*`) from the [Intent AI Dashboard](https://app.intent-ai.com/dashboard/settings).
20
-
21
- ### 2. Add the Provider
22
-
23
- Wrap your app with `IntentAIProvider`:
24
-
25
17
  ```tsx
26
- // app/layout.tsx (Next.js App Router)
27
- import { IntentAIProvider } from '@intentai/react';
18
+ import { IntentAIWidget } from '@intent-ai/react';
28
19
 
29
- export default function RootLayout({ children }) {
20
+ function App() {
30
21
  return (
31
- <html>
32
- <body>
33
- <IntentAIProvider apiKey="pk_live_xxxxx">
34
- {children}
35
- </IntentAIProvider>
36
- </body>
37
- </html>
22
+ <div>
23
+ <h1>My App</h1>
24
+
25
+ {/* Add the widget - it will appear as a floating button */}
26
+ <IntentAIWidget
27
+ apiKey="your-api-key"
28
+ apiUrl="https://your-api-url.com"
29
+ widgetUrl="https://your-app-url.com/widget/v1.js"
30
+ position="bottom-right"
31
+ theme="dark"
32
+ />
33
+ </div>
38
34
  );
39
35
  }
40
36
  ```
41
37
 
42
- That's it! The feedback widget will appear in the bottom-right corner.
38
+ That's it! The widget will appear as a floating button in the bottom-right corner of your app.
43
39
 
44
- ## Environment Variables
40
+ **Note:** Get your personalized `apiKey`, `apiUrl`, and `widgetUrl` from the [Intent AI Setup Page](https://your-dashboard-url/dashboard/setup).
45
41
 
46
- The SDK automatically detects your API key from environment variables:
42
+ ## Props
47
43
 
48
- ```env
49
- # Next.js
50
- NEXT_PUBLIC_INTENT_AI_KEY=pk_live_xxxxx
51
-
52
- # Create React App
53
- REACT_APP_INTENT_AI_KEY=pk_live_xxxxx
44
+ | Prop | Type | Default | Description |
45
+ |------|------|---------|-------------|
46
+ | `apiKey` | `string` | **required** | Your Intent AI API key |
47
+ | `apiUrl` | `string` | **required** | Your Intent AI API URL |
48
+ | `widgetUrl` | `string` | **required** | Your widget script URL |
49
+ | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Widget position |
50
+ | `theme` | `'light' \| 'dark'` | `'light'` | Widget theme |
51
+ | `primaryColor` | `string` | `'#3B82F6'` | Primary color (hex) |
52
+ | `allowVoice` | `boolean` | `true` | Enable voice feedback |
53
+ | `allowText` | `boolean` | `true` | Enable text feedback |
54
+ | `allowScreenshot` | `boolean` | `true` | Enable screenshot capture |
55
+ | `customMetadata` | `object` | `{}` | Custom data to attach to feedback |
56
+ | `user` | `object` | `undefined` | User information |
54
57
 
55
- # Vite
56
- VITE_INTENT_AI_KEY=pk_live_xxxxx
57
- ```
58
+ ## Identifying Users
58
59
 
59
- With environment variables set, you can omit the `apiKey` prop:
60
+ Track feedback by user:
60
61
 
61
62
  ```tsx
62
- <IntentAIProvider>
63
- {children}
64
- </IntentAIProvider>
63
+ <IntentAIWidget
64
+ apiKey="your-api-key"
65
+ apiUrl="https://your-api-url.com"
66
+ widgetUrl="https://your-app-url.com/widget/v1.js"
67
+ user={{
68
+ id: 'user-123',
69
+ email: 'user@example.com',
70
+ name: 'John Doe'
71
+ }}
72
+ />
65
73
  ```
66
74
 
67
- ## Usage
75
+ ## Custom Metadata
68
76
 
69
- ### Basic Setup
77
+ Attach custom data to feedback submissions:
70
78
 
71
79
  ```tsx
72
- import { IntentAIProvider } from '@intentai/react';
73
-
74
- function App() {
75
- return (
76
- <IntentAIProvider
77
- apiKey="pk_live_xxxxx"
78
- position="bottom-right"
79
- theme="auto"
80
- >
81
- <YourApp />
82
- </IntentAIProvider>
83
- );
84
- }
80
+ <IntentAIWidget
81
+ apiKey="your-api-key"
82
+ apiUrl="https://your-api-url.com"
83
+ widgetUrl="https://your-app-url.com/widget/v1.js"
84
+ customMetadata={{
85
+ page: 'checkout',
86
+ planType: 'premium',
87
+ version: '2.0.0'
88
+ }}
89
+ />
85
90
  ```
86
91
 
87
- ### Custom Feedback Button
88
-
89
- ```tsx
90
- import { IntentAIProvider, FeedbackButton } from '@intentai/react';
91
-
92
- function App() {
93
- return (
94
- <IntentAIProvider apiKey="pk_live_xxxxx" autoShow={false}>
95
- <FeedbackButton className="btn btn-primary">
96
- Send Feedback
97
- </FeedbackButton>
98
- </IntentAIProvider>
99
- );
100
- }
101
- ```
92
+ ## Programmatic Control
102
93
 
103
- ### Using the Hook
94
+ Use the `useIntentAI` hook to control the widget:
104
95
 
105
96
  ```tsx
106
- import { useIntentAI } from '@intentai/react';
97
+ import { IntentAIWidget, useIntentAI } from '@intent-ai/react';
107
98
 
108
- function MyComponent() {
109
- const { open, close, isReady, error } = useIntentAI();
99
+ function App() {
100
+ const { open, close, identify, setMetadata } = useIntentAI();
110
101
 
111
- if (error) {
112
- return <div>Failed to load feedback widget</div>;
113
- }
102
+ const handleLogin = (user) => {
103
+ identify({
104
+ id: user.id,
105
+ email: user.email,
106
+ name: user.name
107
+ });
108
+ };
114
109
 
115
110
  return (
116
- <button onClick={() => open()} disabled={!isReady}>
117
- Give Feedback
118
- </button>
111
+ <div>
112
+ <IntentAIWidget
113
+ apiKey="your-api-key"
114
+ apiUrl="https://your-api-url.com"
115
+ widgetUrl="https://your-app-url.com/widget/v1.js"
116
+ />
117
+
118
+ {/* Custom feedback button */}
119
+ <button onClick={open}>
120
+ Give Feedback
121
+ </button>
122
+ </div>
119
123
  );
120
124
  }
121
125
  ```
122
126
 
123
- ### Identify Users
124
-
125
- Using the `useIdentify` hook (recommended):
126
-
127
- ```tsx
128
- import { useIdentify } from '@intentai/react';
129
-
130
- function AuthenticatedApp({ user }) {
131
- // Automatically identifies user when ready
132
- useIdentify(user ? {
133
- id: user.id,
134
- email: user.email,
135
- name: user.name,
136
- plan: user.subscription.plan,
137
- } : null);
138
-
139
- return <YourApp />;
140
- }
141
- ```
127
+ ## Next.js App Router
142
128
 
143
- Using the `IdentifyUser` component:
129
+ The component is marked with `'use client'` and works with Next.js App Router:
144
130
 
145
131
  ```tsx
146
- import { IntentAIProvider, IdentifyUser } from '@intentai/react';
132
+ // app/layout.tsx
133
+ import { IntentAIWidget } from '@intent-ai/react';
147
134
 
148
- function App({ user }) {
135
+ export default function RootLayout({ children }) {
149
136
  return (
150
- <IntentAIProvider apiKey="pk_live_xxxxx">
151
- <IdentifyUser user={{
152
- id: user.id,
153
- email: user.email,
154
- name: user.name
155
- }}>
156
- <YourApp />
157
- </IdentifyUser>
158
- </IntentAIProvider>
137
+ <html>
138
+ <body>
139
+ {children}
140
+ <IntentAIWidget
141
+ apiKey={process.env.NEXT_PUBLIC_INTENT_AI_KEY!}
142
+ apiUrl={process.env.NEXT_PUBLIC_INTENT_AI_API_URL!}
143
+ widgetUrl={process.env.NEXT_PUBLIC_INTENT_AI_WIDGET_URL!}
144
+ />
145
+ </body>
146
+ </html>
159
147
  );
160
148
  }
161
149
  ```
162
150
 
163
- Or using the hook directly:
164
-
165
- ```tsx
166
- import { useIntentAI } from '@intentai/react';
167
-
168
- function AuthenticatedApp({ user }) {
169
- const { identify, isReady } = useIntentAI();
170
-
171
- useEffect(() => {
172
- if (isReady && user) {
173
- identify({
174
- id: user.id,
175
- email: user.email,
176
- name: user.name,
177
- plan: user.subscription.plan, // Custom properties
178
- });
179
- }
180
- }, [isReady, user]);
181
-
182
- return <YourApp />;
183
- }
184
- ```
185
-
186
- ### Add Metadata
187
-
188
- ```tsx
189
- import { SetMetadata } from '@intentai/react';
190
-
191
- function PricingPage() {
192
- return (
193
- <SetMetadata metadata={{ page: 'pricing', feature: 'comparison' }}>
194
- <PricingContent />
195
- </SetMetadata>
196
- );
197
- }
151
+ Add these to your `.env.local`:
198
152
  ```
199
-
200
- Or using the hook:
201
-
202
- ```tsx
203
- const { setMetadata } = useIntentAI();
204
-
205
- useEffect(() => {
206
- setMetadata({
207
- page: window.location.pathname,
208
- viewport: `${window.innerWidth}x${window.innerHeight}`
209
- });
210
- }, []);
153
+ NEXT_PUBLIC_INTENT_AI_KEY=your-api-key
154
+ NEXT_PUBLIC_INTENT_AI_API_URL=https://your-api-url.com
155
+ NEXT_PUBLIC_INTENT_AI_WIDGET_URL=https://your-app-url.com/widget/v1.js
211
156
  ```
212
157
 
213
- ### Track Events
214
-
215
- Using the `TrackEvent` component:
158
+ ## Next.js Pages Router
216
159
 
217
160
  ```tsx
218
- import { TrackEvent } from '@intentai/react';
161
+ // pages/_app.tsx
162
+ import { IntentAIWidget } from '@intent-ai/react';
219
163
 
220
- function CheckoutPage() {
164
+ export default function App({ Component, pageProps }) {
221
165
  return (
222
- <TrackEvent event="checkout_viewed" properties={{ items: 3 }}>
223
- <CheckoutContent />
224
- </TrackEvent>
166
+ <>
167
+ <Component {...pageProps} />
168
+ <IntentAIWidget
169
+ apiKey={process.env.NEXT_PUBLIC_INTENT_AI_KEY!}
170
+ apiUrl={process.env.NEXT_PUBLIC_INTENT_AI_API_URL!}
171
+ widgetUrl={process.env.NEXT_PUBLIC_INTENT_AI_WIDGET_URL!}
172
+ />
173
+ </>
225
174
  );
226
175
  }
227
176
  ```
228
177
 
229
- Using the hook:
178
+ ## Vite / Create React App
230
179
 
231
180
  ```tsx
232
- const { track } = useIntentAI();
233
-
234
- function handlePurchase(item) {
235
- track('purchase', {
236
- itemId: item.id,
237
- price: item.price
238
- });
239
- }
240
- ```
241
-
242
- ### Custom Trigger with FeedbackTrigger
243
-
244
- ```tsx
245
- import { FeedbackTrigger } from '@intentai/react';
181
+ // src/App.tsx or src/main.tsx
182
+ import { IntentAIWidget } from '@intent-ai/react';
246
183
 
247
184
  function App() {
248
185
  return (
249
- <FeedbackTrigger>
250
- {({ open, isReady }) => (
251
- <MyCustomButton onClick={() => open()} disabled={!isReady}>
252
- Feedback
253
- </MyCustomButton>
254
- )}
255
- </FeedbackTrigger>
186
+ <div>
187
+ <YourApp />
188
+ <IntentAIWidget
189
+ apiKey={import.meta.env.VITE_INTENT_AI_KEY}
190
+ apiUrl={import.meta.env.VITE_INTENT_AI_API_URL}
191
+ widgetUrl={import.meta.env.VITE_INTENT_AI_WIDGET_URL}
192
+ />
193
+ </div>
256
194
  );
257
195
  }
258
196
  ```
259
197
 
260
- ### Pre-fill Feedback
261
-
262
- ```tsx
263
- const { open } = useIntentAI();
264
-
265
- // Open with pre-selected type and prefilled text
266
- open({
267
- type: 'bug',
268
- prefill: { text: 'I found an issue with...' },
269
- metadata: { page: 'checkout' }
270
- });
271
- ```
272
-
273
- ## Configuration
274
-
275
- ### IntentAIProvider Props
276
-
277
- | Prop | Type | Default | Description |
278
- |------|------|---------|-------------|
279
- | `apiKey` | `string` | - | Your Intent AI public key (or use env vars) |
280
- | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Widget position |
281
- | `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color theme |
282
- | `primaryColor` | `string` | `'#6366f1'` | Primary brand color (hex) |
283
- | `autoShow` | `boolean` | `true` | Show widget button automatically |
284
- | `user` | `UserIdentity` | - | Initial user identification |
285
- | `metadata` | `Record<string, unknown>` | - | Custom metadata |
286
- | `onReady` | `() => void` | - | Called when widget is ready |
287
- | `onOpen` | `() => void` | - | Called when widget opens |
288
- | `onClose` | `() => void` | - | Called when widget closes |
289
- | `onSubmit` | `(data: FeedbackData) => void` | - | Called on feedback submission |
290
- | `onError` | `(error: Error) => void` | - | Called on errors |
291
-
292
- ### useIntentAI Hook
293
-
294
- ```tsx
295
- const {
296
- isReady, // boolean - Widget loaded and ready
297
- error, // Error | null - Error if widget failed to load
298
- open, // (options?: OpenOptions) => void - Open the widget
299
- close, // () => void - Close the widget
300
- identify, // (user: UserIdentity) => void - Identify user
301
- setMetadata,// (data: Record<string, unknown>) => void - Set metadata
302
- track, // (event: string, properties?: Record<string, unknown>) => void - Track event
303
- } = useIntentAI();
304
- ```
305
-
306
- ### useIdentify Hook
307
-
308
- ```tsx
309
- // Automatically identifies user when widget is ready
310
- useIdentify({
311
- id: 'user_123',
312
- email: 'user@example.com',
313
- name: 'John Doe',
314
- plan: 'pro',
315
- company: 'Acme Inc',
316
- });
317
-
318
- // Pass null to skip identification
319
- useIdentify(user ? { id: user.id, email: user.email } : null);
320
- ```
321
-
322
- ### OpenOptions
323
-
324
- ```tsx
325
- interface OpenOptions {
326
- type?: 'bug' | 'feature' | 'question' | 'praise' | 'other';
327
- prefill?: { text?: string };
328
- metadata?: Record<string, unknown>;
329
- }
198
+ Add these to your `.env`:
330
199
  ```
331
-
332
- ### UserIdentity
333
-
334
- ```tsx
335
- interface UserIdentity {
336
- id: string; // Required
337
- email?: string;
338
- name?: string;
339
- avatar?: string;
340
- plan?: string;
341
- company?: string;
342
- [key: string]: string | number | boolean | undefined; // Custom properties
343
- }
200
+ VITE_INTENT_AI_KEY=your-api-key
201
+ VITE_INTENT_AI_API_URL=https://your-api-url.com
202
+ VITE_INTENT_AI_WIDGET_URL=https://your-app-url.com/widget/v1.js
344
203
  ```
345
204
 
346
- ## Next.js App Router
347
-
348
- The SDK is fully compatible with Next.js App Router and Server Components:
205
+ ## Event Callbacks
349
206
 
350
207
  ```tsx
351
- // app/providers.tsx
352
- 'use client';
353
-
354
- import { IntentAIProvider } from '@intentai/react';
355
-
356
- export function Providers({ children }) {
357
- return (
358
- <IntentAIProvider>
359
- {children}
360
- </IntentAIProvider>
361
- );
362
- }
363
-
364
- // app/layout.tsx
365
- import { Providers } from './providers';
366
-
367
- export default function RootLayout({ children }) {
368
- return (
369
- <html>
370
- <body>
371
- <Providers>{children}</Providers>
372
- </body>
373
- </html>
374
- );
375
- }
208
+ <IntentAIWidget
209
+ apiKey="your-api-key"
210
+ apiUrl="https://your-api-url.com"
211
+ widgetUrl="https://your-app-url.com/widget/v1.js"
212
+ onOpen={() => console.log('Widget opened')}
213
+ onClose={() => console.log('Widget closed')}
214
+ onFeedbackSubmitted={() => console.log('Feedback submitted!')}
215
+ onError={(error) => console.error('Widget error:', error)}
216
+ />
376
217
  ```
377
218
 
378
219
  ## TypeScript
379
220
 
380
- Full TypeScript support with exported types:
221
+ Full TypeScript support included:
381
222
 
382
223
  ```tsx
383
- import type {
384
- UserIdentity,
385
- IntentAIConfig,
386
- FeedbackData,
387
- OpenOptions,
388
- FeedbackType,
389
- } from '@intentai/react';
390
-
391
- const user: UserIdentity = {
224
+ import { IntentAIWidget, IntentAIProps, IntentAIUser } from '@intent-ai/react';
225
+
226
+ const user: IntentAIUser = {
392
227
  id: '123',
393
228
  email: 'user@example.com',
394
- name: 'John Doe',
229
+ name: 'John'
230
+ };
231
+
232
+ const config: IntentAIProps = {
233
+ apiKey: 'your-api-key',
234
+ user,
235
+ theme: 'dark'
395
236
  };
396
237
  ```
397
238
 
398
- ## Browser Support
239
+ ## Getting Your API Key
240
+
241
+ 1. Sign up at [Intent AI Dashboard](https://intetnt-ai-v1-web-app-production.up.railway.app)
242
+ 2. Create an organization and product
243
+ 3. Copy your API key from the setup page
244
+
245
+ ## Support
399
246
 
400
- - Chrome (latest)
401
- - Firefox (latest)
402
- - Safari (latest)
403
- - Edge (latest)
247
+ - Documentation: [docs.intent-ai.com](https://intent-ai.com)
248
+ - Issues: [GitHub Issues](https://github.com/aibasicintent-dev/Intetnt-ai-v1/issues)
404
249
 
405
250
  ## License
406
251
 
407
- MIT © [Intent AI](https://intent-ai.com)
252
+ MIT