@eltjs/source-microsoft-sharepoint 0.0.0-stage → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,59 @@
1
+ import { createdBy, instant, json, lastModifiedBy, sharePointFields, siteUrl, } from './sharepoint-stream.js';
2
+ const { id, text, timestamp } = sharePointFields;
3
+ // The template of the list of the requests for access to a site. Graph
4
+ // refuses its item delta with 503 serviceNotAvailable on each try, while a
5
+ // read of its items works (live, 2026-11-17), so accessRequests reads it in
6
+ // full and listItems leaves it out (ADR 0002).
7
+ export const accessRequestTemplate = 'accessRequest';
8
+ // The fields of an item of a list, the same in listItems and accessRequests.
9
+ export const listItemProperties = {
10
+ siteUrl,
11
+ listId: { ...id, description: 'The list of the item: lists.listId.' },
12
+ itemId: {
13
+ ...id,
14
+ description: "SharePoint's ID of the item in its list, such as 12. In a document library, driveItems.listItemId refers to it.",
15
+ },
16
+ contentType: {
17
+ ...text,
18
+ description: 'The name of the content type of the item, such as Item.',
19
+ },
20
+ contentTypeId: {
21
+ ...text,
22
+ description: 'The ID of the content type of the item.',
23
+ },
24
+ webUrl: { ...text, description: 'The URL of the item.' },
25
+ createdDateTime: {
26
+ ...timestamp,
27
+ description: 'When the item was created, in UTC.',
28
+ },
29
+ lastModifiedDateTime: {
30
+ ...timestamp,
31
+ description: 'When the item last changed, in UTC.',
32
+ },
33
+ createdBy,
34
+ lastModifiedBy,
35
+ eTag: {
36
+ ...text,
37
+ description: 'The version tag of the item, which changes when it changes.',
38
+ },
39
+ fields: {
40
+ ...text,
41
+ description: "The value of each column of the item that is not hidden, as JSON, by the name of the column (listColumns.name), as Graph gives it. Read one with json_extract(fields, '$.Title').",
42
+ },
43
+ };
44
+ export function listItemRecord(url, listId, item) {
45
+ return {
46
+ siteUrl: url,
47
+ listId,
48
+ itemId: item.id,
49
+ contentType: item.contentType.name,
50
+ contentTypeId: item.contentType.id,
51
+ webUrl: item.webUrl,
52
+ createdDateTime: instant(item.createdDateTime),
53
+ lastModifiedDateTime: instant(item.lastModifiedDateTime),
54
+ createdBy: json(item.createdBy),
55
+ lastModifiedBy: json(item.lastModifiedBy),
56
+ eTag: item.eTag,
57
+ fields: JSON.stringify(item.fields),
58
+ };
59
+ }
@@ -0,0 +1,19 @@
1
+ import type { Drive, List, SharePointClient, Site } from '@eltjs/sdk-microsoft-sharepoint';
2
+ /**
3
+ * One read of SharePoint: the client, the site, drives and lists that the
4
+ * run read, and the folder of the files that it staged. Each stream of the
5
+ * run sees the same drives and lists of a site, so the delta streams read the
6
+ * collections that the drives and lists streams load. A read that Graph
7
+ * refused is not kept: the next stream to ask for it asks Graph again.
8
+ */
9
+ export declare class SharePointRun implements AsyncDisposable {
10
+ #private;
11
+ readonly client: SharePointClient;
12
+ private constructor();
13
+ static open(client: SharePointClient): Promise<SharePointRun>;
14
+ site(url: string, signal: AbortSignal): Promise<Site>;
15
+ drives(url: string, signal: AbortSignal): Promise<readonly Drive[]>;
16
+ lists(url: string, signal: AbortSignal): Promise<readonly List[]>;
17
+ staged(name: string): string;
18
+ [Symbol.asyncDispose](): Promise<void>;
19
+ }
@@ -0,0 +1,57 @@
1
+ import { join } from 'node:path';
2
+ import { TemporaryFiles } from '@zukhruf/fs';
3
+ /**
4
+ * One read of SharePoint: the client, the site, drives and lists that the
5
+ * run read, and the folder of the files that it staged. Each stream of the
6
+ * run sees the same drives and lists of a site, so the delta streams read the
7
+ * collections that the drives and lists streams load. A read that Graph
8
+ * refused is not kept: the next stream to ask for it asks Graph again.
9
+ */
10
+ export class SharePointRun {
11
+ client;
12
+ #staging;
13
+ #sites = new Map();
14
+ #drives = new Map();
15
+ #lists = new Map();
16
+ constructor(client, staging) {
17
+ this.client = client;
18
+ this.#staging = staging;
19
+ }
20
+ static async open(client) {
21
+ return new SharePointRun(client, await new TemporaryFiles().directory('elt-sharepoint-'));
22
+ }
23
+ async site(url, signal) {
24
+ const known = this.#sites.get(url);
25
+ if (known !== undefined)
26
+ return known;
27
+ const site = await this.client.site(url, signal);
28
+ this.#sites.set(url, site);
29
+ return site;
30
+ }
31
+ async drives(url, signal) {
32
+ const known = this.#drives.get(url);
33
+ if (known !== undefined)
34
+ return known;
35
+ const { id } = await this.site(url, signal);
36
+ const drives = await this.client.drives(id, signal);
37
+ this.#drives.set(url, drives);
38
+ return drives;
39
+ }
40
+ async lists(url, signal) {
41
+ const known = this.#lists.get(url);
42
+ if (known !== undefined)
43
+ return known;
44
+ const { id } = await this.site(url, signal);
45
+ const lists = await this.client.lists(id, signal);
46
+ this.#lists.set(url, lists);
47
+ return lists;
48
+ }
49
+ // Where a file named name stages in the run's folder. The caller removes
50
+ // it once its record is loaded; the run removes what is left.
51
+ staged(name) {
52
+ return join(this.#staging.path, name);
53
+ }
54
+ async [Symbol.asyncDispose]() {
55
+ await this.#staging.cleanup();
56
+ }
57
+ }
@@ -0,0 +1,33 @@
1
+ import { Catalog, type ChangeSignal, type CopyConfiguration, type ExtractionCoverage, type Partition, Source, type SourceMessage, type Stream } from '@eltjs/elt';
2
+ import { SharePointAccessError, type SharePointClient, SharePointCredentialsError, SharePointSiteNotFoundError } from '@eltjs/sdk-microsoft-sharepoint';
3
+ import { SharePointRun } from './sharepoint-run.ts';
4
+ export type SharePointSourceOptions = {
5
+ readonly client: SharePointClient;
6
+ readonly sites: readonly string[];
7
+ };
8
+ /**
9
+ * Reads the files, lists and pages of SharePoint Online sites through
10
+ * Microsoft Graph, as one app. Each stream is read once for each configured
11
+ * site, its partition.
12
+ */
13
+ export declare class SharePointSource extends Source<SharePointRun> {
14
+ #private;
15
+ readonly identity: string;
16
+ protected readonly catalog: Catalog;
17
+ readonly sites: Stream;
18
+ readonly drives: Stream;
19
+ readonly driveItems: Stream;
20
+ readonly lists: Stream;
21
+ readonly listColumns: Stream;
22
+ readonly listItems: Stream;
23
+ readonly accessRequests: Stream;
24
+ readonly pages: Stream;
25
+ constructor({ client, sites }: SharePointSourceOptions);
26
+ protected readonly configErrors: (typeof SharePointAccessError | typeof SharePointCredentialsError | typeof SharePointSiteNotFoundError)[];
27
+ protected partitions(): readonly Partition[];
28
+ protected open(): Promise<SharePointRun>;
29
+ coverage(stream: Stream): ExtractionCoverage;
30
+ currentAsOf(): Promise<Date | null>;
31
+ changeSignals(streams: readonly Stream[]): ChangeSignal[];
32
+ protected extract(configuration: CopyConfiguration, state: unknown, partition: Partition | null, run: SharePointRun, signal: AbortSignal | undefined): AsyncIterable<SourceMessage>;
33
+ }
@@ -0,0 +1,100 @@
1
+ import { Catalog, Source, } from '@eltjs/elt';
2
+ import { SharePointAccessError, SharePointCredentialsError, SharePointSiteNotFoundError, SiteVersion, } from '@eltjs/sdk-microsoft-sharepoint';
3
+ import { SharePointRun } from './sharepoint-run.js';
4
+ import { AccessRequestsStream } from './streams/access-requests-stream.js';
5
+ import { DriveItemsStream } from './streams/drive-items-stream.js';
6
+ import { DrivesStream } from './streams/drives-stream.js';
7
+ import { ListColumnsStream } from './streams/list-columns-stream.js';
8
+ import { ListItemsStream } from './streams/list-items-stream.js';
9
+ import { ListsStream } from './streams/lists-stream.js';
10
+ import { PagesStream } from './streams/pages-stream.js';
11
+ import { SitesStream } from './streams/sites-stream.js';
12
+ const readers = {
13
+ sites: new SitesStream(),
14
+ drives: new DrivesStream(),
15
+ driveItems: new DriveItemsStream(),
16
+ lists: new ListsStream(),
17
+ listColumns: new ListColumnsStream(),
18
+ listItems: new ListItemsStream(),
19
+ accessRequests: new AccessRequestsStream(),
20
+ pages: new PagesStream(),
21
+ };
22
+ const catalog = new Catalog(Object.values(readers).map((reader) => reader.stream));
23
+ const readersByStream = new Map(Object.values(readers).map((reader) => [reader.stream, reader]));
24
+ // How often a watch reads the version of each site, and how long one read,
25
+ // three requests to Graph with their retries, can take.
26
+ const checkIntervalMs = 60_000;
27
+ const checkTimeoutMs = 30_000;
28
+ /**
29
+ * Reads the files, lists and pages of SharePoint Online sites through
30
+ * Microsoft Graph, as one app. Each stream is read once for each configured
31
+ * site, its partition.
32
+ */
33
+ export class SharePointSource extends Source {
34
+ identity;
35
+ catalog = catalog;
36
+ sites = readers.sites.stream;
37
+ drives = readers.drives.stream;
38
+ driveItems = readers.driveItems.stream;
39
+ lists = readers.lists.stream;
40
+ listColumns = readers.listColumns.stream;
41
+ listItems = readers.listItems.stream;
42
+ accessRequests = readers.accessRequests.stream;
43
+ pages = readers.pages.stream;
44
+ #client;
45
+ #siteUrls;
46
+ constructor({ client, sites }) {
47
+ super();
48
+ if (sites.length === 0)
49
+ throw new TypeError('SharePoint requires one site URL or more');
50
+ // The sites are partitions, with a checkpoint each, so they are not part
51
+ // of the identity: adding a site keeps the checkpoints of the others.
52
+ this.identity = `sharepoint:${client.tenantId}`;
53
+ this.#client = client;
54
+ this.#siteUrls = Object.freeze([...sites]);
55
+ Object.freeze(this);
56
+ }
57
+ configErrors = [
58
+ SharePointAccessError,
59
+ SharePointCredentialsError,
60
+ SharePointSiteNotFoundError,
61
+ ];
62
+ partitions() {
63
+ return this.#siteUrls.map((siteUrl) => ({ siteUrl }));
64
+ }
65
+ open() {
66
+ return SharePointRun.open(this.#client);
67
+ }
68
+ coverage(stream) {
69
+ return {
70
+ description: this.#reader(stream).covers,
71
+ selection: { sites: [...this.#siteUrls] },
72
+ };
73
+ }
74
+ async currentAsOf() {
75
+ return null;
76
+ }
77
+ // Graph sends change notifications only to a public URL, so a watch reads
78
+ // the version of each site, which moves when a list, a library or a page
79
+ // of it changes.
80
+ changeSignals(streams) {
81
+ return this.#siteUrls.map((url) => ({
82
+ gauge: new SiteVersion(this.#client, url),
83
+ streams,
84
+ interval: checkIntervalMs,
85
+ timeout: checkTimeoutMs,
86
+ }));
87
+ }
88
+ extract(configuration, state, partition, run, signal) {
89
+ const siteUrl = partition?.siteUrl;
90
+ if (typeof siteUrl !== 'string')
91
+ throw new TypeError(`SharePoint stream ${configuration.stream.name} is read once for each site`);
92
+ return this.#reader(configuration.stream).extract(configuration, state, siteUrl, run, signal ?? new AbortController().signal);
93
+ }
94
+ #reader(stream) {
95
+ const reader = readersByStream.get(stream);
96
+ if (reader === undefined)
97
+ throw new TypeError(`SharePoint has no stream ${stream.name}`);
98
+ return reader;
99
+ }
100
+ }
@@ -0,0 +1,70 @@
1
+ import { type CopyConfiguration, type Properties, type SourceMessage, Stream } from '@eltjs/elt';
2
+ import type { SharePointRun } from './sharepoint-run.ts';
3
+ export declare const sharePointFields: {
4
+ text: {
5
+ readonly type: 'string';
6
+ };
7
+ id: {
8
+ readonly type: 'string';
9
+ readonly minLength: 1;
10
+ };
11
+ nullableText: {
12
+ readonly type: readonly ['string', 'null'];
13
+ };
14
+ boolean: {
15
+ readonly type: 'boolean';
16
+ };
17
+ timestamp: {
18
+ readonly type: 'string';
19
+ readonly format: 'date-time';
20
+ };
21
+ nullableTimestamp: {
22
+ readonly type: readonly ['string', 'null'];
23
+ readonly format: 'date-time';
24
+ };
25
+ count: {
26
+ readonly type: 'integer';
27
+ readonly minimum: 0;
28
+ };
29
+ nullableCount: {
30
+ readonly type: readonly ['integer', 'null'];
31
+ readonly minimum: 0;
32
+ };
33
+ };
34
+ export declare const siteUrl: {
35
+ type: 'string';
36
+ minLength: 1;
37
+ description: string;
38
+ };
39
+ export declare const createdBy: {
40
+ type: readonly ['string', 'null'];
41
+ description: string;
42
+ };
43
+ export declare const lastModifiedBy: {
44
+ type: readonly ['string', 'null'];
45
+ description: string;
46
+ };
47
+ type StreamDefinition = {
48
+ readonly name: string;
49
+ readonly description: string;
50
+ readonly properties: Properties;
51
+ readonly primaryKey: readonly ['siteUrl', ...string[]];
52
+ readonly covers: string;
53
+ readonly supportsFileTransfer?: true;
54
+ };
55
+ /**
56
+ * A SharePoint stream: its declaration, and how one read of one site turns
57
+ * Graph's answers into messages. Each family that reads alike is a subclass:
58
+ * the snapshots that Graph lists whole on each read, and the delta feeds.
59
+ */
60
+ export declare abstract class SharePointStream {
61
+ readonly stream: Stream;
62
+ readonly covers: string;
63
+ constructor({ name, description, properties, primaryKey, covers, supportsFileTransfer, }: StreamDefinition);
64
+ abstract extract(configuration: CopyConfiguration, state: unknown, siteUrl: string, run: SharePointRun, signal: AbortSignal): AsyncGenerator<SourceMessage>;
65
+ protected validated(draft: Record<string, unknown>): Record<string, unknown>;
66
+ }
67
+ export declare function instant(value: string): string;
68
+ export declare function nullableInstant(value: string | undefined): string | null;
69
+ export declare function json(value: object | undefined): string | null;
70
+ export {};
@@ -0,0 +1,84 @@
1
+ import { Stream, validateRecords, } from '@eltjs/elt';
2
+ const text = { type: 'string' };
3
+ const id = { ...text, minLength: 1 };
4
+ const nullableText = { type: ['string', 'null'] };
5
+ const boolean = { type: 'boolean' };
6
+ const timestamp = { ...text, format: 'date-time' };
7
+ const nullableTimestamp = {
8
+ type: ['string', 'null'],
9
+ format: 'date-time',
10
+ };
11
+ // Graph gives sizes and counts as JSON numbers; a file of SharePoint is at
12
+ // most 250 GB, far below 2^53.
13
+ const count = { type: 'integer', minimum: 0 };
14
+ const nullableCount = { type: ['integer', 'null'], minimum: 0 };
15
+ export const sharePointFields = {
16
+ text,
17
+ id,
18
+ nullableText,
19
+ boolean,
20
+ timestamp,
21
+ nullableTimestamp,
22
+ count,
23
+ nullableCount,
24
+ };
25
+ export const siteUrl = {
26
+ ...id,
27
+ description: 'The URL of the site as the host configured it, such as https://contoso.sharepoint.com/sites/Sales. Each stream is read once for each site.',
28
+ };
29
+ export const createdBy = {
30
+ ...nullableText,
31
+ description: "Who created it: the identitySet of Graph as JSON, with user, application or group, each with id, displayName and email when Graph gives them. Read a part with json_extract(createdBy, '$.user.email'). NULL when Graph gives none.",
32
+ };
33
+ export const lastModifiedBy = {
34
+ ...nullableText,
35
+ description: "Who changed it last: the identitySet of Graph as JSON, as createdBy. Read a part with json_extract(lastModifiedBy, '$.user.displayName'). NULL when Graph gives none.",
36
+ };
37
+ /**
38
+ * A SharePoint stream: its declaration, and how one read of one site turns
39
+ * Graph's answers into messages. Each family that reads alike is a subclass:
40
+ * the snapshots that Graph lists whole on each read, and the delta feeds.
41
+ */
42
+ export class SharePointStream {
43
+ stream;
44
+ covers;
45
+ constructor({ name, description, properties, primaryKey, covers, supportsFileTransfer, }) {
46
+ this.stream = new Stream({
47
+ name,
48
+ jsonSchema: {
49
+ type: 'object',
50
+ description,
51
+ properties,
52
+ required: Object.keys(properties),
53
+ },
54
+ primaryKey,
55
+ supportedSyncModes: ['full_refresh', 'incremental'],
56
+ sourceDefinedCursor: true,
57
+ emitsDeletes: true,
58
+ partitionKey: ['siteUrl'],
59
+ supportsFileTransfer,
60
+ });
61
+ this.covers = covers;
62
+ }
63
+ // One record, checked against the schema as it is read, so a read holds
64
+ // one record at a time.
65
+ validated(draft) {
66
+ const [record] = validateRecords(this.stream, [draft], 'SharePoint');
67
+ if (record === undefined)
68
+ throw new TypeError(`SharePoint ${this.stream.name} lost a record`);
69
+ return record;
70
+ }
71
+ }
72
+ // Graph gives instants to the second (2026-11-17T09:30:00Z); they load in the
73
+ // canonical millisecond form of elt.
74
+ export function instant(value) {
75
+ return new Date(value).toISOString();
76
+ }
77
+ export function nullableInstant(value) {
78
+ return value === undefined ? null : instant(value);
79
+ }
80
+ // An identitySet of Graph, or any other value that Graph gives as an object,
81
+ // as JSON text; null when Graph gives none.
82
+ export function json(value) {
83
+ return value === undefined ? null : JSON.stringify(value);
84
+ }
@@ -0,0 +1,13 @@
1
+ import { type CopyConfiguration, type SourceMessage } from '@eltjs/elt';
2
+ import type { SharePointRun } from './sharepoint-run.ts';
3
+ import { SharePointStream } from './sharepoint-stream.ts';
4
+ /**
5
+ * A stream that Graph lists whole on each read, with no change feed: an
6
+ * incremental copy compares each read with the snapshot of the last one,
7
+ * writes what changed and deletes what Graph no longer lists.
8
+ */
9
+ export declare abstract class SnapshotStream extends SharePointStream {
10
+ #private;
11
+ extract(configuration: CopyConfiguration, state: unknown, siteUrl: string, run: SharePointRun, signal: AbortSignal): AsyncGenerator<SourceMessage>;
12
+ protected abstract scan(siteUrl: string, run: SharePointRun, signal: AbortSignal): AsyncIterable<Record<string, unknown>>;
13
+ }
@@ -0,0 +1,25 @@
1
+ import { ClosedWorld } from '@zukhruf/snapshot-differential';
2
+ import { diffSnapshot, } from '@eltjs/elt';
3
+ import { SharePointStream } from './sharepoint-stream.js';
4
+ /**
5
+ * A stream that Graph lists whole on each read, with no change feed: an
6
+ * incremental copy compares each read with the snapshot of the last one,
7
+ * writes what changed and deletes what Graph no longer lists.
8
+ */
9
+ export class SnapshotStream extends SharePointStream {
10
+ async *extract(configuration, state, siteUrl, run, signal) {
11
+ yield* diffSnapshot(configuration, this.#records(siteUrl, run, signal), state, { policy: new ClosedWorld(), signal });
12
+ }
13
+ // The pages of a collection can give one item twice, as when it changes
14
+ // while a read pages through them, and a snapshot diff fails on a key that
15
+ // a scan gives twice. The last one is the newest.
16
+ async *#records(siteUrl, run, signal) {
17
+ const records = new Map();
18
+ for await (const draft of this.scan(siteUrl, run, signal)) {
19
+ const record = this.validated(draft);
20
+ const key = this.stream.primaryKey.map((field) => record[field]);
21
+ records.set(JSON.stringify(key), record);
22
+ }
23
+ yield* records.values();
24
+ }
25
+ }
@@ -0,0 +1,8 @@
1
+ import type { RecordDraft } from '@eltjs/elt';
2
+ import { listItemProperties } from '../list-item-record.ts';
3
+ import type { SharePointRun } from '../sharepoint-run.ts';
4
+ import { SnapshotStream } from '../snapshot-stream.ts';
5
+ export declare class AccessRequestsStream extends SnapshotStream {
6
+ constructor();
7
+ protected scan(url: string, run: SharePointRun, signal: AbortSignal): AsyncGenerator<RecordDraft<typeof listItemProperties>>;
8
+ }
@@ -0,0 +1,20 @@
1
+ import { accessRequestTemplate, listItemProperties, listItemRecord, } from '../list-item-record.js';
2
+ import { SnapshotStream } from '../snapshot-stream.js';
3
+ export class AccessRequestsStream extends SnapshotStream {
4
+ constructor() {
5
+ super({
6
+ name: 'accessRequests',
7
+ description: 'One record for each item of the lists of the requests for access to the site (template accessRequest), with the value of each column as JSON, as listItems has. Graph serves no item delta for these lists, so each read lists their items in full. Primary key siteUrl, listId, itemId. An incremental read deletes an item that Graph no longer lists.',
8
+ properties: listItemProperties,
9
+ primaryKey: ['siteUrl', 'listId', 'itemId'],
10
+ covers: 'Every item of each list of the requests for access of each configured site.',
11
+ });
12
+ }
13
+ async *scan(url, run, signal) {
14
+ const { id: siteId } = await run.site(url, signal);
15
+ for (const list of await run.lists(url, signal))
16
+ if (list.list.template === accessRequestTemplate)
17
+ for (const item of await run.client.listItems(siteId, list.id, signal))
18
+ yield listItemRecord(url, list.id, item);
19
+ }
20
+ }
@@ -0,0 +1,10 @@
1
+ import { type CopyConfiguration, type SourceMessage } from '@eltjs/elt';
2
+ import { type DeltaPage, type DriveItem } from '@eltjs/sdk-microsoft-sharepoint';
3
+ import { DeltaStream } from '../delta-stream.ts';
4
+ import type { SharePointRun } from '../sharepoint-run.ts';
5
+ export declare class DriveItemsStream extends DeltaStream<DriveItem> {
6
+ constructor();
7
+ protected collections(url: string, run: SharePointRun, signal: AbortSignal): Promise<readonly string[]>;
8
+ protected pages(_url: string, driveId: string, link: string | undefined, run: SharePointRun, signal: AbortSignal): AsyncIterable<DeltaPage<DriveItem>>;
9
+ protected messages(configuration: CopyConfiguration, url: string, driveId: string, item: DriveItem, run: SharePointRun, signal: AbortSignal): AsyncGenerator<SourceMessage>;
10
+ }
@@ -0,0 +1,163 @@
1
+ import { rm } from 'node:fs/promises';
2
+ import { fileExtension, } from '@eltjs/elt';
3
+ import { GraphError, } from '@eltjs/sdk-microsoft-sharepoint';
4
+ import { DeltaStream } from '../delta-stream.js';
5
+ import { createdBy, instant, json, lastModifiedBy, sharePointFields, siteUrl, } from '../sharepoint-stream.js';
6
+ const { id, text, nullableText, boolean, timestamp, count, nullableCount } = sharePointFields;
7
+ const properties = {
8
+ siteUrl,
9
+ driveId: {
10
+ ...id,
11
+ description: 'The document library of the item: drives.driveId.',
12
+ },
13
+ itemId: { ...id, description: "Graph's ID of the file or the folder." },
14
+ name: {
15
+ ...text,
16
+ description: 'The name of the file or the folder, with its extension.',
17
+ },
18
+ isFolder: { ...boolean, description: 'Whether the item is a folder.' },
19
+ size: {
20
+ ...count,
21
+ description: 'The size in bytes: of the file, or of every file in the folder.',
22
+ },
23
+ mimeType: {
24
+ ...nullableText,
25
+ description: 'The media type of the file. NULL for a folder.',
26
+ },
27
+ quickXorHash: {
28
+ ...nullableText,
29
+ description: 'The quickXorHash of the content, in base64. NULL for a folder, or when Graph gives none.',
30
+ },
31
+ sha1Hash: {
32
+ ...nullableText,
33
+ description: 'The SHA-1 of the content, in hex. NULL when Graph gives none, as for most files of SharePoint.',
34
+ },
35
+ sha256Hash: {
36
+ ...nullableText,
37
+ description: 'The SHA-256 of the content, in hex. NULL when Graph gives none, as for most files of SharePoint.',
38
+ },
39
+ childCount: {
40
+ ...nullableCount,
41
+ description: 'How many items the folder holds. NULL for a file.',
42
+ },
43
+ parentId: {
44
+ ...nullableText,
45
+ description: 'The folder that holds the item: its itemId. The root folder of the library has no row.',
46
+ },
47
+ path: {
48
+ ...nullableText,
49
+ description: 'The path of the folder that holds the item, as Graph gives it, such as /drives/<driveId>/root:/02 BD Resources. NULL when the delta of Graph leaves it out.',
50
+ },
51
+ webUrl: { ...text, description: 'The URL of the file or the folder.' },
52
+ createdDateTime: {
53
+ ...timestamp,
54
+ description: 'When the item was created, in UTC.',
55
+ },
56
+ lastModifiedDateTime: {
57
+ ...timestamp,
58
+ description: 'When the item last changed, in UTC.',
59
+ },
60
+ createdBy,
61
+ lastModifiedBy,
62
+ eTag: {
63
+ ...nullableText,
64
+ description: 'The version tag of the item, which changes when its content or its metadata changes. NULL when Graph gives none.',
65
+ },
66
+ cTag: {
67
+ ...nullableText,
68
+ description: 'The version tag of the content of the item, which changes only when the content changes. NULL when the delta of Graph leaves it out.',
69
+ },
70
+ listItemId: {
71
+ ...nullableText,
72
+ description: 'The item of the library list that holds the metadata columns of the file or the folder: listItems.itemId of the list of the library. NULL when Graph gives none.',
73
+ },
74
+ };
75
+ export class DriveItemsStream extends DeltaStream {
76
+ constructor() {
77
+ super({
78
+ name: 'driveItems',
79
+ description: 'One record for each file and folder of each document library of the site, without the root folder of the library, which drives describes. A copy can take the content of a file through the file of the stream; a field that accepts only some file names downloads only those files. Primary key siteUrl, driveId, itemId. Read through the drive delta of Graph: the first read loads every item, and later reads apply the changes and deletions after it.',
80
+ properties,
81
+ primaryKey: ['siteUrl', 'driveId', 'itemId'],
82
+ covers: 'Every file and folder of every document library of each configured site, then the changes that the drive delta of Graph reports.',
83
+ supportsFileTransfer: true,
84
+ });
85
+ }
86
+ async collections(url, run, signal) {
87
+ return (await run.drives(url, signal)).map((drive) => drive.id);
88
+ }
89
+ pages(_url, driveId, link, run, signal) {
90
+ return run.client.driveDelta(driveId, link, signal);
91
+ }
92
+ async *messages(configuration, url, driveId, item, run, signal) {
93
+ if (item.deleted !== undefined) {
94
+ yield* this.deletion(configuration, {
95
+ siteUrl: url,
96
+ driveId,
97
+ itemId: item.id,
98
+ });
99
+ return;
100
+ }
101
+ // A delta gives the root folder of the drive on each of its pages (live,
102
+ // 2026-11-17: 31 times over 31 pages), with no eTag and no author.
103
+ if (item.root !== undefined)
104
+ return;
105
+ const data = this.validated(record(url, driveId, item));
106
+ if (configuration.fileReads.length === 0) {
107
+ yield { stream: this.stream.name, data };
108
+ return;
109
+ }
110
+ const file = item.file !== undefined &&
111
+ configuration.fileReads.some((read) => read.accepts(item.name))
112
+ ? await download(run, driveId, item, signal)
113
+ : null;
114
+ try {
115
+ yield { stream: this.stream.name, data, file };
116
+ }
117
+ finally {
118
+ if (file !== null)
119
+ await rm(file, { force: true });
120
+ }
121
+ }
122
+ }
123
+ function record(url, driveId, item) {
124
+ return {
125
+ siteUrl: url,
126
+ driveId,
127
+ itemId: item.id,
128
+ name: item.name,
129
+ isFolder: item.folder !== undefined,
130
+ size: item.size,
131
+ mimeType: item.file?.mimeType ?? null,
132
+ quickXorHash: item.file?.hashes?.quickXorHash ?? null,
133
+ sha1Hash: item.file?.hashes?.sha1Hash ?? null,
134
+ sha256Hash: item.file?.hashes?.sha256Hash ?? null,
135
+ childCount: item.folder?.childCount ?? null,
136
+ parentId: item.parentReference.id ?? null,
137
+ path: item.parentReference.path ?? null,
138
+ webUrl: item.webUrl,
139
+ createdDateTime: instant(item.createdDateTime),
140
+ lastModifiedDateTime: instant(item.lastModifiedDateTime),
141
+ createdBy: json(item.createdBy),
142
+ lastModifiedBy: json(item.lastModifiedBy),
143
+ eTag: item.eTag ?? null,
144
+ cTag: item.cTag ?? null,
145
+ listItemId: item.sharepointIds?.listItemId ?? null,
146
+ };
147
+ }
148
+ // The content of a file, staged in the run's folder under its item ID and
149
+ // the extension of its name, which a parser reads the format from. null when
150
+ // the file was deleted after the delta listed it: the next delta gives its
151
+ // deletion.
152
+ async function download(run, driveId, item, signal) {
153
+ const path = run.staged(`${item.id}${fileExtension(item.name)}`);
154
+ try {
155
+ await run.client.download(driveId, item.id, path, signal);
156
+ return path;
157
+ }
158
+ catch (error) {
159
+ if (error instanceof GraphError && error.status === 404)
160
+ return null;
161
+ throw error;
162
+ }
163
+ }