@slates-integrations/sharepoint 0.2.0-rc.6

package/README.md

@@ -0,0 +1,65 @@
+# <img src="https://provider-logos.metorial-cdn.com/sharepoint-icon.svg" height="20"> Sharepoint
+
+Manage SharePoint sites, document libraries, lists, and files. Create, read, update, and delete lists and list items with custom columns. Upload, download, move, copy, and version files in document libraries. Search across sites, files, folders, lists, and list items using Microsoft Search. Manage permissions at site, list, and item levels with granular access control. Define and manage content types and site columns. Subscribe to webhooks for list and library change notifications. Retrieve site properties and search for sites across Microsoft 365.
+
+## Authentication
+
+When registering the OAuth app in Microsoft Entra ID for local CLI auth, use `http://localhost:45873/callback` as the redirect URI.
+
+## Tools
+
+### Get Content Types
+
+Retrieve content types and site columns for a SharePoint site. Content types define reusable schemas for lists and libraries. Site columns are reusable field definitions that can be added to content types and lists.
+
+### Get Drives
+
+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.
+
+### Get File Versions
+
+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.
+
+### Get Site
+
+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.
+
+### List Sites
+
+Search for SharePoint sites by keyword, or list subsites of a given site. Returns a list of matching sites with their IDs and URLs.
+
+### Manage Columns
+
+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.
+
+### Manage File
+
+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.
+
+### Manage List Items
+
+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.
+
+### Manage List
+
+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.
+
+### Manage Permissions
+
+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.
+
+### Search Drive
+
+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.
+
+### Search
+
+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.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,98 @@
+# Slates Specification for SharePoint
+
+## Overview
+
+SharePoint is Microsoft's cloud-based platform for document management, content collaboration, and intranet sites, available as part of Microsoft 365. It allows teams to create sites, store and organize files, manage lists, and work together from anywhere. SharePoint can be accessed programmatically via two APIs: the legacy SharePoint REST API (for deep SharePoint-specific operations) and the Microsoft Graph API (the recommended, unified approach for accessing SharePoint alongside other Microsoft 365 services).
+
+## Authentication
+
+SharePoint Online uses **OAuth 2.0** via **Microsoft Entra ID** (formerly Azure AD) for authentication. Both the SharePoint REST API and the Microsoft Graph API use OAuth 2.0 as their standard authentication method.
+
+### Setup
+
+You need to register an app in your Azure Active Directory, obtain the Client ID and Client Secret values, and then use those to obtain an Access Token. You will need the following credentials:
+
+- **Tenant ID**: Identifies the Microsoft Entra ID tenant (directory).
+- **Client ID** (Application ID): Identifies the registered application.
+- **Client Secret** or **Certificate**: Used to authenticate the application.
+- **Redirect URI for local CLI auth**: `http://localhost:45873/callback`
+
+### OAuth 2.0 Flows
+
+1. **Authorization Code Flow (Delegated)**: For acting on behalf of a signed-in user. The user signs in and grants consent. The authorization and token endpoints are:
+   - Authorization: `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize`
+   - Token: `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token`
+
+2. **Client Credentials Flow (Application-only)**: The application can interact with data on its own, without a signed-in user. App-only access is used in scenarios such as automation and backup, and is mostly used by apps that run as background services or daemons. The token request uses:
+   - `grant_type=client_credentials`
+   - `scope=https://graph.microsoft.com/.default` (for Microsoft Graph) or `scope=https://{tenant}.sharepoint.com/.default` (for the SharePoint REST API directly)
+
+### Scopes / Permissions
+
+Permissions are configured on the app registration in Microsoft Entra ID. There are two types:
+
+- **Delegated permissions** (scopes): Allow the application to act on behalf of the signed-in user.
+- **Application permissions** (app roles): Allow the app to access data on its own, without a signed-in user.
+
+Key SharePoint-related scopes for Microsoft Graph include:
+
+- `Sites.Read.All`, `Sites.ReadWrite.All`, `Sites.Manage.All`, `Sites.FullControl.All`
+- `Files.Read.All`, `Files.ReadWrite.All`
+- `User.Read`, `offline_access`
+- `Sites.Selected` — restricts an application's access to specific site collections. Now lists, list items, folders, and files are also supported, and all Selected scopes support delegated and application modes.
+
+Application permissions typically require admin consent. Access tokens generated for Microsoft Graph resources are not valid for the SharePoint REST API — use the correct audience (`https://graph.microsoft.com` vs. `https://{tenant}.sharepoint.com`) depending on which API you call.
+
+### Certificate-Based Authentication
+
+For unattended (app-only) access, authentication can also be done using a certificate instead of a client secret. If you want a delegated call on behalf of a user, you don't need certificate authentication.
+
+## Features
+
+### Site Management
+
+The SharePoint API in Microsoft Graph supports access to SharePoint sites, lists, and drives (document libraries), with read-only support for site resources (no ability to create new sites) and read-write support for lists, listItems, and driveItems. You can retrieve site properties, search for sites, and access sites associated with Microsoft 365 groups or Teams.
+
+### Lists and List Items
+
+Lists are the foundation for data storage in SharePoint. You can create lists to store a variety of business data, from a simple customer contact list to a custom business application. When you use columns to define your schema, SharePoint can protect the integrity of your data as well as enable rich indexing, querying, and search capabilities. The API supports full CRUD operations on lists and list items, including defining custom columns.
+
+### Document Libraries and Files
+
+SharePoint stores files in a special list type called a document library. You can use the OneDrive API to work with a library as a drive, or the SharePoint API to work with it as a list. Just like a regular list, you can extend the schema of a Document Library to support your business needs with custom columns. This includes uploading, downloading, moving, copying, and versioning files.
+
+### Search
+
+The Microsoft Search API in Microsoft Graph can search content stored in OneDrive or SharePoint: files, folders, lists, list items, or sites. Search supports filtering by entity type and using KQL query templates.
+
+### Permissions Management
+
+SharePoint supports managing permissions at the site, list, and item level. Through the Graph API and the Selected permissions model, applications can be granted granular access to specific resources. OneDrive for Business and SharePoint support sending notifications of security events on a driveItem. You can subscribe to these events to receive notifications when the permissions on an item change.
+
+### Content Types and Columns
+
+SharePoint allows defining reusable content types and site columns that govern the schema and metadata of lists and libraries. These can be managed via the API.
+
+## Events
+
+SharePoint supports webhooks through two mechanisms: native SharePoint webhooks and Microsoft Graph change notifications (subscriptions).
+
+### SharePoint Native Webhooks (List/Library Changes)
+
+The SharePoint list webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks only support asynchronous events. This means that webhooks are only fired after a change happened (similar to -ed events), and thus synchronous (-ing events) are not possible.
+
+- **Supported resources**: SharePoint lists and document libraries.
+- **Events**: Item added, item updated, item deleted, item moved/renamed, item checked in/out, item attachment changes.
+- The notification doesn't include any information about the changes that triggered it. Your application is expected to use the GetChanges API on the list to query the collection of changes from the change log.
+- **Subscription expiration**: Webhook subscriptions are set to expire after 180 days by default. You need to set an expiration date when creating the subscription, and the expiration date should be less than 180 days.
+- Subscriptions require specifying a notification URL, and SharePoint validates the endpoint upon creation.
+
+### Microsoft Graph Change Notifications (SharePoint Resources)
+
+Change notifications enable applications to receive alerts when a Microsoft Graph resource they're interested in changes (created, updated, or deleted). Microsoft Graph sends notifications to the specified client endpoint.
+
+- **Supported SharePoint resources**: Sites, lists, list items, and drives (document libraries via driveItem hierarchy).
+- **Change types**: `created`, `updated`, `deleted` (specified when creating the subscription).
+- Microsoft Graph supports basic notifications (containing only the resource ID), and rich notifications (including the resource data of the changed object).
+- **Delivery channels**: The Microsoft Graph REST API can deliver change notifications through webhooks, Event Hubs, and Event Grid.
+- Subscriptions must be renewed before expiration. SharePoint currently does not support subscribing to a single folder; you can only subscribe at the list level.

