@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/google-workspace/references/auth-and-scopes.md

@@ -1,183 +0,0 @@
-# Auth and Scopes
-
-Load this when configuring OAuth2, service accounts, managing tokens, or selecting API scopes.
-
-## OAuth2 for User-Facing Applications
-
-### Authorization Code Flow with PKCE
-
-Use for web and mobile applications where a user grants access to their Google account.
-
-```typescript
-import { google } from 'googleapis';
-
-const oauth2Client = new google.auth.OAuth2(
-  process.env.GOOGLE_CLIENT_ID,
-  process.env.GOOGLE_CLIENT_SECRET,
-  'https://app.example.com/auth/callback'
-);
-
-// Step 1: Generate authorization URL
-const authUrl = oauth2Client.generateAuthUrl({
-  access_type: 'offline',       // Request a refresh token
-  scope: ['https://www.googleapis.com/auth/drive.readonly'],
-  prompt: 'consent',            // Force consent screen to get refresh token
-  code_challenge_method: 'S256',
-  code_challenge: codeChallenge, // PKCE challenge
-});
-
-// Step 2: Exchange authorization code for tokens
-const { tokens } = await oauth2Client.getToken({
-  code: authorizationCode,
-  codeVerifier: codeVerifier, // PKCE verifier
-});
-oauth2Client.setCredentials(tokens);
-
-// Step 3: Use the authenticated client
-const drive = google.drive({ version: 'v3', auth: oauth2Client });
-```
-
-### Token Management
-
-```typescript
-// Store tokens securely (encrypted in database, not in files)
-async function saveTokens(userId: string, tokens: Credentials) {
-  await db.oauthToken.upsert({
-    where: { userId },
-    create: { userId, accessToken: encrypt(tokens.access_token!), refreshToken: encrypt(tokens.refresh_token!) },
-    update: { accessToken: encrypt(tokens.access_token!), ...(tokens.refresh_token && { refreshToken: encrypt(tokens.refresh_token!) }) },
-  });
-}
-
-// Restore tokens for a returning user
-async function getAuthenticatedClient(userId: string) {
-  const stored = await db.oauthToken.findUnique({ where: { userId } });
-  if (!stored) throw new Error('User not authenticated');
-
-  const client = new google.auth.OAuth2(
-    process.env.GOOGLE_CLIENT_ID,
-    process.env.GOOGLE_CLIENT_SECRET,
-    'https://app.example.com/auth/callback'
-  );
-
-  client.setCredentials({
-    access_token: decrypt(stored.accessToken),
-    refresh_token: decrypt(stored.refreshToken),
-  });
-
-  // Client library handles automatic refresh
-  client.on('tokens', async (tokens) => {
-    await saveTokens(userId, tokens);
-  });
-
-  return client;
-}
-```
-
-- Access tokens expire after 1 hour. The client library refreshes automatically if a refresh token is available.
-- Refresh tokens do not expire unless the user revokes access or the token is unused for 6 months.
-- Store refresh tokens encrypted. They grant long-lived access to user data.
-
-## Service Accounts
-
-### Basic Service Account
-
-```typescript
-import { google } from 'googleapis';
-import { JWT } from 'google-auth-library';
-
-const auth = new JWT({
-  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
-  key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
-  scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
-});
-
-const sheets = google.sheets({ version: 'v4', auth });
-```
-
-- Service accounts are for server-to-server operations with no user interaction.
-- The service account has its own identity. Share resources (sheets, folders) with its email address.
-
-### Domain-Wide Delegation
-
-Allows the service account to impersonate any user in a Google Workspace domain.
-
-```typescript
-const auth = new JWT({
-  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
-  key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
-  scopes: ['https://www.googleapis.com/auth/gmail.send'],
-  subject: 'admin@example.com', // Impersonate this user
-});
-```
-
-- Requires a Workspace admin to grant the service account access in the Admin Console.
-- The `subject` field specifies which user to impersonate.
-- Use this for sending emails (Gmail API requires a real user) and managing calendars.
-
-## Scope Reference
-
-### Principle of Least Privilege
-
-Always request the narrowest scope. Broad scopes trigger extended Google review.
-
-| Scope | Access Level |
-|-------|-------------|
-| `drive.readonly` | Read files and metadata |
-| `drive.file` | Files created by or opened with the app |
-| `drive` | Full Drive access (triggers review) |
-| `spreadsheets.readonly` | Read spreadsheet data |
-| `spreadsheets` | Read and write spreadsheet data |
-| `calendar.readonly` | Read calendar events |
-| `calendar.events` | Read and write events |
-| `calendar` | Full calendar access |
-| `gmail.readonly` | Read email messages |
-| `gmail.send` | Send email only |
-| `gmail.modify` | Read, send, and modify (triggers review) |
-
-### Incremental Authorization
-
-Request scopes incrementally as features are used, not all at once during initial login.
-
-```typescript
-const authUrl = oauth2Client.generateAuthUrl({
-  scope: ['openid', 'email'], // Start with basic profile
-  include_granted_scopes: true,
-});
-
-// Later, when the user accesses Drive features:
-const driveAuthUrl = oauth2Client.generateAuthUrl({
-  scope: ['https://www.googleapis.com/auth/drive.readonly'],
-  include_granted_scopes: true, // Merge with existing scopes
-});
-```
-
-## Consent Screen Configuration
-
-1. Create an OAuth consent screen in the Google Cloud Console.
-2. Set the application type: Internal (Workspace users only) or External (any Google account).
-3. Add only the scopes your application needs.
-4. Internal apps skip Google review. External apps with sensitive scopes require review.
-5. Add test users during development. Only test users can access unverified apps.
-
-## Error Handling
-
-```typescript
-try {
-  const response = await drive.files.list({ q: "name = 'test'" });
-} catch (error: any) {
-  if (error.code === 401) {
-    // Token expired or revoked. Re-authenticate.
-  } else if (error.code === 403) {
-    // Insufficient scopes or insufficient permissions on the resource.
-    // Check: is the scope correct? Is the file shared with this account?
-  } else if (error.code === 404) {
-    // Resource not found or no access.
-  } else if (error.code === 429) {
-    // Rate limit exceeded. Implement exponential backoff.
-  }
-}
-```
-
-- 403 errors are the most common. They can mean wrong scopes, unshared resources, or disabled APIs.
-- Always enable the specific API (Drive, Sheets, Calendar, Gmail) in the Google Cloud Console.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/google-workspace/references/sheets-api-patterns.md

