@soederpop/luca 0.0.2

package/src/node/features/google-calendar.ts

@@ -0,0 +1,300 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature, features } from '../feature.js'
+import { google, type calendar_v3 } from 'googleapis'
+import type { GoogleAuth } from './google-auth.js'
+
+export type CalendarInfo = {
+  id: string
+  summary: string
+  description?: string
+  timeZone: string
+  primary?: boolean
+  backgroundColor?: string
+  accessRole: string
+}
+
+export type CalendarEvent = {
+  id: string
+  summary: string
+  description?: string
+  location?: string
+  start: { dateTime?: string; date?: string; timeZone?: string }
+  end: { dateTime?: string; date?: string; timeZone?: string }
+  status: string
+  htmlLink: string
+  creator?: { email?: string; displayName?: string }
+  organizer?: { email?: string; displayName?: string }
+  attendees?: Array<{ email?: string; displayName?: string; responseStatus?: string }>
+  recurrence?: string[]
+}
+
+export type CalendarEventList = {
+  events: CalendarEvent[]
+  nextPageToken?: string
+  timeZone?: string
+}
+
+export type ListEventsOptions = {
+  calendarId?: string
+  timeMin?: string
+  timeMax?: string
+  maxResults?: number
+  query?: string
+  orderBy?: 'startTime' | 'updated'
+  pageToken?: string
+  singleEvents?: boolean
+}
+
+export const GoogleCalendarStateSchema = FeatureStateSchema.extend({
+  lastCalendarId: z.string().optional()
+    .describe('Last calendar ID queried'),
+  lastEventCount: z.number().optional()
+    .describe('Number of events returned in last query'),
+  lastError: z.string().optional()
+    .describe('Last Calendar API error message'),
+})
+export type GoogleCalendarState = z.infer<typeof GoogleCalendarStateSchema>
+
+export const GoogleCalendarOptionsSchema = FeatureOptionsSchema.extend({
+  defaultCalendarId: z.string().optional()
+    .describe('Default calendar ID (default: "primary")'),
+  timeZone: z.string().optional()
+    .describe('Default timezone for event queries (e.g. "America/Chicago")'),
+})
+export type GoogleCalendarOptions = z.infer<typeof GoogleCalendarOptionsSchema>
+
+export const GoogleCalendarEventsSchema = FeatureEventsSchema.extend({
+  eventsFetched: z.tuple([z.number().describe('Number of events returned')])
+    .describe('Events were fetched from Calendar'),
+  error: z.tuple([z.any().describe('The error')]).describe('Calendar API error occurred'),
+})
+
+/**
+ * Google Calendar feature for listing calendars and reading events.
+ *
+ * Depends on the googleAuth feature for authentication. Creates a Calendar v3 API
+ * client lazily. Provides convenience methods for today's events and upcoming days.
+ *
+ * @example
+ * ```typescript
+ * const calendar = container.feature('googleCalendar')
+ *
+ * // List all calendars
+ * const calendars = await calendar.listCalendars()
+ *
+ * // Get today's events
+ * const today = await calendar.getToday()
+ *
+ * // Get next 7 days of events
+ * const upcoming = await calendar.getUpcoming(7)
+ *
+ * // Search events
+ * const meetings = await calendar.searchEvents('standup')
+ *
+ * // List events in a time range
+ * const events = await calendar.listEvents({
+ *   timeMin: '2026-03-01T00:00:00Z',
+ *   timeMax: '2026-03-31T23:59:59Z',
+ * })
+ * ```
+ */
+export class GoogleCalendar extends Feature<GoogleCalendarState, GoogleCalendarOptions> {
+  static override shortcut = 'features.googleCalendar' as const
+  static override stateSchema = GoogleCalendarStateSchema
+  static override optionsSchema = GoogleCalendarOptionsSchema
+  static override eventsSchema = GoogleCalendarEventsSchema
+
+  private _calendar?: calendar_v3.Calendar
+
+  override get initialState(): GoogleCalendarState {
+    return { ...super.initialState }
+  }
+
+  /** Access the google-auth feature lazily. */
+  get auth(): GoogleAuth {
+    return this.container.feature('googleAuth') as unknown as GoogleAuth
+  }
+
+  /** Default calendar ID from options or 'primary'. */
+  get defaultCalendarId(): string {
+    return this.options.defaultCalendarId || 'primary'
+  }
+
+  /** Get or create the Calendar v3 API client. */
+  private async getCalendar(): Promise<calendar_v3.Calendar> {
+    if (this._calendar) return this._calendar
+    const auth = await this.auth.getAuthClient()
+    this._calendar = google.calendar({ version: 'v3', auth: auth as any })
+    return this._calendar
+  }
+
+  /**
+   * List all calendars accessible to the authenticated user.
+   *
+   * @returns Array of calendar info objects
+   */
+  async listCalendars(): Promise<CalendarInfo[]> {
+    try {
+      const cal = await this.getCalendar()
+      const res = await cal.calendarList.list({ maxResults: 250 })
+      return (res.data.items || []).map(c => ({
+        id: c.id || '',
+        summary: c.summary || '',
+        description: c.description || undefined,
+        timeZone: c.timeZone || '',
+        primary: c.primary || undefined,
+        backgroundColor: c.backgroundColor || undefined,
+        accessRole: c.accessRole || '',
+      }))
+    } catch (err: any) {
+      this.setState({ lastError: err.message })
+      this.emit('error', err)
+      throw err
+    }
+  }
+
+  /**
+   * List events from a calendar within a time range.
+   *
+   * @param options - Filtering options including timeMin, timeMax, query, maxResults
+   * @returns Events array with optional nextPageToken and timeZone
+   */
+  async listEvents(options: ListEventsOptions = {}): Promise<CalendarEventList> {
+    const calendarId = options.calendarId || this.defaultCalendarId
+    try {
+      const cal = await this.getCalendar()
+      const res = await cal.events.list({
+        calendarId,
+        timeMin: options.timeMin || undefined,
+        timeMax: options.timeMax || undefined,
+        maxResults: options.maxResults || 250,
+        q: options.query || undefined,
+        orderBy: options.orderBy || 'startTime',
+        pageToken: options.pageToken || undefined,
+        singleEvents: options.singleEvents !== false,
+        timeZone: this.options.timeZone || undefined,
+      })
+
+      const events = (res.data.items || []).map(normalizeEvent)
+      this.setState({ lastCalendarId: calendarId, lastEventCount: events.length })
+      this.emit('eventsFetched', events.length)
+      return {
+        events,
+        nextPageToken: res.data.nextPageToken || undefined,
+        timeZone: res.data.timeZone || undefined,
+      }
+    } catch (err: any) {
+      this.setState({ lastError: err.message })
+      this.emit('error', err)
+      throw err
+    }
+  }
+
+  /**
+   * Get today's events from a calendar.
+   *
+   * @param calendarId - Calendar ID (defaults to options.defaultCalendarId or 'primary')
+   * @returns Array of today's calendar events
+   */
+  async getToday(calendarId?: string): Promise<CalendarEvent[]> {
+    const now = new Date()
+    const startOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+    const endOfDay = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1)
+
+    const { events } = await this.listEvents({
+      calendarId,
+      timeMin: startOfDay.toISOString(),
+      timeMax: endOfDay.toISOString(),
+    })
+    return events
+  }
+
+  /**
+   * Get upcoming events for the next N days.
+   *
+   * @param days - Number of days to look ahead (default: 7)
+   * @param calendarId - Calendar ID
+   * @returns Array of upcoming calendar events
+   */
+  async getUpcoming(days: number = 7, calendarId?: string): Promise<CalendarEvent[]> {
+    const now = new Date()
+    const future = new Date(now.getTime() + days * 24 * 60 * 60 * 1000)
+
+    const { events } = await this.listEvents({
+      calendarId,
+      timeMin: now.toISOString(),
+      timeMax: future.toISOString(),
+    })
+    return events
+  }
+
+  /**
+   * Get a single event by ID.
+   *
+   * @param eventId - The event ID
+   * @param calendarId - Calendar ID
+   * @returns The calendar event
+   */
+  async getEvent(eventId: string, calendarId?: string): Promise<CalendarEvent> {
+    const cid = calendarId || this.defaultCalendarId
+    try {
+      const cal = await this.getCalendar()
+      const res = await cal.events.get({ calendarId: cid, eventId })
+      return normalizeEvent(res.data)
+    } catch (err: any) {
+      this.setState({ lastError: err.message })
+      this.emit('error', err)
+      throw err
+    }
+  }
+
+  /**
+   * Search events by text query across event summaries, descriptions, and locations.
+   *
+   * @param query - Freetext search term
+   * @param options - Additional listing options (timeMin, timeMax, calendarId, etc.)
+   * @returns Array of matching calendar events
+   */
+  async searchEvents(query: string, options: ListEventsOptions = {}): Promise<CalendarEvent[]> {
+    const { events } = await this.listEvents({ ...options, query })
+    return events
+  }
+}
+
+function normalizeEvent(e: calendar_v3.Schema$Event): CalendarEvent {
+  return {
+    id: e.id || '',
+    summary: e.summary || '',
+    description: e.description || undefined,
+    location: e.location || undefined,
+    start: {
+      dateTime: e.start?.dateTime || undefined,
+      date: e.start?.date || undefined,
+      timeZone: e.start?.timeZone || undefined,
+    },
+    end: {
+      dateTime: e.end?.dateTime || undefined,
+      date: e.end?.date || undefined,
+      timeZone: e.end?.timeZone || undefined,
+    },
+    status: e.status || '',
+    htmlLink: e.htmlLink || '',
+    creator: e.creator ? { email: e.creator.email || undefined, displayName: e.creator.displayName || undefined } : undefined,
+    organizer: e.organizer ? { email: e.organizer.email || undefined, displayName: e.organizer.displayName || undefined } : undefined,
+    attendees: e.attendees?.map(a => ({
+      email: a.email || undefined,
+      displayName: a.displayName || undefined,
+      responseStatus: a.responseStatus || undefined,
+    })) || undefined,
+    recurrence: e.recurrence || undefined,
+  }
+}
+
+declare module '../../feature' {
+  interface AvailableFeatures {
+    googleCalendar: typeof GoogleCalendar
+  }
+}
+
+export default features.register('googleCalendar', GoogleCalendar)

