Skip to content

SharePointGraphClient

SharePointGraphClient is a comprehensive Microsoft Graph API client for SharePoint Online. It covers site discovery, drive (document library) operations, file management, folder operations, list management, and Microsoft 365 Group lifecycle.

Import

import { SharePointGraphClient } from "@modernpath/agent-framework";

Constructor

new SharePointGraphClient(opts?: { baseUrl?: string })
Parameter Type Default Description
opts.baseUrl string "https://graph.microsoft.com/v1.0" Microsoft Graph API base URL. Override for testing or sovereign clouds.

Site Discovery

Method Signature Description
getRootSite getRootSite(token: string): Promise<SharePointSite> Gets the root site of the tenant.
getSite getSite(token: string, siteId: string): Promise<SharePointSite> Gets a site by its ID (format: {hostname},{siteCollectionId},{webId}).
getSiteByPath getSiteByPath(token: string, hostname: string, sitePath: string): Promise<SharePointSite> Gets a site by its path (e.g. contoso.sharepoint.com, teams/hr).
getGroupSite getGroupSite(token: string, groupId: string): Promise<SharePointSite> Gets the SharePoint site for a Microsoft 365 Group.
provisionGroupSite provisionGroupSite(token: string, groupId: string): Promise<SharePointSite \| null> Provisions/ensures a SharePoint site exists for a group. Returns null if still provisioning.
searchSites searchSites(token: string, query: string, opts?): Promise<{ sites, nextLink? }> Searches SharePoint sites. Pass "*" to enumerate all accessible sites.
listSubsites listSubsites(token: string, siteId: string): Promise<{ sites, nextLink? }> Lists subsites of a site.

Drive Operations

Method Signature Description
getDefaultDrive getDefaultDrive(token: string, siteId: string): Promise<SharePointDrive> Gets the default document library for a site.
listDrives listDrives(token: string, siteId: string): Promise<SharePointDrive[]> Lists all drives (document libraries) in a site.
getDrive getDrive(token: string, siteId: string, driveId: string): Promise<SharePointDrive> Gets a specific drive by ID.

File Operations

Method Signature Description
listDocuments listDocuments(token, siteId, options?): Promise<{ documents, nextPageToken? }> Lists documents with optional folder path, file type filter, and search query.
listItems listItems(token, siteId, folderPath?): Promise<{ items, nextPageToken? }> Lists both files and folders, sorted with folders first.
getDocument getDocument(token, siteId, documentId): Promise<SharePointDocument> Gets a document's metadata by ID.
downloadDocument downloadDocument(token, siteId, documentId): Promise<Buffer> Downloads a document's content as a Buffer.
uploadFile uploadFile(token, siteId, options): Promise<SharePointDocument> Uploads a file (up to 4MB). For larger files, use upload sessions.
deleteItem deleteItem(token, siteId, itemId): Promise<void> Deletes a file or folder.
createFolder createFolder(token, siteId, options): Promise<SharePointItem> Creates a folder in a site's drive.
ensureFolderPath ensureFolderPath(token, siteId, folderPath): Promise<SharePointItem> Ensures a folder path exists, creating any missing folders.

List Operations

Method Signature Description
listLists listLists(token, siteId): Promise<SharePointList[]> Lists all lists in a site.
createDocumentLibrary createDocumentLibrary(token, siteId, name, description?): Promise<SharePointList> Creates a new document library (list with documentLibrary template).

Group Operations

Method Signature Description
createGroup createGroup(token, options): Promise<Microsoft365Group> Creates a Microsoft 365 Group (auto-creates SharePoint site, mailbox, etc.). Requires Group.ReadWrite.All.
getGroup getGroup(token, groupId): Promise<Microsoft365Group> Gets a group by ID.
listMyGroups listMyGroups(token, options?): Promise<{ groups, nextLink? }> Lists all Microsoft 365 Groups in the tenant. Requires Group.Read.All.
deleteGroup deleteGroup(token, groupId): Promise<void> Deletes a group and its associated resources.

Key Types

SharePointSite

interface SharePointSite {
  id: string;
  name?: string;
  displayName?: string;
  description?: string;
  webUrl?: string;
  createdDateTime?: string;
  lastModifiedDateTime?: string;
}

SharePointDrive

interface SharePointDrive {
  id: string;
  name: string;
  description?: string;
  driveType: "documentLibrary" | "personal" | "business";
  webUrl?: string;
  quota?: { total?: number; used?: number; remaining?: number; state?: string };
}

SharePointDocument

interface SharePointDocument {
  id: string;
  name: string;
  path: string;
  size: number;
  mimeType: string;
  lastModified: string;
  lastModifiedBy?: string;
  downloadUrl?: string;
  webUrl?: string;
}

SharePointUploadFileOptions

interface SharePointUploadFileOptions {
  fileName: string;
  content: Buffer;
  folderPath?: string;
  conflictBehavior?: "rename" | "replace" | "fail";
}

Code Example

import { SharePointGraphClient } from "@modernpath/agent-framework";

const graph = new SharePointGraphClient();

// Search for sites
const { sites } = await graph.searchSites(token, "Project Alpha");
const siteId = sites[0].id;

// List document libraries
const drives = await graph.listDrives(token, siteId);

// List documents in a folder
const { documents } = await graph.listDocuments(token, siteId, {
  folderPath: "Shared Documents/Reports",
  fileTypes: ["pdf", "xlsx"],
  pageSize: 50,
});

// Download a document
const content = await graph.downloadDocument(token, siteId, documents[0].id);

// Upload a file
const uploaded = await graph.uploadFile(token, siteId, {
  fileName: "report.pdf",
  content: pdfBuffer,
  folderPath: "Shared Documents/Reports",
  conflictBehavior: "rename",
});

// Create a folder
await graph.createFolder(token, siteId, {
  name: "New Folder",
  parentPath: "Shared Documents",
});

// Ensure a nested folder path exists
await graph.ensureFolderPath(token, siteId, "Shared Documents/2025/Q1/Reports");