luca 2.0.0 → 3.0.0

package/docs/apis/features/node/google-calendar.md

@@ -0,0 +1,202 @@
+# GoogleCalendar (features.googleCalendar)
+
+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.
+
+## Usage
+
+```ts
+container.feature('googleCalendar', {
+  // An authorized instance of the googleAuth feature
+  auth,
+  // Default calendar ID (default: "primary")
+  defaultCalendarId,
+  // Default timezone for event queries (e.g. "America/Chicago")
+  timeZone,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+| `defaultCalendarId` | `string` | Default calendar ID (default: "primary") |
+| `timeZone` | `string` | Default timezone for event queries (e.g. "America/Chicago") |
+
+## Methods
+
+### listCalendars
+
+List all calendars accessible to the authenticated user.
+
+**Returns:** `Promise<CalendarInfo[]>`
+
+
+
+### listEvents
+
+List events from a calendar within a time range.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `ListEventsOptions` |  | Filtering options including timeMin, timeMax, query, maxResults |
+
+`ListEventsOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `calendarId` | `string` |  |
+| `timeMin` | `string` |  |
+| `timeMax` | `string` |  |
+| `maxResults` | `number` |  |
+| `query` | `string` |  |
+| `orderBy` | `'startTime' | 'updated'` |  |
+| `pageToken` | `string` |  |
+| `singleEvents` | `boolean` |  |
+
+**Returns:** `Promise<CalendarEventList>`
+
+
+
+### getToday
+
+Get today's events from a calendar.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `calendarId` | `string` |  | Calendar ID (defaults to options.defaultCalendarId or 'primary') |
+
+**Returns:** `Promise<CalendarEvent[]>`
+
+
+
+### getUpcoming
+
+Get upcoming events for the next N days.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `days` | `number` |  | Number of days to look ahead (default: 7) |
+| `calendarId` | `string` |  | Calendar ID |
+
+**Returns:** `Promise<CalendarEvent[]>`
+
+
+
+### getEvent
+
+Get a single event by ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `eventId` | `string` | ✓ | The event ID |
+| `calendarId` | `string` |  | Calendar ID |
+
+**Returns:** `Promise<CalendarEvent>`
+
+
+
+### searchEvents
+
+Search events by text query across event summaries, descriptions, and locations.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Freetext search term |
+| `options` | `ListEventsOptions` |  | Additional listing options (timeMin, timeMax, calendarId, etc.) |
+
+`ListEventsOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `calendarId` | `string` |  |
+| `timeMin` | `string` |  |
+| `timeMax` | `string` |  |
+| `maxResults` | `number` |  |
+| `query` | `string` |  |
+| `orderBy` | `'startTime' | 'updated'` |  |
+| `pageToken` | `string` |  |
+| `singleEvents` | `boolean` |  |
+
+**Returns:** `Promise<CalendarEvent[]>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+| `defaultCalendarId` | `string` | Default calendar ID from options or 'primary'. |
+
+## Events (Zod v4 schema)
+
+### error
+
+Calendar API error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### eventsFetched
+
+Events were fetched from Calendar
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Number of events returned |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastCalendarId` | `string` | Last calendar ID queried |
+| `lastEventCount` | `number` | Number of events returned in last query |
+| `lastError` | `string` | Last Calendar API error message |
+
+## Examples
+
+**features.googleCalendar**
+
+```ts
+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',
+})
+```
+

package/docs/apis/features/node/google-docs.md

@@ -0,0 +1,173 @@
+# GoogleDocs (features.googleDocs)
+
+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.
+
+## Usage
+
+```ts
+container.feature('googleDocs', {
+  // An authorized instance of the googleAuth feature
+  auth,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+
+## Methods
+
+### getDocument
+
+Get the raw document structure from the Docs API.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `documentId` | `string` | ✓ | The Google Docs document ID |
+
+**Returns:** `Promise<docs_v1.Schema$Document>`
+
+
+
+### getAsMarkdown
+
+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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `documentId` | `string` | ✓ | The Google Docs document ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### getAsText
+
+Read a Google Doc as plain text (strips all formatting).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `documentId` | `string` | ✓ | The Google Docs document ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### saveAsMarkdown
+
+Download a Google Doc as Markdown and save to a local file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `documentId` | `string` | ✓ | The Google Docs document ID |
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+
+**Returns:** `Promise<string>`
+
+
+
+### listDocs
+
+List Google Docs in Drive (filters by Docs MIME type).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` |  | Optional additional Drive search query |
+| `options` | `{ pageSize?: number; pageToken?: string }` |  | Pagination options |
+
+**Returns:** `Promise<DriveFile[]>`
+
+
+
+### searchDocs
+
+Search for Google Docs by name or content.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `term` | `string` | ✓ | Search term |
+
+**Returns:** `Promise<DriveFile[]>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+| `drive` | `GoogleDrive` | Access the google-drive feature lazily. |
+
+## Events (Zod v4 schema)
+
+### documentFetched
+
+A document was fetched
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Document ID |
+| `arg1` | `string` | Title |
+
+
+
+### error
+
+Docs API error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastDocId` | `string` | Last document ID accessed |
+| `lastDocTitle` | `string` | Title of the last document accessed |
+| `lastError` | `string` | Last Docs API error message |
+
+## Examples
+
+**features.googleDocs**
+
+```ts
+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')
+```
+

package/docs/apis/features/node/google-drive.md

@@ -0,0 +1,246 @@
+# GoogleDrive (features.googleDrive)
+
+Google Drive feature for listing, searching, browsing, and downloading files. Depends on the googleAuth feature for authentication. Creates a Drive v3 API client lazily and passes the auth client from googleAuth.
+
+## Usage
+
+```ts
+container.feature('googleDrive', {
+  // An authorized instance of the googleAuth feature
+  auth,
+  // Default corpus for file queries (default: user)
+  defaultCorpora,
+  // Default number of results per page (default: 100)
+  pageSize,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+| `defaultCorpora` | `string` | Default corpus for file queries (default: user) |
+| `pageSize` | `number` | Default number of results per page (default: 100) |
+
+## Methods
+
+### listFiles
+
+List files in the user's Drive with an optional query filter.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` |  | Drive search query (e.g. "name contains 'report'", "mimeType='application/pdf'") |
+| `options` | `ListFilesOptions` |  | Pagination and filtering options |
+
+`ListFilesOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pageSize` | `number` |  |
+| `pageToken` | `string` |  |
+| `orderBy` | `string` |  |
+| `fields` | `string` |  |
+| `corpora` | `'user' | 'drive' | 'allDrives'` |  |
+
+**Returns:** `Promise<DriveFileList>`
+
+
+
+### listFolder
+
+List files within a specific folder.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `folderId` | `string` | ✓ | The Drive folder ID |
+| `options` | `ListFilesOptions` |  | Pagination and filtering options |
+
+`ListFilesOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pageSize` | `number` |  |
+| `pageToken` | `string` |  |
+| `orderBy` | `string` |  |
+| `fields` | `string` |  |
+| `corpora` | `'user' | 'drive' | 'allDrives'` |  |
+
+**Returns:** `Promise<DriveFileList>`
+
+
+
+### browse
+
+Browse a folder's contents, separating files from subfolders.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `folderId` | `string` |  | Folder ID to browse (defaults to 'root') |
+
+**Returns:** `Promise<DriveBrowseResult>`
+
+
+
+### search
+
+Search files by name, content, or MIME type.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `term` | `string` | ✓ | Search term to look for in file names and content |
+| `options` | `SearchOptions` |  | Additional search options like mimeType filter or folder restriction |
+
+**Returns:** `Promise<DriveFileList>`
+
+
+
+### getFile
+
+Get file metadata by file ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `fileId` | `string` | ✓ | The Drive file ID |
+| `fields` | `string` |  | Specific fields to request (defaults to common fields) |
+
+**Returns:** `Promise<DriveFile>`
+
+
+
+### download
+
+Download a file's content as a Buffer. Uses alt=media for binary download of non-Google files.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `fileId` | `string` | ✓ | The Drive file ID |
+
+**Returns:** `Promise<Buffer>`
+
+
+
+### downloadTo
+
+Download a file and save it to a local path.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `fileId` | `string` | ✓ | The Drive file ID |
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+
+**Returns:** `Promise<string>`
+
+
+
+### exportFile
+
+Export a Google Workspace file (Docs, Sheets, Slides) to a given MIME type. Uses the Files.export endpoint.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `fileId` | `string` | ✓ | The Drive file ID of a Google Workspace document |
+| `mimeType` | `string` | ✓ | Target MIME type (e.g. 'text/plain', 'application/pdf', 'text/csv') |
+
+**Returns:** `Promise<Buffer>`
+
+
+
+### listDrives
+
+List all shared drives the user has access to.
+
+**Returns:** `Promise<SharedDrive[]>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+
+## Events (Zod v4 schema)
+
+### filesFetched
+
+Files were fetched from Drive
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Number of files returned |
+
+
+
+### error
+
+Drive API error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### fileDownloaded
+
+A file was downloaded
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | File ID |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastQuery` | `string` | Last search query or folder ID browsed |
+| `lastResultCount` | `number` | Number of results from last list/search operation |
+| `lastError` | `string` | Last Drive API error message |
+
+## Examples
+
+**features.googleDrive**
+
+```ts
+const drive = container.feature('googleDrive')
+
+// List recent files
+const { files } = await drive.listFiles()
+
+// Search for documents
+const { files: docs } = await drive.search('quarterly report', { mimeType: 'application/pdf' })
+
+// Browse a folder
+const contents = await drive.browse('folder-id-here')
+
+// Download a file to disk
+await drive.downloadTo('file-id', './downloads/report.pdf')
+```
+