@pagelines/sdk 1.0.877 → 1.0.879

package/README.md

@@ -1,6 +1,6 @@
 # PageLines SDK
 
-Lightweight client library for PageLines agent integration. Built for PageLines-owned properties (app, www, widget).
+Lightweight client library for PageLines bot integration. Built for PageLines-owned properties (app, www, widget).
 
 ## Installation
 
@@ -16,8 +16,8 @@ import { PageLinesSDK } from '@pagelines/sdk'
 // Singleton pattern - shares state across your app
 const sdk = PageLinesSDK.getInstance({ isDev: true })
 
-// Get public agent
-const agent = await sdk.getPublicAgent({ handle: 'andrew' })
+// Get public bot
+const bot = await sdk.getPublicBot({ handle: 'andrew' })
 
 // Authenticate user
 await sdk.requestAuthCode({ email: 'user@example.com' })
@@ -25,7 +25,7 @@ await sdk.loginWithCode({ email: 'user@example.com', code: '123456' })
 
 // Access reactive state
 console.log(sdk.activeUser.value)
-console.log(sdk.currentAgent.value)
+console.log(sdk.currentBot.value)
 console.log(sdk.currentOrg.value)
 ```
 
@@ -33,7 +33,7 @@ console.log(sdk.currentOrg.value)
 
 **Minimal API Surface**: Clean wrapper methods hide internal complexity. No direct `apiClient` exposure prevents type generation issues.
 
-**Agent-First Architecture**: Agents are primary entities. Organization context derived from agent, not passed redundantly.
+**Bot-First Architecture**: Bots are primary entities. Organization context derived from bot, not passed redundantly.
 
 **Singleton by Default**: Browser-only singleton prevents duplicate API calls and separate reactive state. Multiple `getInstance()` calls return same instance.
 
@@ -63,14 +63,14 @@ const user = await sdk.getCurrentUser()
 await sdk.logout()
 ```
 
-### Agent Access
+### Bot Access
 
 ```typescript
-// Public agent by handle (no auth)
-const agent = await sdk.getPublicAgent({ handle: 'andrew' })
+// Public bot by handle (no auth)
+const bot = await sdk.getPublicBot({ handle: 'andrew' })
 
-// Public agent by email (no auth)
-const agent = await sdk.getAgentByEmail({ email: 'andrew@pagelines.com' })
+// Public bot by email (no auth)
+const bot = await sdk.getBotByEmail({ email: 'andrew@pagelines.com' })
 ```
 
 ### Usage Tracking
@@ -78,7 +78,7 @@ const agent = await sdk.getAgentByEmail({ email: 'andrew@pagelines.com' })
 ```typescript
 // Unified tracking method
 await sdk.trackUsage({
-  agentId: 'agt_456',      // Agent contains orgId
+  botId: 'agt_456',      // Bot contains orgId
   type: 'voice',          // 'voice' | 'chat'
   quantity: 45,           // Seconds for voice, characters for chat
   participantId: 'usr_123' // Optional: conversation participant
@@ -95,7 +95,7 @@ sdk.loading.value       // boolean
 sdk.error.value         // string | null
 
 // Computed properties (auto-derived from activeUser)
-sdk.currentAgent.value   // Agent | undefined
+sdk.currentBot.value   // Bot | undefined
 sdk.currentOrg.value    // OrgInfo | undefined
 ```
 
