{"_id":"@brunocalmels/helperai-react","_rev":"4-5eb33b3248d5d9235d175463f799ae05","name":"@brunocalmels/helperai-react","dist-tags":{"latest":"0.7.3"},"versions":{"0.7.0":{"name":"@brunocalmels/helperai-react","version":"0.7.0","keywords":["helper","chat","ai","widget","sdk","react","nextjs","customer-service"],"author":{"url":"https://helper.ai","name":"Helper"},"license":"MIT","_id":"@brunocalmels/helperai-react@0.7.0","maintainers":[{"name":"brunocalmels","email":"brunocalmels@gmail.com"}],"homepage":"https://helper.ai","dist":{"shasum":"62f67e53bed56267d8874ceca77dd91c7b61f845","tarball":"https://registry.npmjs.org/@brunocalmels/helperai-react/-/helperai-react-0.7.0.tgz","fileCount":64,"integrity":"sha512-OvFlgQOi6wmIs1/bocfggfsEpvFHk0yosSnr/X8kTT584ZenChHuEo9WEB9qLPzLctFPzISmxSRNt7pTs72r2g==","signatures":[{"sig":"MEUCIQC4VIbn+XMRfBstwEC71jY+m7JitqNwvC9e/Ss43b0Z6wIgZk8WI6F3/a18Y1Ik/D8s5IcMBdAvtU256BUvD48m0FU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47850},"main":"./dist/cjs/index.js","types":"./dist/cjs/index.d.ts","module":"./dist/esm/index.mjs","gitHead":"b53bb8aaa15aa0da4fdcc6be81af8e2657ae44f2","scripts":{"dev":"pnpm build --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"brunocalmels","actor":{"name":"brunocalmels","type":"user","email":"brunocalmels@gmail.com"},"email":"brunocalmels@gmail.com"},"_npmVersion":"10.9.2","description":"React/Next.js integration for Helper chat widget","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.6","jsdom":"^23.2.0","react":"^19.1.0","vitest":"^3.2.4","react-dom":"^19.1.0","typescript":"^5.3.3","@types/node":"^22.15.3","@types/react":"^19.0.0","glob-promise":"^6.0.0","@vitest/coverage-v8":"^1.0.4","@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/helperai-react_0.7.0_1751926031139_0.513852922954025","host":"s3://npm-registry-packages-npm-production"}},"0.7.1":{"name":"@brunocalmels/helperai-react","version":"0.7.1","keywords":["helper","chat","ai","widget","sdk","react","nextjs","customer-service"],"author":{"url":"https://helper.ai","name":"Helper"},"license":"MIT","_id":"@brunocalmels/helperai-react@0.7.1","maintainers":[{"name":"brunocalmels","email":"brunocalmels@gmail.com"}],"homepage":"https://helper.ai","dist":{"shasum":"b46e1f917e9ef05315cd5c269d5c828380f1f74e","tarball":"https://registry.npmjs.org/@brunocalmels/helperai-react/-/helperai-react-0.7.1.tgz","fileCount":64,"integrity":"sha512-Ol9WhX6q+GZfMEwyW1rUR8F9yYYH/Sebqza9+3J48SA2mPeEUKVp9XLu2qNMQng8Q1z4u/Wb5H1MYvLfNZjgJA==","signatures":[{"sig":"MEUCICr4Dw0U1J2KwPUFfdOHe3I23dYjSKBShsUXR/unNu3pAiEAqYshd30aIUs7xBjtPspfbRL5SSpZ92B1nZVYI9mgTH8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47850},"main":"./dist/cjs/index.js","types":"./dist/cjs/index.d.ts","module":"./dist/esm/index.mjs","gitHead":"b53bb8aaa15aa0da4fdcc6be81af8e2657ae44f2","scripts":{"dev":"pnpm build --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"brunocalmels","actor":{"name":"brunocalmels","type":"user","email":"brunocalmels@gmail.com"},"email":"brunocalmels@gmail.com"},"_npmVersion":"10.9.2","description":"React/Next.js integration for Helper chat widget","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.6","jsdom":"^23.2.0","react":"^19.1.0","vitest":"^3.2.4","react-dom":"^19.1.0","typescript":"^5.3.3","@types/node":"^22.15.3","@types/react":"^19.0.0","glob-promise":"^6.0.0","@vitest/coverage-v8":"^1.0.4","@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/helperai-react_0.7.1_1751926335346_0.9207919380290428","host":"s3://npm-registry-packages-npm-production"}},"0.7.2":{"name":"@brunocalmels/helperai-react","version":"0.7.2","keywords":["helper","chat","ai","widget","sdk","react","nextjs","customer-service"],"author":{"url":"https://helper.ai","name":"Helper"},"license":"MIT","_id":"@brunocalmels/helperai-react@0.7.2","maintainers":[{"name":"brunocalmels","email":"brunocalmels@gmail.com"}],"homepage":"https://helper.ai","dist":{"shasum":"e31381da23b53b320eb062eeb5062ac56433d778","tarball":"https://registry.npmjs.org/@brunocalmels/helperai-react/-/helperai-react-0.7.2.tgz","fileCount":70,"integrity":"sha512-0G06NdtClLdVWnAxKcneB7/tB1KRz8DgpAC32rGUjXdAwzWvMA7dx/PbnEHWzx7eGsPPM+VKG19taNafJ2yvbw==","signatures":[{"sig":"MEUCIQC2GM3+TkBL46lbbEbvwrrIk52A0BseS0uEjBRX8kOrkAIgTJGoyQ+8Ssh2U6bdeDBzNCTgqNZMlXhKiqxa2dGBcxI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48492},"main":"./dist/cjs/index.js","types":"./dist/cjs/index.d.ts","module":"./dist/esm/index.mjs","exports":{".":{"types":"./dist/cjs/index.d.ts","import":"./dist/esm/index.mjs","require":"./dist/cjs/index.js"},"./server":{"types":"./dist/cjs/server.d.ts","import":"./dist/esm/server.mjs","require":"./dist/cjs/server.js"}},"gitHead":"b53bb8aaa15aa0da4fdcc6be81af8e2657ae44f2","scripts":{"dev":"pnpm build --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"brunocalmels","actor":{"name":"brunocalmels","type":"user","email":"brunocalmels@gmail.com"},"email":"brunocalmels@gmail.com"},"_npmVersion":"10.9.2","description":"React/Next.js integration for Helper chat widget","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.6","jsdom":"^23.2.0","react":"^19.1.0","vitest":"^3.2.4","react-dom":"^19.1.0","typescript":"^5.3.3","@types/node":"^22.15.3","@types/react":"^19.0.0","glob-promise":"^6.0.0","@vitest/coverage-v8":"^1.0.4","@testing-library/react":"^16.1.0","@testing-library/jest-dom":"^6.6.3"},"peerDependencies":{"react":">=18","react-dom":">=18"},"_npmOperationalInternal":{"tmp":"tmp/helperai-react_0.7.2_1751926618664_0.503479431719972","host":"s3://npm-registry-packages-npm-production"}},"0.7.3":{"name":"@brunocalmels/helperai-react","version":"0.7.3","description":"React/Next.js integration for Helper chat widget","keywords":["helper","chat","ai","widget","sdk","react","nextjs","customer-service"],"author":{"name":"Helper","url":"https://helper.ai"},"license":"MIT","homepage":"https://helper.ai","repository":{"type":"git","url":"git+https://github.com/antiwork/helper.git"},"publishConfig":{"access":"public"},"sideEffects":false,"main":"./dist/cjs/index.js","module":"./dist/esm/index.mjs","types":"./dist/cjs/index.d.ts","scripts":{"build":"tsup","dev":"pnpm build --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage"},"peerDependencies":{"react":">=18","react-dom":">=18"},"devDependencies":{"@testing-library/jest-dom":"^6.6.3","@testing-library/react":"^16.1.0","@types/node":"^22.15.3","@types/react":"^19.0.0","@vitest/coverage-v8":"^1.0.4","glob-promise":"^6.0.0","jsdom":"^23.2.0","react":"^19.1.0","react-dom":"^19.1.0","tsup":"^8.3.6","typescript":"^5.3.3","vitest":"^3.2.4"},"_id":"@brunocalmels/helperai-react@0.7.3","gitHead":"db8d7ba215006cfd41e2eaa1feadf5c7ce3823a3","bugs":{"url":"https://github.com/antiwork/helper/issues"},"_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-bPOkRQP2/PR3tfNZK1yjw0hvQjjvVnyHfS2rSWv7ZhcrZLIOXUmQvUbNZA8RX+42OI3irEzMctaTQsX/uQXYug==","shasum":"b0c9371362643383284b33535a7c06e76b4d4aa9","tarball":"https://registry.npmjs.org/@brunocalmels/helperai-react/-/helperai-react-0.7.3.tgz","fileCount":100,"unpackedSize":120451,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDMZ2AP2k8AYjzIWMGX2HXVIfUrVrkhoxaK+6WtEa6AoAiBcNi/a/ZOi5Y/K7zwFsdqXlwLXNr/QGheV50kWLHIRIQ=="}]},"_npmUser":{"name":"brunocalmels","email":"brunocalmels@gmail.com"},"directories":{},"maintainers":[{"name":"brunocalmels","email":"brunocalmels@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/helperai-react_0.7.3_1752882865304_0.5717654689700806"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-07T22:07:11.070Z","modified":"2025-07-18T23:54:25.740Z","0.7.0":"2025-07-07T22:07:11.312Z","0.7.1":"2025-07-07T22:12:15.547Z","0.7.2":"2025-07-07T22:16:58.825Z","0.7.3":"2025-07-18T23:54:25.537Z"},"author":{"name":"Helper","url":"https://helper.ai"},"license":"MIT","homepage":"https://helper.ai","keywords":["helper","chat","ai","widget","sdk","react","nextjs","customer-service"],"description":"React/Next.js integration for Helper chat widget","maintainers":[{"name":"brunocalmels","email":"brunocalmels@gmail.com"}],"readme":"# Helper React\n\n[![npm version](https://badge.fury.io/js/@helperai/react.svg)](https://badge.fury.io/js/@helperai/react)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA powerful React integration for the Helper chat widget, featuring first-class support for Next.js and modern React applications.\n\n## Features\n\n- 🚀 First-class Next.js App Router support\n- 💪 Full TypeScript support\n- 🔒 Secure authentication handling\n- 🎨 Customizable UI and theming\n- 🔌 Framework-agnostic core\n- �� Responsive design\n- 🔄 Comprehensive API hooks for direct integration\n\n## Installation\n\n```bash\nnpm install @helperai/react\n# or\nyarn add @helperai/react\n# or\npnpm add @helperai/react\n```\n\n## Quick Start\n\n### Basic Setup\n\n```tsx\nimport { generateHelperAuth, HelperProvider } from \"@helperai/react\";\n\nfunction App() {\n  const authData = generateHelperAuth({\n    email: \"user@example.com\",\n    hmacSecret: process.env.HELPER_HMAC_SECRET!,\n  });\n\n  return (\n    <HelperProvider host=\"https://helper.ai\" {...authData}>\n      <YourApp />\n    </HelperProvider>\n  );\n}\n```\n\n### Using API Hooks\n\n```tsx\nimport React, { useState } from \"react\";\nimport { useChat, useConversations, useCreateConversation } from \"@helperai/react\";\n\nfunction ChatComponent() {\n  const { conversations, loading } = useConversations();\n  const { createConversation } = useCreateConversation();\n  const [conversationSlug, setConversationSlug] = useState<string>(\"\");\n  const { messages, send } = useChat(conversationSlug);\n\n  const startChat = async () => {\n    const { conversationSlug: newSlug } = await createConversation();\n    setConversationSlug(newSlug);\n    send(\"Hello!\");\n  };\n\n  return (\n    <div>\n      <button onClick={startChat}>Start Chat</button>\n      {conversations.map((conv) => (\n        <div key={conv.slug}>{conv.subject}</div>\n      ))}\n      {messages.map((msg) => (\n        <div key={msg.id}>{msg.content}</div>\n      ))}\n    </div>\n  );\n}\n```\n\n## API Reference\n\n### Core Provider\n\n#### `HelperProvider`\n\nProvides global state management for Helper functionality, supporting both widget and API-based integrations.\n\n```tsx\n<HelperProvider\n  host=\"https://helper.ai\"\n  email=\"user@example.com\"\n  emailHash=\"hmac-hash\"\n  timestamp={Date.now()}\n  customerMetadata={{\n    name: \"John Doe\",\n    value: 1000,\n    links: { Profile: \"https://example.com/profile\" },\n  }}\n  tools={{\n    searchKnowledge: {\n      description: \"Search knowledge base\",\n      parameters: { query: { type: \"string\", description: \"Search query\" } },\n      execute: async ({ query }) => ({ results: [] }),\n    },\n  }}\n>\n  {children}\n</HelperProvider>\n```\n\n### Hooks\n\n#### `useConversations()`\n\nFetches and manages a list of all conversations.\n\n```tsx\nconst {\n  conversations, // Conversation[]\n  loading, // boolean\n  error, // string | null\n  refetch, // () => void\n} = useConversations();\n```\n\n#### `useConversation(conversationSlug: string)`\n\nFetches messages for a specific conversation.\n\n```tsx\nconst {\n  messages, // Message[]\n  loading, // boolean\n  error, // string | null\n  refetch, // () => void\n} = useConversation(conversationSlug);\n```\n\n#### `useCreateConversation()`\n\nCreates new conversations.\n\n```tsx\nconst {\n  createConversation, // (params?: CreateConversationParams) => Promise<CreateConversationResult>\n  loading, // boolean\n  error, // string | null\n} = useCreateConversation();\n\n// Usage\nconst { conversationSlug } = await createConversation({ isPrompt: false });\n```\n\n#### `useChat(conversationSlug: string)`\n\nProvides AI chat functionality for a specific conversation using the AI SDK.\n\n```tsx\nconst {\n  messages, // Message[] - Array of conversation messages\n  send, // (message: string) => void - Send a message\n  aiChat, // ReturnType<typeof useAIChat> - Direct access to AI SDK chat\n} = useChat(conversationSlug);\n\n// Usage\nconst conversationSlug = \"my-conversation\";\nconst { messages, send } = useChat(conversationSlug);\nsend(\"Hello, how can you help me?\");\n```\n\n#### `useHelperContext()`\n\nAccesses the Helper context for advanced integration scenarios.\n\n```tsx\nconst {\n  host, // string - The Helper host URL\n  tools, // Record<string, HelperTool> - Available tools\n  getToken, // () => Promise<string> - Get authentication token\n} = useHelperContext();\n```\n\n#### `useHelper()`\n\nControls the Helper widget visibility and behavior.\n\n```tsx\nconst {\n  show, // () => void\n  hide, // () => void\n  toggle, // () => void\n  sendPrompt, // (prompt: string) => void\n} = useHelper();\n```\n\n### Authentication\n\n#### `generateHelperAuth()`\n\nServer-side helper for generating HMAC authentication data.\n\n```tsx\nimport { generateHelperAuth } from \"@helperai/react\";\n\nconst authData = generateHelperAuth({\n  email: \"user@example.com\",\n  hmacSecret: process.env.HELPER_HMAC_SECRET!, // Optional: can also use HELPER_HMAC_SECRET env var\n});\n// Returns: { email, timestamp, emailHash }\n```\n\n## Next.js Integration\n\n### App Router\n\n```tsx\n// app/layout.tsx\nimport { HelperProvider } from \"@helperai/react\";\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang=\"en\">\n      <body>\n        <HelperProvider host={process.env.NEXT_PUBLIC_HELPER_HOST!}>{children}</HelperProvider>\n      </body>\n    </html>\n  );\n}\n```\n\n### Server Components\n\n```tsx\n// app/dashboard/page.tsx\nimport { generateHelperAuth } from \"@helperai/react\";\n\nexport default function DashboardPage() {\n  const authData = generateHelperAuth({\n    email: \"user@example.com\",\n    hmacSecret: process.env.HELPER_HMAC_SECRET!,\n  });\n\n  return (\n    <HelperProvider\n      host=\"https://helper.ai\"\n      email={authData.email}\n      emailHash={authData.emailHash}\n      timestamp={authData.timestamp}\n    >\n      <ChatInterface />\n    </HelperProvider>\n  );\n}\n```\n\n## Best Practices\n\n### Security\n\n- Keep `HELPER_HMAC_SECRET` secure and never expose it client-side\n- Generate authentication tokens server-side using `generateHelperAuth()`\n- Validate user sessions before initializing Helper\n- Use environment variables for sensitive configuration\n\n### Performance\n\n- Initialize Helper only after user authentication\n- Implement proper cache invalidation strategies\n- Use framework-specific optimizations when available\n\n### Error Handling\n\n```tsx\nfunction ChatComponent() {\n  const { conversations, loading, error, refetch } = useConversations();\n\n  if (loading) return <LoadingSpinner />;\n  if (error) return <ErrorMessage message={error} onRetry={refetch} />;\n\n  return <ConversationsList conversations={conversations} />;\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Widget Not Loading\n\n- Verify environment variables are correctly set\n- Ensure HMAC generation is working using `generateHelperAuth()`\n- Check network requests for authentication errors\n\n#### Authentication Failures\n\n- Confirm HMAC secret matches dashboard configuration\n- Verify timestamp is current (generated server-side)\n- Validate email format and consistency\n\n#### API Calls Failing\n\n- Ensure authentication data is properly set in the provider\n- Check network connectivity and CORS settings\n- Verify API endpoint URLs are correct\n\n## Contributing\n\nThis package is part of the Helper project. Please refer to the main repository for contribution guidelines.\n\n## License\n\nMIT License - see LICENSE file for details.\n","readmeFilename":"README.md","repository":{"type":"git","url":"git+https://github.com/antiwork/helper.git"},"bugs":{"url":"https://github.com/antiwork/helper/issues"}}