OneDrive

OneDrive and SharePoint document libraries via Microsoft Graph. Path-addressable, no virtual-key bookkeeping.

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

OneDrive and SharePoint document libraries via the official @microsoft/microsoft-graph-client SDK. Microsoft Graph is path-addressable (/drive/root:/folder/file.txt), so the adapter maps virtual keys onto real OneDrive paths - no virtual-key cache, no fsdkKey bookkeeping. Five auth shapes (app-only, OAuth refresh token, raw access token, pre-built Graph client, or env-var fallback) and four drive targets (/me/drive, driveId, siteId, userId) cover the personal-OneDrive, OneDrive-for-Business, and SharePoint-site-library cases.

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

// App-only auth (client credentials) into a SharePoint site library.
// Cannot use /me/drive - pass driveId, siteId, or userId instead.
const files = new Files({
  adapter: onedrive({
    clientCredentials: {
      tenantId: process.env.ONEDRIVE_TENANT_ID!,
      clientId: process.env.ONEDRIVE_CLIENT_ID!,
      clientSecret: process.env.ONEDRIVE_CLIENT_SECRET!,
    },
    siteId: process.env.ONEDRIVE_SITE_ID!,
    rootFolderPath: "Uploads",
    // publicByDefault: true → upload() also creates an anonymous-view
    //                       sharing link and url() returns its webUrl.
  }),
});

Options

PropType

clientCredentials?

{
    tenantId: string;
    clientId: string;
    clientSecret: string;
  }

App-only (client credentials) auth. Required for unattended access to SharePoint or OneDrive-for-Business — the app acts on its own behalf. Cannot use `/me/drive`; you must pass `driveId`, `siteId`, or `userId` to target a specific drive.

Type

{
    tenantId: string;
    clientId: string;
    clientSecret: string;
  }

oauth?

{
    clientId: string;
    clientSecret: string;
    refreshToken: string;
    tenantId?: string;
  }

Delegated (3-legged) auth via OAuth refresh token. The adapter mints fresh access tokens against `clientId`/`clientSecret`. `tenantId` defaults to `"common"`. Mutually exclusive with the other auth shapes.

Type

{
    clientId: string;
    clientSecret: string;
    refreshToken: string;
    tenantId?: string;
  }

accessToken?string | (() => string | Promise<string>)

Static or dynamic access token. Pass a string for a one-shot token, or an async function to mint fresh tokens on demand (e.g. via `@azure/identity`, NextAuth, or your own broker). The adapter does not cache the result — your callable is responsible for caching/refresh.

Typestring | (() => string | Promise<string>)

client?Client

Pre-built `@microsoft/microsoft-graph-client` `Client` — escape hatch for callers that already wire auth themselves. `signedUploadUrl()` still works because Graph's upload-session URL is pre-authenticated by Graph itself.

TypeClient

driveId?string

Target a specific drive by id (`/drives/{driveId}`). Works with any auth shape; **required** for `clientCredentials` since `/me/drive` is not available without an interactive user. Mutually exclusive with `siteId`/`userId`.

Typestring

siteId?string

Target the default document library of a SharePoint site (`/sites/{siteId}/drive`). Mutually exclusive with `driveId`/`userId`.

Typestring

userId?string

Target a specific user's drive (`/users/{userId}/drive`). Typical with app-only auth. Mutually exclusive with `driveId`/`siteId`.

Typestring

rootFolderPath?string

Logical "bucket root" — virtual keys live under this folder path, which must already exist on the drive. Defaults to the drive root.

Typestring

publicByDefault?boolean

When `true`, `upload()` also creates an anonymous-view sharing link and `url()` returns that link's `webUrl`. When `false` (default), `url()` throws — Graph has no signed URL primitive for private items. **Tenant policy note:** anonymous links are blocked on tenants where an admin has disabled them. Upload will surface Graph's `accessDenied` error in that case.

Typeboolean

copyTimeoutMs?number

Maximum time (ms) to wait for an async copy operation to complete. Graph returns 202 + a monitor URL; the adapter polls until completed or this timeout elapses, at which point the call throws `Provider`. Defaults to 60_000.

Typenumber

Compatibility

Method	Status	Notes
`upload`	⚠️	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. `multipart.partSize` tunes the chunk size (rounded to a 320 KiB multiple). 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`	⚠️	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`	⚠️	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`	⚠️	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 - Graph has no Content-Disposition override. Anonymous links are blocked on tenants where admins disable them.
`signedUploadUrl`	⚠️	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.

OneDrive

Installation

Usage

Options

Compatibility