package/src/node/features/google-docs.ts

@@ -0,0 +1,404 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature, features } from '../feature.js'
+import { google, type docs_v1 } from 'googleapis'
+import type { GoogleAuth } from './google-auth.js'
+import type { GoogleDrive, DriveFile } from './google-drive.js'
+
+export const GoogleDocsStateSchema = FeatureStateSchema.extend({
+  lastDocId: z.string().optional()
+    .describe('Last document ID accessed'),
+  lastDocTitle: z.string().optional()
+    .describe('Title of the last document accessed'),
+  lastError: z.string().optional()
+    .describe('Last Docs API error message'),
+})
+export type GoogleDocsState = z.infer<typeof GoogleDocsStateSchema>
+
+export const GoogleDocsOptionsSchema = FeatureOptionsSchema.extend({})
+export type GoogleDocsOptions = z.infer<typeof GoogleDocsOptionsSchema>
+
+export const GoogleDocsEventsSchema = FeatureEventsSchema.extend({
+  documentFetched: z.tuple([z.string().describe('Document ID'), z.string().describe('Title')])
+    .describe('A document was fetched'),
+  error: z.tuple([z.any().describe('The error')]).describe('Docs API error occurred'),
+})
+
+/**
+ * Google Docs feature for reading documents and converting them to Markdown.
+ *
+ * Depends on googleAuth for authentication and optionally googleDrive for listing docs.
+ * The markdown converter handles headings, text formatting, links, lists, tables, and images.
+ *
+ * @example
+ * ```typescript
+ * const docs = container.feature('googleDocs')
+ *
+ * // Get a doc as markdown
+ * const markdown = await docs.getAsMarkdown('1abc_document_id')
+ *
+ * // Save to file
+ * await docs.saveAsMarkdown('1abc_document_id', './output/doc.md')
+ *
+ * // List all Google Docs in Drive
+ * const allDocs = await docs.listDocs()
+ *
+ * // Get raw document structure
+ * const rawDoc = await docs.getDocument('1abc_document_id')
+ *
+ * // Plain text extraction
+ * const text = await docs.getAsText('1abc_document_id')
+ * ```
+ */
+export class GoogleDocs extends Feature<GoogleDocsState, GoogleDocsOptions> {
+  static override shortcut = 'features.googleDocs' as const
+  static override stateSchema = GoogleDocsStateSchema
+  static override optionsSchema = GoogleDocsOptionsSchema
+  static override eventsSchema = GoogleDocsEventsSchema
+
+  private _docs?: docs_v1.Docs
+
+  override get initialState(): GoogleDocsState {
+    return { ...super.initialState }
+  }
+
+  /** Access the google-auth feature lazily. */
+  get auth(): GoogleAuth {
+    return this.container.feature('googleAuth') as unknown as GoogleAuth
+  }
+
+  /** Access the google-drive feature lazily. */
+  get drive(): GoogleDrive {
+    return this.container.feature('googleDrive') as unknown as GoogleDrive
+  }
+
+  /** Get or create the Docs v1 API client. */
+  private async getDocs(): Promise<docs_v1.Docs> {
+    if (this._docs) return this._docs
+    const auth = await this.auth.getAuthClient()
+    this._docs = google.docs({ version: 'v1', auth: auth as any })
+    return this._docs
+  }
+
+  /**
+   * Get the raw document structure from the Docs API.
+   *
+   * @param documentId - The Google Docs document ID
+   * @returns Full document JSON including body, lists, inlineObjects, etc.
+   */
+  async getDocument(documentId: string): Promise<docs_v1.Schema$Document> {
+    try {
+      const docs = await this.getDocs()
+      const res = await docs.documents.get({ documentId })
+      const doc = res.data
+
+      this.setState({
+        lastDocId: documentId,
+        lastDocTitle: doc.title || undefined,
+      })
+      this.emit('documentFetched', documentId, doc.title || '')
+      return doc
+    } catch (err: any) {
+      this.setState({ lastError: err.message })
+      this.emit('error', err)
+      throw err
+    }
+  }
+
+  /**
+   * Read a Google Doc and convert it to Markdown.
+   *
+   * Handles headings, bold/italic/strikethrough, links, code fonts, ordered/unordered
+   * lists with nesting, tables, images, and section breaks.
+   *
+   * @param documentId - The Google Docs document ID
+   * @returns Markdown string representation of the document
+   */
+  async getAsMarkdown(documentId: string): Promise<string> {
+    const doc = await this.getDocument(documentId)
+    return convertDocToMarkdown(doc)
+  }
+
+  /**
+   * Read a Google Doc as plain text (strips all formatting).
+   *
+   * @param documentId - The Google Docs document ID
+   */
+  async getAsText(documentId: string): Promise<string> {
+    const doc = await this.getDocument(documentId)
+    return extractPlainText(doc)
+  }
+
+  /**
+   * Download a Google Doc as Markdown and save to a local file.
+   *
+   * @param documentId - The Google Docs document ID
+   * @param localPath - Local file path (resolved relative to container cwd)
+   * @returns Absolute path of the saved file
+   */
+  async saveAsMarkdown(documentId: string, localPath: string): Promise<string> {
+    const markdown = await this.getAsMarkdown(documentId)
+    const outPath = this.container.paths.resolve(localPath)
+    await this.container.fs.writeFileAsync(outPath, markdown)
+    return outPath
+  }
+
+  /**
+   * List Google Docs in Drive (filters by Docs MIME type).
+   *
+   * @param query - Optional additional Drive search query
+   * @param options - Pagination options
+   * @returns Array of Google Docs as DriveFile objects
+   */
+  async listDocs(query?: string, options?: { pageSize?: number; pageToken?: string }): Promise<DriveFile[]> {
+    const parts = ["mimeType = 'application/vnd.google-apps.document'", 'trashed = false']
+    if (query) parts.push(`name contains '${query.replace(/'/g, "\\'")}'`)
+    const { files } = await this.drive.listFiles(parts.join(' and '), options)
+    return files
+  }
+
+  /**
+   * Search for Google Docs by name or content.
+   *
+   * @param term - Search term
+   * @returns Array of matching Google Docs as DriveFile objects
+   */
+  async searchDocs(term: string): Promise<DriveFile[]> {
+    const { files } = await this.drive.search(term, {
+      mimeType: 'application/vnd.google-apps.document',
+    })
+    return files
+  }
+}
+
+// ─── Markdown Converter ─────────────────────────────────────────────────────
+
+type ListInfo = {
+  ordered: boolean
+}
+
+/**
+ * Convert a Google Docs API document to Markdown.
+ */
+function convertDocToMarkdown(doc: docs_v1.Schema$Document): string {
+  const body = doc.body?.content || []
+  const lists = doc.lists || {}
+  const inlineObjects = doc.inlineObjects || {}
+  const lines: string[] = []
+
+  // Build list type lookup: listId + nestingLevel → ordered/unordered
+  const listLookup = new Map<string, ListInfo>()
+  for (const [listId, listDef] of Object.entries(lists)) {
+    const levels = listDef.listProperties?.nestingLevels || []
+    levels.forEach((level, i) => {
+      const glyphType = level.glyphType
+      // DECIMAL, ALPHA, ROMAN = ordered; everything else (bullet/none) = unordered
+      const ordered = glyphType === 'DECIMAL' || glyphType === 'ALPHA' || glyphType === 'UPPER_ALPHA'
+        || glyphType === 'ROMAN' || glyphType === 'UPPER_ROMAN'
+      listLookup.set(`${listId}:${i}`, { ordered })
+    })
+  }
+
+  for (const element of body) {
+    if (element.paragraph) {
+      const para = element.paragraph
+      const line = convertParagraph(para, listLookup, inlineObjects)
+      lines.push(line)
+    } else if (element.table) {
+      const tableLines = convertTable(element.table, listLookup, inlineObjects)
+      lines.push('', ...tableLines, '')
+    } else if (element.sectionBreak) {
+      lines.push('', '---', '')
+    }
+  }
+
+  // Clean up: collapse 3+ consecutive blank lines into 2
+  let result = lines.join('\n')
+  result = result.replace(/\n{3,}/g, '\n\n')
+  return result.trim() + '\n'
+}
+
+function convertParagraph(
+  para: docs_v1.Schema$Paragraph,
+  listLookup: Map<string, ListInfo>,
+  inlineObjects: Record<string, docs_v1.Schema$InlineObject>
+): string {
+  const style = para.paragraphStyle?.namedStyleType || 'NORMAL_TEXT'
+  const elements = para.elements || []
+  const bullet = para.bullet
+
+  // Build the inline text content
+  let text = ''
+  for (const el of elements) {
+    if (el.textRun) {
+      text += formatTextRun(el.textRun)
+    } else if (el.inlineObjectElement) {
+      const objId = el.inlineObjectElement.inlineObjectId
+      if (objId && inlineObjects[objId]) {
+        const obj = inlineObjects[objId]
+        const embedded = obj.inlineObjectProperties?.embeddedObject
+        const uri = embedded?.imageProperties?.contentUri || embedded?.imageProperties?.sourceUri || ''
+        const alt = embedded?.title || embedded?.description || 'image'
+        if (uri) {
+          text += `![${alt}](${uri})`
+        }
+      }
+    }
+  }
+
+  // Trim trailing newline that Google Docs adds to every paragraph
+  text = text.replace(/\n$/, '')
+
+  // If the paragraph is empty, return a blank line
+  if (!text.trim()) return ''
+
+  // Apply heading prefix
+  const headingMap: Record<string, string> = {
+    TITLE: '# ',
+    SUBTITLE: '## ',
+    HEADING_1: '# ',
+    HEADING_2: '## ',
+    HEADING_3: '### ',
+    HEADING_4: '#### ',
+    HEADING_5: '##### ',
+    HEADING_6: '###### ',
+  }
+
+  if (headingMap[style]) {
+    return `\n${headingMap[style]}${text}\n`
+  }
+
+  // Apply list prefix
+  if (bullet) {
+    const listId = bullet.listId || ''
+    const nestingLevel = bullet.nestingLevel || 0
+    const key = `${listId}:${nestingLevel}`
+    const info = listLookup.get(key)
+    const indent = '  '.repeat(nestingLevel)
+    const prefix = info?.ordered ? '1. ' : '- '
+    return `${indent}${prefix}${text}`
+  }
+
+  return text
+}
+
+function formatTextRun(run: docs_v1.Schema$TextRun): string {
+  let content = run.content || ''
+  const style = run.textStyle
+
+  if (!style || content === '\n') return content
+
+  // Don't format whitespace-only content
+  const trimmed = content.replace(/\n$/, '')
+  if (!trimmed.trim()) return content
+
+  // Detect code font (Courier variants)
+  const fontFamily = style.weightedFontFamily?.fontFamily || ''
+  const isCode = /courier/i.test(fontFamily) || /consolas/i.test(fontFamily) || /mono/i.test(fontFamily)
+
+  // Extract trailing newline to preserve it outside formatting
+  const trailingNewline = content.endsWith('\n') ? '\n' : ''
+  let formatted = content.replace(/\n$/, '')
+
+  if (isCode) {
+    formatted = `\`${formatted}\``
+  } else {
+    // Apply formatting — order matters: bold wraps italic wraps strikethrough
+    if (style.strikethrough) {
+      formatted = `~~${formatted}~~`
+    }
+    if (style.italic) {
+      formatted = `*${formatted}*`
+    }
+    if (style.bold) {
+      formatted = `**${formatted}**`
+    }
+  }
+
+  // Apply link
+  if (style.link?.url) {
+    formatted = `[${formatted}](${style.link.url})`
+  }
+
+  return formatted + trailingNewline
+}
+
+function convertTable(
+  table: docs_v1.Schema$Table,
+  listLookup: Map<string, ListInfo>,
+  inlineObjects: Record<string, docs_v1.Schema$InlineObject>
+): string[] {
+  const rows = table.tableRows || []
+  if (rows.length === 0) return []
+
+  const tableData: string[][] = rows.map(row => {
+    const cells = row.tableCells || []
+    return cells.map(cell => {
+      const content = cell.content || []
+      const cellText = content.map(el => {
+        if (el.paragraph) {
+          return convertParagraph(el.paragraph, listLookup, inlineObjects)
+        }
+        return ''
+      }).join(' ').trim()
+      // Escape pipes in cell content
+      return cellText.replace(/\|/g, '\\|')
+    })
+  })
+
+  if (tableData.length === 0) return []
+
+  const lines: string[] = []
+
+  const header = tableData[0]!
+  // Header row
+  lines.push('| ' + header.join(' | ') + ' |')
+  // Separator
+  lines.push('| ' + header.map(() => '---').join(' | ') + ' |')
+  // Data rows
+  for (let i = 1; i < tableData.length; i++) {
+    lines.push('| ' + tableData[i]!.join(' | ') + ' |')
+  }
+
+  return lines
+}
+
+/**
+ * Extract plain text from a Google Docs document, stripping all formatting.
+ */
+function extractPlainText(doc: docs_v1.Schema$Document): string {
+  const body = doc.body?.content || []
+  const parts: string[] = []
+
+  for (const element of body) {
+    if (element.paragraph) {
+      const text = (element.paragraph.elements || [])
+        .map(el => el.textRun?.content || '')
+        .join('')
+      parts.push(text)
+    } else if (element.table) {
+      const rows = element.table.tableRows || []
+      for (const row of rows) {
+        const cells = row.tableCells || []
+        const cellTexts = cells.map(cell => {
+          return (cell.content || []).map(el => {
+            return (el.paragraph?.elements || [])
+              .map(pe => pe.textRun?.content || '')
+              .join('')
+          }).join('')
+        })
+        parts.push(cellTexts.join('\t'))
+      }
+    }
+  }
+
+  return parts.join('').trim() + '\n'
+}
+
+declare module '../../feature' {
+  interface AvailableFeatures {
+    googleDocs: typeof GoogleDocs
+  }
+}
+
+export default features.register('googleDocs', GoogleDocs)