@skillrecordings/cli 0.1.0

package/src/commands/front/index.ts

@@ -0,0 +1,351 @@
+/**
+ * Front CLI commands for debugging and investigation
+ *
+ * Provides direct access to Front API for:
+ * - Fetching messages (body, author, recipients)
+ * - Fetching conversations with message history
+ * - Listing and looking up teammates
+ * - Comparing webhook data vs API data
+ */
+
+import { createInstrumentedFrontClient } from '@skillrecordings/core/front/instrumented-client'
+import type {
+  Message as FrontMessage,
+  MessageList,
+} from '@skillrecordings/front-sdk'
+import type { Command } from 'commander'
+import { registerCacheCommand } from '../front-cache'
+import { registerPullCommand } from './pull-conversations'
+import { registerTagCommands } from './tags'
+
+type Message = FrontMessage
+
+/**
+ * Get Front API client from environment (instrumented)
+ */
+function getFrontClient() {
+  const apiToken = process.env.FRONT_API_TOKEN
+  if (!apiToken) {
+    throw new Error('FRONT_API_TOKEN environment variable is required')
+  }
+  return createInstrumentedFrontClient({ apiToken })
+}
+
+/**
+ * Get Front SDK client from environment (full typed client)
+ */
+function getFrontSdkClient() {
+  const apiToken = process.env.FRONT_API_TOKEN
+  if (!apiToken) {
+    throw new Error('FRONT_API_TOKEN environment variable is required')
+  }
+  return createInstrumentedFrontClient({ apiToken })
+}
+
+/**
+ * Format timestamp to human-readable
+ */
+function formatTimestamp(ts: number): string {
+  return new Date(ts * 1000).toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/**
+ * Truncate string with ellipsis
+ */
+function truncate(str: string, len: number): string {
+  if (str.length <= len) return str
+  return str.slice(0, len - 3) + '...'
+}
+
+/**
+ * Normalize Front resource ID or URL to ID
+ */
+function normalizeId(idOrUrl: string): string {
+  return idOrUrl.startsWith('http') ? idOrUrl.split('/').pop()! : idOrUrl
+}
+
+/**
+ * Command: skill front message <id>
+ * Fetch full message details from Front API
+ */
+async function getMessage(
+  id: string,
+  options: { json?: boolean }
+): Promise<void> {
+  try {
+    const front = getFrontClient()
+    const message = await front.messages.get(normalizeId(id))
+
+    if (options.json) {
+      console.log(JSON.stringify(message, null, 2))
+      return
+    }
+
+    console.log('\n📧 Message Details:')
+    console.log(`   ID:       ${message.id}`)
+    console.log(`   Type:     ${message.type}`)
+    console.log(`   Subject:  ${message.subject || '(none)'}`)
+    console.log(`   Created:  ${formatTimestamp(message.created_at)}`)
+
+    if (message.author) {
+      console.log(`   Author:   ${message.author.email || message.author.id}`)
+    }
+
+    console.log('\n📬 Recipients:')
+    for (const r of message.recipients) {
+      console.log(`   ${r.role}: ${r.handle}`)
+    }
+
+    console.log('\n📝 Body:')
+    // Strip HTML and show preview
+    const textBody =
+      message.text ||
+      message.body
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+    console.log(
+      `   Length: ${message.body.length} chars (HTML), ${textBody.length} chars (text)`
+    )
+    console.log(`   Preview: ${truncate(textBody, 500)}`)
+
+    if (message.attachments && message.attachments.length > 0) {
+      console.log(`\n📎 Attachments: ${message.attachments.length}`)
+      for (const a of message.attachments) {
+        console.log(`   - ${a.filename} (${a.content_type})`)
+      }
+    }
+
+    console.log('')
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : 'Unknown error',
+        })
+      )
+    } else {
+      console.error(
+        'Error:',
+        error instanceof Error ? error.message : 'Unknown error'
+      )
+    }
+    process.exit(1)
+  }
+}
+
+/**
+ * Command: skill front conversation <id>
+ * Fetch conversation details and optionally messages
+ */
+async function getConversation(
+  id: string,
+  options: { json?: boolean; messages?: boolean }
+): Promise<void> {
+  try {
+    const front = getFrontClient()
+    const conversation = await front.conversations.get(normalizeId(id))
+
+    // Fetch messages if requested
+    let messages: Message[] | undefined
+    if (options.messages) {
+      const messageList = (await front.conversations.listMessages(
+        normalizeId(id)
+      )) as MessageList
+      messages = messageList._results ?? []
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify({ conversation, messages }, null, 2))
+      return
+    }
+
+    console.log('\n💬 Conversation Details:')
+    console.log(`   ID:       ${conversation.id}`)
+    console.log(`   Subject:  ${conversation.subject || '(none)'}`)
+    console.log(`   Status:   ${conversation.status}`)
+    console.log(`   Created:  ${formatTimestamp(conversation.created_at)}`)
+
+    if (conversation.recipient) {
+      console.log(`   Recipient: ${conversation.recipient.handle}`)
+    }
+
+    if (conversation.assignee) {
+      console.log(`   Assignee: ${conversation.assignee.email}`)
+    }
+
+    if (conversation.tags && conversation.tags.length > 0) {
+      console.log(
+        `   Tags:     ${conversation.tags.map((t: { name: string }) => t.name).join(', ')}`
+      )
+    }
+
+    if (options.messages && messages) {
+      console.log(`\n📨 Messages (${messages.length}):`)
+      console.log('-'.repeat(80))
+
+      for (const msg of messages) {
+        const direction = msg.is_inbound ? '← IN' : '→ OUT'
+        const author = msg.author?.email || 'unknown'
+        const time = formatTimestamp(msg.created_at)
+        const textBody =
+          msg.text ||
+          msg.body
+            .replace(/<[^>]*>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim()
+
+        console.log(`\n[${direction}] ${time} - ${author}`)
+        console.log(`   ${truncate(textBody, 200)}`)
+      }
+    } else if (!options.messages) {
+      console.log('\n   (use --messages to see message history)')
+    }
+
+    console.log('')
+  } catch (error) {
+    if (options.json) {
+      console.error(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : 'Unknown error',
+        })
+      )
+    } else {
+      console.error(
+        'Error:',
+        error instanceof Error ? error.message : 'Unknown error'
+      )
+    }
+    process.exit(1)
+  }
+}
+
+/**
+ * Command: skill front teammates
+ * List all teammates in the workspace
+ */
+async function listTeammates(options: { json?: boolean }): Promise<void> {
+  try {
+    const front = getFrontSdkClient()
+    const result = await front.teammates.list()
+
+    if (options.json) {
+      console.log(JSON.stringify(result._results, null, 2))
+      return
+    }
+
+    console.log('\n👥 Teammates:')
+    console.log('-'.repeat(60))
+
+    for (const teammate of result._results) {
+      const available = teammate.is_available ? '✓' : '✗'
+      console.log(`   ${available} ${teammate.id}`)
+      console.log(`      Email: ${teammate.email}`)
+      if (teammate.first_name || teammate.last_name) {
+        console.log(
+          `      Name:  ${teammate.first_name || ''} ${teammate.last_name || ''}`.trim()
+        )
+      }
+      if (teammate.username) {
+        console.log(`      Username: ${teammate.username}`)
+      }
+      console.log('')
+    }
+  } catch (error) {
+    console.error(
+      'Error:',
+      error instanceof Error ? error.message : 'Unknown error'
+    )
+    process.exit(1)
+  }
+}
+
+/**
+ * Command: skill front teammate <id>
+ * Get a specific teammate by ID
+ */
+async function getTeammate(
+  id: string,
+  options: { json?: boolean }
+): Promise<void> {
+  try {
+    const front = getFrontSdkClient()
+    const teammate = await front.teammates.get(id)
+
+    if (options.json) {
+      console.log(JSON.stringify(teammate, null, 2))
+      return
+    }
+
+    console.log('\n👤 Teammate Details:')
+    console.log(`   ID:        ${teammate.id}`)
+    console.log(`   Email:     ${teammate.email}`)
+    if (teammate.first_name || teammate.last_name) {
+      console.log(
+        `   Name:      ${teammate.first_name || ''} ${teammate.last_name || ''}`.trim()
+      )
+    }
+    if (teammate.username) {
+      console.log(`   Username:  ${teammate.username}`)
+    }
+    console.log(`   Available: ${teammate.is_available ? 'Yes' : 'No'}`)
+    console.log('')
+  } catch (error) {
+    console.error(
+      'Error:',
+      error instanceof Error ? error.message : 'Unknown error'
+    )
+    process.exit(1)
+  }
+}
+
+/**
+ * Register Front commands with Commander
+ */
+export function registerFrontCommands(program: Command): void {
+  const front = program
+    .command('front')
+    .description('Front API commands for debugging')
+
+  front
+    .command('message')
+    .description('Get message details from Front API')
+    .argument('<id>', 'Message ID (e.g., msg_xxx)')
+    .option('--json', 'Output as JSON')
+    .action(getMessage)
+
+  front
+    .command('conversation')
+    .description('Get conversation details from Front API')
+    .argument('<id>', 'Conversation ID (e.g., cnv_xxx)')
+    .option('--json', 'Output as JSON')
+    .option('-m, --messages', 'Include message history')
+    .action(getConversation)
+
+  front
+    .command('teammates')
+    .description('List all teammates in the workspace')
+    .option('--json', 'Output as JSON')
+    .action(listTeammates)
+
+  front
+    .command('teammate')
+    .description('Get teammate details by ID')
+    .argument('<id>', 'Teammate ID (e.g., tea_xxx or username)')
+    .option('--json', 'Output as JSON')
+    .action(getTeammate)
+
+  // Register pull command for building eval datasets
+  registerPullCommand(front)
+
+  // Register tag management commands
+  registerTagCommands(front)
+
+  // Register cache command for DuckDB sync
+  registerCacheCommand(front)
+}

