@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/google-workspace/examples/01-basic-usage.md

@@ -1,240 +0,0 @@
-# Example: Google Sheets Data Read/Write with Node.js
-
-## Scenario
-
-A team is building an inventory management dashboard that reads product data from a Google Sheet maintained by the operations team and writes back updated stock counts after warehouse scans. The application uses a service account for server-to-server authentication, reads data with proper type handling, writes updates while preserving existing formulas in calculated columns, and implements error handling for quota limits.
-
-## Prompt
-
-"Build a Node.js service that reads product inventory from a Google Sheet and writes updated stock counts. Use a service account for authentication. Read the 'Inventory' sheet preserving proper types (numbers, dates). Write stock updates to specific cells without overwriting formulas in the 'Total Value' column. Handle rate limiting with exponential backoff."
-
-## Expected Output
-
-### Service Account Setup
-
-```typescript
-// lib/google-auth.ts
-import { google } from 'googleapis';
-import { JWT } from 'google-auth-library';
-
-const SCOPES = ['https://www.googleapis.com/auth/spreadsheets'];
-
-export function getAuthClient(): JWT {
-  const auth = new JWT({
-    email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
-    key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
-    scopes: SCOPES,
-  });
-  return auth;
-}
-
-export function getSheetsClient() {
-  const auth = getAuthClient();
-  return google.sheets({ version: 'v4', auth });
-}
-```
-
-### Read Inventory Data
-
-```typescript
-// services/inventory-reader.ts
-import { getSheetsClient } from '../lib/google-auth';
-
-interface Product {
-  sku: string;
-  name: string;
-  currentStock: number;
-  reorderPoint: number;
-  lastUpdated: Date | null;
-  // totalValue is a formula column -- we read it but never write to it
-  totalValue: number;
-}
-
-const SPREADSHEET_ID = process.env.INVENTORY_SHEET_ID!;
-const RANGE = 'Inventory!A2:F500'; // Skip header row
-
-export async function readInventory(): Promise<Product[]> {
-  const sheets = getSheetsClient();
-
-  const response = await sheets.spreadsheets.values.get({
-    spreadsheetId: SPREADSHEET_ID,
-    range: RANGE,
-    valueRenderOption: 'UNFORMATTED_VALUE', // Get raw numbers, not "$1,234.56"
-    dateTimeRenderOption: 'FORMATTED_STRING',
-  });
-
-  const rows = response.data.values;
-  if (!rows || rows.length === 0) {
-    return [];
-  }
-
-  return rows.map((row) => ({
-    sku: String(row[0] ?? ''),
-    name: String(row[1] ?? ''),
-    currentStock: Number(row[2] ?? 0),
-    reorderPoint: Number(row[3] ?? 0),
-    lastUpdated: row[4] ? new Date(row[4]) : null,
-    totalValue: Number(row[5] ?? 0),
-  }));
-}
-
-export async function getProductBySku(sku: string): Promise<Product | null> {
-  const inventory = await readInventory();
-  return inventory.find((p) => p.sku === sku) ?? null;
-}
-```
-
-### Write Stock Updates
-
-```typescript
-// services/inventory-writer.ts
-import { getSheetsClient } from '../lib/google-auth';
-import { retryWithBackoff } from '../lib/retry';
-
-const SPREADSHEET_ID = process.env.INVENTORY_SHEET_ID!;
-
-interface StockUpdate {
-  sku: string;
-  newStock: number;
-  rowIndex: number; // 0-based index in the data range (row 2 = index 0)
-}
-
-export async function updateStock(updates: StockUpdate[]): Promise<void> {
-  const sheets = getSheetsClient();
-
-  // Build batch update: only write to stock column (C) and timestamp column (E)
-  // Column F (Total Value) contains a formula -- never overwrite it
-  const data = updates.map((update) => {
-    const sheetRow = update.rowIndex + 2; // +2 for header row and 1-based indexing
-    return [
-      {
-        range: `Inventory!C${sheetRow}`,
-        values: [[update.newStock]],
-      },
-      {
-        range: `Inventory!E${sheetRow}`,
-        values: [[new Date().toISOString()]],
-      },
-    ];
-  }).flat();
-
-  await retryWithBackoff(async () => {
-    await sheets.spreadsheets.values.batchUpdate({
-      spreadsheetId: SPREADSHEET_ID,
-      requestBody: {
-        valueInputOption: 'RAW', // Write values as-is, don't interpret as formulas
-        data,
-      },
-    });
-  });
-}
-
-export async function appendNewProduct(
-  sku: string,
-  name: string,
-  stock: number,
-  reorderPoint: number,
-): Promise<void> {
-  const sheets = getSheetsClient();
-
-  await retryWithBackoff(async () => {
-    await sheets.spreadsheets.values.append({
-      spreadsheetId: SPREADSHEET_ID,
-      range: 'Inventory!A:F',
-      valueInputOption: 'USER_ENTERED', // Allow formulas in the appended row
-      requestBody: {
-        values: [[
-          sku,
-          name,
-          stock,
-          reorderPoint,
-          new Date().toISOString(),
-          `=C{ROW}*VLOOKUP(A{ROW},Prices!A:B,2,FALSE)`, // Formula for total value
-        ]],
-      },
-    });
-  });
-}
-```
-
-### Retry with Exponential Backoff
-
-```typescript
-// lib/retry.ts
-export async function retryWithBackoff<T>(
-  fn: () => Promise<T>,
-  maxRetries: number = 5,
-  baseDelayMs: number = 1000,
-): Promise<T> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error: any) {
-      const status = error?.response?.status ?? error?.code;
-
-      // Retry on rate limit (429) and server errors (500, 503)
-      if (attempt < maxRetries && (status === 429 || status >= 500)) {
-        const delay = baseDelayMs * Math.pow(2, attempt) + Math.random() * 1000;
-        console.warn(
-          `Request failed with ${status}, retrying in ${Math.round(delay)}ms ` +
-          `(attempt ${attempt + 1}/${maxRetries})`
-        );
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-
-      throw error;
-    }
-  }
-  throw new Error('Max retries exceeded');
-}
-```
-
-### API Route
-
-```typescript
-// app/api/inventory/update/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { readInventory } from '@/services/inventory-reader';
-import { updateStock } from '@/services/inventory-writer';
-
-export async function POST(req: NextRequest) {
-  const { updates } = await req.json() as {
-    updates: Array<{ sku: string; newStock: number }>;
-  };
-
-  // Read current inventory to find row indices
-  const inventory = await readInventory();
-  const skuToRow = new Map(
-    inventory.map((p, index) => [p.sku, index])
-  );
-
-  const stockUpdates = updates
-    .filter((u) => skuToRow.has(u.sku))
-    .map((u) => ({
-      sku: u.sku,
-      newStock: u.newStock,
-      rowIndex: skuToRow.get(u.sku)!,
-    }));
-
-  if (stockUpdates.length === 0) {
-    return NextResponse.json({ error: 'No matching SKUs found' }, { status: 400 });
-  }
-
-  await updateStock(stockUpdates);
-
-  return NextResponse.json({
-    updated: stockUpdates.length,
-    skus: stockUpdates.map((u) => u.sku),
-  });
-}
-```
-
-## Key Decisions
-
-- **Service account over OAuth2** -- server-to-server operations do not involve a user, so a service account with domain delegation is appropriate and avoids token refresh handling.
-- **`UNFORMATTED_VALUE` for reads** -- returns raw numbers and booleans instead of locale-formatted strings, preventing parsing errors (e.g., "$1,234.56" as a string instead of 1234.56 as a number).
-- **`RAW` valueInputOption for stock writes** -- ensures numbers are stored as numbers, not accidentally interpreted as dates or formulas by Sheets' auto-detection.
-- **`USER_ENTERED` for appending with formulas** -- allows the formula in the Total Value column to be interpreted by Sheets when appending new rows.
-- **Selective column writes** -- the batch update targets only columns C and E, preserving the formula in column F (Total Value) that references external data.
-- **Exponential backoff with jitter** -- Google Sheets API enforces 60 requests per minute per user. Backoff with random jitter prevents thundering herd when multiple instances retry simultaneously.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/google-workspace/examples/02-advanced-usage.md

