Ms Graph
@dougschaefer/ms-graphv2026.08.17.1
01README
Broad Microsoft Graph extension — nine model types over one shared app-only client: calendar (room/user calendarView, current/next meeting), places (room resources), users (Entra directory reads, manager, memberOf), groups, mail (Outlook messages), teams (chats/teams/channels/messages), presence, sharepoint (document-library navigation, search, and file download, working under either Sites.Read.All or Sites.Selected), and intune (enrolled devices, compliance policies, configuration profiles and settings catalog, remediation scripts, confirmation-gated device actions, and async report exports). Token caching, automatic paging, and a raw-bytes downloader; app credentials supplied from a vault. Supersedes the narrow ms-graph-calendar and absorbs azure-ad-user's lookup.
02Release Notes
Adds getMimeContent, which persists a message unmodified RFC822 source (GET /messages/{id}/) as a messageMime file artifact, preserving the Authentication-Results, DKIM-Signature and Received headers that let an email stand on its own as evidence of origin. listMessages now reports when a result set is truncated at maxItems, since results are newest-first and a silent truncation can turn an unsearched window into a false negative.
03Models
@dougschaefer/ms-graph-calendarv2026.08.17.1ms-graph/calendar.ts
fn listEvents(roomEmail: string, startDateTime: string, endDateTime: string, top: number)
GET /users/{roomEmail}/calendarView — return all meetings for a room or user mailbox within a caller-supplied time window, ordered by start time.
| Argument | Type | Description |
|---|---|---|
| roomEmail | string | Room or user mailbox address, e.g. conf-b@example.com |
| startDateTime | string | Window start in ISO-8601 format, e.g. 2026-06-29T00:00:00 |
| endDateTime | string | Window end in ISO-8601 format, e.g. 2026-06-29T23:59:59 |
| top | number | Max events per page (1-999). The method auto-follows @odata.nextLink. |
fn getEvent(roomEmail: string, eventId: string)
GET /users/{roomEmail}/events/{id} — fetch a single calendar event by its Graph event id, normalized to the standard meeting shape. (Permission: Calendars.Read)
| Argument | Type | Description |
|---|---|---|
| roomEmail | string | Room or user mailbox address that owns the event, e.g. conf-b@example.com |
| eventId | string | Graph event id |
fn getCurrentMeeting(roomEmail: string)
Convenience method: returns the meeting currently in progress for the room, or null if the room is free.
| Argument | Type | Description |
|---|---|---|
| roomEmail | string | Room mailbox address, e.g. conf-b@example.com |
fn getNextMeeting(roomEmail: string, lookAheadHours: number)
Convenience method: returns the next upcoming meeting for the room — the first meeting that starts after now (within the look-ahead window).
| Argument | Type | Description |
|---|---|---|
| roomEmail | string | Room mailbox address, e.g. conf-b@example.com |
| lookAheadHours | number | How many hours ahead to search for the next meeting (default 8 — remainder of the workday) |
Resources
calendarView(5m)— Ordered list of meetings for a mailbox within a time window (from /users/{mailbox}/calendarView). Normalized to {subject, start, end, organizer, attendees, attendeeCount}.
event(5m)— A single calendar event fetched by id from /users/{mailbox}/events/{id}, normalized to the standard meeting shape.
currentMeeting(2m)— The meeting in progress right now for the mailbox, or null if none. Derived from a narrow calendarView window centered on the current time. The IARS meeting-agent's primary calendar signal.
nextMeeting(2m)— The next upcoming meeting for the mailbox (the first meeting starting after now). Null if nothing is on the calendar in the look-ahead window. Used by the IARS meeting-agent to prepare the room ahead of time.
@dougschaefer/ms-graph-placesv2026.08.17.1ms-graph/places.ts
fn listRooms(top: number)
GET /places/microsoft.graph.room — list all room resources in the tenant. Returns displayName + emailAddress for each room. Use the emailAddress as the roomEmail input for the calendar model. The method auto-follows @odata.nextLink. (Permission: Place.Read.All)
| Argument | Type | Description |
|---|---|---|
| top | number | Max rooms to return per page (1-100). Paging is handled automatically. |
fn getRoom(idOrEmail: string)
GET /places/{idOrEmail} — fetch detail for a single room resource: capacity, building, floor, A/V device names, accessibility, and tags. Pass the room's emailAddress or object ID. (Permission: Place.Read.All)
| Argument | Type | Description |
|---|---|---|
| idOrEmail | string | Room emailAddress (e.g. conf-b@example.com) or Graph object ID |
Resources
roomList(1d)— Snapshot of all room resources in the tenant from /places/microsoft.graph.room. Each entry includes displayName and emailAddress.
roomDetail(7d)— Detail for a single room resource from GET /places/{id-or-email}: displayName, emailAddress, capacity, building, floor, and A/V capabilities.
@dougschaefer/ms-graph-usersv2026.08.17.1ms-graph/users.ts
fn get(idOrUpn: string)
GET /users/{idOrUpn} — resolve one user by Entra object id or userPrincipalName, selected to the standard profile fields (displayName, department, jobTitle, officeLocation, mail, etc.). Writes the user under a slug of the object id. This is the IARS reverse-lookup signal — pass the object id. (Permission: User.Read.All)
| Argument | Type | Description |
|---|---|---|
| idOrUpn | string | Entra object id (GUID) or userPrincipalName (user@example.com) |
fn list(filter?: string, maxItems: number)
GET /users — enumerate directory users, selected to the standard profile fields. Optionally narrow with an OData $filter and cap the total with maxItems. Auto-follows @odata.nextLink. (Permission: User.Read.All)
| Argument | Type | Description |
|---|---|---|
| filter? | string | OData $filter, e.g. "startswith(displayName,\ |
| maxItems | number | Hard cap on total users collected across pages (default 200). |
fn getManager(idOrUpn: string)
GET /users/{idOrUpn}/manager — return a user's manager as a user record. Throws if the user has no manager assigned. (Permission: User.Read.All)
| Argument | Type | Description |
|---|---|---|
| idOrUpn | string | Entra object id (GUID) or userPrincipalName of the user whose manager to fetch |
fn memberOf(idOrUpn: string)
GET /users/{idOrUpn}/memberOf — list the groups and directory roles a user is a member of, for access review. Auto-follows @odata.nextLink. (Permission: User.Read.All)
| Argument | Type | Description |
|---|---|---|
| idOrUpn | string | Entra object id (GUID) or userPrincipalName of the user |
Resources
user(infinite)— An Entra ID user from GET /users/{id}, selected to the standard profile fields. Written under a slug of the object id; the user fields land under the data instance's content.
membership(infinite)— A directory object (group or directory role) a user is a member of, from /users/{id}/memberOf.
@dougschaefer/ms-graph-groupsv2026.08.17.1ms-graph/groups.ts
fn list(filter?: string, maxItems: number)
GET /groups — enumerate directory groups, selected to the standard fields. Optionally narrow with an OData $filter and cap the total with maxItems. Auto-follows @odata.nextLink. (Permission: Group.Read.All)
| Argument | Type | Description |
|---|---|---|
| filter? | string | OData $filter, e.g. "securityEnabled eq true" or "startswith(displayName,\ |
| maxItems | number | Hard cap on total groups collected across pages (default 200). |
fn get(id: string)
GET /groups/{id} — resolve one group by Entra object id, selected to the standard fields. (Permission: Group.Read.All)
| Argument | Type | Description |
|---|---|---|
| id | string | Entra group object id (GUID) |
fn listMembers(id: string, maxItems: number)
GET /groups/{id}/members — list the members of a group (users, devices, nested groups). Auto-follows @odata.nextLink. (Permission: Group.Read.All)
| Argument | Type | Description |
|---|---|---|
| id | string | Entra group object id (GUID) |
| maxItems | number | Hard cap on total members collected across pages (default 500). |
Resources
group(infinite)— An Entra ID group from GET /groups/{id}, selected to the standard fields (displayName, mail, securityEnabled, groupTypes, membershipRule, etc.).
member(infinite)— A member of a group (user, device, or nested group) from /groups/{id}/members.
@dougschaefer/ms-graph-mailv2026.08.17.1ms-graph/mail.ts
fn listMessages(userId: string, filter?: string, maxItems: number)
GET /users/{userId}/messages — list a mailbox's messages, ordered newest first, with metadata and bodyPreview. Optionally narrow with an OData $filter and cap with maxItems. Auto-follows @odata.nextLink. (Permission: Mail.Read)
| Argument | Type | Description |
|---|---|---|
| userId | string | Mailbox userPrincipalName or object id, e.g. user@example.com |
| filter? | string | OData $filter, e.g. "isRead eq false" or "importance eq \ |
| maxItems | number | Hard cap on total messages collected across pages (default 50). |
fn getMessage(userId: string, messageId: string)
GET /users/{userId}/messages/{id} — fetch one message including its full body. (Permission: Mail.Read)
| Argument | Type | Description |
|---|---|---|
| userId | string | Mailbox userPrincipalName or object id that owns the message |
| messageId | string | Graph message id |
fn getMimeContent(userId: string, messageId: string, resultName?: string)
GET /users/{userId}/messages/{id}/$value — persist a message's unmodified RFC822 source as a messageMime file artifact. Unlike getMessage, which returns a parsed body, this preserves the full header block including Authentication-Results, DKIM-Signature and Received chain, so the file stands on its own as evidence of who sent the message and when. Write it to disk with a .eml extension. (Permission: Mail.Read)
| Argument | Type | Description |
|---|---|---|
| userId | string | Mailbox userPrincipalName or object id that owns the message |
| messageId | string | Graph message id |
| resultName? | string | Instance label for the file artifact; defaults to a slug of the mailbox and message id |
Resources
messageList(5m)— Snapshot of a mailbox's messages from GET /users/{userId}/messages, newest first, with metadata and bodyPreview.
message(5m)— A single Outlook message from GET /users/{userId}/messages/{id}, including the full body.
Files
messageMime(message/rfc822)— One message's unmodified RFC822 source from GET /messages/{id}/$value, headers intact.
@dougschaefer/ms-graph-teamsv2026.08.17.1ms-graph/teams.ts
fn listChats(userId: string, maxItems: number)
GET /users/{userId}/chats — list a user's Teams chats. Auto-follows @odata.nextLink. (Permission: Chat.Read.All)
| Argument | Type | Description |
|---|---|---|
| userId | string | User userPrincipalName or object id, e.g. user@example.com |
| maxItems | number | Hard cap on total chats collected across pages (default 100). |
fn listJoinedTeams(userId: string)
GET /users/{userId}/joinedTeams — list the teams a user has joined. Auto-follows @odata.nextLink. (Permission: Team.ReadBasic.All)
| Argument | Type | Description |
|---|---|---|
| userId | string | User userPrincipalName or object id, e.g. user@example.com |
fn listChannels(teamId: string)
GET /teams/{teamId}/channels — list a team's channels. Auto-follows @odata.nextLink. (Permission: Channel.ReadBasic.All)
| Argument | Type | Description |
|---|---|---|
| teamId | string | Team (group) object id |
fn listMessages(chatId?: string, teamId?: string, channelId?: string, maxItems: number)
List messages from a chat (pass chatId) or a channel (pass teamId + channelId). Auto-follows @odata.nextLink.
| Argument | Type | Description |
|---|---|---|
| chatId? | string | Chat id — provide for chat messages (mutually exclusive with teamId/channelId) |
| teamId? | string | Team id — provide with channelId for channel messages |
| channelId? | string | Channel id — provide with teamId for channel messages |
| maxItems | number | Hard cap on total messages collected across pages (default 50). |
Resources
chat(1h)— A Teams chat from /users/{userId}/chats.
team(1d)— A team the user has joined, from /users/{userId}/joinedTeams.
channel(1d)— A channel of a team, from /teams/{teamId}/channels.
messageList(5m)— Snapshot of messages from a chat or channel, from /chats/{id}/messages or /teams/{teamId}/channels/{channelId}/messages.
@dougschaefer/ms-graph-presencev2026.08.17.1ms-graph/presence.ts
fn getPresence(userId: string)
GET /users/{userId}/presence — return a user's current Teams presence (availability + activity). (Permission: Presence.Read.All)
| Argument | Type | Description |
|---|---|---|
| userId | string | User object id or userPrincipalName, e.g. user@example.com |
Resources
presence(2m)— A user's Teams presence from GET /users/{userId}/presence: availability and activity at capture time.
@dougschaefer/ms-graph-sharepointv2026.08.17.1ms-graph/sharepoint.ts
fn getSite()
Resolve and persist the configured SharePoint site.
fn listFolder()
List one folder's children (drive-relative path; empty = library root). Persists a single folderListing snapshot.
fn searchDriveItems(query: string, maxItems: number, maxScan: number)
Find drive items matching a query, optionally scoped to a folder path. Persists one searchResult snapshot whose matchedOn field records how the hits were found. Graph's /drive/root/search(q=) searches document CONTENT as well as names and is used by default, but it is not supported under the Sites.Selected permission — there it fails with HTTP 500 rather than a permission error. On that failure this falls back to a bounded folder walk that matches NAMES only, so the method works under either per
| Argument | Type | Description |
|---|---|---|
| query | string | Search terms, e.g. a project number. Matched against content and names by Graph search, or as a case-insensitive name substring by the walk. |
| maxItems | number | Cap on hits returned |
| maxScan | number | Walk only — cap on entries examined. A site-wide walk issues one request per folder and is slow on deep libraries; prefer scopePath. |
fn downloadDriveItem()
Download one file by drive-relative path and persist its bytes as a document file artifact.
Resources
site(infinite)— SharePoint site metadata
folderListing(infinite)— One folder's children (a navigation snapshot)
searchResult(infinite)— Drive search hits for a query
Files
document(application/octet-stream)— A downloaded SharePoint file's bytes
@dougschaefer/ms-graph-intunev2026.08.17.1ms-graph/intune.ts
fn listDevices(filter?: string, maxItems: number)
GET /deviceManagement/managedDevices — enumerate enrolled devices, selected to the standard inventory fields. Auto-follows @odata.nextLink. Note that managedDevices supports $filter on only a subset of properties (operatingSystem, complianceState, ownerType and similar); filtering on an unsupported property returns HTTP 400 rather than an empty set. (Permission: DeviceManagementManagedDevices.Read.All)
| Argument | Type | Description |
|---|---|---|
| filter? | string | OData $filter over supported properties, e.g. \ |
| maxItems | number | Hard cap on total devices collected across pages (default 500). |
fn getDevice(id: string)
GET /deviceManagement/managedDevices/{id} — resolve one enrolled device by its Intune managed-device id, selected to the standard inventory fields. (Permission: DeviceManagementManagedDevices.Read.All)
| Argument | Type | Description |
|---|---|---|
| id | string | Intune managed-device id (GUID) |
fn listCompliancePolicies(includeAssignments: boolean, maxItems: number)
GET /deviceManagement/deviceCompliancePolicies — enumerate compliance policies across platforms, optionally expanding their group assignments. (Permission: DeviceManagementConfiguration.Read.All)
| Argument | Type | Description |
|---|---|---|
| includeAssignments | boolean | Expand each policy's assignments so the groups it targets come back in the same call. |
| maxItems | number | Hard cap on total policies collected across pages (default 200). |
fn listConfigurationProfiles(includeSettingsCatalog: boolean, maxItems: number)
Enumerate device configuration profiles. Always reads the classic templates from /deviceManagement/deviceConfigurations; with includeSettingsCatalog it also reads /deviceManagement/configurationPolicies, which is beta-only. Each resource carries a profileKind marking which surface it came from. (Permission: DeviceManagementConfiguration.Read.All)
| Argument | Type | Description |
|---|---|---|
| includeSettingsCatalog | boolean | Also collect settings-catalog policies. These live only on the beta endpoint, so their shape is not contract-guaranteed. |
| maxItems | number | Hard cap on profiles collected from each surface (default 200 each). |
fn listHealthScripts(apiVersion: enum, maxItems: number)
GET /deviceManagement/deviceHealthScripts — enumerate remediation script pairs (detection plus remediation), the mechanism behind Intune Remediations. Defaults to the beta endpoint because that is where the resource is published. Note this is the one read that does NOT ride DeviceManagementConfiguration.Read.All — scripts are a separate scope. (Permission: DeviceManagementScripts.Read.All)
| Argument | Type | Description |
|---|---|---|
| apiVersion | enum | Graph version to read from. Move this to v1.0 once the resource graduates. |
| maxItems | number | Hard cap on total scripts collected across pages (default 200). |
fn runDeviceAction(deviceIds: array, confirm: boolean, keepUserData: boolean)
Dispatch one device action across many devices in a single call, recording a per-device result so one failure does not abort the batch. Sync and locate run immediately; reboot, shutDown, remoteLock, retire and wipe only dispatch when confirm is true, and otherwise return a preview listing exactly which devices would be acted on. Retire removes company data and unenrolls; wipe is a factory reset — both are irreversible from Intune. (Permissions: DeviceManagementManagedDevices.Read.All, plus Devic
| Argument | Type | Description |
|---|---|---|
| deviceIds | array | Intune managed-device ids to act on. |
| confirm | boolean | Required for anything beyond sync and locate. Left false, the method previews the batch without calling Graph. |
| keepUserData | boolean | Wipe only — preserve user data instead of a full factory reset. Ignored by every other action. |
fn exportReport(reportName: string, format: enum, filter?: string, select?: array, apiVersion: enum, timeoutSeconds: number)
POST /deviceManagement/reports/exportJobs then poll to completion — ask Intune to build a whole report server-side and hand back one file, instead of walking devices individually. This keeps call count independent of fleet size and stays clear of throttling on large tenants. Writes the finished job including its download URL, which carries a short-lived SAS token; fetch it in a following step rather than storing it. (Permission: DeviceManagementManagedDevices.Read.All)
| Argument | Type | Description |
|---|---|---|
| reportName | string | Intune report to build, e.g. Devices, DevicesWithInventory, DeviceCompliance, DeviceNonCompliance, or DeviceInstallStatusByApp. |
| format | enum | Payload format inside the returned zip. |
| filter? | string | Report-specific filter expression, passed through to the export job unchanged. |
| select? | array | Columns to include. Omit for the report's default column set. |
| apiVersion | enum | Graph version to submit against. Several report names are published only on beta. |
| timeoutSeconds | number | How long to poll before giving up on the job (default 300). |
Resources
managedDevice(infinite)— An Intune-enrolled device from /deviceManagement/managedDevices, selected to the standard inventory fields (owner, OS, compliance state, last sync, hardware identifiers).
compliancePolicy(infinite)— A device compliance policy from /deviceManagement/deviceCompliancePolicies. The @odata.type identifies the platform the policy targets.
configurationProfile(infinite)— A device configuration profile — either a classic template from /deviceManagement/deviceConfigurations or a settings-catalog policy from /deviceManagement/configurationPolicies, distinguished by profileKind.
healthScript(infinite)— A remediation script pair (detection plus remediation) from /deviceManagement/deviceHealthScripts.
deviceAction(infinite)— The outcome of one fan-out device action: which devices succeeded, which failed and why, and which were skipped because the run was an unconfirmed preview.
reportExport(infinite)— A finished Intune report export job, including the short-lived download URL for the zipped CSV or JSON payload.
04Previous Versions
2026.08.10.2
Corrects the registry description: sharepoint is app-only as of this release, not delegated.
2026.08.10.1
Adds the intune model type (enrolled devices, compliance policies, configuration profiles and settings catalog, remediation health scripts, confirmation-gated device actions, async report exports) and moves sharepoint from a delegated az-session token to app-only credentials so it runs unattended. Shared client gains a beta base URL, request bodies, and a raw-bytes downloader.
Added 1 models. updated labels
2026.07.13.4
Manifest description corrected to match the v2026.07.13.3 scope reduction: sharepoint model advertises document-library navigation, drive search, and file download only. No code changes.
2026.07.13.3
Scope reduction: ms-graph-sharepoint now carries only the general-purpose SharePoint surface (getSite, listFolder, searchDriveItems, downloadDriveItem). The organization-specific customer-folder resolution and evidence-collection heuristics moved out of the published artifact into a private internal model. No changes to the four remaining methods.
Modified 1 models
2026.07.13.2
Documentation hardening from a security audit: org-specific references removed from published docs and JSDoc (vault-name examples neutralized to azure-graph, tenant consent-state disclosures dropped, evidence-collection description genericized). No functional changes.
2026.07.13.1
New ms-graph-sharepoint model: document-library navigation, customer-folder resolution (auto-detected letter-bucket layouts), scoped drive search, file download, and the collectCustomerDocs fan-out evidence collector with keyword and project-number scoring. Uses the delegated az-session token so document access rides the operator's own SharePoint permissions; site locator supplied per instance.
Added 1 models. updated labels
2026.06.29.1
Initial public publish (extension was catalog-only after the productization merge).
05Stats
A
100 / 100
Downloads
45
Archive size
60.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels