@slates-integrations/sharepoint 0.2.0-rc.6

package/src/tools/manage-file.ts

@@ -0,0 +1,262 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { oneOfRequiredError } from './errors';
+import { z } from 'zod';
+
+let fileOutputSchema = z.object({
+  itemId: z.string().describe('Drive item ID'),
+  fileName: z.string().describe('Name of the file or folder'),
+  webUrl: z.string().optional().describe('URL to access the item'),
+  downloadUrl: z.string().optional().describe('Direct download URL (for files)'),
+  size: z.number().optional().describe('Size in bytes'),
+  mimeType: z.string().optional().describe('MIME type of the file'),
+  isFolder: z.boolean().describe('Whether this is a folder'),
+  createdDateTime: z.string().optional().describe('When the item was created'),
+  lastModifiedDateTime: z.string().optional().describe('When the item was last modified'),
+  createdBy: z.string().optional().describe('User who created the item'),
+  lastModifiedBy: z.string().optional().describe('User who last modified the item'),
+  parentPath: z.string().optional().describe('Path of the parent folder')
+});
+
+export let manageFile = SlateTool.create(spec, {
+  name: 'Manage File',
+  key: 'manage_file',
+  description: `Upload, download, move, copy, rename, or delete files and folders in a SharePoint document library. Also supports creating folders and listing folder contents. Use this for all file and folder operations within document libraries.`,
+  instructions: [
+    'Set **action** to "upload", "download", "get", "list", "createFolder", "move", "copy", "rename", or "delete".',
+    'For **upload**, provide **fileContent** (text/base64), **fileName**, and either **parentPath** or **parentFolderId**.',
+    'For **download**, returns the download URL of the file.',
+    "For **list**, provide **driveId** and optionally **folderId** to list a specific folder's contents.",
+    'For **move**, provide **destinationFolderId** in the same drive.',
+    'For **copy**, provide **destinationDriveId** and **destinationFolderId**.'
+  ],
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum([
+          'upload',
+          'download',
+          'get',
+          'list',
+          'createFolder',
+          'move',
+          'copy',
+          'rename',
+          'delete'
+        ])
+        .describe('File action to perform'),
+      driveId: z.string().describe('Drive (document library) ID'),
+      itemId: z
+        .string()
+        .optional()
+        .describe('Drive item ID (required for get, download, move, copy, rename, delete)'),
+      itemPath: z
+        .string()
+        .optional()
+        .describe(
+          'Path to the item relative to the drive root (alternative to itemId for get)'
+        ),
+      fileName: z
+        .string()
+        .optional()
+        .describe('File or folder name (for upload, createFolder, rename, copy)'),
+      fileContent: z
+        .string()
+        .optional()
+        .describe('File content as text (for upload, max ~4MB)'),
+      parentPath: z
+        .string()
+        .optional()
+        .describe('Parent folder path relative to drive root (for upload)'),
+      parentFolderId: z
+        .string()
+        .optional()
+        .describe('Parent folder ID (for upload, createFolder)'),
+      folderId: z
+        .string()
+        .optional()
+        .describe('Folder ID to list contents of (for list action)'),
+      destinationFolderId: z
+        .string()
+        .optional()
+        .describe('Destination folder ID (for move, copy)'),
+      destinationDriveId: z
+        .string()
+        .optional()
+        .describe('Destination drive ID (for copy across drives)'),
+      newName: z.string().optional().describe('New name (for rename)')
+    })
+  )
+  .output(
+    z.object({
+      file: fileOutputSchema.optional().describe('File/folder details'),
+      files: z
+        .array(fileOutputSchema)
+        .optional()
+        .describe('List of files and folders (for list action)'),
+      downloadUrl: z.string().optional().describe('Direct download URL (for download action)'),
+      deleted: z.boolean().optional().describe('Whether the item was deleted'),
+      copied: z.boolean().optional().describe('Whether the copy was initiated'),
+      copyMonitorUrl: z
+        .string()
+        .optional()
+        .describe('Monitor URL returned by Microsoft Graph for async copy operations')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let {
+      action,
+      driveId,
+      itemId,
+      itemPath,
+      fileName,
+      fileContent,
+      parentPath,
+      parentFolderId,
+      folderId,
+      destinationFolderId,
+      destinationDriveId,
+      newName
+    } = ctx.input;
+
+    let mapItem = (item: any) => ({
+      itemId: item.id,
+      fileName: item.name,
+      webUrl: item.webUrl,
+      downloadUrl: item['@microsoft.graph.downloadUrl'],
+      size: item.size,
+      mimeType: item.file?.mimeType,
+      isFolder: !!item.folder,
+      createdDateTime: item.createdDateTime,
+      lastModifiedDateTime: item.lastModifiedDateTime,
+      createdBy: item.createdBy?.user?.displayName,
+      lastModifiedBy: item.lastModifiedBy?.user?.displayName,
+      parentPath: item.parentReference?.path
+    });
+
+    switch (action) {
+      case 'get': {
+        let item: any;
+        if (itemPath) {
+          item = await client.getDriveItemByPath(driveId, itemPath);
+        } else if (itemId) {
+          item = await client.getDriveItem(driveId, itemId);
+        } else {
+          throw oneOfRequiredError(
+            'For get action, one of itemId or itemPath must be provided.',
+            ['itemId', 'itemPath']
+          );
+        }
+        return {
+          output: { file: mapItem(item) },
+          message: `Retrieved **${item.name}** (${item.folder ? 'folder' : `${item.size} bytes`}).`
+        };
+      }
+
+      case 'list': {
+        let data = await client.listDriveItems(driveId, folderId);
+        let files = (data.value || []).map(mapItem);
+        return {
+          output: { files },
+          message: `Found **${files.length}** item(s) in the folder.`
+        };
+      }
+
+      case 'upload': {
+        if (!fileName) throw new Error('fileName is required for upload.');
+        if (fileContent === undefined) throw new Error('fileContent is required for upload.');
+        let item: any;
+        if (parentFolderId) {
+          item = await client.uploadSmallFileToFolder(
+            driveId,
+            parentFolderId,
+            fileName,
+            fileContent
+          );
+        } else {
+          let path = parentPath || '';
+          item = await client.uploadSmallFile(driveId, path, fileName, fileContent);
+        }
+        return {
+          output: { file: mapItem(item) },
+          message: `Uploaded **${fileName}** (${item.size} bytes).`
+        };
+      }
+
+      case 'download': {
+        if (!itemId) throw new Error('itemId is required for download.');
+        let downloadUrl = await client.getFileDownloadUrl(driveId, itemId);
+        return {
+          output: { downloadUrl },
+          message: `Download URL generated for item \`${itemId}\`.`
+        };
+      }
+
+      case 'createFolder': {
+        if (!fileName) throw new Error('fileName is required for createFolder.');
+        let parent = parentFolderId || 'root';
+        let item = await client.createFolder(driveId, parent, fileName);
+        return {
+          output: { file: mapItem(item) },
+          message: `Created folder **${fileName}**.`
+        };
+      }
+
+      case 'move': {
+        if (!itemId) throw new Error('itemId is required for move.');
+        if (!destinationFolderId) throw new Error('destinationFolderId is required for move.');
+        let item = await client.moveDriveItem(driveId, itemId, destinationFolderId, newName);
+        return {
+          output: { file: mapItem(item) },
+          message: `Moved item to folder \`${destinationFolderId}\`.`
+        };
+      }
+
+      case 'copy': {
+        if (!itemId) throw new Error('itemId is required for copy.');
+        if (!destinationFolderId) throw new Error('destinationFolderId is required for copy.');
+        let targetDrive = destinationDriveId || driveId;
+        let copy = await client.copyDriveItem(
+          driveId,
+          itemId,
+          targetDrive,
+          destinationFolderId,
+          fileName
+        );
+        return {
+          output: {
+            copied: true,
+            copyMonitorUrl: copy.copyMonitorUrl
+          },
+          message: `Copy initiated for item \`${itemId}\`.`
+        };
+      }
+
+      case 'rename': {
+        if (!itemId) throw new Error('itemId is required for rename.');
+        if (!newName) throw new Error('newName is required for rename.');
+        let item = await client.renameDriveItem(driveId, itemId, newName);
+        return {
+          output: { file: mapItem(item) },
+          message: `Renamed item to **${newName}**.`
+        };
+      }
+
+      case 'delete': {
+        if (!itemId) throw new Error('itemId is required for delete.');
+        await client.deleteDriveItem(driveId, itemId);
+        return {
+          output: { deleted: true },
+          message: `Deleted item \`${itemId}\`.`
+        };
+      }
+    }
+  })
+  .build();

package/src/tools/manage-list-items.ts

@@ -0,0 +1,203 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let listItemOutputSchema = z.object({
+  itemId: z.string().describe('List item ID'),
+  webUrl: z.string().optional().describe('URL of the list item'),
+  createdDateTime: z.string().optional().describe('When the item was created'),
+  lastModifiedDateTime: z.string().optional().describe('When the item was last modified'),
+  createdBy: z.string().optional().describe('User who created the item'),
+  lastModifiedBy: z.string().optional().describe('User who last modified the item'),
+  fields: z
+    .record(z.string(), z.any())
+    .optional()
+    .describe('Custom field values of the list item')
+});
+
+export let manageListItems = SlateTool.create(spec, {
+  name: 'Manage List Items',
+  key: 'manage_list_items',
+  description: `Full CRUD operations on SharePoint list items. Create, read, update, delete, or list items in a SharePoint list. Supports OData filtering and ordering when listing items. Field values match the list's column schema.`,
+  instructions: [
+    'Set **action** to "get", "list", "create", "update", or "delete".',
+    'When creating or updating, pass **fields** as a key-value object matching the list column names.',
+    'When listing, use **filter** for OData filter expressions (e.g. "fields/Status eq \'Active\'") and **orderBy** for sorting.',
+    'For pagination, set **top** to limit page size. If the response includes **nextLink**, pass it as **skipToken** in the next request to get the next page (do not use $skip — SharePoint Lists API does not support it).',
+    'SharePoint requires columns referenced in **filter** or **orderBy** to be indexed. If a query fails with "Field X cannot be referenced in filter or orderby as it is not indexed", either index the column in SharePoint (Site Settings → List settings → Indexed columns) or retry with **allowUnindexedQuery: true** to send the "Prefer: HonorNonIndexedQueriesWarningMayFailRandomly" header (may fail on lists with >5000 items).'
+  ],
+  constraints: ['Maximum of 5000 items can be returned in a single list request.'],
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['get', 'list', 'create', 'update', 'delete'])
+        .describe('Action to perform'),
+      siteId: z.string().describe('SharePoint site ID'),
+      listId: z.string().describe('SharePoint list ID'),
+      itemId: z
+        .string()
+        .optional()
+        .describe('List item ID (required for get, update, delete)'),
+      fields: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe('Field values for create or update, keyed by column name'),
+      filter: z.string().optional().describe('OData filter expression for list action'),
+      orderBy: z.string().optional().describe('OData orderby expression for list action'),
+      top: z
+        .number()
+        .optional()
+        .describe('Maximum number of items to return (for list action)'),
+      skipToken: z
+        .string()
+        .optional()
+        .describe(
+          "Pagination token from a previous response's **nextLink** field; pass this instead of repeating filter/orderBy/top to fetch the next page."
+        ),
+      allowUnindexedQuery: z
+        .boolean()
+        .optional()
+        .describe(
+          'Set true to send "Prefer: HonorNonIndexedQueriesWarningMayFailRandomly" — lets you filter/orderBy on non-indexed columns. May fail on lists with >5000 items. Prefer indexing the column in SharePoint instead.'
+        )
+    })
+  )
+  .output(
+    z.object({
+      item: listItemOutputSchema
+        .optional()
+        .describe('Single list item (for get, create, update)'),
+      items: z
+        .array(listItemOutputSchema)
+        .optional()
+        .describe('List of items (for list action)'),
+      deleted: z
+        .boolean()
+        .optional()
+        .describe('Whether the item was deleted (for delete action)'),
+      totalCount: z.number().optional().describe('Number of items returned (for list action)'),
+      nextLink: z
+        .string()
+        .optional()
+        .describe('Pagination token — pass as **skipToken** to get the next page')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let {
+      action,
+      siteId,
+      listId,
+      itemId,
+      fields,
+      filter,
+      orderBy,
+      top,
+      skipToken,
+      allowUnindexedQuery
+    } = ctx.input;
+
+    let mapItem = (item: any) => ({
+      itemId: item.id,
+      webUrl: item.webUrl,
+      createdDateTime: item.createdDateTime,
+      lastModifiedDateTime: item.lastModifiedDateTime,
+      createdBy: item.createdBy?.user?.displayName,
+      lastModifiedBy: item.lastModifiedBy?.user?.displayName,
+      fields: item.fields
+    });
+
+    switch (action) {
+      case 'get': {
+        if (!itemId) throw new Error('itemId is required for get action.');
+        let item = await client.getListItem(siteId, listId, itemId);
+        return {
+          output: { item: mapItem(item) },
+          message: `Retrieved list item \`${itemId}\`.`
+        };
+      }
+
+      case 'list': {
+        let data: any;
+        try {
+          data = await client.listListItems(siteId, listId, {
+            expand: 'fields',
+            filter,
+            orderby: orderBy,
+            top,
+            skipToken,
+            allowUnindexedQuery
+          });
+        } catch (err: any) {
+          let apiMsg =
+            err?.response?.data?.error?.message ?? err?.response?.data?.message ?? '';
+          let combined = `${err?.message || ''} ${apiMsg}`;
+          let notIndexed = /is not indexed|HonorNonIndexedQueriesWarningMayFailRandomly/i.test(
+            combined
+          );
+          if (notIndexed && !allowUnindexedQuery) {
+            let fieldMatch = combined.match(/Field '([^']+)'/);
+            let fieldName = fieldMatch?.[1];
+            let status = err?.response?.status;
+            let baseMsg = `HTTP ${status ?? 400}: ${apiMsg || err?.message || 'Unindexed column referenced in filter/orderby'}`;
+            throw new Error(
+              `${baseMsg}\n\nTo resolve, either:\n` +
+                `  1. Index the column${fieldName ? ` '${fieldName}'` : ''} in SharePoint: Site Settings → List settings → Indexed columns → Create a new index. This is the recommended long-term fix.\n` +
+                `  2. Retry this tool with **allowUnindexedQuery: true** to send the "Prefer: HonorNonIndexedQueriesWarningMayFailRandomly" header. Works for lists with <5000 items; may fail on larger lists.`
+            );
+          }
+          throw err;
+        }
+        let items = (data.value || []).map(mapItem);
+        let nextLink: string | undefined = data['@odata.nextLink'];
+        return {
+          output: { items, totalCount: items.length, nextLink },
+          message: `Found **${items.length}** item(s) in the list.${nextLink ? ' More pages available.' : ''}`
+        };
+      }
+
+      case 'create': {
+        if (!fields || Object.keys(fields).length === 0) {
+          throw new Error('fields are required for create action.');
+        }
+        let item = await client.createListItem(siteId, listId, fields);
+        return {
+          output: { item: mapItem(item) },
+          message: `Created new list item \`${item.id}\`.`
+        };
+      }
+
+      case 'update': {
+        if (!itemId) throw new Error('itemId is required for update action.');
+        if (!fields || Object.keys(fields).length === 0) {
+          throw new Error('fields are required for update action.');
+        }
+        let updatedFields = await client.updateListItem(siteId, listId, itemId, fields);
+        return {
+          output: {
+            item: {
+              itemId,
+              fields: updatedFields
+            }
+          },
+          message: `Updated list item \`${itemId}\`.`
+        };
+      }
+
+      case 'delete': {
+        if (!itemId) throw new Error('itemId is required for delete action.');
+        await client.deleteListItem(siteId, listId, itemId);
+        return {
+          output: { deleted: true },
+          message: `Deleted list item \`${itemId}\`.`
+        };
+      }
+    }
+  })
+  .build();