@@ -1,325 +0,0 @@
-# Example: Multi-Service Workflow Automation
-
-## Scenario
-
-A team is building an automated onboarding system for new employees. When HR adds a new employee to a Google Sheet, the system should: (1) create a Google Calendar event for the orientation meeting, (2) create a personal Google Drive folder with onboarding documents copied from a template, (3) send a welcome email via Gmail with links to the folder and calendar event, and (4) update the Sheet with status and links. The system uses OAuth2 with domain-wide delegation for a service account that impersonates the HR admin.
-
-## Prompt
-
-"Build an automated employee onboarding workflow that reads new hires from a Google Sheet, creates a Calendar orientation event, sets up a Drive folder with template documents, sends a Gmail welcome message, and updates the Sheet with completion status. Use a service account with domain-wide delegation. Coordinate all four APIs with error handling and partial failure recovery."
-
-## Expected Output
-
-### Multi-Scope Authentication
-
-```typescript
-// lib/workspace-auth.ts
-import { google } from 'googleapis';
-import { JWT } from 'google-auth-library';
-
-const SCOPES = [
-  'https://www.googleapis.com/auth/spreadsheets',
-  'https://www.googleapis.com/auth/calendar',
-  'https://www.googleapis.com/auth/drive',
-  'https://www.googleapis.com/auth/gmail.send',
-];
-
-export function getImpersonatedClient(impersonateEmail: string): JWT {
-  return new JWT({
-    email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
-    key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
-    scopes: SCOPES,
-    subject: impersonateEmail, // Domain-wide delegation: act as this user
-  });
-}
-
-export function getClients(impersonateEmail: string) {
-  const auth = getImpersonatedClient(impersonateEmail);
-  return {
-    sheets: google.sheets({ version: 'v4', auth }),
-    calendar: google.calendar({ version: 'v3', auth }),
-    drive: google.drive({ version: 'v3', auth }),
-    gmail: google.gmail({ version: 'v1', auth }),
-  };
-}
-```
-
-### Read New Hires from Sheet
-
-```typescript
-// services/new-hire-reader.ts
-interface NewHire {
-  rowIndex: number;
-  name: string;
-  email: string;
-  department: string;
-  startDate: string;
-  manager: string;
-  managerEmail: string;
-  status: string;
-}
-
-export async function getUnprocessedHires(
-  sheets: any,
-  spreadsheetId: string
-): Promise<NewHire[]> {
-  const response = await sheets.spreadsheets.values.get({
-    spreadsheetId,
-    range: 'New Hires!A2:H100',
-    valueRenderOption: 'UNFORMATTED_VALUE',
-  });
-
-  const rows = response.data.values ?? [];
-
-  return rows
-    .map((row: any[], index: number) => ({
-      rowIndex: index + 2,
-      name: row[0] ?? '',
-      email: row[1] ?? '',
-      department: row[2] ?? '',
-      startDate: row[3] ?? '',
-      manager: row[4] ?? '',
-      managerEmail: row[5] ?? '',
-      status: row[6] ?? '',
-    }))
-    .filter((hire: NewHire) => hire.status === '' || hire.status === 'pending');
-}
-```
-
-### Create Calendar Orientation Event
-
-```typescript
-// services/calendar-service.ts
-export async function createOrientationEvent(
-  calendar: any,
-  hire: NewHire
-): Promise<string> {
-  const startDate = new Date(hire.startDate);
-  startDate.setHours(9, 0, 0); // 9:00 AM
-
-  const endDate = new Date(startDate);
-  endDate.setHours(12, 0, 0); // 12:00 PM
-
-  const event = await calendar.events.insert({
-    calendarId: 'primary',
-    requestBody: {
-      summary: `Orientation: ${hire.name}`,
-      description: `New employee orientation for ${hire.name} (${hire.department}).\n\nManager: ${hire.manager}`,
-      start: {
-        dateTime: startDate.toISOString(),
-        timeZone: 'America/New_York',
-      },
-      end: {
-        dateTime: endDate.toISOString(),
-        timeZone: 'America/New_York',
-      },
-      attendees: [
-        { email: hire.email },
-        { email: hire.managerEmail },
-        { email: 'hr-onboarding@example.com' },
-      ],
-      reminders: {
-        useDefault: false,
-        overrides: [
-          { method: 'email', minutes: 1440 }, // 1 day before
-          { method: 'popup', minutes: 60 },
-        ],
-      },
-    },
-    sendUpdates: 'all',
-  });
-
-  return event.data.htmlLink!;
-}
-```
-
-### Create Drive Folder with Templates
-
-```typescript
-// services/drive-service.ts
-export async function createOnboardingFolder(
-  drive: any,
-  hire: NewHire,
-  templateFolderId: string
-): Promise<{ folderId: string; folderUrl: string }> {
-  // Create personal onboarding folder
-  const folder = await drive.files.create({
-    requestBody: {
-      name: `Onboarding - ${hire.name}`,
-      mimeType: 'application/vnd.google-apps.folder',
-      parents: [process.env.ONBOARDING_ROOT_FOLDER_ID],
-    },
-    fields: 'id, webViewLink',
-    supportsAllDrives: true,
-  });
-
-  // Copy template documents into the new folder
-  const templates = await drive.files.list({
-    q: `'${templateFolderId}' in parents and trashed = false`,
-    fields: 'files(id, name, mimeType)',
-    supportsAllDrives: true,
-  });
-
-  for (const template of templates.data.files ?? []) {
-    await drive.files.copy({
-      fileId: template.id,
-      requestBody: {
-        name: template.name.replace('{{name}}', hire.name),
-        parents: [folder.data.id],
-      },
-      supportsAllDrives: true,
-    });
-  }
-
-  // Share folder with the new hire
-  await drive.permissions.create({
-    fileId: folder.data.id,
-    requestBody: {
-      role: 'writer',
-      type: 'user',
-      emailAddress: hire.email,
-    },
-    sendNotificationEmail: false,
-    supportsAllDrives: true,
-  });
-
-  // Share with manager (read-only)
-  await drive.permissions.create({
-    fileId: folder.data.id,
-    requestBody: {
-      role: 'reader',
-      type: 'user',
-      emailAddress: hire.managerEmail,
-    },
-    sendNotificationEmail: false,
-    supportsAllDrives: true,
-  });
-
-  return { folderId: folder.data.id, folderUrl: folder.data.webViewLink };
-}
-```
-
-### Send Welcome Email via Gmail
-
-```typescript
-// services/gmail-service.ts
-export async function sendWelcomeEmail(
-  gmail: any,
-  hire: NewHire,
-  calendarLink: string,
-  folderUrl: string
-): Promise<void> {
-  const subject = `Welcome to the team, ${hire.name}!`;
-  const htmlBody = `
-    <h2>Welcome to ${hire.department}!</h2>
-    <p>Hi ${hire.name},</p>
-    <p>We're excited to have you join us on ${hire.startDate}.</p>
-    <h3>Your onboarding resources:</h3>
-    <ul>
-      <li><a href="${calendarLink}">Orientation meeting</a> (${hire.startDate}, 9:00 AM - 12:00 PM)</li>
-      <li><a href="${folderUrl}">Onboarding documents folder</a></li>
-    </ul>
-    <p>Your manager ${hire.manager} (${hire.managerEmail}) will be your primary contact.</p>
-    <p>See you soon!</p>
-    <p>HR Team</p>
-  `;
-
-  // Build RFC 2822 message
-  const message = [
-    `To: ${hire.email}`,
-    `Cc: ${hire.managerEmail}`,
-    `Subject: ${subject}`,
-    'MIME-Version: 1.0',
-    'Content-Type: text/html; charset=UTF-8',
-    '',
-    htmlBody,
-  ].join('\r\n');
-
-  const encodedMessage = Buffer.from(message)
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/, '');
-
-  await gmail.users.messages.send({
-    userId: 'me',
-    requestBody: { raw: encodedMessage },
-  });
-}
-```
-
-### Orchestrator with Partial Failure Recovery
-
-```typescript
-// services/onboarding-orchestrator.ts
-import { getClients } from '../lib/workspace-auth';
-import { getUnprocessedHires } from './new-hire-reader';
-import { createOrientationEvent } from './calendar-service';
-import { createOnboardingFolder } from './drive-service';
-import { sendWelcomeEmail } from './gmail-service';
-
-export async function processNewHires() {
-  const clients = getClients(process.env.HR_ADMIN_EMAIL!);
-  const spreadsheetId = process.env.ONBOARDING_SHEET_ID!;
-  const templateFolderId = process.env.TEMPLATE_FOLDER_ID!;
-
-  const hires = await getUnprocessedHires(clients.sheets, spreadsheetId);
-
-  for (const hire of hires) {
-    const result: Record<string, string> = {};
-    let status = 'complete';
-
-    try {
-      result.calendarLink = await createOrientationEvent(clients.calendar, hire);
-    } catch (err) {
-      console.error(`Calendar failed for ${hire.name}:`, err);
-      result.calendarLink = 'FAILED';
-      status = 'partial';
-    }
-
-    try {
-      const folder = await createOnboardingFolder(clients.drive, hire, templateFolderId);
-      result.folderUrl = folder.folderUrl;
-    } catch (err) {
-      console.error(`Drive failed for ${hire.name}:`, err);
-      result.folderUrl = 'FAILED';
-      status = 'partial';
-    }
-
-    try {
-      await sendWelcomeEmail(
-        clients.gmail, hire,
-        result.calendarLink ?? '#',
-        result.folderUrl ?? '#',
-      );
-    } catch (err) {
-      console.error(`Gmail failed for ${hire.name}:`, err);
-      status = 'partial';
-    }
-
-    // Update the Sheet with results regardless of partial failures
-    await clients.sheets.spreadsheets.values.update({
-      spreadsheetId,
-      range: `New Hires!G${hire.rowIndex}:J${hire.rowIndex}`,
-      valueInputOption: 'RAW',
-      requestBody: {
-        values: [[
-          status,
-          result.calendarLink ?? '',
-          result.folderUrl ?? '',
-          new Date().toISOString(),
-        ]],
-      },
-    });
-  }
-}
-```
-
-## Key Decisions
-
-- **Domain-wide delegation with `subject` impersonation** -- the service account acts as the HR admin so that calendar events and emails come from a real person, not a service account address.
-- **Four narrow scopes instead of broad access** -- requesting only `spreadsheets`, `calendar`, `drive`, and `gmail.send` reduces the security surface and simplifies consent review.
-- **Partial failure recovery** -- each API call is wrapped independently so that a Drive failure does not block the calendar event or email. The Sheet records partial status for manual follow-up.
-- **`supportsAllDrives: true` on Drive operations** -- ensures the service works with both personal and shared drives, preventing silent failures when the onboarding folder is on a shared drive.
-- **RFC 2822 message construction for Gmail** -- the Gmail API requires base64url-encoded MIME messages. Building the message manually avoids heavy email library dependencies.
-- **Sheet as the source of truth** -- the orchestrator reads pending hires and writes status back to the same Sheet, making the process visible to HR without a separate dashboard.