{"_id":"@aimoverse/note-agent-react","name":"@aimoverse/note-agent-react","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aimoverse/note-agent-react","version":"0.1.0","type":"module","description":"React TypeScript SDK for WASM note agent","main":"lib/index.js","types":"lib/index.d.ts","module":"lib/index.esm.js","scripts":{"build":"tsc && rollup -c","build:types":"tsc --emitDeclarationOnly --declaration","build:js":"rollup -c","dev":"tsc --watch","clean":"rimraf lib","prepare":"npm run build","test":"jest","test:watch":"jest --watch","lint":"eslint src/**/*.{ts,tsx}","lint:fix":"eslint src/**/*.{ts,tsx} --fix"},"peerDependencies":{"react":">=16.8.0","react-dom":">=16.8.0"},"dependencies":{"@types/react":"^18.0.0","@types/react-dom":"^18.0.0"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.0","@rollup/plugin-node-resolve":"^15.0.0","@rollup/plugin-typescript":"^11.0.0","@types/jest":"^29.0.0","@types/node":"^18.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","eslint-plugin-react":"^7.32.0","eslint-plugin-react-hooks":"^4.6.0","jest":"^29.0.0","react":"^18.0.0","react-dom":"^18.0.0","rimraf":"^5.0.0","rollup":"^3.0.0","ts-jest":"^29.0.0","tslib":"^2.8.1","typescript":"^5.0.0"},"keywords":["react","typescript","wasm","agent","note","ai","lexical"],"repository":{"type":"git","url":"git+https://github.com/AIMOverse/note-agent.git"},"bugs":{"url":"https://github.com/AIMOverse/note-agent/issues"},"homepage":"https://github.com/AIMOverse/note-agent#readme","author":{"name":"Archer"},"license":"MIT","_id":"@aimoverse/note-agent-react@0.1.0","gitHead":"d81f135303eac1b97a6ef265247ada338fe6b023","_nodeVersion":"22.15.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-oXAhGc5Df2J5TgG5bBzjcjfVW93htukqypopHJZ5FRqN7Zztdd420Z7iQpYLoxKsou9XIIGzW4BZLuzlGL0GjA==","shasum":"e1c7a9cce0b05f4480e0ab6acf04a983c497e3be","tarball":"https://registry.npmjs.org/@aimoverse/note-agent-react/-/note-agent-react-0.1.0.tgz","fileCount":29,"unpackedSize":623332,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGRxWRT6DbCkcLeuGAqw/L9nHy9AyAEBoVM3m9KGA2ASAiEAkkbwPW78lgasONLjBzHIIQhnQW84+MCFtXCEhBcoZLA="}]},"_npmUser":{"name":"zane-archer","email":"fracher21@gmail.com"},"directories":{},"maintainers":[{"name":"zane-archer","email":"fracher21@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/note-agent-react_0.1.0_1752398078769_0.5331312588501158"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-13T09:14:38.687Z","0.1.0":"2025-07-13T09:14:39.024Z","modified":"2025-07-13T09:14:39.368Z"},"maintainers":[{"name":"zane-archer","email":"fracher21@gmail.com"}],"description":"React TypeScript SDK for WASM note agent","homepage":"https://github.com/AIMOverse/note-agent#readme","keywords":["react","typescript","wasm","agent","note","ai","lexical"],"repository":{"type":"git","url":"git+https://github.com/AIMOverse/note-agent.git"},"author":{"name":"Archer"},"bugs":{"url":"https://github.com/AIMOverse/note-agent/issues"},"license":"MIT","readme":"# @aimoverse/note-agent-react\r\n\r\nA React TypeScript SDK for interacting with the AIMO note agent WASM module. This library provides hooks and components for chat functionality, note manipulation, and real-time agent interactions.\r\n\r\n## Features\r\n\r\n- 🚀 **React Hooks**: Easy-to-use hooks for agent interaction\r\n- 📝 **Note Management**: Full support for Lexical note structure\r\n- 💬 **Chat Interface**: Real-time chat with the AI agent\r\n- 🔄 **State Management**: Global agent state with React Context\r\n- 📦 **TypeScript**: Full type safety with comprehensive type definitions\r\n- 🎯 **Tree Shaking**: Optimized bundle size with ES modules\r\n- 🛠️ **Utilities**: Helper functions for note and message manipulation\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @aimoverse/note-agent-react\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Wrap your app with the AgentProvider\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { AgentProvider } from '@aimoverse/note-agent-react';\r\n\r\nfunction App() {\r\n  return (\r\n    <AgentProvider \r\n      config={{ \r\n        jwt: 'your-jwt-token',\r\n        autoStart: true \r\n      }}\r\n    >\r\n      <YourAppContent />\r\n    </AgentProvider>\r\n  );\r\n}\r\n```\r\n\r\n### 2. Use the agent in your components\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { useAgent, useChat, NoteUtils } from '@aimoverse/note-agent-react';\r\n\r\nfunction ChatComponent() {\r\n  const { status, isReady } = useAgent();\r\n  const { sendMessage, messages, isLoading } = useChat();\r\n\r\n  const handleSendMessage = async () => {\r\n    const note = NoteUtils.createEmptyNote('example-note');\r\n    const action = await sendMessage(\r\n      'Hello, agent!',\r\n      0, // cursor position\r\n      note\r\n    );\r\n    \r\n    if (action) {\r\n      console.log('Agent action:', action);\r\n    }\r\n  };\r\n\r\n  return (\r\n    <div>\r\n      <div>Status: {status}</div>\r\n      <button \r\n        onClick={handleSendMessage} \r\n        disabled={!isReady || isLoading}\r\n      >\r\n        Send Message\r\n      </button>\r\n      <div>\r\n        {messages.map((msg, index) => (\r\n          <div key={index}>\r\n            <strong>{msg.role}:</strong> {msg.content}\r\n          </div>\r\n        ))}\r\n      </div>\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### Components\r\n\r\n#### AgentProvider\r\n\r\nThe main provider component that manages the global agent state.\r\n\r\n```tsx\r\ninterface AgentProviderProps {\r\n  children: React.ReactNode;\r\n  config?: AgentConfig;\r\n  onError?: (error: AgentError) => void;\r\n  onStatusChange?: (status: AgentStatus) => void;\r\n}\r\n```\r\n\r\n### Hooks\r\n\r\n#### useAgent(config?: AgentConfig)\r\n\r\nMain hook for interacting with the agent.\r\n\r\n```tsx\r\nconst {\r\n  agent,           // AgentWasmRuntime instance\r\n  status,          // 'idle' | 'starting' | 'running' | 'error'\r\n  error,           // AgentError | null\r\n  isReady,         // boolean\r\n  isInitialized,   // boolean\r\n  initialize,      // (config: AgentConfig) => Promise<void>\r\n  start,           // () => Promise<void>\r\n  stop,            // () => void\r\n  clearError,      // () => void\r\n  chat,            // (messages, cursorPosition, note) => Promise<ChatAction>\r\n} = useAgent();\r\n```\r\n\r\n#### useChat(config?: ChatConfig)\r\n\r\nHook for managing chat conversations.\r\n\r\n```tsx\r\nconst {\r\n  messages,        // Message[]\r\n  isLoading,       // boolean\r\n  error,           // AgentError | null\r\n  lastMessage,     // Message | null\r\n  sendMessage,     // (content, cursorPosition, note, role?) => Promise<ChatAction>\r\n  addMessage,      // (message: Message) => void\r\n  clearMessages,   // () => void\r\n  clearError,      // () => void\r\n} = useChat();\r\n```\r\n\r\n#### useAgentStatus()\r\n\r\nHook for monitoring agent status.\r\n\r\n```tsx\r\nconst {\r\n  status,          // AgentStatus\r\n  error,           // AgentError | null\r\n  isReady,         // boolean\r\n  statusHistory,   // AgentStatus[]\r\n  isIdle,          // boolean\r\n  isStarting,      // boolean\r\n  isRunning,       // boolean\r\n  hasError,        // boolean\r\n} = useAgentStatus();\r\n```\r\n\r\n#### useMessages(initialMessages?: Message[])\r\n\r\nHook for managing message collections.\r\n\r\n```tsx\r\nconst {\r\n  messages,        // Message[]\r\n  addMessage,      // (message: Message) => void\r\n  removeMessage,   // (index: number) => void\r\n  updateMessage,   // (index: number, message: Message) => void\r\n  clearMessages,   // () => void\r\n  getMessagesByRole, // (role: string) => Message[]\r\n  userMessages,    // Message[]\r\n  assistantMessages, // Message[]\r\n  systemMessages,  // Message[]\r\n  isEmpty,         // boolean\r\n  count,           // number\r\n} = useMessages();\r\n```\r\n\r\n#### useConversation(config?: ChatConfig & { persistKey?: string })\r\n\r\nAdvanced hook for managing conversation history with persistence.\r\n\r\n```tsx\r\nconst {\r\n  ...chatHookValues,\r\n  conversationHistory,    // Message[][]\r\n  startNewConversation,   // () => void\r\n  loadConversation,       // (index: number) => void\r\n  deleteConversation,     // (index: number) => void\r\n  clearAllConversations,  // () => void\r\n  hasHistory,             // boolean\r\n  conversationCount,      // number\r\n} = useConversation();\r\n```\r\n\r\n### Utilities\r\n\r\n#### NodeUtils\r\n\r\nUtilities for working with Lexical nodes.\r\n\r\n```tsx\r\nNodeUtils.extractText(node: LexicalNode): string\r\nNodeUtils.isEmpty(node: LexicalNode): boolean\r\nNodeUtils.getNodeTypeLabel(node: LexicalNode): string\r\nNodeUtils.hasChildren(node: LexicalNode): boolean\r\nNodeUtils.countChildren(node: LexicalNode): number\r\nNodeUtils.findNodesByType<T>(node: LexicalNode, type: T['type']): T[]\r\nNodeUtils.createTextNode(text: string, format?: number): TextNode\r\nNodeUtils.createParagraphNode(children?: LexicalNode[]): ParagraphNode\r\nNodeUtils.createHeadingNode(tag: HeadingTag, children?: LexicalNode[]): HeadingNode\r\nNodeUtils.createAIEmbeddingNode(content: string, isLoading?: boolean): AIEmbeddingNode\r\n```\r\n\r\n#### NoteUtils\r\n\r\nUtilities for working with notes.\r\n\r\n```tsx\r\nNoteUtils.extractText(note: Note): string\r\nNoteUtils.getBrief(note: Note): BriefNode[]\r\nNoteUtils.countWords(note: Note): number\r\nNoteUtils.countCharacters(note: Note): number\r\nNoteUtils.findNodesByType<T>(note: Note, type: T['type']): T[]\r\nNoteUtils.isEmpty(note: Note): boolean\r\nNoteUtils.getNodeById(note: Note, id: number): LexicalNode | null\r\nNoteUtils.createEmptyNote(noteId: string): Note\r\nNoteUtils.addNode(note: Note, node: LexicalNode, position?: number): Note\r\nNoteUtils.removeNode(note: Note, nodeId: number): Note\r\nNoteUtils.updateNode(note: Note, nodeId: number, newNode: LexicalNode): Note\r\n```\r\n\r\n#### MessageUtils\r\n\r\nUtilities for working with messages.\r\n\r\n```tsx\r\nMessageUtils.createMessage(content: string, role?: string): Message\r\nMessageUtils.createUserMessage(content: string): Message\r\nMessageUtils.createAssistantMessage(content: string): Message\r\nMessageUtils.createSystemMessage(content: string): Message\r\nMessageUtils.filterByRole(messages: Message[], role: string): Message[]\r\nMessageUtils.getLastMessage(messages: Message[]): Message | null\r\nMessageUtils.getLastMessageByRole(messages: Message[], role: string): Message | null\r\nMessageUtils.countByRole(messages: Message[], role: string): number\r\nMessageUtils.truncate(messages: Message[], maxCount: number): Message[]\r\nMessageUtils.formatForDisplay(message: Message): string\r\n```\r\n\r\n#### ChatActionUtils\r\n\r\nUtilities for working with chat actions.\r\n\r\n```tsx\r\nChatActionUtils.isReply(action: ChatAction): boolean\r\nChatActionUtils.isInsertNode(action: ChatAction): boolean\r\nChatActionUtils.isModifyNode(action: ChatAction): boolean\r\nChatActionUtils.applyToNote(note: Note, action: ChatAction): Note\r\nChatActionUtils.getDescription(action: ChatAction): string\r\n```\r\n\r\n## Type Definitions\r\n\r\n### Core Types\r\n\r\n```tsx\r\ninterface Note {\r\n  noteId: string;\r\n  lexicalState: LexicalState;\r\n}\r\n\r\ninterface Message {\r\n  content: string;\r\n  role: string;\r\n}\r\n\r\ninterface ChatAction {\r\n  action: 'reply' | 'insert_node' | 'modify_node';\r\n  // ... specific properties based on action type\r\n}\r\n\r\ntype AgentStatus = 'idle' | 'starting' | 'running' | 'error';\r\n\r\ninterface AgentError {\r\n  message: string;\r\n  code?: string;\r\n}\r\n```\r\n\r\n### Configuration Types\r\n\r\n```tsx\r\ninterface AgentConfig {\r\n  jwt: string;\r\n  autoStart?: boolean;\r\n}\r\n\r\ninterface ChatConfig {\r\n  maxMessages?: number;\r\n  timeout?: number;\r\n}\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Custom Error Handling\r\n\r\n```tsx\r\nfunction MyApp() {\r\n  const handleError = (error: AgentError) => {\r\n    console.error('Agent error:', error);\r\n    // Custom error handling logic\r\n  };\r\n\r\n  return (\r\n    <AgentProvider onError={handleError}>\r\n      <YourApp />\r\n    </AgentProvider>\r\n  );\r\n}\r\n```\r\n\r\n### Persistent Conversations\r\n\r\n```tsx\r\nfunction ChatWithHistory() {\r\n  const { \r\n    conversationHistory, \r\n    startNewConversation,\r\n    loadConversation \r\n  } = useConversation({ \r\n    persistKey: 'my-app-conversations' \r\n  });\r\n\r\n  return (\r\n    <div>\r\n      <button onClick={startNewConversation}>\r\n        New Conversation\r\n      </button>\r\n      {conversationHistory.map((_, index) => (\r\n        <button key={index} onClick={() => loadConversation(index)}>\r\n          Load Conversation {index + 1}\r\n        </button>\r\n      ))}\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n### Working with Notes\r\n\r\n```tsx\r\nfunction NoteEditor() {\r\n  const [note, setNote] = useState(NoteUtils.createEmptyNote('my-note'));\r\n  const { sendMessage } = useChat();\r\n\r\n  const handleAgentAction = async (userMessage: string) => {\r\n    const action = await sendMessage(userMessage, 0, note);\r\n    \r\n    if (action && action.action !== 'reply') {\r\n      const updatedNote = ChatActionUtils.applyToNote(note, action);\r\n      setNote(updatedNote);\r\n    }\r\n  };\r\n\r\n  return (\r\n    <div>\r\n      <div>Word count: {NoteUtils.countWords(note)}</div>\r\n      <div>Character count: {NoteUtils.countCharacters(note)}</div>\r\n      <button onClick={() => handleAgentAction('Add a paragraph')}>\r\n        Ask Agent to Add Content\r\n      </button>\r\n    </div>\r\n  );\r\n}\r\n```\r\n\r\n## Development\r\n\r\n### Building the SDK\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n### Development Mode\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\n## Requirements\r\n\r\n- React >= 16.8.0\r\n- TypeScript >= 4.0.0\r\n- WASM support in the browser\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please read the contributing guidelines before submitting PRs.\r\n\r\n## Support\r\n\r\nFor support, please open an issue on the GitHub repository or contact the maintainers. ","readmeFilename":"README.md","_rev":"1-64c7e8e5391cd01a4ebfd8346ad26c49"}