veryfront 0.0.49 → 0.0.50

package/dist/integrations/sheets/README.md

@@ -0,0 +1,331 @@
+# Google Sheets Integration for Veryfront
+
+A complete Google Sheets integration following the Notion integration pattern. Provides AI tools for reading, writing, and managing Google Sheets spreadsheets.
+
+## Features
+
+- **OAuth 2.0 Authentication** - Secure Google OAuth flow with token refresh
+- **Read Operations** - List spreadsheets, read metadata, and fetch cell data
+- **Write Operations** - Create spreadsheets, write data, and update ranges
+- **Type-Safe Client** - Fully typed TypeScript API client
+- **AI Tools** - Five AI tools for spreadsheet operations
+
+## Directory Structure
+
+```
+sheets/
+├── connector.json                           # Integration metadata and configuration
+└── files/
+    ├── _env.example                        # Environment variables template
+    ├── lib/
+    │   ├── oauth.ts                        # OAuth 2.0 helpers
+    │   ├── token-store.ts                  # Token storage (in-memory for dev)
+    │   └── sheets-client.ts                # Google Sheets API client
+    ├── app/api/auth/sheets/
+    │   ├── route.ts                        # OAuth initiation endpoint
+    │   └── callback/route.ts               # OAuth callback handler
+    └── ai/tools/
+        ├── list-spreadsheets.ts            # List recent spreadsheets
+        ├── get-spreadsheet.ts              # Get spreadsheet metadata
+        ├── read-range.ts                   # Read cell data from range
+        ├── write-range.ts                  # Write data to range
+        └── create-spreadsheet.ts           # Create new spreadsheet
+```
+
+## Setup Instructions
+
+### 1. Create Google OAuth Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create a new OAuth 2.0 Client ID (or use existing)
+3. Add authorized redirect URI: `http://localhost:3000/api/auth/sheets/callback`
+4. Copy Client ID and Client Secret
+
+### 2. Enable Required APIs
+
+Enable these APIs in your Google Cloud project:
+- [Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)
+- [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com)
+
+### 3. Configure Environment Variables
+
+```bash
+GOOGLE_CLIENT_ID=your_client_id_here
+GOOGLE_CLIENT_SECRET=your_client_secret_here
+```
+
+### 4. OAuth Scopes
+
+The integration requests these scopes:
+- `https://www.googleapis.com/auth/spreadsheets` - Full access to spreadsheets
+- `https://www.googleapis.com/auth/drive.readonly` - Read-only access to Drive (for listing)
+
+## API Client Usage
+
+### Create Client
+
+```typescript
+import { createSheetsClient } from "./lib/sheets-client.ts";
+
+const client = createSheetsClient("user-id");
+```
+
+### List Spreadsheets
+
+```typescript
+const spreadsheets = await client.listSpreadsheets({
+  maxResults: 20,
+  orderBy: "modifiedTime",
+});
+```
+
+### Get Spreadsheet Metadata
+
+```typescript
+const spreadsheet = await client.getSpreadsheet("spreadsheet-id");
+console.log(spreadsheet.properties.title);
+console.log(spreadsheet.sheets); // All sheet tabs
+```
+
+### Read Data
+
+```typescript
+// Read specific range
+const data = await client.readRange("spreadsheet-id", "Sheet1!A1:D10");
+console.log(data.values); // 2D array of cell values
+
+// Read entire sheet
+const allData = await client.readRange("spreadsheet-id", "Sheet1");
+```
+
+### Write Data
+
+```typescript
+await client.writeRange({
+  spreadsheetId: "spreadsheet-id",
+  range: "Sheet1!A1",
+  values: [
+    ["Name", "Age", "City"],
+    ["John", 30, "New York"],
+    ["Jane", 25, "Boston"],
+  ],
+  valueInputOption: "USER_ENTERED", // Parses formulas, numbers, dates
+});
+```
+
+### Create Spreadsheet
+
+```typescript
+const newSpreadsheet = await client.createSpreadsheet({
+  title: "My New Spreadsheet",
+  sheets: [
+    { title: "Data", rowCount: 1000, columnCount: 26 },
+    { title: "Summary", rowCount: 100, columnCount: 10 },
+  ],
+});
+```
+
+## AI Tools
+
+### 1. list-spreadsheets
+
+List recent Google Sheets from Drive.
+
+```typescript
+{
+  maxResults: 20,
+  orderBy: "modifiedTime" // or "createdTime", "name"
+}
+```
+
+### 2. get-spreadsheet
+
+Get spreadsheet metadata including all sheets and properties.
+
+```typescript
+{
+  spreadsheetId: "abc123..."
+}
+```
+
+### 3. read-range
+
+Read cell data from a range using A1 notation.
+
+```typescript
+{
+  spreadsheetId: "abc123...",
+  range: "Sheet1!A1:D10" // or "A1:B", or just "Sheet1"
+}
+```
+
+### 4. write-range
+
+Write data to a spreadsheet range.
+
+```typescript
+{
+  spreadsheetId: "abc123...",
+  range: "Sheet1!A1",
+  values: [["Header1", "Header2"], ["Value1", "Value2"]],
+  valueInputOption: "USER_ENTERED" // or "RAW"
+}
+```
+
+### 5. create-spreadsheet
+
+Create a new spreadsheet with optional initial data.
+
+```typescript
+{
+  title: "My Spreadsheet",
+  sheets: [{ title: "Sheet1", rowCount: 1000, columnCount: 26 }],
+  initialData: {
+    sheetTitle: "Sheet1",
+    range: "A1",
+    values: [["Name", "Value"], ["Item1", 100]]
+  }
+}
+```
+
+## Suggested Prompts
+
+The integration includes three AI prompts:
+
+1. **Analyze spreadsheet data** - Read and analyze data with insights and statistics
+2. **Create a report spreadsheet** - Generate formatted spreadsheets with calculations
+3. **Update a tracker** - Update tracking spreadsheets with new data
+
+## Integration with Other Services
+
+This integration works well with:
+- **Gmail** - Export email data to sheets
+- **Calendar** - Create event trackers
+- **Notion** - Sync data between Notion and Sheets
+
+## Advanced Features
+
+### Token Management
+
+The integration includes automatic token refresh:
+- Tokens expire after 1 hour
+- Refresh tokens are used automatically
+- Failed refreshes trigger re-authentication
+
+### Batch Operations
+
+```typescript
+// Read multiple ranges at once
+const ranges = await client.readRanges("spreadsheet-id", [
+  "Sheet1!A1:B10",
+  "Sheet2!C1:D10",
+]);
+
+// Append data to a sheet
+await client.appendRange("spreadsheet-id", "Sheet1!A1", [
+  ["New Row 1", "Value 1"],
+  ["New Row 2", "Value 2"],
+]);
+
+// Clear a range
+await client.clearRange("spreadsheet-id", "Sheet1!A1:Z100");
+```
+
+### Sheet Management
+
+```typescript
+// Add a new sheet
+await client.addSheet("spreadsheet-id", "New Sheet", {
+  rowCount: 500,
+  columnCount: 20,
+});
+
+// Delete a sheet
+await client.deleteSheet("spreadsheet-id", sheetId);
+```
+
+## Production Considerations
+
+### Token Storage
+
+The default implementation uses in-memory storage. For production:
+
+```typescript
+import { createTokenStore } from "./lib/token-store.ts";
+
+const tokenStore = createTokenStore({
+  get: async (key) => await db.get(key),
+  set: async (key, value) => await db.set(key, value),
+  delete: async (key) => await db.delete(key),
+});
+```
+
+### User Authentication
+
+Replace `DEFAULT_USER_ID` with actual user session management:
+
+```typescript
+// Get user from session
+const userId = await getSessionUserId(request);
+const client = createSheetsClient(userId);
+```
+
+### Error Handling
+
+The client throws descriptive errors:
+- `"Google Sheets not connected"` - User needs to authenticate
+- `"Sheets API error: 404"` - Spreadsheet not found
+- `"Token refresh failed"` - Re-authentication required
+
+## Type Definitions
+
+### Spreadsheet
+
+```typescript
+interface Spreadsheet {
+  spreadsheetId: string;
+  properties: {
+    title: string;
+    locale: string;
+    timeZone: string;
+  };
+  sheets: Sheet[];
+  spreadsheetUrl: string;
+}
+```
+
+### Sheet
+
+```typescript
+interface Sheet {
+  properties: {
+    sheetId: number;
+    title: string;
+    index: number;
+    sheetType: "GRID" | "OBJECT";
+    gridProperties?: {
+      rowCount: number;
+      columnCount: number;
+    };
+  };
+}
+```
+
+### CellData
+
+```typescript
+interface CellData {
+  values: unknown[][];
+  range: string;
+}
+```
+
+## API Documentation
+
+- [Google Sheets API v4](https://developers.google.com/sheets/api/reference/rest)
+- [Google OAuth 2.0](https://developers.google.com/identity/protocols/oauth2)
+- [A1 Notation](https://developers.google.com/sheets/api/guides/concepts#cell)
+
+## License
+
+Part of the Veryfront framework.

package/dist/integrations/sheets/connector.json

@@ -0,0 +1,99 @@
+{
+  "name": "sheets",
+  "displayName": "Google Sheets",
+  "icon": "sheets.svg",
+  "description": "Read, write, and manage Google Sheets spreadsheets",
+  "auth": {
+    "type": "oauth2",
+    "provider": "google",
+    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+    "tokenUrl": "https://oauth2.googleapis.com/token",
+    "scopes": [
+      "https://www.googleapis.com/auth/spreadsheets",
+      "https://www.googleapis.com/auth/drive.readonly"
+    ],
+    "callbackPath": "/api/auth/sheets/callback",
+    "requiredApis": [
+      {
+        "name": "Google Sheets API",
+        "enableUrl": "https://console.cloud.google.com/apis/library/sheets.googleapis.com"
+      },
+      {
+        "name": "Google Drive API",
+        "enableUrl": "https://console.cloud.google.com/apis/library/drive.googleapis.com"
+      }
+    ]
+  },
+  "envVars": [
+    {
+      "name": "GOOGLE_CLIENT_ID",
+      "description": "Google OAuth Client ID",
+      "required": true,
+      "sensitive": false,
+      "docsUrl": "https://console.cloud.google.com/apis/credentials"
+    },
+    {
+      "name": "GOOGLE_CLIENT_SECRET",
+      "description": "Google OAuth Client Secret",
+      "required": true,
+      "sensitive": true,
+      "docsUrl": "https://console.cloud.google.com/apis/credentials"
+    }
+  ],
+  "tools": [
+    {
+      "id": "list-spreadsheets",
+      "name": "List Spreadsheets",
+      "description": "List recent Google Sheets spreadsheets from Drive",
+      "requiresWrite": false
+    },
+    {
+      "id": "get-spreadsheet",
+      "name": "Get Spreadsheet",
+      "description": "Get spreadsheet metadata including sheet names and properties",
+      "requiresWrite": false
+    },
+    {
+      "id": "read-range",
+      "name": "Read Range",
+      "description": "Read cell data from a spreadsheet range",
+      "requiresWrite": false
+    },
+    {
+      "id": "write-range",
+      "name": "Write Range",
+      "description": "Write data to a spreadsheet range",
+      "requiresWrite": true
+    },
+    {
+      "id": "create-spreadsheet",
+      "name": "Create Spreadsheet",
+      "description": "Create a new spreadsheet with optional initial data",
+      "requiresWrite": true
+    }
+  ],
+  "prompts": [
+    {
+      "id": "analyze-data",
+      "title": "Analyze spreadsheet data",
+      "prompt": "Read and analyze data from a Google Sheets spreadsheet. Provide insights, trends, and statistics.",
+      "category": "productivity",
+      "icon": "chart"
+    },
+    {
+      "id": "create-report",
+      "title": "Create a report spreadsheet",
+      "prompt": "Create a new Google Sheets spreadsheet with formatted data, headers, and calculations.",
+      "category": "productivity",
+      "icon": "plus"
+    },
+    {
+      "id": "update-tracker",
+      "title": "Update a tracker",
+      "prompt": "Update a tracking spreadsheet with new data. Add rows, update values, or calculate totals.",
+      "category": "productivity",
+      "icon": "edit"
+    }
+  ],
+  "suggestedWith": ["gmail", "calendar", "notion"]
+}

package/dist/integrations/sheets/files/_env.example

@@ -0,0 +1,8 @@
+# Google Sheets Integration
+# Create OAuth credentials at https://console.cloud.google.com/apis/credentials
+# Make sure to enable:
+# - Google Sheets API: https://console.cloud.google.com/apis/library/sheets.googleapis.com
+# - Google Drive API: https://console.cloud.google.com/apis/library/drive.googleapis.com
+
+GOOGLE_CLIENT_ID=your_client_id_here
+GOOGLE_CLIENT_SECRET=your_client_secret_here

package/dist/integrations/sheets/files/ai/tools/create-spreadsheet.ts

@@ -0,0 +1,85 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { createSheetsClient } from "../../lib/sheets-client.ts";
+
+// Default user ID for demo/dev purposes
+// In production, get from authenticated session
+const DEFAULT_USER_ID = "demo-user";
+
+export default tool({
+  id: "create-spreadsheet",
+  description:
+    "Create a new Google Sheets spreadsheet with optional sheet configurations. Returns the new spreadsheet ID and URL.",
+  inputSchema: z.object({
+    title: z
+      .string()
+      .describe("Title of the new spreadsheet"),
+    sheets: z
+      .array(
+        z.object({
+          title: z.string().describe("Name of the sheet/tab"),
+          rowCount: z
+            .number()
+            .min(1)
+            .max(10000)
+            .optional()
+            .describe("Number of rows (default: 1000)"),
+          columnCount: z
+            .number()
+            .min(1)
+            .max(26)
+            .optional()
+            .describe("Number of columns (default: 26)"),
+        }),
+      )
+      .optional()
+      .describe(
+        "Optional array of sheet configurations. If not provided, a single default sheet is created.",
+      ),
+    initialData: z
+      .object({
+        sheetTitle: z.string().describe("Name of the sheet to write data to"),
+        range: z
+          .string()
+          .describe("Range in A1 notation (e.g., 'A1', 'A1:D10')"),
+        values: z
+          .array(z.array(z.any()))
+          .describe(
+            "2D array of values to write. Example: [['Name', 'Age'], ['John', 30]]",
+          ),
+      })
+      .optional()
+      .describe("Optional initial data to populate the spreadsheet"),
+  }),
+  async execute({ title, sheets, initialData }) {
+    const client = createSheetsClient(DEFAULT_USER_ID);
+
+    // Create the spreadsheet
+    const spreadsheet = await client.createSpreadsheet({
+      title,
+      sheets,
+    });
+
+    // Write initial data if provided
+    if (initialData) {
+      const range = `${initialData.sheetTitle}!${initialData.range}`;
+      await client.writeRange({
+        spreadsheetId: spreadsheet.spreadsheetId,
+        range,
+        values: initialData.values,
+        valueInputOption: "USER_ENTERED",
+      });
+    }
+
+    return {
+      id: spreadsheet.spreadsheetId,
+      title: spreadsheet.properties.title,
+      url: spreadsheet.spreadsheetUrl,
+      sheets: spreadsheet.sheets.map((sheet) => ({
+        id: sheet.properties.sheetId,
+        title: sheet.properties.title,
+        index: sheet.properties.index,
+      })),
+    };
+  },
+});

package/dist/integrations/sheets/files/ai/tools/get-spreadsheet.ts

@@ -0,0 +1,39 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { createSheetsClient } from "../../lib/sheets-client.ts";
+
+// Default user ID for demo/dev purposes
+// In production, get from authenticated session
+const DEFAULT_USER_ID = "demo-user";
+
+export default tool({
+  id: "get-spreadsheet",
+  description:
+    "Get metadata about a Google Sheets spreadsheet including all sheet names, properties, and structure. Use this to discover available sheets and their dimensions.",
+  inputSchema: z.object({
+    spreadsheetId: z
+      .string()
+      .describe("The ID of the spreadsheet (from URL or list-spreadsheets)"),
+  }),
+  async execute({ spreadsheetId }) {
+    const client = createSheetsClient(DEFAULT_USER_ID);
+
+    const spreadsheet = await client.getSpreadsheet(spreadsheetId);
+
+    return {
+      id: spreadsheet.spreadsheetId,
+      title: spreadsheet.properties.title,
+      url: spreadsheet.spreadsheetUrl,
+      locale: spreadsheet.properties.locale,
+      timeZone: spreadsheet.properties.timeZone,
+      sheets: spreadsheet.sheets.map((sheet) => ({
+        id: sheet.properties.sheetId,
+        title: sheet.properties.title,
+        index: sheet.properties.index,
+        type: sheet.properties.sheetType,
+        rowCount: sheet.properties.gridProperties?.rowCount,
+        columnCount: sheet.properties.gridProperties?.columnCount,
+      })),
+    };
+  },
+});

package/dist/integrations/sheets/files/ai/tools/list-spreadsheets.ts

@@ -0,0 +1,41 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { createSheetsClient } from "../../lib/sheets-client.ts";
+
+// Default user ID for demo/dev purposes
+// In production, get from authenticated session
+const DEFAULT_USER_ID = "demo-user";
+
+export default tool({
+  id: "list-spreadsheets",
+  description:
+    "List recent Google Sheets spreadsheets from Google Drive. Returns spreadsheet names, IDs, and metadata.",
+  inputSchema: z.object({
+    maxResults: z
+      .number()
+      .min(1)
+      .max(100)
+      .default(20)
+      .describe("Maximum number of spreadsheets to return"),
+    orderBy: z
+      .enum(["createdTime", "modifiedTime", "name"])
+      .default("modifiedTime")
+      .describe("Sort order for results"),
+  }),
+  async execute({ maxResults, orderBy }) {
+    const client = createSheetsClient(DEFAULT_USER_ID);
+
+    const spreadsheets = await client.listSpreadsheets({
+      maxResults,
+      orderBy,
+    });
+
+    return spreadsheets.map((sheet) => ({
+      id: sheet.id,
+      name: sheet.name,
+      url: sheet.webViewLink,
+      createdTime: sheet.createdTime,
+      modifiedTime: sheet.modifiedTime,
+    }));
+  },
+});

package/dist/integrations/sheets/files/ai/tools/read-range.ts

@@ -0,0 +1,35 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { createSheetsClient } from "../../lib/sheets-client.ts";
+
+// Default user ID for demo/dev purposes
+// In production, get from authenticated session
+const DEFAULT_USER_ID = "demo-user";
+
+export default tool({
+  id: "read-range",
+  description:
+    "Read cell data from a Google Sheets range. Returns a 2D array of values. Use A1 notation (e.g., 'Sheet1!A1:D10', 'A1:B', or just 'Sheet1' for entire sheet).",
+  inputSchema: z.object({
+    spreadsheetId: z
+      .string()
+      .describe("The ID of the spreadsheet"),
+    range: z
+      .string()
+      .describe(
+        "Range in A1 notation (e.g., 'Sheet1!A1:D10', 'A1:B5', or 'Sheet1' for entire sheet)",
+      ),
+  }),
+  async execute({ spreadsheetId, range }) {
+    const client = createSheetsClient(DEFAULT_USER_ID);
+
+    const result = await client.readRange(spreadsheetId, range);
+
+    return {
+      range: result.range,
+      values: result.values,
+      rowCount: result.values.length,
+      columnCount: result.values[0]?.length || 0,
+    };
+  },
+});

package/dist/integrations/sheets/files/ai/tools/write-range.ts

@@ -0,0 +1,51 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { createSheetsClient } from "../../lib/sheets-client.ts";
+
+// Default user ID for demo/dev purposes
+// In production, get from authenticated session
+const DEFAULT_USER_ID = "demo-user";
+
+export default tool({
+  id: "write-range",
+  description:
+    "Write data to a Google Sheets range. Overwrites existing content in the specified range. Provide data as a 2D array where each inner array is a row.",
+  inputSchema: z.object({
+    spreadsheetId: z
+      .string()
+      .describe("The ID of the spreadsheet"),
+    range: z
+      .string()
+      .describe(
+        "Range in A1 notation where to write data (e.g., 'Sheet1!A1', 'Sheet1!A1:D5')",
+      ),
+    values: z
+      .array(z.array(z.any()))
+      .describe(
+        "2D array of values to write. Each inner array represents a row. Example: [['Name', 'Age'], ['John', 30], ['Jane', 25]]",
+      ),
+    valueInputOption: z
+      .enum(["RAW", "USER_ENTERED"])
+      .default("USER_ENTERED")
+      .describe(
+        "RAW: Values are stored as-is. USER_ENTERED: Values are parsed as if typed by user (formulas, numbers, dates)",
+      ),
+  }),
+  async execute({ spreadsheetId, range, values, valueInputOption }) {
+    const client = createSheetsClient(DEFAULT_USER_ID);
+
+    const result = await client.writeRange({
+      spreadsheetId,
+      range,
+      values,
+      valueInputOption,
+    });
+
+    return {
+      updatedRange: result.updatedRange,
+      updatedRows: result.updatedRows,
+      updatedColumns: result.updatedColumns,
+      updatedCells: result.updatedCells,
+    };
+  },
+});