package/src/commands/front/pull-conversations.ts

@@ -0,0 +1,275 @@
+/**
+ * Pull conversations from Front for eval dataset
+ *
+ * Usage:
+ *   skill front pull --inbox <inbox_id> --limit 100 --output data/front-conversations.json
+ */
+
+import { writeFileSync } from 'fs'
+import { createInstrumentedFrontClient } from '@skillrecordings/core/front/instrumented-client'
+import type { Command } from 'commander'
+
+interface PullOptions {
+  inbox?: string
+  limit?: number
+  output?: string
+  filter?: string
+  json?: boolean
+}
+
+interface FrontConversation {
+  id: string
+  subject: string
+  status: string
+  created_at: number
+  last_message_at?: number
+  tags: Array<{ id: string; name: string }>
+  recipient?: { handle: string; name?: string }
+  assignee?: { email: string }
+}
+
+interface FrontMessage {
+  id: string
+  type: string
+  is_inbound: boolean
+  created_at: number
+  subject?: string
+  body?: string
+  text?: string
+  author?: { email?: string; name?: string }
+}
+
+interface EvalSample {
+  id: string
+  conversationId: string
+  subject: string
+  customerEmail: string
+  status: string
+  tags: string[]
+  triggerMessage: {
+    id: string
+    subject: string
+    body: string
+    timestamp: number
+  }
+  conversationHistory: Array<{
+    direction: 'in' | 'out'
+    body: string
+    timestamp: number
+    author?: string
+  }>
+  category: string // inferred from tags/content
+}
+
+export async function pullConversations(options: PullOptions): Promise<void> {
+  const { inbox, limit = 50, output, filter, json = false } = options
+
+  const frontToken = process.env.FRONT_API_TOKEN
+  if (!frontToken) {
+    console.error('Error: FRONT_API_TOKEN environment variable required')
+    process.exit(1)
+  }
+
+  const front = createInstrumentedFrontClient({ apiToken: frontToken })
+
+  try {
+    // If no inbox specified, list available inboxes
+    if (!inbox) {
+      console.log('Fetching available inboxes...\n')
+      const inboxesData = (await front.raw.get('/inboxes')) as {
+        _results: Array<{ id: string; name: string; address?: string }>
+      }
+
+      console.log('Available inboxes:')
+      for (const ib of inboxesData._results || []) {
+        console.log(`  ${ib.id}: ${ib.name} (${ib.address || 'no address'})`)
+      }
+      console.log(
+        '\nUse --inbox <id> to pull conversations from a specific inbox'
+      )
+      return
+    }
+
+    console.log(`Pulling conversations from inbox ${inbox}...`)
+
+    // Get conversations from inbox
+    let allConversations: FrontConversation[] = []
+    let nextUrl: string | null = `/inboxes/${inbox}/conversations?limit=50`
+
+    while (nextUrl && allConversations.length < limit) {
+      const data = (await front.raw.get(nextUrl)) as {
+        _results: FrontConversation[]
+        _pagination?: { next?: string }
+      }
+
+      allConversations = allConversations.concat(data._results || [])
+      nextUrl = data._pagination?.next || null
+
+      process.stdout.write(
+        `\r  Fetched ${allConversations.length} conversations...`
+      )
+    }
+
+    allConversations = allConversations.slice(0, limit)
+    console.log(`\n  Total: ${allConversations.length} conversations`)
+
+    // Filter if specified
+    if (filter) {
+      const filterLower = filter.toLowerCase()
+      allConversations = allConversations.filter((c) => {
+        const subject = (c.subject || '').toLowerCase()
+        const tags = c.tags.map((t) => t.name.toLowerCase()).join(' ')
+        return subject.includes(filterLower) || tags.includes(filterLower)
+      })
+      console.log(
+        `  After filter "${filter}": ${allConversations.length} conversations`
+      )
+    }
+
+    // Build eval samples
+    console.log('\nFetching message details...')
+    const samples: EvalSample[] = []
+    let processed = 0
+
+    for (const conv of allConversations) {
+      processed++
+      process.stdout.write(
+        `\r  Processing ${processed}/${allConversations.length}...`
+      )
+
+      try {
+        // Get messages for this conversation
+        const messagesData = (await front.raw.get(
+          `/conversations/${conv.id}/messages`
+        )) as { _results: FrontMessage[] }
+        const messages = messagesData._results || []
+
+        // Find the most recent inbound message as trigger
+        const inboundMessages = messages
+          .filter((m) => m.is_inbound)
+          .sort((a, b) => b.created_at - a.created_at)
+
+        const triggerMessage = inboundMessages[0]
+        if (!triggerMessage) continue // Skip if no inbound messages
+
+        // Extract body text
+        const bodyText =
+          triggerMessage.text ||
+          triggerMessage.body
+            ?.replace(/<[^>]*>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim() ||
+          ''
+
+        // Skip very short messages
+        if (bodyText.length < 20) continue
+
+        // Build conversation history
+        const history = messages
+          .sort((a, b) => a.created_at - b.created_at)
+          .map((m) => ({
+            direction: (m.is_inbound ? 'in' : 'out') as 'in' | 'out',
+            body:
+              m.text ||
+              m.body
+                ?.replace(/<[^>]*>/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim() ||
+              '',
+            timestamp: m.created_at,
+            author: m.author?.email,
+          }))
+
+        // Infer category from tags/subject
+        const tagNames = conv.tags.map((t) => t.name.toLowerCase()).join(' ')
+        const subject = (conv.subject || '').toLowerCase()
+        let category = 'general'
+
+        if (tagNames.includes('refund') || subject.includes('refund'))
+          category = 'refund'
+        else if (
+          tagNames.includes('access') ||
+          subject.includes('login') ||
+          subject.includes('access')
+        )
+          category = 'access'
+        else if (
+          tagNames.includes('technical') ||
+          subject.includes('error') ||
+          subject.includes('bug')
+        )
+          category = 'technical'
+        else if (subject.includes('feedback') || subject.includes('suggestion'))
+          category = 'feedback'
+        else if (
+          subject.includes('partnership') ||
+          subject.includes('collaborate')
+        )
+          category = 'business'
+
+        samples.push({
+          id: conv.id,
+          conversationId: conv.id,
+          subject: conv.subject || '(no subject)',
+          customerEmail: conv.recipient?.handle || 'unknown',
+          status: conv.status,
+          tags: conv.tags.map((t) => t.name),
+          triggerMessage: {
+            id: triggerMessage.id,
+            subject: triggerMessage.subject || conv.subject || '',
+            body: bodyText,
+            timestamp: triggerMessage.created_at,
+          },
+          conversationHistory: history,
+          category,
+        })
+
+        // Rate limit
+        await new Promise((r) => setTimeout(r, 100))
+      } catch (err) {
+        // Skip failed conversations
+        continue
+      }
+    }
+
+    console.log(`\n\nBuilt ${samples.length} eval samples`)
+
+    // Category breakdown
+    const byCategory: Record<string, number> = {}
+    for (const s of samples) {
+      byCategory[s.category] = (byCategory[s.category] || 0) + 1
+    }
+    console.log('\nBy category:')
+    for (const [cat, count] of Object.entries(byCategory).sort(
+      (a, b) => b[1] - a[1]
+    )) {
+      console.log(`  ${cat}: ${count}`)
+    }
+
+    // Output
+    if (output) {
+      writeFileSync(output, JSON.stringify(samples, null, 2))
+      console.log(`\nSaved to ${output}`)
+    } else if (json) {
+      console.log(JSON.stringify(samples, null, 2))
+    }
+  } catch (error) {
+    console.error(
+      '\nError:',
+      error instanceof Error ? error.message : 'Unknown error'
+    )
+    process.exit(1)
+  }
+}
+
+export function registerPullCommand(parent: Command): void {
+  parent
+    .command('pull')
+    .description('Pull conversations from Front for eval dataset')
+    .option('-i, --inbox <id>', 'Inbox ID to pull from')
+    .option('-l, --limit <n>', 'Max conversations to pull', parseInt)
+    .option('-o, --output <file>', 'Output file path')
+    .option('-f, --filter <term>', 'Filter by subject/tag containing term')
+    .option('--json', 'JSON output')
+    .action(pullConversations)
+}