@@ -166,12 +166,12 @@ const testSDK = PageLinesSDK.getInstance({
 import { PageLinesSDK } from '@pagelines/sdk'
 
 const sdk = PageLinesSDK.getInstance({ isDev: import.meta.env.DEV })
-const authorAgent = await sdk.getAgentByEmail({ email: 'andrew@pagelines.com' })
+const authorBot = await sdk.getBotByEmail({ email: 'andrew@pagelines.com' })
 
-// Use agent data instead of static strings
-const authorAvatar = authorAgent?.avatar?.url
-const authorName = authorAgent?.name
-const authorBio = authorAgent?.summary
+// Use bot data instead of static strings
+const authorAvatar = authorBot?.avatar?.url
+const authorName = authorBot?.name
+const authorBio = authorBot?.summary
 ```
 
 ### Widget Integration
@@ -181,14 +181,14 @@ import { PLWidget } from '@pagelines/sdk/widget'
 
 const widget = new PLWidget({
   mode: 'modal',        // 'inline' | 'popup' | 'modal'
-  handle: 'andrew',     // Or provide agent object directly
-  context: 'support',   // Optional: agent context override
+  handle: 'andrew',     // Or provide bot object directly
+  context: 'support',   // Optional: bot context override
   firstMessage: 'Hi!'   // Optional: custom greeting
 })
 
 // Update without re-mount
 widget.update({
-  agent: newAgent,
+  bot: newBot,
   context: 'sales'
 })
 
@@ -199,17 +199,17 @@ widget.destroy()
 ### Profile Page
 
 ```typescript
-import { AgentChat } from '@pagelines/sdk/agent'
+import { BotChat } from '@pagelines/sdk/bot'
 
 const sdk = PageLinesSDK.getInstance({ isDev: true })
-const agent = await sdk.getPublicAgent({ handle: 'andrew' })
+const bot = await sdk.getPublicBot({ handle: 'andrew' })
 ```
 
 ```vue
 <template>
-  <AgentChat
+  <BotChat
     :sdk="sdk"
-    :agent="agent"
+    :bot="bot"
     theme-color="#3b82f6"
   />
 </template>
@@ -220,10 +220,10 @@ const agent = await sdk.getPublicAgent({ handle: 'andrew' })
 All wrapper methods return `undefined` on error (no exceptions thrown). Check reactive error state for details.
 
 ```typescript
-const agent = await sdk.getPublicAgent({ handle: 'nonexistent' })
+const bot = await sdk.getPublicBot({ handle: 'nonexistent' })
 
-if (!agent) {
-  console.error(sdk.error.value) // 'Agent not found'
+if (!bot) {
+  console.error(sdk.error.value) // 'Bot not found'
 }
 ```
 
@@ -244,12 +244,12 @@ if (!agent) {
 ```typescript
 // ✅ Correct - Use bundled entry points
 import { PageLinesSDK } from '@pagelines/sdk'
-import { AgentChat, AgentProvider } from '@pagelines/sdk/agent'
+import { BotChat, BotProvider } from '@pagelines/sdk/bot'
 import { PLWidget } from '@pagelines/sdk/widget'
 
 // ❌ Wrong - Deep imports don't work
 import { PageLinesSDK } from '@pagelines/sdk/PageLinesSDK'
-import AgentChat from '@pagelines/sdk/agent/ui/AgentChat.vue'
+import BotChat from '@pagelines/sdk/bot/ui/BotChat.vue'
 ```
 
 ## Package Exports
@@ -261,9 +261,9 @@ import AgentChat from '@pagelines/sdk/agent/ui/AgentChat.vue'
       "import": "./dist/sdk.js",
       "types": "./dist/sdk.d.ts"
     },
-    "./agent": {
-      "import": "./dist/agent.js",
-      "types": "./dist/agent.d.ts"
+    "./bot": {
+      "import": "./dist/bot.js",
+      "types": "./dist/bot.d.ts"
     },
     "./widget": {
       "import": "./dist/widget.js",
@@ -273,22 +273,22 @@ import AgentChat from '@pagelines/sdk/agent/ui/AgentChat.vue'
 }
 ```
 
-## Agent-First Architecture
+## Bot-First Architecture
 
-Agents are primary entities that determine organizational context.
+Bots are primary entities that determine organizational context.
 
 ```typescript
-// ✅ Agent contains all context
+// ✅ Bot contains all context
 await sdk.trackUsage({
-  agentId: 'agt_456',  // Includes orgId internally
+  botId: 'agt_456',  // Includes orgId internally
   type: 'voice',
   quantity: 45
 })
 
 // ❌ Don't pass redundant orgId
 await sdk.trackUsage({
-  orgId: 'org_123',   // Redundant - derived from agentId
-  agentId: 'agt_456',
+  orgId: 'org_123',   // Redundant - derived from botId
+  botId: 'agt_456',
   type: 'voice',
   quantity: 45
 })
@@ -296,7 +296,7 @@ await sdk.trackUsage({
 
 **Benefits**:
 - Simpler APIs (fewer parameters)
-- Single source of truth (agent determines org)
+- Single source of truth (bot determines org)
 - Automatic context resolution
 - Consistent across all SDK methods
 
@@ -314,20 +314,20 @@ sdk.loading.value       // Updated during API calls
 sdk.error.value         // Updated on errors
 
 // Computed properties (auto-derived)
-sdk.currentAgent.value = computed(() => {
+sdk.currentBot.value = computed(() => {
   const user = sdk.activeUser.value
-  if (!user?.agents) return undefined
+  if (!user?.bots) return undefined
 
-  const agentId = user.primaryAgentId || user.agents[0]?.agentId
-  return user.agents.find(a => a.agentId === agentId)
+  const botId = user.primaryBotId || user.bots[0]?.botId
+  return user.bots.find(a => a.botId === botId)
 })
 
 sdk.currentOrg.value = computed(() => {
-  const agent = sdk.currentAgent.value
-  if (!agent?.orgId) return undefined
+  const bot = sdk.currentBot.value
+  if (!bot?.orgId) return undefined
 
   return sdk.activeUser.value?.orgs.find(org =>
-    org.orgId === agent.orgId
+    org.orgId === bot.orgId
   )
 })
 ```
@@ -336,7 +336,7 @@ sdk.currentOrg.value = computed(() => {
 - Components auto-update when user changes
 - No manual state management needed
 - Consistent with PageLines app patterns
-- Agent-first architecture (org derived from agent)
+- Bot-first architecture (org derived from bot)
 
 ## Component Integration
 
@@ -347,16 +347,16 @@ SDK components accept `sdk` prop instead of using global services.
 ```vue
 <script setup>
 import { PageLinesSDK } from '@pagelines/sdk'
-import { AgentChat } from '@pagelines/sdk/agent'
+import { BotChat } from '@pagelines/sdk/bot'
 
 const sdk = PageLinesSDK.getInstance({ isDev: true })
-const agent = await sdk.getPublicAgent({ handle: 'andrew' })
+const bot = await sdk.getPublicBot({ handle: 'andrew' })
 </script>
 
 <template>
-  <AgentChat
+  <BotChat
     :sdk="sdk"
-    :agent="agent"
+    :bot="bot"
     theme-color="#3b82f6"
   />
 </template>
@@ -364,20 +364,20 @@ const agent = await sdk.getPublicAgent({ handle: 'andrew' })
 
 ### Available Components
 
-**AgentChat** - Main agent interface (chat/voice)
-**AgentProvider** - Handle → agent resolver wrapper
-**ElAgentAbout** - Profile information display
-**ElAgentChat** - Text chat interface
-**ElAgentVoice** - Voice call interface
-**ElAgentSidebar** - Navigation sidebar
+**BotChat** - Main bot interface (chat/voice)
+**BotProvider** - Handle → bot resolver wrapper
+**ElBotAbout** - Profile information display
+**ElBotChat** - Text chat interface
+**ElBotVoice** - Voice call interface
+**ElBotSidebar** - Navigation sidebar
 
 ## Security Model
 
-**Public-Only Access**: `getPublicAgent()` and `getAgentByEmail()` only return agents with `visibility: 'public'`.
+**Public-Only Access**: `getPublicBot()` and `getBotByEmail()` only return bots with `visibility: 'public'`.
 
 **Authentication Required**: User operations require a valid opaque session token in `sdk.token.value`.
 
-**Rate Limiting**: Widget includes 10 comments/hour per agent, 100 likes/hour (future).
+**Rate Limiting**: Widget includes 10 comments/hour per bot, 100 likes/hour (future).
 
 ## Performance Optimization
 
@@ -395,16 +395,16 @@ const agent = await sdk.getPublicAgent({ handle: 'andrew' })
 
 **Wrapper Method Pattern**: Clean function signatures serialize perfectly to `.d.ts` files.
 
-**No Complex Types**: Simple `Promise<Agent | undefined>` instead of Hono RPC types.
+**No Complex Types**: Simple `Promise<Bot | undefined>` instead of Hono RPC types.
 
 ```typescript
 // Clean wrapper method
-async getPublicAgent(args: {
+async getPublicBot(args: {
   handle: string
-}): Promise<Agent | undefined>
+}): Promise<Bot | undefined>
 
 // Internal complexity hidden
-const response = await this.api.agent.public[':handle'].$get({
+const response = await this.api.bot.public[':handle'].$get({
   param: { handle: args.handle }
 })
 ```
@@ -445,20 +445,20 @@ afterEach(() => {
 **4. Check Error State**: Methods return `undefined` on error.
 
 ```typescript
-const agent = await sdk.getPublicAgent({ handle: 'test' })
-if (!agent) {
+const bot = await sdk.getPublicBot({ handle: 'test' })
+if (!bot) {
   console.error(sdk.error.value)
 }
 ```
 
-**5. Agent-First APIs**: Pass `agentId`, let SDK resolve `orgId`.
+**5. Bot-First APIs**: Pass `botId`, let SDK resolve `orgId`.
 
 ```typescript
 // ✅ Minimal args
-await sdk.trackUsage({ agentId, type, quantity })
+await sdk.trackUsage({ botId, type, quantity })
 
 // ❌ Redundant args
-await sdk.trackUsage({ orgId, agentId, type, quantity })
+await sdk.trackUsage({ orgId, botId, type, quantity })
 ```
 
 ## Architecture Principles