@@ -1,226 +0,0 @@
-# Sheets API Patterns
-
-Load this when reading, writing, formatting, or batch-updating Google Sheets data.
-
-## Reading Data
-
-### Basic Read
-
-```typescript
-const response = await sheets.spreadsheets.values.get({
-  spreadsheetId: SHEET_ID,
-  range: 'Sheet1!A1:D100',
-  valueRenderOption: 'UNFORMATTED_VALUE',
-  dateTimeRenderOption: 'SERIAL_NUMBER',
-});
-
-const rows = response.data.values; // string[][] | undefined
-```
-
-### Value Render Options
-
-| Option | Returns | Use When |
-|--------|---------|----------|
-| `FORMATTED_VALUE` | Display strings: "$1,234.56" | Showing to users directly |
-| `UNFORMATTED_VALUE` | Raw values: 1234.56 | Processing numbers in code |
-| `FORMULA` | Cell formulas: "=SUM(A1:A10)" | Auditing or copying formulas |
-
-- Default is `FORMATTED_VALUE`, which returns strings for all numeric cells. Always override for data processing.
-- `UNFORMATTED_VALUE` returns numbers as numbers and booleans as booleans.
-
-### Date-Time Render Options
-
-| Option | Returns |
-|--------|---------|
-| `SERIAL_NUMBER` | Days since Dec 30, 1899: 45000 |
-| `FORMATTED_STRING` | Locale-formatted: "2023-03-15" |
-
-### Reading Multiple Ranges
-
-```typescript
-const response = await sheets.spreadsheets.values.batchGet({
-  spreadsheetId: SHEET_ID,
-  ranges: ['Sheet1!A1:B10', 'Sheet2!A1:C5', 'Config!A1:A20'],
-  valueRenderOption: 'UNFORMATTED_VALUE',
-});
-
-const [sheet1Data, sheet2Data, configData] = response.data.valueRanges!;
-```
-
-- Batch reads count as one API call. Always prefer `batchGet` over multiple `get` calls.
-
-## Writing Data
-
-### Single Range Write
-
-```typescript
-await sheets.spreadsheets.values.update({
-  spreadsheetId: SHEET_ID,
-  range: 'Sheet1!A1:C3',
-  valueInputOption: 'RAW',
-  requestBody: {
-    values: [
-      ['Name', 'Score', 'Grade'],
-      ['Alice', 95, 'A'],
-      ['Bob', 82, 'B'],
-    ],
-  },
-});
-```
-
-### Value Input Options
-
-| Option | Behavior | Use When |
-|--------|----------|----------|
-| `RAW` | Stores values as-is | Writing numbers, IDs, timestamps |
-| `USER_ENTERED` | Parses like user typed it | Writing formulas, letting Sheets auto-detect types |
-
-- `RAW` prevents "1/1" from becoming a date. Use for data pipelines.
-- `USER_ENTERED` is required when writing formulas like `=SUM(A1:A10)`.
-- Never use `USER_ENTERED` for user-provided text -- they might accidentally inject formulas.
-
-### Batch Write
-
-```typescript
-await sheets.spreadsheets.values.batchUpdate({
-  spreadsheetId: SHEET_ID,
-  requestBody: {
-    valueInputOption: 'RAW',
-    data: [
-      { range: 'Sheet1!A1', values: [['Updated Name']] },
-      { range: 'Sheet1!C5', values: [[99]] },
-      { range: 'Sheet2!B2:C2', values: [['Active', new Date().toISOString()]] },
-    ],
-  },
-});
-```
-
-### Appending Rows
-
-```typescript
-await sheets.spreadsheets.values.append({
-  spreadsheetId: SHEET_ID,
-  range: 'Sheet1!A:D',          // Append after last row with data
-  valueInputOption: 'RAW',
-  insertDataOption: 'INSERT_ROWS', // or 'OVERWRITE'
-  requestBody: {
-    values: [
-      ['New Item', 42, 'Category A', new Date().toISOString()],
-    ],
-  },
-});
-```
-
-- `INSERT_ROWS` adds new rows. `OVERWRITE` writes into existing empty rows.
-- The range only determines which sheet and columns to use. Sheets finds the last row automatically.
-
-## Formatting and Structure
-
-### Conditional Formatting, Borders, Colors
-
-Use `spreadsheets.batchUpdate` with structured requests (not `values` API).
-
-```typescript
-await sheets.spreadsheets.batchUpdate({
-  spreadsheetId: SHEET_ID,
-  requestBody: {
-    requests: [
-      {
-        repeatCell: {
-          range: { sheetId: 0, startRowIndex: 0, endRowIndex: 1 },
-          cell: {
-            userEnteredFormat: {
-              backgroundColor: { red: 0.2, green: 0.4, blue: 0.8 },
-              textFormat: { bold: true, foregroundColor: { red: 1, green: 1, blue: 1 } },
-            },
-          },
-          fields: 'userEnteredFormat(backgroundColor,textFormat)',
-        },
-      },
-      {
-        autoResizeDimensions: {
-          dimensions: { sheetId: 0, dimension: 'COLUMNS', startIndex: 0, endIndex: 5 },
-        },
-      },
-    ],
-  },
-});
-```
-
-### Creating a New Sheet Tab
-
-```typescript
-await sheets.spreadsheets.batchUpdate({
-  spreadsheetId: SHEET_ID,
-  requestBody: {
-    requests: [
-      {
-        addSheet: {
-          properties: {
-            title: 'Q1 Report',
-            gridProperties: { rowCount: 1000, columnCount: 10 },
-          },
-        },
-      },
-    ],
-  },
-});
-```
-
-## Preserving Formulas
-
-When updating cells adjacent to formulas:
-
-1. Read the range with `valueRenderOption: 'FORMULA'` to see which cells contain formulas.
-2. Write only to non-formula cells using specific cell ranges, not entire row ranges.
-3. Use `RAW` input option for data cells; formulas are not affected if you do not write to their cells.
-
-```typescript
-// Bad: overwrites the entire row including formula in column D
-await sheets.spreadsheets.values.update({
-  range: 'Sheet1!A2:D2',
-  requestBody: { values: [['Name', 100, 'Cat', 'oops formula gone']] },
-});
-
-// Good: write only to columns A-C, preserving the formula in D
-await sheets.spreadsheets.values.update({
-  range: 'Sheet1!A2:C2',
-  requestBody: { values: [['Name', 100, 'Cat']] },
-});
-```
-
-## Pagination for Large Sheets
-
-The Sheets API returns all rows in a range by default. For very large sheets:
-
-```typescript
-async function readInChunks(sheetId: string, sheetName: string, chunkSize = 1000) {
-  const allRows: any[][] = [];
-  let startRow = 2; // skip header
-
-  while (true) {
-    const range = `${sheetName}!A${startRow}:Z${startRow + chunkSize - 1}`;
-    const response = await sheets.spreadsheets.values.get({
-      spreadsheetId: sheetId,
-      range,
-      valueRenderOption: 'UNFORMATTED_VALUE',
-    });
-
-    const rows = response.data.values ?? [];
-    if (rows.length === 0) break;
-
-    allRows.push(...rows);
-    startRow += chunkSize;
-  }
-
-  return allRows;
-}
-```
-
-## Quota Management
-
-- **Read requests**: 60 per minute per user, 300 per minute per project.
-- **Write requests**: 60 per minute per user, 300 per minute per project.
-- Batch operations (batchGet, batchUpdate) count as one request regardless of sub-operations.
-- Always use batch operations when performing multiple reads or writes.
-- Implement exponential backoff for 429 (rate limit) errors.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/google-workspace/references/workspace-automation.md