package/src/tools/manage-list.ts

@@ -0,0 +1,133 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let listOutputSchema = z.object({
+  listId: z.string().describe('Unique list ID'),
+  listName: z.string().describe('Display name of the list'),
+  listDescription: z.string().nullable().describe('List description'),
+  webUrl: z.string().optional().describe('URL of the list'),
+  createdDateTime: z.string().optional().describe('When the list was created'),
+  lastModifiedDateTime: z.string().optional().describe('When the list was last modified'),
+  template: z.string().optional().describe('List template type'),
+  itemCount: z.number().optional().describe('Number of items in the list')
+});
+
+export let manageList = SlateTool.create(spec, {
+  name: 'Manage List',
+  key: 'manage_list',
+  description: `Create, read, update, or delete SharePoint lists within a site. Also supports listing all lists on a site. Lists are the foundation for data storage in SharePoint and can represent custom business data, contact lists, task trackers, and more.`,
+  instructions: [
+    'Set **action** to "get" to retrieve a single list, "list" to list all lists on a site, "create" to create a new list, "update" to rename or re-describe a list, or "delete" to remove a list.',
+    'For "create", provide **displayName** and optionally **template** (defaults to "genericList").'
+  ],
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['get', 'list', 'create', 'update', 'delete'])
+        .describe('Action to perform'),
+      siteId: z.string().describe('SharePoint site ID'),
+      listId: z.string().optional().describe('List ID (required for get, update, delete)'),
+      displayName: z
+        .string()
+        .optional()
+        .describe('Display name for the list (for create/update)'),
+      description: z
+        .string()
+        .optional()
+        .describe('Description for the list (for create/update)'),
+      template: z
+        .string()
+        .optional()
+        .describe(
+          'List template, e.g. "genericList", "documentLibrary", "events" (for create, defaults to "genericList")'
+        )
+    })
+  )
+  .output(
+    z.object({
+      list: listOutputSchema
+        .optional()
+        .describe('Single list details (for get, create, update)'),
+      lists: z.array(listOutputSchema).optional().describe('All lists (for list action)'),
+      deleted: z
+        .boolean()
+        .optional()
+        .describe('Whether the list was deleted (for delete action)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let { action, siteId, listId, displayName, description, template } = ctx.input;
+
+    let mapList = (l: any) => ({
+      listId: l.id,
+      listName: l.displayName,
+      listDescription: l.description || null,
+      webUrl: l.webUrl,
+      createdDateTime: l.createdDateTime,
+      lastModifiedDateTime: l.lastModifiedDateTime,
+      template: l.list?.template,
+      itemCount: l.list?.contentTypesEnabled != null ? undefined : undefined
+    });
+
+    switch (action) {
+      case 'get': {
+        if (!listId) throw new Error('listId is required for get action.');
+        let list = await client.getList(siteId, listId);
+        return {
+          output: { list: mapList(list) },
+          message: `Retrieved list **${list.displayName}** (${list.id}).`
+        };
+      }
+
+      case 'list': {
+        let data = await client.listLists(siteId);
+        let lists = (data.value || []).map(mapList);
+        return {
+          output: { lists },
+          message: `Found **${lists.length}** list(s) on site.`
+        };
+      }
+
+      case 'create': {
+        if (!displayName) throw new Error('displayName is required for create action.');
+        let list = await client.createList(siteId, displayName, template || 'genericList');
+        if (description) {
+          list = await client.updateList(siteId, list.id, { description });
+        }
+        return {
+          output: { list: mapList(list) },
+          message: `Created list **${displayName}**.`
+        };
+      }
+
+      case 'update': {
+        if (!listId) throw new Error('listId is required for update action.');
+        let updates: any = {};
+        if (displayName) updates.displayName = displayName;
+        if (description !== undefined) updates.description = description;
+        let list = await client.updateList(siteId, listId, updates);
+        return {
+          output: { list: mapList(list) },
+          message: `Updated list **${list.displayName}**.`
+        };
+      }
+
+      case 'delete': {
+        if (!listId) throw new Error('listId is required for delete action.');
+        await client.deleteList(siteId, listId);
+        return {
+          output: { deleted: true },
+          message: `Deleted list \`${listId}\`.`
+        };
+      }
+    }
+  })
+  .build();