{"_id":"@aichatkit/storage-adapter","_rev":"7-7aa6a957417f3cba8b5588c0f3bd74ec","name":"@aichatkit/storage-adapter","dist-tags":{"latest":"0.0.0-alpha.6"},"versions":{"0.0.0-alpha.0":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.0","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.0","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"c7ea39d216b64ed3ccb3326c213fe1263f687b23","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.0.tgz","fileCount":7,"integrity":"sha512-qcXjahebMGDpYqIA3fkR67e0utJUh6f7CwFRhQ6G/0+f40WzFsisdDWthYiok+1yrqQKdk/UYZJyvD55SrjKNg==","signatures":[{"sig":"MEQCIG6LxC4CaE1OKfkRqqhCURr5OiuiUU+ALTuAJVyTDGfEAiANcq+xNDPp4tA6COzP73rS+EIc6QF4Phihx9eTib6vvw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9309},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","gitHead":"ff46453f845c886e2819a16bfcee93f01706eabf","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com"},"_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.14.0","dependencies":{"@aichatkit/types":"workspace:^"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.0_1748541598796_0.4270706672815936","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.1":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.1","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.1","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"b01a493ff38409980cdf7b28c0f2a2a104197c99","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.1.tgz","fileCount":4,"integrity":"sha512-sWVJT9tqM1SVbwR1WzWPv3P0IkfE4PYz5ZnUkI3c4v54Xt8wrWXBiju/Zqg865qVYfwPsNefOar08RDW5NW8Yg==","signatures":[{"sig":"MEYCIQD1+iGBPPpIdTTqZVwJoRtcOai1BIYxA3ftynMG+POQpAIhAIuR+VB6GJ2CfCT4vuC3+FAAuMuK4H4JGH6V4quIeGid","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5424},"main":"dist/index.js","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.1.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com"},"_resolved":"/tmp/aff2348fde92b7f7b2720ed4522922ba/aichatkit-storage-adapter-0.0.0-alpha.1.tgz","_integrity":"sha512-sWVJT9tqM1SVbwR1WzWPv3P0IkfE4PYz5ZnUkI3c4v54Xt8wrWXBiju/Zqg865qVYfwPsNefOar08RDW5NW8Yg==","_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.13.0","dependencies":{"@aichatkit/types":"0.0.0-alpha.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.1_1748543218604_0.2641849744656515","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.2":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.2","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.2","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"4ac7fc71913ae4a3c29a18397ba33830ae0c6984","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.2.tgz","fileCount":8,"integrity":"sha512-5Aud0W0abzmzWOiaMD8Lj1vxOdpSp+AtJE5USoC6uh2NG6h7C5Sp1vYoBDpKrqIOVSoXHWattmZJTsZnNYeYlg==","signatures":[{"sig":"MEYCIQDgQFOs9j2lm8s8J2/7dBUKf2JWoqGro0lQ6XtADSEF8gIhANgWtgc7dYJexTIZTPAcWmDBwtnyhWesqdDeoqYR+cRO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10376},"main":"dist/index.js","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.2.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com"},"_resolved":"/tmp/80d388af0c3bd26c7cc31f1eb30bdd83/aichatkit-storage-adapter-0.0.0-alpha.2.tgz","_integrity":"sha512-5Aud0W0abzmzWOiaMD8Lj1vxOdpSp+AtJE5USoC6uh2NG6h7C5Sp1vYoBDpKrqIOVSoXHWattmZJTsZnNYeYlg==","_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.13.0","dependencies":{"@aichatkit/types":"0.0.0-alpha.2"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.2_1748544028099_0.3047112896441717","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.3":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.3","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.3","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"69b176bf45367001fd67f08b60dcc925fa01bb39","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.3.tgz","fileCount":8,"integrity":"sha512-4V29CMoJAoDaa2GPwYYJHpvmzs9GghGYAFV0XnPLJ7NGg7Wl0bhIRZU8YKDC25OXW9UqOoriZ2CUE6vJMdw80g==","signatures":[{"sig":"MEQCIGzd0DGVZoQFGhsXMtfFNR13BdwYh2GPlFAqzJ1nEpTxAiBpFARfPrbNN+8aJPb0ORGz1y4KOM2+4QQnh89TjoMIvg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10376},"main":"dist/index.js","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.3.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com"},"_resolved":"/tmp/49f07e7ff62c48938dca61542e7008ad/aichatkit-storage-adapter-0.0.0-alpha.3.tgz","_integrity":"sha512-4V29CMoJAoDaa2GPwYYJHpvmzs9GghGYAFV0XnPLJ7NGg7Wl0bhIRZU8YKDC25OXW9UqOoriZ2CUE6vJMdw80g==","_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.13.0","dependencies":{"@aichatkit/types":"0.0.0-alpha.3"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.3_1748544381796_0.42762373006874244","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.4":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.4","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.4","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"de445ea3b4b9e77df523bd7f2495bcb8835a9d90","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.4.tgz","fileCount":8,"integrity":"sha512-cqfsc1/nlp/zkjouiwHQEY5x1B7BuL9UDr2vlowhnQhC/ZGASYQnEFI2tXwF+CCM+2M3asL0EAYozSWhkLSbSg==","signatures":[{"sig":"MEQCIHJOr3j4xhePwV0gLVLVgnlr2ecqjEwkr/H9vtr2d6YTAiA3FKuIQht0bClc8eb4io+mDwp3GIiNo5TSMvVMTVDfMw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17491},"main":"dist/index.js","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.4.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com"},"_resolved":"/tmp/eef16e0a5c649c53543b73cf0e95b584/aichatkit-storage-adapter-0.0.0-alpha.4.tgz","_integrity":"sha512-cqfsc1/nlp/zkjouiwHQEY5x1B7BuL9UDr2vlowhnQhC/ZGASYQnEFI2tXwF+CCM+2M3asL0EAYozSWhkLSbSg==","_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.13.0","dependencies":{"@aichatkit/types":"0.0.0-alpha.4"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.4_1748599505134_0.5561894809078749","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.5":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.5","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","_id":"@aichatkit/storage-adapter@0.0.0-alpha.5","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dist":{"shasum":"4dcfe29462aabe0915ee1d108f9ded4374aed208","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.5.tgz","fileCount":8,"integrity":"sha512-ALc7Cpm0QLwSSIdEJzT0hnG9JLxqwXGThSEemj54RRt+J7LyD2E4BJf6yZ1P24Tyv+LcZFrjMTLv9FpsxgMTTw==","signatures":[{"sig":"MEUCIHR9WDriFDKesL2Hze/KIcGx/sXO1Xp+KWsPJegQpC52AiEA0aQa6OoFpgFmXgm1nCjtJDQjSSWV6/TTPnWU6huSDdE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26123},"main":"dist/index.js","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.5.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","build":"tsup src/index.ts --format cjs,esm --dts"},"_npmUser":{"name":"danstarns","actor":{"name":"danstarns","type":"user","email":"danielstarns@hotmail.com"},"email":"danielstarns@hotmail.com"},"_resolved":"/tmp/227e35825327db1db9fa8aab47f54982/aichatkit-storage-adapter-0.0.0-alpha.5.tgz","_integrity":"sha512-ALc7Cpm0QLwSSIdEJzT0hnG9JLxqwXGThSEemj54RRt+J7LyD2E4BJf6yZ1P24Tyv+LcZFrjMTLv9FpsxgMTTw==","_npmVersion":"10.9.2","description":"Base storage adapter for Hypermode ChatKit","directories":{},"_nodeVersion":"22.13.0","dependencies":{"@aichatkit/types":"0.0.0-alpha.5"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/storage-adapter_0.0.0-alpha.5_1750312728944_0.22288503134563298","host":"s3://npm-registry-packages-npm-production"}},"0.0.0-alpha.6":{"name":"@aichatkit/storage-adapter","version":"0.0.0-alpha.6","description":"Base storage adapter for Hypermode ChatKit","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","keywords":["chat","storage","adapter","persistence","hypermode"],"author":{"name":"Hypermode"},"license":"MIT","homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","dependencies":{"@aichatkit/types":"0.0.0-alpha.6"},"devDependencies":{"typescript":"^5.0.0","tsup":"^8.0.0"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch"},"_id":"@aichatkit/storage-adapter@0.0.0-alpha.6","_integrity":"sha512-g9kuMAP63vpvtCbjjZI/KAzGzxcPa6TH/Q57IqARFPxPyzc+rvqlIhh5CHv4RkzWV6+vJmOdBRY5ifBf2gMc3w==","_resolved":"/tmp/12e74fc441cc7f5975d6552a33a3c182/aichatkit-storage-adapter-0.0.0-alpha.6.tgz","_from":"file:aichatkit-storage-adapter-0.0.0-alpha.6.tgz","_nodeVersion":"22.13.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-g9kuMAP63vpvtCbjjZI/KAzGzxcPa6TH/Q57IqARFPxPyzc+rvqlIhh5CHv4RkzWV6+vJmOdBRY5ifBf2gMc3w==","shasum":"fd7b6867943b914beb41e05864353a7c54837ad1","tarball":"https://registry.npmjs.org/@aichatkit/storage-adapter/-/storage-adapter-0.0.0-alpha.6.tgz","fileCount":8,"unpackedSize":35515,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCbtaR18A+IvM2coQDIxYUwvn+zM9+tCoDe3HuAVOylmwIhAMcg6XAc5iRnnrb2LUGy+T9NCV6tRC2JkN+kS5+mdoh0"}]},"_npmUser":{"name":"danstarns","email":"danielstarns@hotmail.com","actor":{"name":"danstarns","email":"danielstarns@hotmail.com","type":"user"}},"directories":{},"maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storage-adapter_0.0.0-alpha.6_1751223240662_0.27668035932953305"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-29T17:59:58.709Z","modified":"2025-06-29T18:54:00.985Z","0.0.0-alpha.0":"2025-05-29T17:59:58.966Z","0.0.0-alpha.1":"2025-05-29T18:26:58.788Z","0.0.0-alpha.2":"2025-05-29T18:40:28.289Z","0.0.0-alpha.3":"2025-05-29T18:46:21.980Z","0.0.0-alpha.4":"2025-05-30T10:05:05.347Z","0.0.0-alpha.5":"2025-06-19T05:58:49.112Z","0.0.0-alpha.6":"2025-06-29T18:54:00.820Z"},"author":{"name":"Hypermode"},"license":"MIT","homepage":"https://github.com/hypermodeinc/chatkit/tree/main/packages/storage-adapter#readme","keywords":["chat","storage","adapter","persistence","hypermode"],"description":"Base storage adapter for Hypermode ChatKit","maintainers":[{"name":"danstarns","email":"danielstarns@hotmail.com"}],"readme":"# @aichatkit/storage-adapter\n\nBase storage adapter abstract class for Hypermode ChatKit with backend synchronization support and\nrich response items.\n\n## Installation\n\n```bash\nnpm install @aichatkit/storage-adapter\n```\n\n## Usage\n\nThis package provides the base abstract class for implementing storage adapters. You typically won't\nuse this package directly, but rather create or use an implementation like\n`@aichatkit/localstorage-adapter`.\n\n```typescript\nimport { StorageAdapter } from \"@aichatkit/storage-adapter\"\nimport { Conversation, ChatResponseItem, Message } from \"@aichatkit/types\"\n\n// Example: Create a custom adapter implementation\nclass CustomStorageAdapter extends StorageAdapter {\n  private conversations: Map<string, Conversation> = new Map()\n  private agentMapping: Map<string, string> = new Map()\n\n  async saveConversation(conversation: Conversation): Promise<void> {\n    this.conversations.set(conversation.id, { ...conversation })\n  }\n\n  async getConversation(id: string): Promise<Conversation | null> {\n    return this.conversations.get(id) || null\n  }\n\n  async getAllConversations(): Promise<Conversation[]> {\n    return Array.from(this.conversations.values())\n  }\n\n  async deleteConversation(id: string): Promise<boolean> {\n    const deleted = this.conversations.delete(id)\n    this.agentMapping.delete(id)\n    return deleted\n  }\n\n  async addItem(conversationId: string, item: ChatResponseItem): Promise<Conversation | null> {\n    const conversation = this.conversations.get(conversationId)\n    if (!conversation) return null\n\n    conversation.items.push(item)\n    await this.saveConversation(conversation)\n    return conversation\n  }\n\n  async getConversationItems(conversationId: string): Promise<ChatResponseItem[]> {\n    // Check if we have network callbacks for backend sync\n    const agentId = await this.getConversationAgent(conversationId)\n\n    if (agentId && this.callbacks?.getConversationItems) {\n      try {\n        const backendItems = await this.callbacks.getConversationItems(agentId)\n\n        // Update local storage with backend data\n        const conversation = await this.getConversation(conversationId)\n        if (conversation) {\n          conversation.items = backendItems\n          await this.saveConversation(conversation)\n        }\n\n        return backendItems\n      } catch (error) {\n        console.error(\"Backend sync failed, using local data:\", error)\n      }\n    }\n\n    // Fall back to local data\n    const conversation = await this.getConversation(conversationId)\n    return conversation?.items || []\n  }\n\n  async clearConversationHistory(conversationId: string): Promise<void> {\n    const agentId = await this.getConversationAgent(conversationId)\n\n    // Clear on backend if possible\n    if (agentId && this.callbacks?.clearConversationHistory) {\n      try {\n        await this.callbacks.clearConversationHistory(agentId)\n      } catch (error) {\n        console.error(\"Failed to clear backend history:\", error)\n      }\n    }\n\n    // Clear locally\n    const conversation = await this.getConversation(conversationId)\n    if (conversation) {\n      conversation.items = []\n      await this.saveConversation(conversation)\n    }\n  }\n\n  async setConversationAgent(conversationId: string, agentId: string): Promise<void> {\n    this.agentMapping.set(conversationId, agentId)\n  }\n\n  async getConversationAgent(conversationId: string): Promise<string | null> {\n    return this.agentMapping.get(conversationId) || null\n  }\n}\n```\n\n## Abstract Methods\n\nAll storage adapters must implement these core methods:\n\n### saveConversation(conversation: Conversation): Promise<void>\n\nSaves a conversation with all its response items to storage.\n\n```typescript\nabstract saveConversation(conversation: Conversation): Promise<void>;\n```\n\n**Parameters**:\n\n- `conversation`: The conversation object with items array containing messages, tool calls, cards,\n  etc.\n\n**Example**:\n\n```typescript\nawait adapter.saveConversation({\n  id: \"conv-1\",\n  title: \"My Chat\",\n  items: [\n    {\n      id: \"msg_1\",\n      type: \"message\",\n      content: \"Hello\",\n      role: \"user\",\n    },\n    {\n      id: \"tool_1\",\n      type: \"tool_call\",\n      toolCall: {\n        id: \"call_1\",\n        name: \"get_weather\",\n        arguments: { location: \"NYC\" },\n        status: \"completed\",\n        result: { temperature: \"22°C\" },\n      },\n    },\n  ],\n})\n```\n\n### getConversation(id: string): Promise<Conversation | null>\n\nRetrieves a conversation from storage by ID with all its response items.\n\n```typescript\nabstract getConversation(id: string): Promise<Conversation | null>;\n```\n\n**Parameters**:\n\n- `id`: ID of the conversation to retrieve\n\n**Returns**: Promise resolving to the conversation with all item types or null if not found\n\n### getAllConversations(): Promise<Conversation[]>\n\nRetrieves all conversations from storage with their complete response items.\n\n```typescript\nabstract getAllConversations(): Promise<Conversation[]>;\n```\n\n**Returns**: Promise resolving to an array of all conversations with their items\n\n### deleteConversation(id: string): Promise<boolean>\n\nDeletes a conversation from storage.\n\n```typescript\nabstract deleteConversation(id: string): Promise<boolean>;\n```\n\n**Parameters**:\n\n- `id`: ID of the conversation to delete\n\n**Returns**: Promise resolving to true if successful, false otherwise\n\n### addItem(conversationId: string, item: ChatResponseItem): Promise<Conversation | null>\n\nAdds any type of response item to a conversation.\n\n```typescript\nabstract addItem(conversationId: string, item: ChatResponseItem): Promise<Conversation | null>;\n```\n\n**Parameters**:\n\n- `conversationId`: ID of the conversation\n- `item`: Response item to add (message, tool call, card, etc.)\n\n**Returns**: Promise resolving to the updated conversation or null if not found\n\n**Example**:\n\n```typescript\n// Add a message\nawait adapter.addItem(\"conv-1\", {\n  id: \"msg_2\",\n  type: \"message\",\n  content: \"How's the weather?\",\n  role: \"user\",\n})\n\n// Add a tool call\nawait adapter.addItem(\"conv-1\", {\n  id: \"tool_2\",\n  type: \"tool_call\",\n  toolCall: {\n    id: \"call_2\",\n    name: \"get_weather\",\n    arguments: { location: \"NYC\" },\n    status: \"executing\",\n  },\n})\n```\n\n### addMessage(conversationId: string, message: Message): Promise<Conversation | null>\n\nConvenience method for adding message items.\n\n```typescript\nasync addMessage(conversationId: string, message: Message): Promise<Conversation | null>\n```\n\nThis method converts a Message to a MessageItem and calls `addItem()`.\n\n## Backend Synchronization Methods\n\nThese methods enable synchronization with backend agents:\n\n### getConversationItems(conversationId: string): Promise<ChatResponseItem[]>\n\nGets all conversation items with backend synchronization.\n\n```typescript\nabstract getConversationItems(conversationId: string): Promise<ChatResponseItem[]>;\n```\n\nThis method should:\n\n1. Check if a backend agent exists for the conversation\n2. Sync with backend if available to get all item types\n3. Fall back to local storage if backend sync fails\n\n### getConversationHistory(conversationId: string): Promise<Message[]>\n\nGets conversation history (messages only) with backend synchronization.\n\n```typescript\nasync getConversationHistory(conversationId: string): Promise<Message[]>\n```\n\nThis convenience method filters message items from all response items.\n\n### clearConversationHistory(conversationId: string): Promise<void>\n\nClears conversation history both locally and on backend.\n\n```typescript\nabstract clearConversationHistory(conversationId: string): Promise<void>;\n```\n\n### setConversationAgent(conversationId: string, agentId: string): Promise<void>\n\nMaps a conversation to a backend agent ID.\n\n```typescript\nabstract setConversationAgent(conversationId: string, agentId: string): Promise<void>;\n```\n\n### getConversationAgent(conversationId: string): Promise<string | null>\n\nGets the backend agent ID for a conversation.\n\n```typescript\nabstract getConversationAgent(conversationId: string): Promise<string | null>;\n```\n\n## Optional Methods\n\n### initialize(config?: Record<string, any>): Promise<void>\n\nOptional initialization method.\n\n```typescript\nasync initialize(config?: Record<string, any>): Promise<void> {\n  return Promise.resolve();\n}\n```\n\n### syncAllConversationsWithBackend(): Promise<void>\n\nSyncs all conversations with backend (called on app load).\n\n```typescript\nasync syncAllConversationsWithBackend?(): Promise<void> {\n  return Promise.resolve();\n}\n```\n\n## Network Callbacks\n\nStorage adapters can receive network callbacks for backend synchronization:\n\n### StorageAdapterCallbacks Interface\n\n```typescript\ninterface StorageAdapterCallbacks {\n  getConversationItems?: (agentId: string) => Promise<ChatResponseItem[]>\n  clearConversationHistory?: (agentId: string) => Promise<void>\n}\n```\n\n### setNetworkCallbacks(callbacks: StorageAdapterCallbacks): void\n\nSets network callbacks for backend communication.\n\n```typescript\nimport { NetworkAdapter } from \"@aichatkit/network-adapter\"\n\nconst networkAdapter = new SomeNetworkAdapter()\nconst storageAdapter = new SomeStorageAdapter()\n\n// Connect storage with network for syncing\nstorageAdapter.setNetworkCallbacks({\n  getConversationItems: (agentId) => networkAdapter.getConversationItems(agentId),\n  clearConversationHistory: (agentId) => networkAdapter.clearConversationHistory(agentId),\n})\n```\n\n## Data Types\n\n### Conversation\n\n```typescript\ninterface Conversation {\n  id: string\n  title: string\n  items: ChatResponseItem[] // Mixed array of messages, tool calls, cards, etc.\n}\n```\n\n### ChatResponseItem\n\nUnion type supporting multiple item types:\n\n```typescript\ntype ChatResponseItem = MessageItem | ToolCallItem | CardItem\n\ninterface MessageItem {\n  id: string | number\n  type: \"message\"\n  content: string\n  role: \"user\" | \"assistant\"\n  timestamp?: string\n}\n\ninterface ToolCallItem {\n  id: string | number\n  type: \"tool_call\"\n  toolCall: {\n    id: string\n    name: string\n    arguments: Record<string, any>\n    status: \"pending\" | \"executing\" | \"completed\" | \"error\"\n    result?: any\n    error?: string\n  }\n}\n\ninterface CardItem {\n  id: string | number\n  type: \"card\"\n  card: {\n    id: string\n    type: string\n    title?: string\n    content: Record<string, any>\n    actions?: CardAction[]\n  }\n}\n```\n\n### Message\n\n```typescript\ninterface Message {\n  id: string | number\n  content: string\n  role: \"user\" | \"assistant\"\n  timestamp?: string\n}\n```\n\n## Agent-Conversation Mapping\n\nStorage adapters maintain a mapping between conversations and backend agents:\n\n```typescript\n// When creating a new conversation with an agent\nawait storageAdapter.setConversationAgent(\"conv-1\", \"agent-123\")\n\n// When retrieving the agent for a conversation\nconst agentId = await storageAdapter.getConversationAgent(\"conv-1\")\n\n// When deleting a conversation, also remove the agent mapping\nawait storageAdapter.deleteConversation(\"conv-1\") // Should also remove agent mapping\n```\n\n## Synchronization Flow\n\n1. **App Initialization**: Call `syncAllConversationsWithBackend()` to get latest state\n2. **Conversation Switch**: Sync specific conversation when user switches to it\n3. **Item History**: Always try backend first, fall back to local storage\n4. **Background Sync**: Periodically sync to keep data fresh\n\n### Example Sync Implementation\n\n```typescript\nasync getConversationItems(conversationId: string): Promise<ChatResponseItem[]> {\n  const agentId = await this.getConversationAgent(conversationId);\n\n  if (agentId && this.callbacks?.getConversationItems) {\n    try {\n      // Try to get latest from backend\n      const backendItems = await this.callbacks.getConversationItems(agentId);\n\n      // Update local storage with backend data\n      const conversation = await this.getConversation(conversationId);\n      if (conversation) {\n        conversation.items = backendItems;\n        await this.saveConversation(conversation);\n      }\n\n      return backendItems;\n    } catch (error) {\n      console.error('Backend sync failed:', error);\n      // Continue to local fallback\n    }\n  }\n\n  // Fall back to local storage\n  const conversation = await this.getConversation(conversationId);\n  return conversation?.items || [];\n}\n```\n\n## Available Implementations\n\n- **[@aichatkit/localstorage-adapter](../localstorage-adapter)**: Browser localStorage\n  implementation\n- **Custom implementations**: Create your own for databases, cloud storage, etc.\n\n## Testing\n\nMock storage adapters for testing:\n\n```typescript\nclass MockStorageAdapter extends StorageAdapter {\n  private data: Map<string, Conversation> = new Map()\n\n  async saveConversation(conversation: Conversation): Promise<void> {\n    this.data.set(conversation.id, { ...conversation })\n  }\n\n  async getConversation(id: string): Promise<Conversation | null> {\n    return this.data.get(id) || null\n  }\n\n  // ... implement other methods\n}\n```\n\n## License\n\n[MIT](../../LICENSE) © Hypermode\n","readmeFilename":"README.md"}