> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SharePoint

> Virtualize SharePoint Online sites and document libraries from Node or the browser.

`SharePointVFS` mounts SharePoint Online: every site the token can reach
becomes a folder of its document libraries, each holding its real files as raw
bytes. Site and library names are resolved to Microsoft Graph IDs by the
mount, so no drive ID is needed. Set up the tokens as in [SharePoint setup](https://docs.mirage.strukto.ai/home/setup/sharepoint.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, SharePointVFS, Workspace } from '@struktoai/mirage-node'

const sharepoint = new SharePointVFS({
  accessToken: process.env.MS_GRAPH_DRIVE_TOKEN!,
  tenantHost: 'contoso.sharepoint.com',
})
const ws = new Workspace({ '/sharepoint': sharepoint }, { mode: MountMode.WRITE })

const result = await ws.shell('ls /sharepoint && ls /sharepoint/Engineering')
console.log(result.stdoutText)
await ws.close()
```

`tenantHost` and `siteFilter` narrow the sites listed. `site` and `drive`
together mount one library as the root, and `keyPrefix` one folder inside it.

### Fields

**accessToken** `string | function` *required*

Microsoft Graph bearer token, or a function (sync or async) that returns one; it is called for each request and again after a `401`.

**tenantHost** `string`

SharePoint host, such as `contoso.sharepoint.com`; the `sharepoint` mount lists only the sites whose `webUrl` is on it. The `onedrive` mount ignores it.

**graphBaseUrl** `string`

Full Graph service root, version segment included, for any deployment but the worldwide one: a sovereign cloud, a private endpoint or a test server. Unset uses `https://graph.microsoft.com/v1.0`.

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a Graph request may wait to connect, or between two reads of its answer, before it fails; also how long a server-side copy is polled before it fails as unconfirmed.

**maxRetries** `number` (default: 5)

Times a request is retried after a `429`, `503` or `504` response. Each retry waits what `Retry-After` asks or an exponential backoff, at most 30 seconds.

**siteFilter** `string` (default: '\*')

Search term passed to Graph's `/sites?search=` to choose which sites the mount lists.

**site** `string`

Site, by display name or internal name, that scopes the mount to one document library together with `drive`. With either unset the mount lists every site as `/<site>/<library>/...`.

**drive** `string`

Document library in `site` that the mount uses as its root; takes effect only with `site` set.

**keyPrefix** `string`

Folder path inside the scoped library that the mount uses as its root; takes effect only with `site` and `drive` set. `..` segments are rejected.

Fields marked secret are redacted in snapshots.

## Authentication

`accessToken` is a Microsoft Graph bearer token, or a function (sync or async)
that returns one. A function is called for each request and again after a
`401`, so a long-running mount outlives one token; a plain string lasts about
an hour.

An app-only token works, since the mount reaches sites through `/sites` and
needs no signed-in user. Reads need `Sites.Read.All`; writes need
`Sites.ReadWrite.All`. A delegated token reaches only what its user can.

## Layout

```text theme={null}
/sharepoint/
  Engineering/
    Documents/
      specs/
        api.md
    Design Reviews/
  Marketing/
    Documents/
```

Paths read `/<site>/<library>/<path>`, with the site's display name. The first
two levels are sites and libraries; everything below is a real driveItem.
`/sharepoint/Engineering/Documents/specs/api.md` is the driveItem
`/root:/specs/api.md` in the `Documents` library of the `Engineering` site.

With `site: 'Engineering'` and `drive: 'Documents'`, those two levels
disappear. Adding `keyPrefix: 'team/reports'` makes that folder the root, so
`/sharepoint/q1.csv` is the driveItem `/root:/team/reports/q1.csv`.

## Behavior

* **Scoping:** `drive` takes effect only with `site` set, and `keyPrefix`
  only with both. `..` segments in `keyPrefix` are rejected.
* **Service root:** mounts address `https://graph.microsoft.com/v1.0` unless
  `graphBaseUrl` names another root, given in full with its version segment,
  such as `https://graph.microsoft.us/v1.0`. A token minted for one sovereign
  cloud is rejected by the others, so a mount on the wrong root fails
  outright.
* **Raw bytes:** Office files stay as they are stored, with no conversion.
* **Snapshots:** a snapshot pins each file the agent read to its version, and
  replaying it reads those exact bytes. A file the agent wrote carries no
  version and is not checked on replay. Old versions read only while the
  library keeps them; an admin can cap or turn off versioning.
* **One drive instead:** for a single drive, such as a personal OneDrive or
  one known library, use [OneDrive](https://docs.mirage.strukto.ai/typescript/vfs/onedrive.md).

## Browser

`@struktoai/mirage-browser` exports the same `SharePointVFS` with the same
fields.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { MountMode, SharePointVFS, Workspace } from '@struktoai/mirage-browser'

const sharepoint = new SharePointVFS({ accessToken: () => getMicrosoftGraphToken() })
const ws = new Workspace({ '/sharepoint': sharepoint }, { mode: MountMode.READ })
```

* Pass a token function, such as one backed by the page's sign-in library, so
  a `401` fetches a fresh token and retries.

## Integration

SharePoint answers these commands through its own API, so fewer files are
read. See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: Microsoft Graph search names the files to read,
  for whole words, within one document library; a directory above a library
  is read in full. Every file is read when the search fails or finds nothing.
  Graph searches the text it extracted, not the bytes, and indexes a write
  some time after it lands, so it can miss Office files, PDFs, archives, the
  end of a large file, a word Graph splits differently (`foo.bar`) and recent
  writes. `walk_limit: -1` in the mount's `"@all"`
  [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file instead.
* `grep -r` and `rg` without `-w`: every file is read.
* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with SharePoint mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `sharepoint`, `<mode>` |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   <site>/             # every SharePoint site the account reaches
>     <library>/        # its document libraries (drives)
>       <path>          # the drive's files and folders
> ```
>
> * An unscoped mount reads `/{site_name}/{library_name}/{path_to_file}`.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `sharepoint` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `sharepoint`, `<mode>` |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   <site>/             # every SharePoint site the account reaches
>     <library>/        # its document libraries (drives)
>       <path>          # the drive's files and folders
> ```
>
> - An unscoped mount reads `/{site_name}/{library_name}/{path_to_file}`.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `sharepoint` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.