slates 0.0.2 → 1.0.0-rc.1

package/example/google-sheets/tools/manage-rows-columns.ts

@@ -0,0 +1,160 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let manageRowsColumnsTool = SlateTool.create(spec, {
+  name: 'Manage Rows and Columns',
+  key: 'manage_rows_columns',
+  description: `Insert, delete, or resize rows and columns in a Google Sheets spreadsheet.
+Supports bulk operations and auto-resizing to fit content.`,
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      sheetId: z.number().describe('ID of the sheet'),
+      dimension: z.enum(['ROWS', 'COLUMNS']).describe('Whether to operate on rows or columns'),
+      operation: z
+        .enum(['insert', 'delete', 'append', 'autoResize'])
+        .describe('Operation to perform'),
+      startIndex: z
+        .number()
+        .optional()
+        .describe('Start index (0-based) for insert/delete operations'),
+      endIndex: z
+        .number()
+        .optional()
+        .describe('End index (exclusive) for insert/delete operations'),
+      count: z.number().optional().describe('Number of rows/columns to append'),
+      inheritFromBefore: z
+        .boolean()
+        .optional()
+        .describe('Inherit formatting from row/column before (insert only)')
+    })
+  )
+  .output(
+    z.object({
+      operationPerformed: z.string().describe('Description of the operation performed'),
+      affectedRange: z
+        .object({
+          dimension: z.enum(['ROWS', 'COLUMNS']).describe('Dimension affected'),
+          startIndex: z.number().optional().describe('Start index'),
+          endIndex: z.number().optional().describe('End index'),
+          count: z.number().optional().describe('Count affected')
+        })
+        .describe('Range that was affected')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+
+    switch (ctx.input.operation) {
+      case 'insert': {
+        if (ctx.input.startIndex === undefined || ctx.input.endIndex === undefined) {
+          throw new Error('startIndex and endIndex are required for insert operation');
+        }
+        await client.insertDimension(
+          ctx.input.spreadsheetId,
+          ctx.input.sheetId,
+          ctx.input.dimension,
+          ctx.input.startIndex,
+          ctx.input.endIndex,
+          ctx.input.inheritFromBefore
+        );
+        let count = ctx.input.endIndex - ctx.input.startIndex;
+        return {
+          output: {
+            operationPerformed: `Inserted ${count} ${ctx.input.dimension.toLowerCase()} at index ${ctx.input.startIndex}`,
+            affectedRange: {
+              dimension: ctx.input.dimension,
+              startIndex: ctx.input.startIndex,
+              endIndex: ctx.input.endIndex,
+              count
+            }
+          },
+          message: `Inserted **${count}** ${ctx.input.dimension.toLowerCase()} starting at index ${ctx.input.startIndex}.`
+        };
+      }
+
+      case 'delete': {
+        if (ctx.input.startIndex === undefined || ctx.input.endIndex === undefined) {
+          throw new Error('startIndex and endIndex are required for delete operation');
+        }
+        await client.deleteDimension(
+          ctx.input.spreadsheetId,
+          ctx.input.sheetId,
+          ctx.input.dimension,
+          ctx.input.startIndex,
+          ctx.input.endIndex
+        );
+        let count = ctx.input.endIndex - ctx.input.startIndex;
+        return {
+          output: {
+            operationPerformed: `Deleted ${count} ${ctx.input.dimension.toLowerCase()} from index ${ctx.input.startIndex}`,
+            affectedRange: {
+              dimension: ctx.input.dimension,
+              startIndex: ctx.input.startIndex,
+              endIndex: ctx.input.endIndex,
+              count
+            }
+          },
+          message: `Deleted **${count}** ${ctx.input.dimension.toLowerCase()} starting at index ${ctx.input.startIndex}.`
+        };
+      }
+
+      case 'append': {
+        if (ctx.input.count === undefined) {
+          throw new Error('count is required for append operation');
+        }
+        await client.appendDimension(
+          ctx.input.spreadsheetId,
+          ctx.input.sheetId,
+          ctx.input.dimension,
+          ctx.input.count
+        );
+        return {
+          output: {
+            operationPerformed: `Appended ${ctx.input.count} ${ctx.input.dimension.toLowerCase()}`,
+            affectedRange: {
+              dimension: ctx.input.dimension,
+              count: ctx.input.count
+            }
+          },
+          message: `Appended **${ctx.input.count}** ${ctx.input.dimension.toLowerCase()} to the sheet.`
+        };
+      }
+
+      case 'autoResize': {
+        await client.autoResizeDimensions(
+          ctx.input.spreadsheetId,
+          ctx.input.sheetId,
+          ctx.input.dimension,
+          ctx.input.startIndex,
+          ctx.input.endIndex
+        );
+        let rangeDesc =
+          ctx.input.startIndex !== undefined && ctx.input.endIndex !== undefined
+            ? `from index ${ctx.input.startIndex} to ${ctx.input.endIndex}`
+            : 'all';
+        return {
+          output: {
+            operationPerformed: `Auto-resized ${ctx.input.dimension.toLowerCase()} ${rangeDesc}`,
+            affectedRange: {
+              dimension: ctx.input.dimension,
+              startIndex: ctx.input.startIndex,
+              endIndex: ctx.input.endIndex
+            }
+          },
+          message: `Auto-resized ${ctx.input.dimension.toLowerCase()} to fit content.`
+        };
+      }
+
+      default:
+        throw new Error(`Unknown operation: ${ctx.input.operation}`);
+    }
+  })
+  .build();

package/example/google-sheets/tools/manage-sheets.ts

@@ -0,0 +1,183 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let manageSheetsTool = SlateTool.create(spec, {
+  name: 'Manage Sheets',
+  key: 'manage_sheets',
+  description: `Manages sheets (tabs) within a Google Sheets spreadsheet.
+Supports adding, deleting, duplicating, renaming, and reordering sheets.`,
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      operation: z
+        .enum(['add', 'delete', 'duplicate', 'rename', 'move', 'hide', 'show'])
+        .describe('Operation to perform'),
+      sheetId: z
+        .number()
+        .optional()
+        .describe(
+          'ID of the sheet to operate on (required for delete, duplicate, rename, move, hide, show)'
+        ),
+      title: z.string().optional().describe('Title for new sheet (add) or new name (rename)'),
+      index: z
+        .number()
+        .optional()
+        .describe('Index position for new sheet (add, duplicate) or new position (move)'),
+      rowCount: z.number().optional().describe('Initial row count for new sheet'),
+      columnCount: z.number().optional().describe('Initial column count for new sheet')
+    })
+  )
+  .output(
+    z.object({
+      sheetId: z.number().optional().describe('ID of the created/modified sheet'),
+      title: z.string().optional().describe('Title of the sheet'),
+      index: z.number().optional().describe('Index position of the sheet'),
+      operationPerformed: z.string().describe('Description of the operation performed')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+    let output: {
+      sheetId?: number;
+      title?: string;
+      index?: number;
+      operationPerformed: string;
+    };
+
+    switch (ctx.input.operation) {
+      case 'add': {
+        let result = await client.addSheet(ctx.input.spreadsheetId, {
+          title: ctx.input.title,
+          index: ctx.input.index,
+          gridProperties: {
+            rowCount: ctx.input.rowCount,
+            columnCount: ctx.input.columnCount
+          }
+        });
+        output = {
+          sheetId: result?.sheetId,
+          title: result?.title,
+          index: result?.index,
+          operationPerformed: `Added sheet "${result?.title}"`
+        };
+        break;
+      }
+
+      case 'delete': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for delete operation');
+        }
+        await client.deleteSheet(ctx.input.spreadsheetId, ctx.input.sheetId);
+        output = {
+          sheetId: ctx.input.sheetId,
+          operationPerformed: `Deleted sheet with ID ${ctx.input.sheetId}`
+        };
+        break;
+      }
+
+      case 'duplicate': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for duplicate operation');
+        }
+        let result = await client.duplicateSheet(ctx.input.spreadsheetId, ctx.input.sheetId, {
+          newSheetName: ctx.input.title,
+          insertSheetIndex: ctx.input.index
+        });
+        output = {
+          sheetId: result?.sheetId,
+          title: result?.title,
+          index: result?.index,
+          operationPerformed: `Duplicated sheet to "${result?.title}"`
+        };
+        break;
+      }
+
+      case 'rename': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for rename operation');
+        }
+        if (!ctx.input.title) {
+          throw new Error('title is required for rename operation');
+        }
+        await client.updateSheetProperties(
+          ctx.input.spreadsheetId,
+          { sheetId: ctx.input.sheetId, title: ctx.input.title, index: 0 },
+          'title'
+        );
+        output = {
+          sheetId: ctx.input.sheetId,
+          title: ctx.input.title,
+          operationPerformed: `Renamed sheet to "${ctx.input.title}"`
+        };
+        break;
+      }
+
+      case 'move': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for move operation');
+        }
+        if (ctx.input.index === undefined) {
+          throw new Error('index is required for move operation');
+        }
+        await client.updateSheetProperties(
+          ctx.input.spreadsheetId,
+          { sheetId: ctx.input.sheetId, index: ctx.input.index, title: '' },
+          'index'
+        );
+        output = {
+          sheetId: ctx.input.sheetId,
+          index: ctx.input.index,
+          operationPerformed: `Moved sheet to index ${ctx.input.index}`
+        };
+        break;
+      }
+
+      case 'hide': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for hide operation');
+        }
+        await client.updateSheetProperties(
+          ctx.input.spreadsheetId,
+          { sheetId: ctx.input.sheetId, hidden: true, index: 0, title: '' },
+          'hidden'
+        );
+        output = {
+          sheetId: ctx.input.sheetId,
+          operationPerformed: `Hidden sheet with ID ${ctx.input.sheetId}`
+        };
+        break;
+      }
+
+      case 'show': {
+        if (ctx.input.sheetId === undefined) {
+          throw new Error('sheetId is required for show operation');
+        }
+        await client.updateSheetProperties(
+          ctx.input.spreadsheetId,
+          { sheetId: ctx.input.sheetId, hidden: false, index: 0, title: '' },
+          'hidden'
+        );
+        output = {
+          sheetId: ctx.input.sheetId,
+          operationPerformed: `Shown sheet with ID ${ctx.input.sheetId}`
+        };
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown operation: ${ctx.input.operation}`);
+    }
+
+    return {
+      output,
+      message: output.operationPerformed
+    };
+  })
+  .build();

package/example/google-sheets/tools/merge-cells.ts

@@ -0,0 +1,76 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let mergeCellsTool = SlateTool.create(spec, {
+  name: 'Merge Cells',
+  key: 'merge_cells',
+  description: `Merges or unmerges cells in a Google Sheets spreadsheet.
+Supports merging all cells in a range, merging cells column by column, or row by row.`,
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      sheetId: z.number().describe('ID of the sheet'),
+      startRowIndex: z.number().describe('Start row index (0-based)'),
+      endRowIndex: z.number().describe('End row index (exclusive)'),
+      startColumnIndex: z.number().describe('Start column index (0-based)'),
+      endColumnIndex: z.number().describe('End column index (exclusive)'),
+      operation: z.enum(['merge', 'unmerge']).describe('Whether to merge or unmerge cells'),
+      mergeType: z
+        .enum(['MERGE_ALL', 'MERGE_COLUMNS', 'MERGE_ROWS'])
+        .optional()
+        .describe(
+          'Type of merge: MERGE_ALL (single cell), MERGE_COLUMNS (merge within columns), MERGE_ROWS (merge within rows)'
+        )
+    })
+  )
+  .output(
+    z.object({
+      operationPerformed: z.string().describe('Description of the operation performed'),
+      range: z.string().describe('Description of the affected range')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+
+    let range = {
+      sheetId: ctx.input.sheetId,
+      startRowIndex: ctx.input.startRowIndex,
+      endRowIndex: ctx.input.endRowIndex,
+      startColumnIndex: ctx.input.startColumnIndex,
+      endColumnIndex: ctx.input.endColumnIndex
+    };
+
+    if (ctx.input.operation === 'merge') {
+      await client.mergeCells(
+        ctx.input.spreadsheetId,
+        range,
+        ctx.input.mergeType || 'MERGE_ALL'
+      );
+    } else {
+      await client.unmergeCells(ctx.input.spreadsheetId, range);
+    }
+
+    let rowCount = ctx.input.endRowIndex - ctx.input.startRowIndex;
+    let colCount = ctx.input.endColumnIndex - ctx.input.startColumnIndex;
+
+    let output = {
+      operationPerformed:
+        ctx.input.operation === 'merge'
+          ? `Merged cells (${ctx.input.mergeType || 'MERGE_ALL'})`
+          : 'Unmerged cells',
+      range: `${rowCount} row(s) x ${colCount} column(s)`
+    };
+
+    return {
+      output,
+      message: `${ctx.input.operation === 'merge' ? 'Merged' : 'Unmerged'} cells in range (${rowCount} x ${colCount}).`
+    };
+  })
+  .build();

package/example/google-sheets/tools/named-ranges.ts

@@ -0,0 +1,82 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let namedRangesTool = SlateTool.create(spec, {
+  name: 'Manage Named Ranges',
+  key: 'manage_named_ranges',
+  description: `Creates or deletes named ranges in a Google Sheets spreadsheet.
+Named ranges allow you to reference a cell range by name instead of A1 notation, making formulas more readable.`,
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      operation: z.enum(['create', 'delete']).describe('Operation to perform'),
+      name: z.string().optional().describe('Name for the range (required for create)'),
+      namedRangeId: z.string().optional().describe('ID of the named range to delete'),
+      sheetId: z
+        .number()
+        .optional()
+        .describe('Sheet ID containing the range (required for create)'),
+      startRowIndex: z.number().optional().describe('Start row index (0-based)'),
+      endRowIndex: z.number().optional().describe('End row index (exclusive)'),
+      startColumnIndex: z.number().optional().describe('Start column index (0-based)'),
+      endColumnIndex: z.number().optional().describe('End column index (exclusive)')
+    })
+  )
+  .output(
+    z.object({
+      namedRangeId: z.string().optional().describe('ID of the named range'),
+      name: z.string().optional().describe('Name of the range'),
+      operationPerformed: z.string().describe('Description of the operation')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+
+    if (ctx.input.operation === 'create') {
+      if (!ctx.input.name) {
+        throw new Error('name is required for create operation');
+      }
+      if (ctx.input.sheetId === undefined) {
+        throw new Error('sheetId is required for create operation');
+      }
+
+      let namedRangeId = await client.addNamedRange(ctx.input.spreadsheetId, ctx.input.name, {
+        sheetId: ctx.input.sheetId,
+        startRowIndex: ctx.input.startRowIndex,
+        endRowIndex: ctx.input.endRowIndex,
+        startColumnIndex: ctx.input.startColumnIndex,
+        endColumnIndex: ctx.input.endColumnIndex
+      });
+
+      return {
+        output: {
+          namedRangeId,
+          name: ctx.input.name,
+          operationPerformed: `Created named range "${ctx.input.name}"`
+        },
+        message: `Created named range **"${ctx.input.name}"** with ID \`${namedRangeId}\`.`
+      };
+    } else {
+      if (!ctx.input.namedRangeId) {
+        throw new Error('namedRangeId is required for delete operation');
+      }
+
+      await client.deleteNamedRange(ctx.input.spreadsheetId, ctx.input.namedRangeId);
+
+      return {
+        output: {
+          namedRangeId: ctx.input.namedRangeId,
+          operationPerformed: 'Deleted named range'
+        },
+        message: `Deleted named range with ID \`${ctx.input.namedRangeId}\`.`
+      };
+    }
+  })
+  .build();

package/example/google-sheets/tools/protect-range.ts

@@ -0,0 +1,100 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let protectRangeTool = SlateTool.create(spec, {
+  name: 'Protect Range',
+  key: 'protect_range',
+  description: `Protects or unprotects a range of cells in a Google Sheets spreadsheet.
+Protected ranges prevent unauthorized users from editing specified cells.`,
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      operation: z.enum(['protect', 'unprotect']).describe('Whether to protect or unprotect'),
+      sheetId: z.number().optional().describe('ID of the sheet (required for protect)'),
+      startRowIndex: z.number().optional().describe('Start row index (0-based)'),
+      endRowIndex: z.number().optional().describe('End row index (exclusive)'),
+      startColumnIndex: z.number().optional().describe('Start column index (0-based)'),
+      endColumnIndex: z.number().optional().describe('End column index (exclusive)'),
+      protectedRangeId: z
+        .number()
+        .optional()
+        .describe('ID of the protected range to remove (for unprotect)'),
+      description: z.string().optional().describe('Description of why the range is protected'),
+      warningOnly: z.boolean().optional().describe('Show warning instead of blocking edits'),
+      editors: z
+        .object({
+          users: z
+            .array(z.string())
+            .optional()
+            .describe('Email addresses of users who can edit'),
+          groups: z
+            .array(z.string())
+            .optional()
+            .describe('Email addresses of groups who can edit'),
+          domainUsersCanEdit: z.boolean().optional().describe('Allow all domain users to edit')
+        })
+        .optional()
+        .describe('Users/groups allowed to edit the protected range')
+    })
+  )
+  .output(
+    z.object({
+      protectedRangeId: z.number().optional().describe('ID of the protected range'),
+      operationPerformed: z.string().describe('Description of the operation')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+
+    if (ctx.input.operation === 'protect') {
+      if (ctx.input.sheetId === undefined) {
+        throw new Error('sheetId is required for protect operation');
+      }
+
+      let protectedRangeId = await client.addProtectedRange(
+        ctx.input.spreadsheetId,
+        {
+          sheetId: ctx.input.sheetId,
+          startRowIndex: ctx.input.startRowIndex,
+          endRowIndex: ctx.input.endRowIndex,
+          startColumnIndex: ctx.input.startColumnIndex,
+          endColumnIndex: ctx.input.endColumnIndex
+        },
+        {
+          description: ctx.input.description,
+          warningOnly: ctx.input.warningOnly,
+          editors: ctx.input.editors
+        }
+      );
+
+      return {
+        output: {
+          protectedRangeId,
+          operationPerformed: 'Created protected range'
+        },
+        message: `Protected range created with ID **${protectedRangeId}**.`
+      };
+    } else {
+      if (ctx.input.protectedRangeId === undefined) {
+        throw new Error('protectedRangeId is required for unprotect operation');
+      }
+
+      await client.deleteProtectedRange(ctx.input.spreadsheetId, ctx.input.protectedRangeId);
+
+      return {
+        output: {
+          protectedRangeId: ctx.input.protectedRangeId,
+          operationPerformed: 'Removed protected range'
+        },
+        message: `Removed protected range with ID **${ctx.input.protectedRangeId}**.`
+      };
+    }
+  })
+  .build();

package/example/google-sheets/tools/read-values.ts

@@ -0,0 +1,94 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { SheetsClient } from '../lib/client';
+import { spec } from '../spec';
+
+export let readValuesTool = SlateTool.create(spec, {
+  name: 'Read Values',
+  key: 'read_values',
+  description: `Reads cell values from a Google Sheets spreadsheet.
+Supports reading a single range or multiple ranges in one request. Values can be returned as formatted strings, raw values, or formulas.`,
+  instructions: [
+    'Use A1 notation for ranges (e.g., "Sheet1!A1:B10", "A1:C5")',
+    'Omit sheet name to read from the first sheet'
+  ],
+  tags: {
+    destructive: false,
+    readOnly: true
+  }
+})
+  .input(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      ranges: z
+        .array(z.string())
+        .describe('Ranges to read in A1 notation (e.g., ["Sheet1!A1:B10", "Sheet2!C1:D5"])'),
+      valueRenderOption: z
+        .enum(['FORMATTED_VALUE', 'UNFORMATTED_VALUE', 'FORMULA'])
+        .optional()
+        .describe(
+          'How values should be rendered: FORMATTED_VALUE (display value), UNFORMATTED_VALUE (raw value), or FORMULA'
+        ),
+      dateTimeRenderOption: z
+        .enum(['SERIAL_NUMBER', 'FORMATTED_STRING'])
+        .optional()
+        .describe('How dates should be rendered'),
+      majorDimension: z
+        .enum(['ROWS', 'COLUMNS'])
+        .optional()
+        .describe('Whether to return data row-by-row or column-by-column')
+    })
+  )
+  .output(
+    z.object({
+      spreadsheetId: z.string().describe('ID of the spreadsheet'),
+      valueRanges: z
+        .array(
+          z.object({
+            range: z.string().optional().describe('The range that was read'),
+            majorDimension: z
+              .enum(['ROWS', 'COLUMNS'])
+              .optional()
+              .describe('How the data is organized'),
+            values: z
+              .array(z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])))
+              .optional()
+              .describe('2D array of cell values')
+          })
+        )
+        .describe('Values for each requested range')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SheetsClient({ token: ctx.auth.token });
+
+    let result = await client.batchGetValues(ctx.input.spreadsheetId, ctx.input.ranges, {
+      valueRenderOption: ctx.input.valueRenderOption,
+      dateTimeRenderOption: ctx.input.dateTimeRenderOption,
+      majorDimension: ctx.input.majorDimension
+    });
+
+    let totalCells = 0;
+    for (let vr of result.valueRanges || []) {
+      if (vr.values) {
+        for (let row of vr.values) {
+          totalCells += row.length;
+        }
+      }
+    }
+
+    let output = {
+      spreadsheetId: result.spreadsheetId || ctx.input.spreadsheetId,
+      valueRanges: (result.valueRanges || []).map(vr => ({
+        range: vr.range,
+        majorDimension: vr.majorDimension,
+        values: vr.values
+      }))
+    };
+
+    return {
+      output,
+      message: `Read **${totalCells}** cells from **${ctx.input.ranges.length}** range(s).`
+    };
+  })
+  .build();