SharePoint

SharePoint document libraries via Microsoft Graph. Resolves siteUrl and library names; delegates to the OneDrive adapter for the file operations.

Installation

@azure/identity and @microsoft/microsoft-graph-client are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @azure/identity @microsoft/microsoft-graph-client

pnpm add files-sdk @azure/identity @microsoft/microsoft-graph-client

yarn add files-sdk @azure/identity @microsoft/microsoft-graph-client

bun add files-sdk @azure/identity @microsoft/microsoft-graph-client

SharePoint document libraries via Microsoft Graph. Wraps the onedrive adapter and adds SharePoint-shaped resolution - siteUrl parsing, named documentLibrary lookup, and SHAREPOINT_* env-var fallbacks. Resolution is lazy: the first method call triggers Graph traffic to convert names into drive IDs, then subsequent calls reuse the resolved drive.

import { Files } from "files-sdk";
import { sharepoint } from "files-sdk/sharepoint";

const files = new Files({
  adapter: sharepoint({
    siteUrl: "https://contoso.sharepoint.com/sites/marketing",
    documentLibrary: "Reports", // optional, omit for default library
    clientCredentials: {
      tenantId: process.env.SHAREPOINT_TENANT_ID!,
      clientId: process.env.SHAREPOINT_CLIENT_ID!,
      clientSecret: process.env.SHAREPOINT_CLIENT_SECRET!,
    },
    rootFolderPath: "Uploads",
  }),
});

Options

PropType

siteId?string

Direct SharePoint site ID (`<host>,<id1>,<id2>` triple form from Graph). Mutually exclusive with `siteUrl` / `hostname` / `sitePath`. Falls back to `SHAREPOINT_SITE_ID`.

Typestring

siteUrl?string

SharePoint site URL (e.g. `https://contoso.sharepoint.com/sites/marketing`). Resolved to a site ID on first call via Graph `/sites/{hostname}:{path}`. Falls back to `SHAREPOINT_SITE_URL`.

Typestring

hostname?string

SharePoint hostname (e.g. `contoso.sharepoint.com`). Combine with `sitePath`. Falls back to `SHAREPOINT_HOSTNAME`.

Typestring

sitePath?string

Site path on the hostname (e.g. `/sites/marketing`). Used with `hostname`. Defaults to the tenant root when omitted.

Typestring

documentLibrary?string

Name of the SharePoint document library to target (e.g. `Documents`, `Reports`). Resolved to a drive ID on first call. Omit to use the site's default library. Falls back to `SHAREPOINT_DOCUMENT_LIBRARY`.

Typestring

driveId?string

Explicit drive ID. Skips both site and library resolution entirely. Falls back to `SHAREPOINT_DRIVE_ID`.

Typestring

clientCredentials?OneDriveAdapterOptions["clientCredentials"]

App-only (client credentials) auth. Same shape as `onedrive()`. Falls back to `SHAREPOINT_TENANT_ID` + `SHAREPOINT_CLIENT_ID` + `SHAREPOINT_CLIENT_SECRET`, then to the `ONEDRIVE_*` equivalents.

TypeOneDriveAdapterOptions["clientCredentials"]

oauth?OneDriveAdapterOptions["oauth"]

Delegated OAuth refresh-token auth. Same shape as `onedrive()`.

TypeOneDriveAdapterOptions["oauth"]

accessToken?OneDriveAdapterOptions["accessToken"]

Static or dynamic access token. Same shape as `onedrive()`. Falls back to `SHAREPOINT_ACCESS_TOKEN` then `ONEDRIVE_ACCESS_TOKEN`.

TypeOneDriveAdapterOptions["accessToken"]

client?Client

Pre-built `@microsoft/microsoft-graph-client` `Client`. Same escape hatch as `onedrive()`.

TypeClient

rootFolderPath?string

Logical "bucket root" — virtual keys live under this folder path within the document library. Must already exist on the drive. Defaults to the drive root.

Typestring

publicByDefault?boolean

Mint an anonymous-view sharing link on every upload and return it from `url()`. Defaults to `false` — `url()` throws when off. Subject to tenant link-sharing policy.

Typeboolean

copyTimeoutMs?number

Maximum time (ms) to wait for a copy operation. Same semantics as `onedrive()`.

Typenumber

Limitations

The adapter delegates to onedrive after resolution, so the OneDrive per-method caveats in the table below apply. SharePoint-specific: siteUrl parsing errors and missing documentLibrary names throw Provider on the first method call - resolution is lazy, so construction never fails for these, and the resolved drive is cached for the adapter’s lifetime after 1-2 extra Graph round-trips on first use. delete() moves items to the recycle bin (soft delete).

Compatibility

Method	Status	Notes
`upload`	⚠️	Delegates to `onedrive` after site/library resolution: single-PUT simple upload up to OneDrive’s 250 MB limit; larger bodies (or any `multipart` upload) automatically switch to a chunked Graph upload session. User `metadata` and `cacheControl` throw - Graph drive items have no native arbitrary-metadata field; use `raw` to set Open Extensions if you need them.
`download`	✅
`delete`	✅
`list`	⚠️	Delegates to `onedrive`: returns immediate-children files only at `rootFolderPath` - no recursion, and subfolders are filtered out. `prefix` is filename-prefix only (matched client-side within the page). Pagination uses Graph’s `@odata.nextLink` as the opaque cursor.
`search`	⚠️	Built on `listAll` — inherits this adapter’s `list` behavior above. Client-side key match (glob, regex, substring, exact).
`head`	✅
`exists`	✅
`copy`	⚠️	Delegates to `onedrive`: async copy on Graph (`POST /items/{id}/copy` returns 202 + monitor URL). The adapter polls the monitor every 500 ms until status is `completed`/`failed`, capped by `copyTimeoutMs` (default 60_000). On timeout the call throws `Provider`; tune `copyTimeoutMs` for large files.
`url`	⚠️	Delegates to `onedrive`: throws by default - Graph has no signed URL primitive. With `publicByDefault: true` at construction, `upload()` calls `createLink` (anonymous-view scope) and `url()` returns the share link’s `webUrl`. The link is permanent (`expiresIn` ignored) and `responseContentDisposition` always throws. Anonymous links are blocked on tenants where admins disable them.
`signedUploadUrl`	⚠️	Delegates to `onedrive`: initiates a Graph upload session via `POST /createUploadSession` and returns the session URL as a one-shot PUT (the session URL is pre-authenticated by Graph itself). `maxSize` and `minSize` throw because Graph does not enforce a server-side `content-length-range` policy on upload sessions; enforce size limits at your application gateway instead.

SharePoint

Installation

Usage

Options

Limitations

Compatibility