package/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1333.34 1333.34" shape-rendering="geometricPrecision" text-rendering="geometricPrecision" image-rendering="optimizeQuality" fill-rule="evenodd" clip-rule="evenodd"><defs><style>.fil4{fill:#000;fill-rule:nonzero;fill-opacity:.2}</style></defs><g id="Layer_x0020_1"><g id="_2630364347808"><circle cx="625" cy="395.83" r="395.84" fill="#036c70" fill-rule="nonzero"/><circle cx="994.79" cy="744.79" r="338.54" fill="#1a9ba1" fill-rule="nonzero"/><circle cx="666.67" cy="1062.5" r="270.83" fill="#37c6d0" fill-rule="nonzero"/><path d="M694.46 291.67H243.04a396.731 396.731 0 00-13.87 103.92c0 218.62 177.22 395.99 395.84 396.08 11.54 0 22.96-.54 34.29-1.5l.21 1.58c-146.72 3.87-263.68 123.96-263.68 270.74 0 7.01.26 13.96.8 20.85h297.83c30.63-.09 55.46-24.91 55.54-55.55V347.21c-.09-30.63-24.91-55.46-55.55-55.54z" fill-rule="nonzero" fill-opacity=".102"/><path class="fil4" d="M652.79 333.33H234.04c-3.24 20.57-4.93 41.45-4.93 62.3 0 218.64 177.26 395.99 395.9 396.04 11.54 0 22.96-.54 34.29-1.5l.21 1.58c-146.78 3.97-263.69 124.12-263.69 270.95 0 20.98 2.45 41.89 7.25 62.31h249.72c30.63-.09 55.45-24.91 55.54-55.54V388.89c-.09-30.63-24.91-55.45-55.55-55.54z"/><path class="fil4" d="M652.79 333.33H234.04c-3.24 20.57-4.93 41.45-4.93 62.3 0 218.64 177.26 395.99 395.9 396.04 11.54 0 22.96-.54 34.29-1.5l.21 1.58c-138.68 3.65-252.29 111.6-262.93 249.91l256.22.01c30.63-.09 55.45-24.91 55.54-55.54V388.88c-.09-30.63-24.91-55.45-55.55-55.54z"/><path class="fil4" d="M611.13 333.33H234.04c-3.24 20.57-4.93 41.45-4.93 62.3 0 218.64 177.26 395.99 395.9 396.04 11.54 0 22.96-.54 34.29-1.5l.21 1.58c-138.68 3.65-252.29 111.6-262.93 249.91l214.55.01c30.63-.09 55.45-24.91 55.54-55.54V388.88c-.09-30.63-24.91-55.45-55.54-55.54z"/><path d="M55.54 333.33h555.59c30.67 0 55.54 24.87 55.54 55.54v555.58c0 30.67-24.87 55.54-55.54 55.54H55.54C24.87 999.99 0 975.12 0 944.45V388.87c0-30.67 24.87-55.54 55.54-55.54z" fill="#03787c" fill-rule="nonzero"/><path d="M236.25 659.38A110.186 110.186 0 01202 623.12a98.306 98.306 0 01-11.99-47.06c0-.83.02-1.69.04-2.51-.02-.97-.05-1.98-.05-2.96 0-22.39 7.89-44.09 22.25-61.25 15.76-17.96 36.22-31.3 59.01-38.5 25.12-8.29 51.5-12.52 77.98-12.52h2.65c3.7-.08 7.51-.19 11.25-.19 32.21 0 64.34 5.13 94.95 15.07v75c-14.86-9-31.1-15.65-48.04-19.63a234.22 234.22 0 00-55.7-6.74h-.51a121.89 121.89 0 00-57.76 12.22c-13.84 5.97-22.83 19.61-22.87 34.7v.32c0 9.03 3.48 17.73 9.71 24.26A88.548 88.548 0 00309.04 612c10.95 5.44 27.28 12.67 49 21.67 2.41.76 4.77 1.7 7.04 2.79a404.138 404.138 0 0161.82 30.5 110.62 110.62 0 0136.52 36.78c8.7 15.78 13.28 33.51 13.28 51.53 0 1.31-.04 2.67-.07 3.97a103.37 103.37 0 01-20.79 66.88c-14.48 17.63-33.83 30.63-55.62 37.33a251.94 251.94 0 01-75.49 11.57c-1.23 0-2.56-.03-3.75-.03-.5.01-1.17.01-1.67.01-23.47 0-46.98-1.99-70.09-5.92-20.03-3.15-39.7-8.87-58.34-16.84v-79.25c17.87 12.74 37.86 22.29 59.01 28.12 21 6.57 42.93 10.08 64.92 10.42 2.35.15 4.74.23 7.1.23 18.02 0 35.82-4.38 51.78-12.72a39.498 39.498 0 0019.8-34.22c0-.36 0-.72-.02-1.07v-.31c0-10.01-3.99-19.62-11.08-26.69a112.794 112.794 0 00-30.63-21.34c-13.03-6.56-32.28-15.17-57.75-25.83-20.17-8.07-39.6-18.3-57.76-30.22v.01z" fill="#fff" fill-rule="nonzero"/><path fill="none" fill-rule="nonzero" d="M0 0h1333.34v1333.34H0z"/></g></g></svg>

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@slates-integrations/sharepoint",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@slates/oauth-microsoft": "1.0.0-rc.2",
+    "@lowerdeck/error": "^1.1.0",
+    "@types/node": "^20",
+    "slates": "1.0.0-rc.9",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "version": "0.2.0-rc.6"
+}

