@slates-integrations/sharepoint 0.2.0-rc.6

package/src/tools/manage-permissions.ts

@@ -0,0 +1,195 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let getPermissionPrincipal = (permission: any) => {
+  let identities = [
+    permission.grantedToV2,
+    ...(permission.grantedToIdentitiesV2 || []),
+    permission.grantedTo,
+    ...(permission.grantedToIdentities || [])
+  ].filter(Boolean);
+
+  for (let identity of identities) {
+    let principal =
+      identity.user ||
+      identity.siteUser ||
+      identity.group ||
+      identity.siteGroup ||
+      identity.application ||
+      identity.device;
+    if (principal) {
+      return principal;
+    }
+  }
+
+  return null;
+};
+
+let permissionOutputSchema = z.object({
+  permissionId: z.string().describe('Permission ID'),
+  roles: z
+    .array(z.string())
+    .optional()
+    .describe('Permission roles (e.g. "read", "write", "owner")'),
+  grantedTo: z.string().optional().describe('User or group the permission is granted to'),
+  grantedToEmail: z
+    .string()
+    .optional()
+    .describe('Email of the user the permission is granted to'),
+  linkType: z.string().optional().describe('Type of sharing link (if applicable)'),
+  linkScope: z.string().optional().describe('Scope of sharing link'),
+  linkUrl: z.string().optional().describe('URL of the sharing link'),
+  expirationDateTime: z.string().optional().describe('When the permission expires')
+});
+
+export let managePermissions = SlateTool.create(spec, {
+  name: 'Manage Permissions',
+  key: 'manage_permissions',
+  description: `View, grant, and revoke permissions on SharePoint files and folders. Create sharing links, invite users with specific roles, list current permissions, or remove a permission. Works with drive items in document libraries.`,
+  instructions: [
+    'Set **action** to "list" to see all current permissions on an item.',
+    'Set **action** to "createLink" to generate a sharing link. Specify **linkType** (view/edit) and **linkScope** (anonymous/organization/users).',
+    'Set **action** to "invite" to grant access to specific users by email with specified roles.',
+    'Set **action** to "delete" to revoke a specific permission by its ID.'
+  ],
+  tags: {
+    destructive: false,
+    readOnly: false
+  }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['list', 'createLink', 'invite', 'delete'])
+        .describe('Permission action to perform'),
+      driveId: z.string().describe('Drive ID containing the item'),
+      itemId: z.string().describe('Drive item ID to manage permissions for'),
+      linkType: z
+        .enum(['view', 'edit', 'embed'])
+        .optional()
+        .describe('Type of sharing link (for createLink)'),
+      linkScope: z
+        .enum(['anonymous', 'organization', 'users'])
+        .optional()
+        .describe('Scope of the sharing link (for createLink)'),
+      linkExpiration: z
+        .string()
+        .optional()
+        .describe('Expiration datetime in ISO 8601 format (for createLink)'),
+      linkPassword: z
+        .string()
+        .optional()
+        .describe('Password for the sharing link (for createLink)'),
+      recipientEmails: z
+        .array(z.string())
+        .optional()
+        .describe('Email addresses to invite (for invite)'),
+      roles: z
+        .array(z.enum(['read', 'write', 'owner']))
+        .optional()
+        .describe('Roles to assign to invitees (for invite)'),
+      inviteMessage: z
+        .string()
+        .optional()
+        .describe('Message to include in the invitation email (for invite)'),
+      sendInvitation: z
+        .boolean()
+        .optional()
+        .describe('Whether to send an email notification (for invite, default true)'),
+      permissionId: z
+        .string()
+        .optional()
+        .describe('Permission ID to delete (for delete action)')
+    })
+  )
+  .output(
+    z.object({
+      permissions: z.array(permissionOutputSchema).optional().describe('List of permissions'),
+      permission: permissionOutputSchema.optional().describe('Created or updated permission'),
+      deleted: z.boolean().optional().describe('Whether the permission was deleted')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let { action, driveId, itemId } = ctx.input;
+
+    let mapPermission = (p: any) => {
+      let principal = getPermissionPrincipal(p);
+      return {
+        permissionId: p.id,
+        roles: p.roles,
+        grantedTo:
+          principal?.displayName ||
+          principal?.loginName ||
+          principal?.email ||
+          principal?.userPrincipalName ||
+          principal?.id,
+        grantedToEmail: principal?.email || principal?.userPrincipalName,
+        linkType: p.link?.type,
+        linkScope: p.link?.scope,
+        linkUrl: p.link?.webUrl,
+        expirationDateTime: p.expirationDateTime
+      };
+    };
+
+    switch (action) {
+      case 'list': {
+        let data = await client.getDriveItemPermissions(driveId, itemId);
+        let permissions = (data.value || []).map(mapPermission);
+        return {
+          output: { permissions },
+          message: `Found **${permissions.length}** permission(s) on the item.`
+        };
+      }
+
+      case 'createLink': {
+        if (!ctx.input.linkType) throw new Error('linkType is required for createLink.');
+        if (!ctx.input.linkScope) throw new Error('linkScope is required for createLink.');
+        let perm = await client.createSharingLink(
+          driveId,
+          itemId,
+          ctx.input.linkType,
+          ctx.input.linkScope,
+          ctx.input.linkExpiration,
+          ctx.input.linkPassword
+        );
+        return {
+          output: { permission: mapPermission(perm) },
+          message: `Created **${ctx.input.linkType}** sharing link with **${ctx.input.linkScope}** scope.`
+        };
+      }
+
+      case 'invite': {
+        if (!ctx.input.recipientEmails || ctx.input.recipientEmails.length === 0) {
+          throw new Error('recipientEmails are required for invite.');
+        }
+        let roles = ctx.input.roles || ['read'];
+        let data = await client.inviteToItem(
+          driveId,
+          itemId,
+          ctx.input.recipientEmails.map(email => ({ email })),
+          roles,
+          ctx.input.inviteMessage,
+          true,
+          ctx.input.sendInvitation
+        );
+        let permissions = (data.value || []).map(mapPermission);
+        return {
+          output: { permissions },
+          message: `Invited **${ctx.input.recipientEmails.length}** user(s) with **${roles.join(', ')}** role(s).`
+        };
+      }
+
+      case 'delete': {
+        if (!ctx.input.permissionId) throw new Error('permissionId is required for delete.');
+        await client.deletePermission(driveId, itemId, ctx.input.permissionId);
+        return {
+          output: { deleted: true },
+          message: `Deleted permission \`${ctx.input.permissionId}\`.`
+        };
+      }
+    }
+  })
+  .build();

package/src/tools/search-drive.ts

@@ -0,0 +1,61 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let searchResultSchema = z.object({
+  itemId: z.string().describe('Drive item ID'),
+  fileName: z.string().describe('File or folder name'),
+  webUrl: z.string().optional().describe('URL to access the item'),
+  size: z.number().optional().describe('File size in bytes'),
+  isFolder: z.boolean().describe('Whether this is a folder'),
+  lastModifiedDateTime: z.string().optional().describe('Last modified date'),
+  lastModifiedBy: z.string().optional().describe('User who last modified the item'),
+  parentPath: z.string().optional().describe('Path of the parent folder')
+});
+
+export let searchDrive = SlateTool.create(spec, {
+  name: 'Search Drive',
+  key: 'search_drive',
+  description: `Search for files and folders within a specific SharePoint document library (drive). Uses the OneDrive search API scoped to a single drive. Returns matching items with their metadata.`,
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      driveId: z.string().describe('Drive (document library) ID to search within'),
+      query: z.string().describe('Search query text')
+    })
+  )
+  .output(
+    z.object({
+      results: z.array(searchResultSchema).describe('Matching files and folders'),
+      totalCount: z.number().describe('Number of results returned')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let data = await client.searchDriveItems(ctx.input.driveId, ctx.input.query);
+
+    let results = (data.value || []).map((item: any) => ({
+      itemId: item.id,
+      fileName: item.name,
+      webUrl: item.webUrl,
+      size: item.size,
+      isFolder: !!item.folder,
+      lastModifiedDateTime: item.lastModifiedDateTime,
+      lastModifiedBy: item.lastModifiedBy?.user?.displayName,
+      parentPath: item.parentReference?.path
+    }));
+
+    return {
+      output: {
+        results,
+        totalCount: results.length
+      },
+      message: `Found **${results.length}** result(s) for "${ctx.input.query}" in the drive.`
+    };
+  })
+  .build();

package/src/tools/search.ts

@@ -0,0 +1,132 @@
+import { SlateTool } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+let sharepointIdsSchema = z.object({
+  siteId: z.string().optional().describe('SharePoint site ID'),
+  siteUrl: z.string().optional().describe('SharePoint site URL'),
+  webId: z.string().optional().describe('SharePoint web ID'),
+  listId: z.string().optional().describe('SharePoint list ID'),
+  listItemId: z.string().optional().describe('SharePoint list item ID'),
+  listItemUniqueId: z.string().optional().describe('SharePoint list item unique ID'),
+  driveId: z.string().optional().describe('Drive ID'),
+  driveItemId: z.string().optional().describe('Drive item ID'),
+  tenantId: z.string().optional().describe('Tenant ID')
+});
+
+let searchResultSchema = z.object({
+  resourceId: z.string().optional().describe('ID of the matched resource'),
+  hitId: z.string().optional().describe('Hit ID returned by Microsoft Search'),
+  resourceName: z.string().optional().describe('Name or title of the matched resource'),
+  resourceType: z
+    .string()
+    .optional()
+    .describe('Type of the matched resource (e.g. driveItem, site, listItem)'),
+  webUrl: z.string().optional().describe('URL of the resource'),
+  sharepointIds: sharepointIdsSchema.optional().describe('Graph sharepointIds for the resource'),
+  summary: z.string().optional().describe('Search result summary/snippet'),
+  lastModifiedDateTime: z.string().optional().describe('Last modified date'),
+  lastModifiedBy: z.string().optional().describe('User who last modified the resource')
+});
+
+export let search = SlateTool.create(spec, {
+  name: 'Search',
+  key: 'search',
+  description: `Search across SharePoint content using the Microsoft Search API. Search for files, folders, lists, list items, or sites using KQL (Keyword Query Language) queries. Supports filtering by entity type and pagination.`,
+  instructions: [
+    'Use **query** with KQL syntax for powerful searches, e.g. "budget filetype:xlsx" or "author:john".',
+    'Use **entityTypes** to narrow results to specific types: "driveItem" (files/folders), "listItem", "list", "site".',
+    'Use **from** and **size** for pagination.'
+  ],
+  tags: {
+    readOnly: true,
+    destructive: false
+  }
+})
+  .input(
+    z.object({
+      query: z.string().describe('Search query string (supports KQL syntax)'),
+      entityTypes: z
+        .array(z.enum(['driveItem', 'listItem', 'list', 'site']))
+        .optional()
+        .describe('Types of entities to search for. Defaults to all types.'),
+      from: z.number().optional().describe('Offset for pagination (default 0)'),
+      size: z.number().optional().describe('Number of results to return (default 25, max 500)')
+    })
+  )
+  .output(
+    z.object({
+      results: z.array(searchResultSchema).describe('Search results'),
+      totalCount: z.number().describe('Total number of matching results (may be approximate)'),
+      moreResultsAvailable: z.boolean().describe('Whether there are more results to fetch')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = new SharePointClient(ctx.auth.token);
+    let entityTypes = ctx.input.entityTypes?.length
+      ? ctx.input.entityTypes
+      : ['driveItem', 'listItem', 'list', 'site'];
+
+    let data = await client.search(
+      ctx.input.query,
+      entityTypes,
+      ctx.input.from,
+      ctx.input.size
+    );
+
+    let results: Array<any> = [];
+    let totalCount = 0;
+    let moreResultsAvailable = false;
+
+    let hitsContainers = data.value?.[0]?.hitsContainers || [];
+    for (let container of hitsContainers) {
+      totalCount += container.total || 0;
+      moreResultsAvailable = moreResultsAvailable || container.moreResultsAvailable || false;
+
+      for (let hit of container.hits || []) {
+        let resource = hit.resource || {};
+        let sharepointIds =
+          resource.sharepointIds && typeof resource.sharepointIds === 'object'
+            ? {
+                siteId: resource.sharepointIds.siteId,
+                siteUrl: resource.sharepointIds.siteUrl,
+                webId: resource.sharepointIds.webId,
+                listId: resource.sharepointIds.listId,
+                listItemId: resource.sharepointIds.listItemId,
+                listItemUniqueId: resource.sharepointIds.listItemUniqueId,
+                driveId: resource.sharepointIds.driveId,
+                driveItemId: resource.sharepointIds.driveItemId,
+                tenantId: resource.sharepointIds.tenantId
+              }
+            : undefined;
+        results.push({
+          resourceId:
+            resource.id ||
+            sharepointIds?.driveItemId ||
+            sharepointIds?.listItemId ||
+            sharepointIds?.listId ||
+            sharepointIds?.siteId ||
+            hit.hitId,
+          hitId: hit.hitId,
+          resourceName: resource.name || resource.displayName,
+          resourceType: hit.resource?.['@odata.type']?.replace('#microsoft.graph.', ''),
+          webUrl: resource.webUrl,
+          sharepointIds,
+          summary: hit.summary,
+          lastModifiedDateTime: resource.lastModifiedDateTime,
+          lastModifiedBy: resource.lastModifiedBy?.user?.displayName
+        });
+      }
+    }
+
+    return {
+      output: {
+        results,
+        totalCount,
+        moreResultsAvailable
+      },
+      message: `Found **${totalCount}** result(s) for "${ctx.input.query}". Returned ${results.length} in this page.`
+    };
+  })
+  .build();

package/src/triggers/drive-item-changes.ts

@@ -0,0 +1,202 @@
+import { SlateTrigger, SlateDefaultPollingIntervalSeconds } from 'slates';
+import { SharePointClient } from '../lib/client';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let driveItemChanges = SlateTrigger.create(spec, {
+  name: 'Drive Item Changes',
+  key: 'drive_item_changes',
+  description:
+    'Triggers when files or folders are created, updated, or deleted in a SharePoint document library. Polls the drive delta API to detect changes.'
+})
+  .input(
+    z.object({
+      driveId: z.string().describe('Drive ID being monitored'),
+      changeType: z
+        .enum(['created', 'updated', 'deleted'])
+        .describe('Type of change detected'),
+      itemId: z.string().describe('Drive item ID'),
+      fileName: z.string().optional().describe('Name of the file or folder'),
+      isFolder: z.boolean().optional().describe('Whether this item is a folder'),
+      webUrl: z.string().optional().describe('URL of the item'),
+      size: z.number().optional().describe('File size in bytes'),
+      mimeType: z.string().optional().describe('MIME type of the file'),
+      lastModifiedDateTime: z.string().optional().describe('Last modified date'),
+      lastModifiedBy: z.string().optional().describe('User who modified the item'),
+      parentPath: z.string().optional().describe('Parent folder path')
+    })
+  )
+  .output(
+    z.object({
+      driveId: z.string().describe('Drive ID'),
+      itemId: z.string().describe('Drive item ID'),
+      changeType: z.enum(['created', 'updated', 'deleted']).describe('Type of change'),
+      fileName: z.string().optional().describe('Name of the file or folder'),
+      isFolder: z.boolean().optional().describe('Whether this item is a folder'),
+      webUrl: z.string().optional().describe('URL of the item'),
+      size: z.number().optional().describe('File size in bytes'),
+      mimeType: z.string().optional().describe('MIME type of the file'),
+      lastModifiedDateTime: z.string().optional().describe('Last modified date'),
+      lastModifiedBy: z.string().optional().describe('User who modified the item'),
+      parentPath: z.string().optional().describe('Parent folder path')
+    })
+  )
+  .polling({
+    options: {
+      intervalInSeconds: SlateDefaultPollingIntervalSeconds
+    },
+
+    pollEvents: async ctx => {
+      let client = new SharePointClient(ctx.auth.token);
+      let state = ctx.state as {
+        deltaToken?: string;
+        knownItems?: Record<string, string>;
+        driveId?: string;
+        initialized?: boolean;
+      } | null;
+
+      let driveId = state?.driveId;
+
+      if (!driveId) {
+        return {
+          inputs: [],
+          updatedState: {
+            ...state,
+            initialized: false
+          }
+        };
+      }
+
+      let deltaToken = state?.deltaToken;
+      let knownItems = state?.knownItems || {};
+
+      let data = await client.getDelta(driveId, deltaToken);
+      let items = data.value || [];
+      let newDeltaToken = data['@odata.deltaLink'];
+      let nextLink = data['@odata.nextLink'];
+
+      // Process all pages
+      let allItems = [...items];
+      let currentNextLink = nextLink;
+      while (currentNextLink) {
+        let nextData = await client.getDelta(driveId, currentNextLink);
+        allItems = allItems.concat(nextData.value || []);
+        currentNextLink = nextData['@odata.nextLink'];
+        if (nextData['@odata.deltaLink']) {
+          newDeltaToken = nextData['@odata.deltaLink'];
+        }
+      }
+
+      if (!state?.initialized) {
+        let updatedKnown: Record<string, string> = {};
+        for (let item of allItems) {
+          let isDeleted = item.deleted !== undefined || item['@removed'] !== undefined;
+          if (!isDeleted) {
+            updatedKnown[item.id] = item.lastModifiedDateTime || '';
+          }
+        }
+        return {
+          inputs: [],
+          updatedState: {
+            driveId,
+            deltaToken: newDeltaToken,
+            knownItems: updatedKnown,
+            initialized: true
+          }
+        };
+      }
+
+      let inputs: Array<{
+        driveId: string;
+        changeType: 'created' | 'updated' | 'deleted';
+        itemId: string;
+        fileName?: string;
+        isFolder?: boolean;
+        webUrl?: string;
+        size?: number;
+        mimeType?: string;
+        lastModifiedDateTime?: string;
+        lastModifiedBy?: string;
+        parentPath?: string;
+      }> = [];
+
+      let updatedKnown = { ...knownItems };
+
+      for (let item of allItems) {
+        let isDeleted = item.deleted !== undefined || item['@removed'] !== undefined;
+
+        if (isDeleted) {
+          if (knownItems[item.id]) {
+            inputs.push({
+              driveId,
+              changeType: 'deleted',
+              itemId: item.id
+            });
+            delete updatedKnown[item.id];
+          }
+        } else if (!knownItems[item.id]) {
+          inputs.push({
+            driveId,
+            changeType: 'created',
+            itemId: item.id,
+            fileName: item.name,
+            isFolder: !!item.folder,
+            webUrl: item.webUrl,
+            size: item.size,
+            mimeType: item.file?.mimeType,
+            lastModifiedDateTime: item.lastModifiedDateTime,
+            lastModifiedBy: item.lastModifiedBy?.user?.displayName,
+            parentPath: item.parentReference?.path
+          });
+          updatedKnown[item.id] = item.lastModifiedDateTime || '';
+        } else {
+          inputs.push({
+            driveId,
+            changeType: 'updated',
+            itemId: item.id,
+            fileName: item.name,
+            isFolder: !!item.folder,
+            webUrl: item.webUrl,
+            size: item.size,
+            mimeType: item.file?.mimeType,
+            lastModifiedDateTime: item.lastModifiedDateTime,
+            lastModifiedBy: item.lastModifiedBy?.user?.displayName,
+            parentPath: item.parentReference?.path
+          });
+          updatedKnown[item.id] = item.lastModifiedDateTime || '';
+        }
+      }
+
+      return {
+        inputs,
+        updatedState: {
+          driveId,
+          deltaToken: newDeltaToken,
+          knownItems: updatedKnown,
+          initialized: true
+        }
+      };
+    },
+
+    handleEvent: async ctx => {
+      let resourceType = ctx.input.isFolder ? 'folder' : 'file';
+      return {
+        type: `drive_item.${ctx.input.changeType}`,
+        id: `${ctx.input.driveId}_${ctx.input.itemId}_${ctx.input.lastModifiedDateTime || Date.now()}`,
+        output: {
+          driveId: ctx.input.driveId,
+          itemId: ctx.input.itemId,
+          changeType: ctx.input.changeType,
+          fileName: ctx.input.fileName,
+          isFolder: ctx.input.isFolder,
+          webUrl: ctx.input.webUrl,
+          size: ctx.input.size,
+          mimeType: ctx.input.mimeType,
+          lastModifiedDateTime: ctx.input.lastModifiedDateTime,
+          lastModifiedBy: ctx.input.lastModifiedBy,
+          parentPath: ctx.input.parentPath
+        }
+      };
+    }
+  })
+  .build();

package/src/triggers/inbound-webhook.ts

@@ -0,0 +1,67 @@
+import { SlateTrigger } from 'slates';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+/**
+ * Generic inbound webhook for providers without a tailored webhook trigger yet.
+ * POST JSON is parsed into `payload` (non-objects are wrapped as { _value }).
+ * Refine in the workflow mapper or replace with a provider-specific trigger.
+ */
+export let inboundWebhook = SlateTrigger.create(spec, {
+  name: 'Inbound Webhook',
+  key: 'inbound_webhook',
+  description:
+    'Receives HTTP POST at the Slates webhook URL. Parses JSON into payload (or stores raw body if not JSON). Configure your provider to POST here when supported.'
+})
+  .input(
+    z.object({
+      payload: z
+        .record(z.string(), z.any())
+        .describe('Parsed JSON object from the request body'),
+      rawBody: z.string().optional().describe('Raw body when JSON parsing failed'),
+      contentType: z.string().optional().describe('Content-Type header')
+    })
+  )
+  .output(
+    z.object({
+      payload: z.record(z.string(), z.any()),
+      rawBody: z.string().optional()
+    })
+  )
+  .webhook({
+    handleRequest: async ctx => {
+      let contentType = ctx.request.headers.get('content-type') ?? '';
+      let text = await ctx.request.text();
+      if (!text || !text.trim()) {
+        return {
+          inputs: [{ payload: {}, contentType }]
+        };
+      }
+      try {
+        let parsed = JSON.parse(text);
+        let payload =
+          parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : { _value: parsed };
+        return {
+          inputs: [{ payload, contentType }]
+        };
+      } catch {
+        return {
+          inputs: [{ payload: {}, rawBody: text, contentType }]
+        };
+      }
+    },
+
+    handleEvent: async ctx => {
+      return {
+        type: 'webhook.inbound',
+        id: `inbound-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+        output: {
+          payload: ctx.input.payload,
+          rawBody: ctx.input.rawBody
+        }
+      };
+    }
+  })
+  .build();

package/src/triggers/index.ts

@@ -0,0 +1,3 @@
+export * from './list-item-changes';
+export * from './drive-item-changes';
+export * from './inbound-webhook';