@@ -1,283 +0,0 @@
-# Workspace Automation
-
-Load this when building multi-service workflows, batch operations, push notifications, or automated processes with Google Workspace APIs.
-
-## Batch Requests
-
-Combine up to 100 API calls into a single HTTP request to reduce latency and quota consumption.
-
-### Google API Client Batching
-
-```typescript
-import { google } from 'googleapis';
-
-const drive = google.drive({ version: 'v3', auth });
-
-// Create a batch request
-const batch = new google.Batch();
-
-const fileIds = ['file1', 'file2', 'file3', 'file4', 'file5'];
-
-for (const fileId of fileIds) {
-  batch.add(
-    drive.files.get({ fileId, fields: 'id, name, mimeType, modifiedTime' })
-  );
-}
-
-const responses = await batch.execute();
-```
-
-### Manual Batch with Promise.allSettled
-
-When the client library batch API is not available or practical:
-
-```typescript
-async function batchProcess<T, R>(
-  items: T[],
-  processor: (item: T) => Promise<R>,
-  concurrency: number = 5,
-): Promise<Array<{ status: 'fulfilled'; value: R } | { status: 'rejected'; reason: any }>> {
-  const results: Array<PromiseSettledResult<R>> = [];
-
-  for (let i = 0; i < items.length; i += concurrency) {
-    const chunk = items.slice(i, i + concurrency);
-    const chunkResults = await Promise.allSettled(
-      chunk.map(processor)
-    );
-    results.push(...chunkResults);
-
-    // Respect rate limits: pause between batches
-    if (i + concurrency < items.length) {
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-  }
-
-  return results;
-}
-
-// Usage
-const results = await batchProcess(
-  fileIds,
-  async (fileId) => {
-    const res = await drive.files.get({ fileId, fields: 'id, name' });
-    return res.data;
-  },
-  10 // process 10 files concurrently
-);
-```
-
-## Push Notifications (Watch API)
-
-### Drive Change Notifications
-
-```typescript
-import { v4 as uuidv4 } from 'uuid';
-
-// Register a watch channel
-const channel = await drive.files.watch({
-  fileId: 'spreadsheet_id_here',
-  requestBody: {
-    id: uuidv4(),                    // Unique channel ID
-    type: 'web_hook',
-    address: 'https://api.example.com/webhooks/drive',
-    expiration: String(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
-  },
-});
-
-// Channel expires. Set up a cron job to renew before expiration.
-console.log('Channel ID:', channel.data.id);
-console.log('Resource ID:', channel.data.resourceId);
-console.log('Expiration:', channel.data.expiration);
-```
-
-### Calendar Change Notifications
-
-```typescript
-const watchResponse = await calendar.events.watch({
-  calendarId: 'primary',
-  requestBody: {
-    id: uuidv4(),
-    type: 'web_hook',
-    address: 'https://api.example.com/webhooks/calendar',
-  },
-});
-```
-
-### Webhook Handler
-
-```typescript
-// POST /webhooks/drive
-app.post('/webhooks/drive', (req, res) => {
-  const channelId = req.headers['x-goog-channel-id'];
-  const resourceState = req.headers['x-goog-resource-state'];
-  const resourceId = req.headers['x-goog-resource-id'];
-
-  // Verify this is a known channel
-  if (!isValidChannel(channelId)) {
-    return res.status(403).send('Unknown channel');
-  }
-
-  if (resourceState === 'sync') {
-    // Initial sync notification -- confirms the channel is active
-    return res.status(200).send('OK');
-  }
-
-  if (resourceState === 'update' || resourceState === 'change') {
-    // Resource changed. Fetch the latest state.
-    processResourceChange(resourceId);
-  }
-
-  res.status(200).send('OK');
-});
-```
-
-### Stopping a Watch Channel
-
-```typescript
-await drive.channels.stop({
-  requestBody: {
-    id: channelId,
-    resourceId: resourceId,
-  },
-});
-```
-
-- Channels expire after at most 7 days. Renew before expiration.
-- The webhook receives a notification that something changed, not what changed. You must fetch the resource to see the new state.
-- Always respond with HTTP 200 quickly. Google retries on non-2xx responses.
-
-## Drive Automation Patterns
-
-### Recursive Folder Listing
-
-```typescript
-async function listAllFiles(
-  drive: any,
-  folderId: string,
-  files: any[] = []
-): Promise<any[]> {
-  let pageToken: string | undefined;
-
-  do {
-    const response = await drive.files.list({
-      q: `'${folderId}' in parents and trashed = false`,
-      fields: 'nextPageToken, files(id, name, mimeType, modifiedTime)',
-      pageSize: 100,
-      pageToken,
-      supportsAllDrives: true,
-      includeItemsFromAllDrives: true,
-    });
-
-    for (const file of response.data.files ?? []) {
-      files.push(file);
-      if (file.mimeType === 'application/vnd.google-apps.folder') {
-        await listAllFiles(drive, file.id, files);
-      }
-    }
-
-    pageToken = response.data.nextPageToken;
-  } while (pageToken);
-
-  return files;
-}
-```
-
-### File Export (Google Docs to PDF)
-
-```typescript
-async function exportAsPdf(drive: any, fileId: string): Promise<Buffer> {
-  const response = await drive.files.export(
-    { fileId, mimeType: 'application/pdf' },
-    { responseType: 'arraybuffer' }
-  );
-  return Buffer.from(response.data);
-}
-```
-
-## Calendar Automation
-
-### Free/Busy Availability Check
-
-```typescript
-const response = await calendar.freebusy.query({
-  requestBody: {
-    timeMin: new Date('2024-03-01T09:00:00Z').toISOString(),
-    timeMax: new Date('2024-03-01T17:00:00Z').toISOString(),
-    items: [
-      { id: 'user1@example.com' },
-      { id: 'user2@example.com' },
-    ],
-  },
-});
-
-for (const [calendarId, data] of Object.entries(response.data.calendars!)) {
-  const busy = (data as any).busy;
-  console.log(`${calendarId}: ${busy.length} busy periods`);
-}
-```
-
-### Recurring Events
-
-```typescript
-const event = await calendar.events.insert({
-  calendarId: 'primary',
-  requestBody: {
-    summary: 'Weekly Standup',
-    start: { dateTime: '2024-03-04T09:00:00', timeZone: 'America/New_York' },
-    end: { dateTime: '2024-03-04T09:15:00', timeZone: 'America/New_York' },
-    recurrence: ['RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=52'],
-    attendees: [
-      { email: 'team@example.com' },
-    ],
-  },
-});
-```
-
-## Error Recovery Patterns
-
-### Partial Failure Tracking
-
-```typescript
-interface OperationResult {
-  id: string;
-  success: boolean;
-  error?: string;
-}
-
-async function processWithRecovery<T>(
-  items: T[],
-  processor: (item: T) => Promise<string>,
-  getId: (item: T) => string,
-): Promise<OperationResult[]> {
-  const results: OperationResult[] = [];
-
-  for (const item of items) {
-    try {
-      await processor(item);
-      results.push({ id: getId(item), success: true });
-    } catch (error: any) {
-      results.push({
-        id: getId(item),
-        success: false,
-        error: error.message ?? String(error),
-      });
-    }
-  }
-
-  const failed = results.filter(r => !r.success);
-  if (failed.length > 0) {
-    console.warn(`${failed.length}/${results.length} operations failed:`,
-      failed.map(f => `${f.id}: ${f.error}`).join(', ')
-    );
-  }
-
-  return results;
-}
-```
-
-### Idempotent Operations
-
-- Use `fileId` checks before creating files to avoid duplicates on retry.
-- Use `eventId` for calendar events to prevent duplicate events.
-- Store operation IDs in your database to track completed steps in multi-service workflows.
-- Design each step to be safely re-runnable. Check for existing resources before creating new ones.