@soederpop/luca 0.0.2

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

@@ -0,0 +1,151 @@
+# 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')
+```
+
+## 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
+
+Event emitted by GoogleDocs
+
+
+
+### error
+
+Event emitted by GoogleDocs
+
+
+
+## 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,225 @@
+# 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', {
+  // Default corpus for file queries (default: user)
+  defaultCorpora,
+  // Default number of results per page (default: 100)
+  pageSize,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `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
+
+Event emitted by GoogleDrive
+
+
+
+### error
+
+Event emitted by GoogleDrive
+
+
+
+### fileDownloaded
+
+Event emitted by GoogleDrive
+
+
+
+## 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')
+```
+

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

@@ -0,0 +1,179 @@
+# GoogleSheets (features.googleSheets)
+
+Google Sheets feature for reading spreadsheet data as JSON, CSV, or raw arrays. Depends on the googleAuth feature for authentication. Creates a Sheets v4 API client lazily and provides convenient methods for reading tabular data.
+
+## Usage
+
+```ts
+container.feature('googleSheets', {
+  // Default spreadsheet ID for operations
+  defaultSpreadsheetId,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `defaultSpreadsheetId` | `string` | Default spreadsheet ID for operations |
+
+## Methods
+
+### getSpreadsheet
+
+Get spreadsheet metadata including title, locale, and sheet list.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `spreadsheetId` | `string` |  | The spreadsheet ID (defaults to options.defaultSpreadsheetId) |
+
+**Returns:** `Promise<SpreadsheetMeta>`
+
+
+
+### listSheets
+
+List all sheets (tabs) in a spreadsheet.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<SheetInfo[]>`
+
+
+
+### getRange
+
+Read a range of values from a sheet.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `range` | `string` | ✓ | A1 notation range (e.g. "Sheet1!A1:D10" or "Sheet1" for entire sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string[][]>`
+
+
+
+### getAsJson
+
+Read a sheet as an array of JSON objects. The first row is treated as headers; subsequent rows become objects keyed by those headers.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sheetName` | `string` |  | Name of the sheet tab (if omitted, reads the first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<T[]>`
+
+
+
+### getAsCsv
+
+Read a sheet and return it as a CSV string.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sheetName` | `string` |  | Name of the sheet tab (if omitted, reads the first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### saveAsJson
+
+Download sheet data as JSON and save to a local file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+| `sheetName` | `string` |  | Sheet tab name (defaults to first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### saveAsCsv
+
+Download sheet data as CSV and save to a local file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+| `sheetName` | `string` |  | Sheet tab name (defaults to first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+
+## Events (Zod v4 schema)
+
+### error
+
+Event emitted by GoogleSheets
+
+
+
+### dataFetched
+
+Event emitted by GoogleSheets
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastSpreadsheetId` | `string` | Last spreadsheet ID accessed |
+| `lastSheetName` | `string` | Last sheet/tab name accessed |
+| `lastRowCount` | `number` | Number of rows returned in last read |
+| `lastError` | `string` | Last Sheets API error message |
+
+## Examples
+
+**features.googleSheets**
+
+```ts
+const sheets = container.feature('googleSheets', {
+ defaultSpreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
+})
+
+// Read as JSON objects (first row = headers)
+const data = await sheets.getAsJson('Sheet1')
+// => [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+
+// Read as CSV string
+const csv = await sheets.getAsCsv('Revenue')
+
+// Read a specific range
+const values = await sheets.getRange('Sheet1!A1:D10')
+
+// Save to file
+await sheets.saveAsJson('./data/export.json')
+```
+