@eltjs/sdk-microsoft-sharepoint 0.0.0-stage → 0.3.11

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.
package/dist/page.d.ts ADDED
@@ -0,0 +1,137 @@
1
+ import { z } from 'zod';
2
+ /** A modern page of the site's Site Pages library, without its content. */
3
+ export declare const sitePage: z.ZodObject<{
4
+ id: z.ZodString;
5
+ name: z.ZodString;
6
+ title: z.ZodString;
7
+ description: z.ZodOptional<z.ZodString>;
8
+ webUrl: z.ZodString;
9
+ pageLayout: z.ZodOptional<z.ZodString>;
10
+ eTag: z.ZodOptional<z.ZodString>;
11
+ createdDateTime: z.ZodOptional<z.ZodISODateTime>;
12
+ lastModifiedDateTime: z.ZodISODateTime;
13
+ createdBy: z.ZodOptional<z.ZodObject<{
14
+ user: z.ZodOptional<z.ZodObject<{
15
+ id: z.ZodOptional<z.ZodString>;
16
+ displayName: z.ZodOptional<z.ZodString>;
17
+ email: z.ZodOptional<z.ZodString>;
18
+ }, z.core.$strip>>;
19
+ application: z.ZodOptional<z.ZodObject<{
20
+ id: z.ZodOptional<z.ZodString>;
21
+ displayName: z.ZodOptional<z.ZodString>;
22
+ email: z.ZodOptional<z.ZodString>;
23
+ }, z.core.$strip>>;
24
+ group: z.ZodOptional<z.ZodObject<{
25
+ id: z.ZodOptional<z.ZodString>;
26
+ displayName: z.ZodOptional<z.ZodString>;
27
+ email: z.ZodOptional<z.ZodString>;
28
+ }, z.core.$strip>>;
29
+ }, z.core.$strip>>;
30
+ lastModifiedBy: z.ZodOptional<z.ZodObject<{
31
+ user: z.ZodOptional<z.ZodObject<{
32
+ id: z.ZodOptional<z.ZodString>;
33
+ displayName: z.ZodOptional<z.ZodString>;
34
+ email: z.ZodOptional<z.ZodString>;
35
+ }, z.core.$strip>>;
36
+ application: z.ZodOptional<z.ZodObject<{
37
+ id: z.ZodOptional<z.ZodString>;
38
+ displayName: z.ZodOptional<z.ZodString>;
39
+ email: z.ZodOptional<z.ZodString>;
40
+ }, z.core.$strip>>;
41
+ group: z.ZodOptional<z.ZodObject<{
42
+ id: z.ZodOptional<z.ZodString>;
43
+ displayName: z.ZodOptional<z.ZodString>;
44
+ email: z.ZodOptional<z.ZodString>;
45
+ }, z.core.$strip>>;
46
+ }, z.core.$strip>>;
47
+ publishingState: z.ZodOptional<z.ZodObject<{
48
+ level: z.ZodString;
49
+ versionId: z.ZodString;
50
+ }, z.core.$strip>>;
51
+ }, z.core.$strip>;
52
+ export type SitePage = z.infer<typeof sitePage>;
53
+ declare const textWebPart: z.ZodPipe<z.ZodObject<{
54
+ '@odata.type': z.ZodLiteral<"#microsoft.graph.textWebPart">;
55
+ id: z.ZodString;
56
+ innerHtml: z.ZodString;
57
+ }, z.core.$strip>, z.ZodTransform<{
58
+ id: string;
59
+ innerHtml: string;
60
+ }, {
61
+ '@odata.type': "#microsoft.graph.textWebPart";
62
+ id: string;
63
+ innerHtml: string;
64
+ }>>;
65
+ export type TextWebPart = z.infer<typeof textWebPart>;
66
+ /**
67
+ * A page with its canvas, read for its text web parts: the HTML that people
68
+ * wrote on the page, in the order of the canvas (each horizontal section's
69
+ * columns from left to right, then the vertical section).
70
+ */
71
+ export declare const pageCanvas: z.ZodPipe<z.ZodObject<{
72
+ canvasLayout: z.ZodObject<{
73
+ horizontalSections: z.ZodArray<z.ZodObject<{
74
+ columns: z.ZodArray<z.ZodObject<{
75
+ webparts: z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
76
+ '@odata.type': z.ZodLiteral<"#microsoft.graph.textWebPart">;
77
+ id: z.ZodString;
78
+ innerHtml: z.ZodString;
79
+ }, z.core.$strip>, z.ZodTransform<{
80
+ id: string;
81
+ innerHtml: string;
82
+ }, {
83
+ '@odata.type': "#microsoft.graph.textWebPart";
84
+ id: string;
85
+ innerHtml: string;
86
+ }>>, z.ZodPipe<z.ZodObject<{
87
+ '@odata.type': z.ZodString;
88
+ id: z.ZodString;
89
+ }, z.core.$strip>, z.ZodTransform<undefined, {
90
+ '@odata.type': string;
91
+ id: string;
92
+ }>>]>>;
93
+ }, z.core.$strip>>;
94
+ }, z.core.$strip>>;
95
+ verticalSection: z.ZodOptional<z.ZodNullable<z.ZodObject<{
96
+ webparts: z.ZodArray<z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
97
+ '@odata.type': z.ZodLiteral<"#microsoft.graph.textWebPart">;
98
+ id: z.ZodString;
99
+ innerHtml: z.ZodString;
100
+ }, z.core.$strip>, z.ZodTransform<{
101
+ id: string;
102
+ innerHtml: string;
103
+ }, {
104
+ '@odata.type': "#microsoft.graph.textWebPart";
105
+ id: string;
106
+ innerHtml: string;
107
+ }>>, z.ZodPipe<z.ZodObject<{
108
+ '@odata.type': z.ZodString;
109
+ id: z.ZodString;
110
+ }, z.core.$strip>, z.ZodTransform<undefined, {
111
+ '@odata.type': string;
112
+ id: string;
113
+ }>>]>>;
114
+ }, z.core.$strip>>>;
115
+ }, z.core.$strip>;
116
+ }, z.core.$strip>, z.ZodTransform<readonly {
117
+ id: string;
118
+ innerHtml: string;
119
+ }[], {
120
+ canvasLayout: {
121
+ horizontalSections: {
122
+ columns: {
123
+ webparts: ({
124
+ id: string;
125
+ innerHtml: string;
126
+ } | undefined)[];
127
+ }[];
128
+ }[];
129
+ verticalSection?: {
130
+ webparts: ({
131
+ id: string;
132
+ innerHtml: string;
133
+ } | undefined)[];
134
+ } | null | undefined;
135
+ };
136
+ }>>;
137
+ export {};
package/dist/page.js ADDED
@@ -0,0 +1,53 @@
1
+ import { z } from 'zod';
2
+ import { identitySet, timestamp } from './graph-values.js';
3
+ /** A modern page of the site's Site Pages library, without its content. */
4
+ export const sitePage = z.object({
5
+ id: z.string(),
6
+ name: z.string(),
7
+ title: z.string(),
8
+ description: z.string().optional(),
9
+ webUrl: z.string(),
10
+ pageLayout: z.string().optional(),
11
+ eTag: z.string().optional(),
12
+ // Graph's own example of a page list leaves it out.
13
+ createdDateTime: timestamp.optional(),
14
+ lastModifiedDateTime: timestamp,
15
+ createdBy: identitySet.optional(),
16
+ lastModifiedBy: identitySet.optional(),
17
+ publishingState: z
18
+ .object({ level: z.string(), versionId: z.string() })
19
+ .optional(),
20
+ });
21
+ const TEXT = '#microsoft.graph.textWebPart';
22
+ const textWebPart = z
23
+ .object({
24
+ '@odata.type': z.literal(TEXT),
25
+ id: z.string(),
26
+ innerHtml: z.string(),
27
+ })
28
+ .transform(({ id, innerHtml }) => ({ id, innerHtml }));
29
+ // Every web part that is not text, such as an image or a list view: it holds
30
+ // no text that people wrote.
31
+ const otherWebPart = z
32
+ .object({
33
+ '@odata.type': z.string().refine((type) => type !== TEXT),
34
+ id: z.string(),
35
+ })
36
+ .transform(() => undefined);
37
+ const webParts = z.array(z.union([textWebPart, otherWebPart]));
38
+ /**
39
+ * A page with its canvas, read for its text web parts: the HTML that people
40
+ * wrote on the page, in the order of the canvas (each horizontal section's
41
+ * columns from left to right, then the vertical section).
42
+ */
43
+ export const pageCanvas = z
44
+ .object({
45
+ canvasLayout: z.object({
46
+ horizontalSections: z.array(z.object({ columns: z.array(z.object({ webparts: webParts })) })),
47
+ verticalSection: z.object({ webparts: webParts }).nullish(),
48
+ }),
49
+ })
50
+ .transform(({ canvasLayout }) => [
51
+ ...canvasLayout.horizontalSections.flatMap((section) => section.columns.flatMap((column) => column.webparts)),
52
+ ...(canvasLayout.verticalSection?.webparts ?? []),
53
+ ].filter((part) => part !== undefined));
@@ -0,0 +1,56 @@
1
+ import { type Column } from './column.ts';
2
+ import { type DeltaPage } from './delta.ts';
3
+ import { type DriveItem } from './drive-item.ts';
4
+ import { type Drive } from './drive.ts';
5
+ import { type SharePointClientOptions } from './graph.ts';
6
+ import { type ListItem, type PresentListItem } from './list-item.ts';
7
+ import { type List } from './list.ts';
8
+ import { type SitePage, type TextWebPart } from './page.ts';
9
+ import { type Site } from './site.ts';
10
+ /**
11
+ * Reads SharePoint Online through Microsoft Graph, as one app with an
12
+ * app-only token. Each call stops when `signal` aborts.
13
+ */
14
+ export declare class SharePointClient {
15
+ #private;
16
+ /** The Microsoft Entra tenant of the app, which owns the sites it reads. */
17
+ readonly tenantId: string;
18
+ constructor(options: SharePointClientOptions);
19
+ /** The site at `url`, such as `https://contoso.sharepoint.com/sites/Sales`. */
20
+ site(url: string, signal: AbortSignal): Promise<Site>;
21
+ /** The document libraries of the site. */
22
+ drives(siteId: string, signal: AbortSignal): Promise<readonly Drive[]>;
23
+ /**
24
+ * The lists of the site, its document libraries and hidden lists included.
25
+ * Graph leaves out the lists that it marks `system`.
26
+ */
27
+ lists(siteId: string, signal: AbortSignal): Promise<readonly List[]>;
28
+ /** The columns of a list that are not hidden. */
29
+ columns(siteId: string, listId: string, signal: AbortSignal): Promise<readonly Column[]>;
30
+ /** The modern pages of the site, without their content. */
31
+ pages(siteId: string, signal: AbortSignal): Promise<readonly SitePage[]>;
32
+ /** The text web parts of a page, in the order of its canvas. */
33
+ textWebParts(siteId: string, pageId: string, signal: AbortSignal): Promise<readonly TextWebPart[]>;
34
+ /**
35
+ * The files and folders of a drive: every one without `link`, else the
36
+ * changes after it. `link` is a nextLink or a deltaLink of an earlier page.
37
+ */
38
+ driveDelta(driveId: string, link: string | undefined, signal: AbortSignal): AsyncGenerator<DeltaPage<DriveItem>, void, undefined>;
39
+ /**
40
+ * The items of a list with their fields: every one without `link`, else
41
+ * the changes after it. `link` is a nextLink or a deltaLink of an earlier
42
+ * page.
43
+ */
44
+ listItemsDelta(siteId: string, listId: string, link: string | undefined, signal: AbortSignal): AsyncGenerator<DeltaPage<ListItem>, void, undefined>;
45
+ /**
46
+ * Every item of a list, read in full. Graph serves no item delta for some
47
+ * lists, such as the hidden `accessRequest` list, which answers 503
48
+ * `serviceNotAvailable` on each try while its items read (live, 2026-11-17).
49
+ */
50
+ listItems(siteId: string, listId: string, signal: AbortSignal): Promise<readonly PresentListItem[]>;
51
+ /**
52
+ * Writes the content of a file of a drive to `path`, as it arrives. Graph
53
+ * redirects to a pre-signed URL, which the request follows.
54
+ */
55
+ download(driveId: string, itemId: string, path: string, signal: AbortSignal): Promise<void>;
56
+ }
@@ -0,0 +1,109 @@
1
+ import { createWriteStream } from 'node:fs';
2
+ import { Readable } from 'node:stream';
3
+ import { pipeline } from 'node:stream/promises';
4
+ import { column } from './column.js';
5
+ import { deltaPage } from './delta.js';
6
+ import { DRIVE_ITEM_FIELDS, driveItem } from './drive-item.js';
7
+ import { DRIVE_FIELDS, drive } from './drive.js';
8
+ import { DeltaExpiredError, GraphError, SharePointSiteNotFoundError, } from './errors.js';
9
+ import { Graph } from './graph.js';
10
+ import { listItem, presentListItem, } from './list-item.js';
11
+ import { LIST_FIELDS, list } from './list.js';
12
+ import { pageCanvas, sitePage, } from './page.js';
13
+ import { SITE_FIELDS, site, sitePath } from './site.js';
14
+ /**
15
+ * Reads SharePoint Online through Microsoft Graph, as one app with an
16
+ * app-only token. Each call stops when `signal` aborts.
17
+ */
18
+ export class SharePointClient {
19
+ /** The Microsoft Entra tenant of the app, which owns the sites it reads. */
20
+ tenantId;
21
+ #graph;
22
+ constructor(options) {
23
+ this.tenantId = options.tenantId;
24
+ this.#graph = new Graph(options);
25
+ }
26
+ /** The site at `url`, such as `https://contoso.sharepoint.com/sites/Sales`. */
27
+ async site(url, signal) {
28
+ try {
29
+ return await this.#graph.json(`${sitePath(url)}?$select=${SITE_FIELDS}`, site, url, signal);
30
+ }
31
+ catch (error) {
32
+ if (error instanceof GraphError && error.status === 404)
33
+ throw new SharePointSiteNotFoundError(url, { cause: error });
34
+ throw error;
35
+ }
36
+ }
37
+ /** The document libraries of the site. */
38
+ drives(siteId, signal) {
39
+ return this.#graph.collection(`/sites/${siteId}/drives?$select=${DRIVE_FIELDS}`, drive, siteId, signal);
40
+ }
41
+ /**
42
+ * The lists of the site, its document libraries and hidden lists included.
43
+ * Graph leaves out the lists that it marks `system`.
44
+ */
45
+ lists(siteId, signal) {
46
+ return this.#graph.collection(`/sites/${siteId}/lists?$select=${LIST_FIELDS}`, list, siteId, signal);
47
+ }
48
+ /** The columns of a list that are not hidden. */
49
+ columns(siteId, listId, signal) {
50
+ return this.#graph.collection(`/sites/${siteId}/lists/${listId}/columns`, column, siteId, signal);
51
+ }
52
+ /** The modern pages of the site, without their content. */
53
+ pages(siteId, signal) {
54
+ return this.#graph.collection(`/sites/${siteId}/pages`, sitePage, siteId, signal);
55
+ }
56
+ /** The text web parts of a page, in the order of its canvas. */
57
+ textWebParts(siteId, pageId, signal) {
58
+ return this.#graph.json(`/sites/${siteId}/pages/${pageId}/microsoft.graph.sitePage?$expand=canvasLayout`, pageCanvas, siteId, signal);
59
+ }
60
+ /**
61
+ * The files and folders of a drive: every one without `link`, else the
62
+ * changes after it. `link` is a nextLink or a deltaLink of an earlier page.
63
+ */
64
+ driveDelta(driveId, link, signal) {
65
+ return this.#delta(link ?? `/drives/${driveId}/root/delta?$select=${DRIVE_ITEM_FIELDS}`, driveItem, `the drive ${driveId}`, signal);
66
+ }
67
+ /**
68
+ * The items of a list with their fields: every one without `link`, else
69
+ * the changes after it. `link` is a nextLink or a deltaLink of an earlier
70
+ * page.
71
+ */
72
+ listItemsDelta(siteId, listId, link, signal) {
73
+ return this.#delta(link ?? `/sites/${siteId}/lists/${listId}/items/delta?$expand=fields`, listItem, siteId, signal);
74
+ }
75
+ /**
76
+ * Every item of a list, read in full. Graph serves no item delta for some
77
+ * lists, such as the hidden `accessRequest` list, which answers 503
78
+ * `serviceNotAvailable` on each try while its items read (live, 2026-11-17).
79
+ */
80
+ listItems(siteId, listId, signal) {
81
+ return this.#graph.collection(`/sites/${siteId}/lists/${listId}/items?$expand=fields`, presentListItem, siteId, signal);
82
+ }
83
+ /**
84
+ * Writes the content of a file of a drive to `path`, as it arrives. Graph
85
+ * redirects to a pre-signed URL, which the request follows.
86
+ */
87
+ async download(driveId, itemId, path, signal) {
88
+ const response = await this.#graph.get(`/drives/${driveId}/items/${itemId}/content`, `the drive ${driveId}`, signal);
89
+ // A 204 has no body: the file is empty.
90
+ const body = response.body ?? Readable.from([]);
91
+ await pipeline(body, createWriteStream(path), { signal });
92
+ }
93
+ async *#delta(first, item, resource, signal) {
94
+ const page = deltaPage(item);
95
+ for (let next = first;;) {
96
+ const body = await this.#graph
97
+ .json(next, page, resource, signal)
98
+ .catch((error) => {
99
+ if (error instanceof GraphError && error.status === 410)
100
+ throw new DeltaExpiredError({ cause: error });
101
+ throw error;
102
+ });
103
+ yield body;
104
+ if ('deltaLink' in body)
105
+ return;
106
+ next = body.nextLink;
107
+ }
108
+ }
109
+ }
@@ -0,0 +1,14 @@
1
+ import { type Check, Gauge } from '@zukhruf/async';
2
+ import type { SharePointClient } from './sharepoint-client.ts';
3
+ /**
4
+ * What changes when the content of a site does: the lastModifiedDateTime of
5
+ * each of its lists, which include its document libraries, and of each of
6
+ * its pages. A change watcher reads it as a gauge. Each read finds the site
7
+ * first, so a site that the app cannot read fails that read, not the gauge's
8
+ * creation (elt ADR 0020).
9
+ */
10
+ export declare class SiteVersion extends Gauge<string> {
11
+ #private;
12
+ constructor(client: SharePointClient, url: string);
13
+ protected read({ signal }: Check): Promise<string>;
14
+ }
@@ -0,0 +1,30 @@
1
+ import { Gauge } from '@zukhruf/async';
2
+ /**
3
+ * What changes when the content of a site does: the lastModifiedDateTime of
4
+ * each of its lists, which include its document libraries, and of each of
5
+ * its pages. A change watcher reads it as a gauge. Each read finds the site
6
+ * first, so a site that the app cannot read fails that read, not the gauge's
7
+ * creation (elt ADR 0020).
8
+ */
9
+ export class SiteVersion extends Gauge {
10
+ #client;
11
+ #url;
12
+ constructor(client, url) {
13
+ super();
14
+ this.#client = client;
15
+ this.#url = url;
16
+ }
17
+ async read({ signal }) {
18
+ const { id: siteId } = await this.#client.site(this.#url, signal);
19
+ const [lists, pages] = await Promise.all([
20
+ this.#client.lists(siteId, signal),
21
+ this.#client.pages(siteId, signal),
22
+ ]);
23
+ return [
24
+ ...lists.map((list) => `list ${list.id} ${list.lastModifiedDateTime}`),
25
+ ...pages.map((page) => `page ${page.id} ${page.lastModifiedDateTime}`),
26
+ ]
27
+ .sort()
28
+ .join('\n');
29
+ }
30
+ }
package/dist/site.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ import { z } from 'zod';
2
+ export declare const SITE_FIELDS = "id,name,displayName,description,webUrl,createdDateTime,lastModifiedDateTime";
3
+ /** A SharePoint site. `id` is Graph's composite `<host>,<site collection>,<web>`. */
4
+ export declare const site: z.ZodObject<{
5
+ id: z.ZodString;
6
+ name: z.ZodString;
7
+ displayName: z.ZodString;
8
+ description: z.ZodOptional<z.ZodString>;
9
+ webUrl: z.ZodString;
10
+ createdDateTime: z.ZodISODateTime;
11
+ lastModifiedDateTime: z.ZodISODateTime;
12
+ }, z.core.$strip>;
13
+ export type Site = z.infer<typeof site>;
14
+ /**
15
+ * The Graph path of the site at `url`, such as
16
+ * `https://contoso.sharepoint.com/sites/Sales`:
17
+ * `/sites/contoso.sharepoint.com:/sites/Sales`.
18
+ */
19
+ export declare function sitePath(url: string): string;
package/dist/site.js ADDED
@@ -0,0 +1,24 @@
1
+ import { z } from 'zod';
2
+ import { timestamp } from './graph-values.js';
3
+ export const SITE_FIELDS = 'id,name,displayName,description,webUrl,createdDateTime,lastModifiedDateTime';
4
+ /** A SharePoint site. `id` is Graph's composite `<host>,<site collection>,<web>`. */
5
+ export const site = z.object({
6
+ id: z.string(),
7
+ name: z.string(),
8
+ displayName: z.string(),
9
+ // Graph leaves out a description that nobody wrote.
10
+ description: z.string().optional(),
11
+ webUrl: z.string(),
12
+ createdDateTime: timestamp,
13
+ lastModifiedDateTime: timestamp,
14
+ });
15
+ /**
16
+ * The Graph path of the site at `url`, such as
17
+ * `https://contoso.sharepoint.com/sites/Sales`:
18
+ * `/sites/contoso.sharepoint.com:/sites/Sales`.
19
+ */
20
+ export function sitePath(url) {
21
+ const { hostname, pathname } = new URL(url);
22
+ const path = pathname.replace(/\/+$/, '');
23
+ return path === '' ? `/sites/${hostname}` : `/sites/${hostname}:${path}`;
24
+ }
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@eltjs/sdk-microsoft-sharepoint",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.11",
4
+ "description": "Reads SharePoint Online sites through Microsoft Graph with an app-only token: drives, lists, pages, delta feeds, downloads and a change signal. It knows nothing of elt.",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/ezzabuzaid/elt",
9
+ "directory": "packages/sdks/microsoft/sharepoint"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/ezzabuzaid/elt/issues"
13
+ },
14
+ "homepage": "https://github.com/ezzabuzaid/elt/tree/main/packages/sdks/microsoft/sharepoint#readme",
15
+ "keywords": [
16
+ "sharepoint",
17
+ "microsoft-graph",
18
+ "delta-query",
19
+ "sites-selected"
20
+ ],
21
+ "type": "module",
22
+ "exports": {
23
+ "./package.json": "./package.json",
24
+ ".": {
25
+ "types": "./dist/index.d.ts",
26
+ "default": "./dist/index.js"
27
+ }
28
+ },
29
+ "files": [
30
+ "dist",
31
+ "!dist/spec/**",
32
+ "!**/*.tsbuildinfo",
33
+ "!**/*.test.*"
34
+ ],
35
+ "publishConfig": {
36
+ "access": "public"
37
+ },
38
+ "dependencies": {
39
+ "@azure/msal-node": "^7.2.2",
40
+ "@zukhruf/async": "^0.8.27",
41
+ "zod": "4.6.5"
42
+ },
43
+ "devDependencies": {
44
+ "@zukhruf/fs": "^0.8.27",
45
+ "@zukhruf/testing": "^0.8.27",
46
+ "msw": "^3.0.3"
47
+ }
48
+ }