package/slate.json

@@ -0,0 +1,19 @@
+{
+  "name": "@microsoft/sharepoint",
+  "description": "Manage SharePoint sites, document libraries, lists, and files. Create, read, update, and delete lists and list items with custom columns. Upload, download, move, copy, and version files in document libraries. Search across sites, files, folders, lists, and list items using Microsoft Search. Manage permissions at site, list, and item levels with granular access control. Define and manage content types and site columns. Subscribe to webhooks for list and library change notifications. Retrieve site properties and search for sites across Microsoft 365.",
+  "categories": ["apis-and-http-requests", "document-processing", "email-and-messaging"],
+  "skills": [
+    "manage sites and libraries",
+    "upload and download files",
+    "create and manage lists",
+    "CRUD list items",
+    "search files and sites",
+    "manage permissions",
+    "define content types",
+    "subscribe to webhooks",
+    "version file history",
+    "move and copy files"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/sharepoint-icon.svg",
+  "version": "0.1.11"
+}

package/src/auth.ts

@@ -0,0 +1,69 @@
+import { createMicrosoftGraphOauth } from '@slates/oauth-microsoft';
+import { SlateAuth } from 'slates';
+import { z } from 'zod';
+
+let scopes = [
+  {
+    title: 'Sites Read',
+    description: 'Read items in all site collections',
+    scope: 'Sites.Read.All'
+  },
+  {
+    title: 'Sites Read Write',
+    description: 'Read and write items in all site collections',
+    scope: 'Sites.ReadWrite.All'
+  },
+  {
+    title: 'Sites Manage',
+    description: 'Create, edit, and delete items and lists in all site collections',
+    scope: 'Sites.Manage.All'
+  },
+  {
+    title: 'Sites Full Control',
+    description: 'Full control of all site collections',
+    scope: 'Sites.FullControl.All'
+  },
+  {
+    title: 'Files Read',
+    description: 'Read all files that user can access',
+    scope: 'Files.Read.All'
+  },
+  {
+    title: 'Files Read Write',
+    description: 'Read and write all files that user can access',
+    scope: 'Files.ReadWrite.All'
+  },
+  {
+    title: 'User Read',
+    description: 'Read user profile',
+    scope: 'User.Read'
+  },
+  {
+    title: 'Offline Access',
+    description:
+      'Maintain access to data you have given it access to (enables refresh tokens)',
+    scope: 'offline_access'
+  }
+];
+
+let createMicrosoftOauth = (name: string, key: string, tenant: string) =>
+  createMicrosoftGraphOauth({
+    name,
+    key,
+    tenant,
+    scopes,
+    normalizeRedirectUri: true,
+    missingRefreshTokenMessage:
+      'No refresh token available. Ensure "offline_access" scope is included.'
+  });
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      token: z.string(),
+      refreshToken: z.string().optional(),
+      expiresAt: z.string().optional()
+    })
+  )
+  .addOauth(createMicrosoftOauth('Work & Personal', 'oauth_common', 'common'))
+  .addOauth(createMicrosoftOauth('Work Only', 'oauth_organizations', 'organizations'));

package/src/config.ts

@@ -0,0 +1,4 @@
+import { SlateConfig } from 'slates';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(z.object({}));

package/src/index.ts

@@ -0,0 +1,36 @@
+import { Slate } from 'slates';
+import { spec } from './spec';
+import {
+  getSite,
+  listSites,
+  search,
+  searchDrive,
+  manageList,
+  manageListItems,
+  manageFile,
+  getDrive,
+  getFileVersions,
+  managePermissions,
+  manageColumns,
+  getContentTypes
+} from './tools';
+import { listItemChanges, driveItemChanges, inboundWebhook } from './triggers';
+
+export let provider = Slate.create({
+  spec,
+  tools: [
+    getSite,
+    listSites,
+    search,
+    searchDrive,
+    manageList,
+    manageListItems,
+    manageFile,
+    getDrive,
+    getFileVersions,
+    managePermissions,
+    manageColumns,
+    getContentTypes
+  ],
+  triggers: [inboundWebhook, listItemChanges, driveItemChanges]
+});