@slates-integrations/sharepoint 0.2.0-rc.6

package/src/tools/get-drive.ts

@@ -0,0 +1,96 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { oneOfRequiredError } from './errors';
+import { z } from 'zod';
+
+let driveOutputSchema = z.object({
+  driveId: z.string().describe('Unique drive ID'),
+  driveName: z.string().describe('Display name of the drive'),
+  driveType: z.string().optional().describe('Type of drive (e.g. "documentLibrary")'),
+  webUrl: z.string().optional().describe('URL of the drive'),
+  createdDateTime: z.string().optional().describe('When the drive was created'),
+  lastModifiedDateTime: z.string().optional().describe('When the drive was last modified'),
+  totalSize: z.number().optional().describe('Total storage quota in bytes'),
+  usedSize: z.number().optional().describe('Used storage in bytes'),
+  remainingSize: z.number().optional().describe('Remaining storage in bytes'),
+  ownerName: z.string().optional().describe('Display name of the drive owner')
+});
+
+export let getDrive = SlateTool.create(spec, {
+  name: 'Get Drives',
+  key: 'get_drive',
+  description: `Retrieve document libraries (drives) for a SharePoint site. Can get the default drive, a specific drive by ID, or list all drives on a site. Drives are the containers for files in SharePoint.`,
+  instructions: [
+    'Provide **siteId** with **listAll** set to true to list all drives on a site.',
+    'Provide **driveId** to retrieve a specific drive by ID.',
+    'Provide **siteId** without **listAll** to get the default document library.'
+  ],
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      siteId: z.string().optional().describe('SharePoint site ID'),
+      driveId: z.string().optional().describe('Specific drive ID to retrieve'),
+      listAll: z.boolean().optional().describe('If true, list all drives on the site')
+    })
+  )
+  .output(
+    z.object({
+      drive: driveOutputSchema.optional().describe('Single drive details'),
+      drives: z
+        .array(driveOutputSchema)
+        .optional()
+        .describe('All drives (when listAll is true)')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+
+    let mapDrive = (d: any) => ({
+      driveId: d.id,
+      driveName: d.name,
+      driveType: d.driveType,
+      webUrl: d.webUrl,
+      createdDateTime: d.createdDateTime,
+      lastModifiedDateTime: d.lastModifiedDateTime,
+      totalSize: d.quota?.total,
+      usedSize: d.quota?.used,
+      remainingSize: d.quota?.remaining,
+      ownerName: d.owner?.user?.displayName
+    });
+
+    if (ctx.input.driveId) {
+      let drive = await client.getDrive(ctx.input.driveId);
+      return {
+        output: { drive: mapDrive(drive) },
+        message: `Retrieved drive **${drive.name}** (\`${drive.id}\`).`
+      };
+    }
+
+    if (!ctx.input.siteId) {
+      throw oneOfRequiredError('One of siteId or driveId must be provided.', [
+        'siteId',
+        'driveId'
+      ]);
+    }
+
+    if (ctx.input.listAll) {
+      let data = await client.listDrives(ctx.input.siteId);
+      let drives = (data.value || []).map(mapDrive);
+      return {
+        output: { drives },
+        message: `Found **${drives.length}** drive(s) on the site.`
+      };
+    }
+
+    let drive = await client.getDefaultDrive(ctx.input.siteId);
+    return {
+      output: { drive: mapDrive(drive) },
+      message: `Retrieved default drive **${drive.name}** (\`${drive.id}\`).`
+    };
+  })
+  .build();

package/src/tools/get-file-versions.ts

@@ -0,0 +1,53 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let versionSchema = z.object({
+  versionId: z.string().describe('Version ID'),
+  lastModifiedDateTime: z.string().optional().describe('When this version was created'),
+  lastModifiedBy: z.string().optional().describe('User who created this version'),
+  size: z.number().optional().describe('Size of this version in bytes')
+});
+
+export let getFileVersions = SlateTool.create(spec, {
+  name: 'Get File Versions',
+  key: 'get_file_versions',
+  description: `Retrieve the version history of a file in a SharePoint document library. Returns all versions with their IDs, timestamps, and authors. Useful for auditing changes or rolling back to a previous version.`,
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      driveId: z.string().describe('Drive (document library) ID'),
+      itemId: z.string().describe('File item ID')
+    })
+  )
+  .output(
+    z.object({
+      versions: z.array(versionSchema).describe('File version history'),
+      totalCount: z.number().describe('Number of versions')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let data = await client.listDriveItemVersions(ctx.input.driveId, ctx.input.itemId);
+
+    let versions = (data.value || []).map((v: any) => ({
+      versionId: v.id,
+      lastModifiedDateTime: v.lastModifiedDateTime,
+      lastModifiedBy: v.lastModifiedBy?.user?.displayName,
+      size: v.size
+    }));
+
+    return {
+      output: {
+        versions,
+        totalCount: versions.length
+      },
+      message: `Found **${versions.length}** version(s) for the file.`
+    };
+  })
+  .build();

package/src/tools/get-site.ts

@@ -0,0 +1,79 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { oneOfRequiredError } from './errors';
+import { z } from 'zod';
+
+export let getSite = SlateTool.create(spec, {
+  name: 'Get Site',
+  key: 'get_site',
+  description: `Retrieve detailed information about a SharePoint site. Look up a site by its ID, hostname and path, or get the root site. Also supports listing subsites of a given site.`,
+  instructions: [
+    'Provide **siteId** to look up a specific site by ID.',
+    'Provide **hostname** (e.g. "contoso.sharepoint.com") and optionally **sitePath** (e.g. "sites/marketing") to look up by URL.',
+    'Set **getRootSite** to true to get the tenant root site.'
+  ],
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      siteId: z.string().optional().describe('SharePoint site ID'),
+      hostname: z
+        .string()
+        .optional()
+        .describe('SharePoint site hostname, e.g. "contoso.sharepoint.com"'),
+      sitePath: z
+        .string()
+        .optional()
+        .describe('Relative path on the hostname, e.g. "sites/marketing"'),
+      getRootSite: z
+        .boolean()
+        .optional()
+        .describe('If true, returns the root site of the tenant')
+    })
+  )
+  .output(
+    z.object({
+      siteId: z.string().describe('Unique site ID'),
+      siteName: z.string().describe('Display name of the site'),
+      siteDescription: z.string().nullable().describe('Site description'),
+      webUrl: z.string().describe('Full URL of the site'),
+      createdDateTime: z.string().optional().describe('When the site was created'),
+      lastModifiedDateTime: z.string().optional().describe('When the site was last modified'),
+      hostname: z.string().optional().describe('Hostname of the site')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let site: any;
+
+    if (ctx.input.getRootSite) {
+      site = await client.getRootSite();
+    } else if (ctx.input.hostname) {
+      site = await client.getSiteByHostnameAndPath(ctx.input.hostname, ctx.input.sitePath);
+    } else if (ctx.input.siteId) {
+      site = await client.getSite(ctx.input.siteId);
+    } else {
+      throw oneOfRequiredError(
+        'One of siteId, hostname, or getRootSite must be provided.',
+        ['siteId', 'hostname', 'getRootSite']
+      );
+    }
+
+    return {
+      output: {
+        siteId: site.id,
+        siteName: site.displayName || site.name,
+        siteDescription: site.description || null,
+        webUrl: site.webUrl,
+        createdDateTime: site.createdDateTime,
+        lastModifiedDateTime: site.lastModifiedDateTime,
+        hostname: site.siteCollection?.hostname
+      },
+      message: `Retrieved site **${site.displayName || site.name}** at ${site.webUrl}.`
+    };
+  })
+  .build();

package/src/tools/index.ts

@@ -0,0 +1,12 @@
+export * from './get-site';
+export * from './list-sites';
+export * from './search';
+export * from './search-drive';
+export * from './manage-list';
+export * from './manage-list-items';
+export * from './manage-file';
+export * from './get-drive';
+export * from './get-file-versions';
+export * from './manage-permissions';
+export * from './manage-columns';
+export * from './get-content-types';

package/src/tools/list-sites.ts

@@ -0,0 +1,76 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { oneOfRequiredError } from './errors';
+import { z } from 'zod';
+
+let siteSchema = z.object({
+  siteId: z.string().describe('Unique site ID'),
+  siteName: z.string().describe('Display name of the site'),
+  siteDescription: z.string().nullable().describe('Site description'),
+  webUrl: z.string().describe('Full URL of the site'),
+  createdDateTime: z.string().optional().describe('When the site was created'),
+  lastModifiedDateTime: z.string().optional().describe('When the site was last modified')
+});
+
+export let listSites = SlateTool.create(spec, {
+  name: 'List Sites',
+  key: 'list_sites',
+  description: `Search for SharePoint sites by keyword, or list subsites of a given site. Returns a list of matching sites with their IDs and URLs.`,
+  instructions: [
+    'Provide a **searchQuery** to find sites across the tenant.',
+    'Provide a **parentSiteId** to list subsites of a specific site.'
+  ],
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      searchQuery: z
+        .string()
+        .optional()
+        .describe('Keyword to search for sites across the tenant'),
+      parentSiteId: z.string().optional().describe('Site ID to list subsites of')
+    })
+  )
+  .output(
+    z.object({
+      sites: z.array(siteSchema).describe('List of matching sites'),
+      totalCount: z.number().describe('Number of sites returned')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let result: any;
+
+    if (ctx.input.parentSiteId) {
+      result = await client.listSubsites(ctx.input.parentSiteId);
+    } else if (ctx.input.searchQuery) {
+      result = await client.searchSites(ctx.input.searchQuery);
+    } else {
+      throw oneOfRequiredError(
+        'One of searchQuery or parentSiteId must be provided.',
+        ['searchQuery', 'parentSiteId']
+      );
+    }
+
+    let sites = (result.value || []).map((site: any) => ({
+      siteId: site.id,
+      siteName: site.displayName || site.name,
+      siteDescription: site.description || null,
+      webUrl: site.webUrl,
+      createdDateTime: site.createdDateTime,
+      lastModifiedDateTime: site.lastModifiedDateTime
+    }));
+
+    return {
+      output: {
+        sites,
+        totalCount: sites.length
+      },
+      message: `Found **${sites.length}** site(s)${ctx.input.searchQuery ? ` matching "${ctx.input.searchQuery}"` : ''}.`
+    };
+  })
+  .build();

package/src/tools/manage-columns.ts

@@ -0,0 +1,159 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let columnOutputSchema = z.object({
+  columnId: z.string().describe('Column ID'),
+  columnName: z.string().describe('Internal name of the column'),
+  displayName: z.string().describe('Display name of the column'),
+  columnDescription: z.string().optional().describe('Column description'),
+  columnType: z
+    .string()
+    .optional()
+    .describe('Column type (text, number, boolean, dateTime, choice, etc.)'),
+  required: z.boolean().optional().describe('Whether the column is required'),
+  readOnly: z.boolean().optional().describe('Whether the column is read-only'),
+  hidden: z.boolean().optional().describe('Whether the column is hidden'),
+  choices: z.array(z.string()).optional().describe('Available choices (for choice columns)')
+});
+
+export let manageColumns = SlateTool.create(spec, {
+  name: 'Manage Columns',
+  key: 'manage_columns',
+  description: `List, create, update, or delete columns (fields) on a SharePoint list. Columns define the schema and metadata structure of a list. Supports various column types including text, number, boolean, dateTime, choice, currency, and personOrGroup.`,
+  instructions: [
+    'Set **action** to "list" to view all columns, "create" to add a new column, "update" to modify an existing column, or "delete" to remove a column.',
+    'For "create", provide **columnName**, **columnType**, and optionally **choices** (for choice columns).',
+    'For "update", provide **columnId** and the fields to update.'
+  ],
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['list', 'create', 'update', 'delete'])
+        .describe('Column action to perform'),
+      siteId: z.string().describe('SharePoint site ID'),
+      listId: z.string().describe('SharePoint list ID'),
+      columnId: z.string().optional().describe('Column ID (required for update, delete)'),
+      columnName: z.string().optional().describe('Column name (for create)'),
+      columnDescription: z
+        .string()
+        .optional()
+        .describe('Column description (for create, update)'),
+      columnType: z
+        .enum(['text', 'number', 'boolean', 'dateTime', 'choice', 'currency', 'personOrGroup'])
+        .optional()
+        .describe('Column type (for create)'),
+      required: z
+        .boolean()
+        .optional()
+        .describe('Whether the column is required (for create, update)'),
+      choices: z
+        .array(z.string())
+        .optional()
+        .describe('Available choices for choice columns (for create)')
+    })
+  )
+  .output(
+    z.object({
+      column: columnOutputSchema.optional().describe('Column details (for create, update)'),
+      columns: z
+        .array(columnOutputSchema)
+        .optional()
+        .describe('List of columns (for list action)'),
+      deleted: z.boolean().optional().describe('Whether the column was deleted')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let {
+      action,
+      siteId,
+      listId,
+      columnId,
+      columnName,
+      columnDescription,
+      columnType,
+      required,
+      choices
+    } = ctx.input;
+
+    let detectType = (col: any): string => {
+      if (col.text) return 'text';
+      if (col.number) return 'number';
+      if (col.boolean) return 'boolean';
+      if (col.dateTime) return 'dateTime';
+      if (col.choice) return 'choice';
+      if (col.currency) return 'currency';
+      if (col.personOrGroup) return 'personOrGroup';
+      if (col.lookup) return 'lookup';
+      if (col.calculated) return 'calculated';
+      return 'unknown';
+    };
+
+    let mapColumn = (col: any) => ({
+      columnId: col.id,
+      columnName: col.name,
+      displayName: col.displayName || col.name,
+      columnDescription: col.description,
+      columnType: detectType(col),
+      required: col.required,
+      readOnly: col.readOnly,
+      hidden: col.hidden,
+      choices: col.choice?.choices
+    });
+
+    switch (action) {
+      case 'list': {
+        let data = await client.listColumns(siteId, listId);
+        let columns = (data.value || []).map(mapColumn);
+        return {
+          output: { columns },
+          message: `Found **${columns.length}** column(s) on the list.`
+        };
+      }
+
+      case 'create': {
+        if (!columnName) throw new Error('columnName is required for create.');
+        if (!columnType) throw new Error('columnType is required for create.');
+        let column = await client.createColumn(siteId, listId, {
+          name: columnName,
+          description: columnDescription,
+          type: columnType,
+          required,
+          choices
+        });
+        return {
+          output: { column: mapColumn(column) },
+          message: `Created column **${columnName}** (${columnType}).`
+        };
+      }
+
+      case 'update': {
+        if (!columnId) throw new Error('columnId is required for update.');
+        let updates: { description?: string; required?: boolean } = {};
+        if (columnDescription !== undefined) updates.description = columnDescription;
+        if (required !== undefined) updates.required = required;
+        let column = await client.updateColumn(siteId, listId, columnId, updates);
+        return {
+          output: { column: mapColumn(column) },
+          message: `Updated column \`${columnId}\`.`
+        };
+      }
+
+      case 'delete': {
+        if (!columnId) throw new Error('columnId is required for delete.');
+        await client.deleteColumn(siteId, listId, columnId);
+        return {
+          output: { deleted: true },
+          message: `Deleted column \`${columnId}\`.`
+        };
+      }
+    }
+  })
+  .build();