@lindle/sharepoint_requests 0.1.18 → 0.1.20

package/src/root/index.ts

@@ -2,41 +2,64 @@ import { AxiosInstance, CreateAxiosDefaults as AxiosConfig } from 'axios';
 import instance from './instance';
 import {
   CreateFileProps,
-  DeleteFileProps,
   CurrentUser,
+  DeleteFileProps,
   EmailProps,
   Field_Options,
   Folder_Options,
-  UploadFileProps,
-  IListName,
   ItemID,
   ListData,
   Options,
   PersonField,
   SHAREPOINT_VER,
+  UploadFileProps,
   UserPermision,
   UserProfile,
 } from '../types';
 import { RequestContext } from './internal/context';
+import { sendEmail as sendEmailRequest } from './internal/emailRequests';
+import { fetchDigest } from './internal/digest';
 import {
   createAttachment,
   createListItem,
-  deleteItem,
   deleteFile as deleteLibraryFile,
+  deleteItem,
   getFiles,
   getListItems,
   getOnly,
   updateListItem,
   uploadFile,
 } from './internal/listRequests';
-import { sendEmail as sendEmailRequest } from './internal/emailRequests';
+import {
+  buildListByTitleEndpoint,
+  escapeODataStringLiteral,
+} from './internal/sharepointUrl';
 import {
   currentUserPermissions as resolveCurrentUserPermissions,
   currentUserProperties as loadCurrentUserProperties,
   getSiteUser as fetchSiteUser,
   typeAhead,
 } from './internal/userRequests';
-import { fetchDigest } from './internal/digest';
+
+type ListKey<T extends { LISTS: Record<string, unknown> }> = Extract<
+  keyof T['LISTS'],
+  string
+>;
+
+/**
+ * @deprecated SP.Utilities.Utility.SendEmail was retired by Microsoft on 2025-10-31
+ * and no longer sends emails. Migrate to Microsoft Graph API:
+ * POST /v1.0/me/sendMail  (delegated) or  POST /v1.0/users/{id}/sendMail  (app)
+ * https://learn.microsoft.com/en-us/graph/api/user-sendmail
+ */
+type EmailApi = ((
+  from: string,
+  to: string[] | string,
+  subject: string | undefined,
+  body: string
+) => ReturnType<typeof sendEmailRequest>) & {
+  send: (props: EmailProps) => ReturnType<typeof sendEmailRequest>;
+};
 
 class HTTPSharePointRequests<
   T extends {
@@ -44,52 +67,79 @@ class HTTPSharePointRequests<
     FOLDERS?: Record<string, unknown>;
   }
 > {
-  private baseURL: string;
-  private endpoint: string;
-  private listName: string;
-  private instance: AxiosInstance;
-  private sharepointVersion: SHAREPOINT_VER;
-  private listItemEntityTypeFullName?: string;
+  private readonly baseURL: string;
+  private readonly instance: AxiosInstance;
+  private readonly listItemEntityTypeCache: Map<string, string>;
+  /**
+   * @deprecated SP.Utilities.Utility.SendEmail was retired by Microsoft on 2025-10-31.
+   * Migrate to Microsoft Graph API POST /v1.0/me/sendMail
+   * https://learn.microsoft.com/en-us/graph/api/user-sendmail
+   */
+  public readonly email: EmailApi;
 
   constructor(baseURL: string, config?: AxiosConfig) {
     this.baseURL = baseURL.endsWith('/') ? baseURL : `${baseURL}/`;
-    this.endpoint = '/api';
-    this.listName = '';
     this.instance = instance(this.baseURL, config);
-    this.sharepointVersion = '2013';
-    this.listItemEntityTypeFullName = undefined;
+    this.listItemEntityTypeCache = new Map<string, string>();
+    const buildEmailContext = () =>
+      this.createContext<'2013'>({
+        endpoint: '_api/SP.Utilities.Utility.SendEmail',
+        listName: '',
+        sharepointVersion: '2013',
+      });
+    this.email = Object.assign(
+      (
+        from: string,
+        to: string[] | string,
+        subject: string | undefined,
+        body: string
+      ) =>
+        sendEmailRequest(buildEmailContext(), {
+          From: from,
+          To: to,
+          Subject: subject,
+          Body: body,
+        }),
+      {
+        send: (props: EmailProps) => sendEmailRequest(buildEmailContext(), props),
+      }
+    );
   }
 
-  private getContext<V extends SHAREPOINT_VER = '2013'>(): RequestContext<V> {
+  private createContext<V extends SHAREPOINT_VER = '2013'>({
+    endpoint,
+    listName,
+    sharepointVersion,
+    listItemEntityTypeFullName,
+    resolveListItemEntityType,
+  }: {
+    endpoint: string;
+    listName: string;
+    sharepointVersion: V;
+    listItemEntityTypeFullName?: string;
+    resolveListItemEntityType?: () => Promise<string>;
+  }): RequestContext<V> {
     return {
       instance: this.instance,
-      baseURL: this.baseURL,
-      endpoint: this.endpoint,
-      listName: this.listName,
-      sharepointVersion: this.sharepointVersion as V,
-      listItemEntityTypeFullName: this.listItemEntityTypeFullName,
-      resolveListItemEntityType: this.resolveListItemEntityTypeFullName.bind(
-        this
-      ),
+      endpoint,
+      listName,
+      sharepointVersion,
+      listItemEntityTypeFullName,
+      resolveListItemEntityType,
     };
   }
 
-  private async resolveListItemEntityTypeFullName(): Promise<string> {
-    if (this.listItemEntityTypeFullName) {
-      return this.listItemEntityTypeFullName;
-    }
-
-    if (!this.listName) {
-      throw new Error('List name is not set.');
-    }
-
-    if (this.sharepointVersion !== '2013') {
-      this.listItemEntityTypeFullName = `SP.Data.${this.listName}ListItem`;
-      return this.listItemEntityTypeFullName;
+  private async resolveListItemEntityTypeFullName(
+    listName: string
+  ): Promise<string> {
+    const cacheKey = listName;
+    const cachedType = this.listItemEntityTypeCache.get(cacheKey);
+    if (cachedType) {
+      return cachedType;
     }
 
     const response = await this.instance.get(
-      `_api/web/lists/GetByTitle('${this.listName}')?$select=ListItemEntityTypeFullName`
+      `${buildListByTitleEndpoint(listName)}?$select=ListItemEntityTypeFullName`
     );
 
     const entityType =
@@ -98,161 +148,246 @@ class HTTPSharePointRequests<
 
     if (!entityType || typeof entityType !== 'string') {
       throw new Error(
-        `Unable to resolve ListItemEntityTypeFullName for list "${this.listName}".`
+        `Unable to resolve ListItemEntityTypeFullName for list "${listName}".`
       );
     }
 
-    this.listItemEntityTypeFullName = entityType;
-    return this.listItemEntityTypeFullName;
+    this.listItemEntityTypeCache.set(cacheKey, entityType);
+    return entityType;
   }
 
-  /**
-   * @deprecated Use `from` instead.
-   */
-  list(listName: IListName<T>) {
-    this.listName = listName;
-    this.endpoint = `_vti_bin/ListData.svc/${listName}`;
-    this.sharepointVersion = '2010';
-    this.listItemEntityTypeFullName = undefined;
-    return this;
-  }
+  private buildListScope<
+    K extends ListKey<T>,
+    V extends SHAREPOINT_VER = '2013'
+  >(listName: K, version: V) {
+    const listNameValue = String(listName);
+    const endpoint =
+      version === '2013'
+        ? `${buildListByTitleEndpoint(listNameValue)}/items`
+        : `_vti_bin/ListData.svc/${encodeURIComponent(listNameValue)}`;
 
-  public readonly lists = {
-    get: () => {
-      this.endpoint = '_api/web/lists';
-      this.sharepointVersion = '2013';
-      return getListItems(this.getContext());
-    },
-  };
+    let scopedEntityType: string | undefined;
+    const resolveListItemEntityType = async () => {
+      if (scopedEntityType) {
+        return scopedEntityType;
+      }
 
-  public getDigest() {
-    return fetchDigest(this.instance, this.baseURL);
-  }
+      if (version !== '2013') {
+        scopedEntityType = `SP.Data.${listNameValue}ListItem`;
+        return scopedEntityType;
+      }
 
-  public from<
-    K extends Extract<keyof T['LISTS'], string>,
-    V extends SHAREPOINT_VER = '2013'
-  >(listName: K, sharepoint_ver?: V) {
-    const version = (sharepoint_ver ?? '2013') as V;
+      scopedEntityType = await this.resolveListItemEntityTypeFullName(
+        listNameValue
+      );
+      return scopedEntityType;
+    };
 
-    this.listName = listName;
-    this.sharepointVersion = version;
-    this.listItemEntityTypeFullName = undefined;
-    this.endpoint =
-      version === '2013'
-        ? `_api/web/lists/GetByTitle('${this.listName}')/items`
-        : `_vti_bin/ListData.svc/${listName}`;
+    const getContext = () =>
+      this.createContext<V>({
+        endpoint,
+        listName: listNameValue,
+        sharepointVersion: version,
+        listItemEntityTypeFullName: scopedEntityType,
+        resolveListItemEntityType,
+      });
 
-    const getContext = () => this.getContext<V>();
+    const removeItem = (id: ItemID) => deleteItem(getContext(), id);
+    const removeFile = (props: DeleteFileProps) =>
+      deleteLibraryFile(getContext(), props);
 
     return {
       create: (data: ListData<T['LISTS'][K]>) =>
         createListItem<T['LISTS'][K], V>(getContext(), data),
       get: (options?: Options<T['LISTS'][K], V>) =>
         getListItems<T['LISTS'][K], V>(getContext(), options),
-      update: (
-        id: ItemID,
-        data: ListData<T['LISTS'][K]>,
-        digest?: string
-      ) => updateListItem<T['LISTS'][K], V>(getContext(), id, data, digest),
-      delete: (id: ItemID) => deleteItem(getContext(), id),
+      update: (id: ItemID, data: ListData<T['LISTS'][K]>, digest?: string) =>
+        updateListItem<T['LISTS'][K], V>(getContext(), id, data, digest),
+      delete: removeItem,
+      remove: removeItem,
       createFile: (props: CreateFileProps) =>
         createAttachment(getContext(), props),
       uploadFile: (props: UploadFileProps) => uploadFile(getContext(), props),
-      deleteFile: (props: DeleteFileProps) =>
-        deleteLibraryFile(getContext(), props),
+      deleteFile: removeFile,
+      removeFile,
       fields: (options?: Field_Options<T['LISTS'][K], V>) => {
-        this.endpoint = !options?.fieldName
-          ? `_api/web/lists/GetByTitle('${this.listName}')/fields`
-          : `_api/web/lists/GetByTitle('${this.listName}')/fields/getbytitle('${options.fieldName}')`;
+        const fieldsEndpoint = !options?.fieldName
+          ? `${buildListByTitleEndpoint(listNameValue)}/fields`
+          : `${buildListByTitleEndpoint(
+              listNameValue
+            )}/fields/getbytitle('${escapeODataStringLiteral(
+              String(options.fieldName)
+            )}')`;
         return {
           get: () =>
-            getOnly<T['LISTS'][K], V>(this.instance, this.endpoint, options),
+            getOnly<T['LISTS'][K], V>(this.instance, fieldsEndpoint, options),
         };
       },
+      items: {
+        create: (data: ListData<T['LISTS'][K]>) =>
+          createListItem<T['LISTS'][K], V>(getContext(), data),
+        get: (options?: Options<T['LISTS'][K], V>) =>
+          getListItems<T['LISTS'][K], V>(getContext(), options),
+        update: (id: ItemID, data: ListData<T['LISTS'][K]>, digest?: string) =>
+          updateListItem<T['LISTS'][K], V>(getContext(), id, data, digest),
+        delete: removeItem,
+        remove: removeItem,
+      },
+      files: {
+        attach: (props: CreateFileProps) =>
+          createAttachment(getContext(), props),
+        upload: (props: UploadFileProps) => uploadFile(getContext(), props),
+        delete: removeFile,
+        remove: removeFile,
+      },
     };
   }
 
-  public folders = {
-    get: () => {
-      this.endpoint = '_api/web/folders';
-      this.sharepointVersion = '2013';
-      getListItems(this.getContext());
-    },
-  };
+  /**
+   * @deprecated Use `from(listName, '2010')` instead.
+   */
+  list<K extends ListKey<T>>(listName: K) {
+    return this.from<K, '2010'>(listName, '2010');
+  }
 
-  public folder(folderName?: string | string[]) {
-    let filePath = ['Shared Documents'];
+  public from<K extends ListKey<T>, V extends SHAREPOINT_VER = '2013'>(
+    listName: K,
+    sharepointVersion?: V
+  ) {
+    const version = (sharepointVersion ?? '2013') as V;
+    return this.buildListScope<K, V>(listName, version);
+  }
 
-    if (folderName) {
-      filePath = Array.isArray(folderName)
-        ? [...filePath, ...folderName]
-        : [...filePath, folderName];
-    }
+  public field<K extends ListKey<T>, V extends SHAREPOINT_VER = '2013'>(
+    listName: K,
+    fieldName?: Extract<keyof T['LISTS'][K], string>,
+    sharepointVersion?: V
+  ) {
+    return this.from<K, V>(listName, sharepointVersion)
+      .fields({
+        fieldName,
+      } as Field_Options<T['LISTS'][K], V>)
+      .get();
+  }
+
+  public lists(options?: Options<Record<string, unknown>, '2013'>) {
+    const context = this.createContext<'2013'>({
+      endpoint: '_api/web/lists',
+      listName: '',
+      sharepointVersion: '2013',
+    });
+
+    return {
+      get: () => getListItems<Record<string, unknown>, '2013'>(context, options),
+    };
+  }
 
-    this.endpoint = `_api/web/GetFolderByServerRelativeUrl('${filePath.join(
-      '/'
-    )}')`;
-    this.sharepointVersion = '2013';
+  public getDigest() {
+    return fetchDigest(this.instance);
+  }
 
-    const getContext = () => this.getContext();
+  public folders(options?: Folder_Options<Record<string, unknown>>) {
+    const context = this.createContext<'2013'>({
+      endpoint: '_api/web/folders',
+      listName: '',
+      sharepointVersion: '2013',
+    });
 
     return {
-      get: (options?: Folder_Options<any>) => {
-        if (!options?.type) {
-          this.endpoint += '/Files';
-        } else {
-          this.endpoint += `/${options.type}`;
-        }
-        return getFiles(getContext(), options);
+      get: () => getFiles<Record<string, unknown>, '2013'>(context, options),
+    };
+  }
+
+  public folder(folderName?: string | string[]) {
+    const defaultPath = ['Shared Documents'];
+    const segments = folderName
+      ? Array.isArray(folderName)
+        ? [...defaultPath, ...folderName]
+        : [...defaultPath, ...folderName.split('/').filter(Boolean)]
+      : defaultPath;
+
+    const serverRelativePath = escapeODataStringLiteral(segments.join('/'));
+    const baseEndpoint = `_api/web/GetFolderByServerRelativeUrl('${serverRelativePath}')`;
+
+    return {
+      get: (options?: Folder_Options<Record<string, unknown>>) => {
+        const folderType = options?.type ?? 'Files';
+        const endpoint = `${baseEndpoint}/${folderType}`;
+        const context = this.createContext<'2013'>({
+          endpoint,
+          listName: '',
+          sharepointVersion: '2013',
+        });
+
+        return getFiles<Record<string, unknown>, '2013'>(context, {
+          ...options,
+          type: folderType,
+        });
       },
     };
   }
 
-  public users(options?: Options<any>) {
-    this.endpoint = '_api/web/SiteUserInfoList/items';
-    this.sharepointVersion = '2013';
+  public users(options?: Options<Record<string, unknown>, '2013'>) {
+    const context = this.createContext<'2013'>({
+      endpoint: '_api/web/SiteUserInfoList/items',
+      listName: '',
+      sharepointVersion: '2013',
+    });
+
     return {
-      get: () => getListItems(this.getContext(), options),
+      get: () => getListItems<Record<string, unknown>, '2013'>(context, options),
     };
   }
 
-  public email = {
-    send: (props: EmailProps) => {
-      this.sharepointVersion = '2013';
-      return sendEmailRequest(this.getContext(), props);
-    },
-  };
+  /**
+   * @deprecated SP.Utilities.Utility.SendEmail was retired by Microsoft on 2025-10-31.
+   * Migrate to Microsoft Graph API POST /v1.0/me/sendMail
+   * https://learn.microsoft.com/en-us/graph/api/user-sendmail
+   */
+  public sendEmail(props: EmailProps) {
+    const context = this.createContext<'2013'>({
+      endpoint: '_api/SP.Utilities.Utility.SendEmail',
+      listName: '',
+      sharepointVersion: '2013',
+    });
+    return sendEmailRequest(context, props);
+  }
 
-  public user = {
+  public readonly user = {
     properties: () => ({
-      get: (): Promise<UserProfile> => {
-        this.sharepointVersion = '2013';
-        return loadCurrentUserProperties(this.instance);
-      },
+      get: (): Promise<UserProfile> => loadCurrentUserProperties(this.instance),
+    }),
+    searchSiteUser: (searchValue: string) =>
+      fetchSiteUser(this.instance, searchValue),
+    searchUser: (input: string, filter?: string): Promise<PersonField> =>
+      typeAhead(this.instance, input, filter),
+    current: () => ({
+      get: (): Promise<CurrentUser> =>
+        getOnly(this.instance, '_api/web/currentUser'),
     }),
-    searchSiteUser: (searchValue: string) => {
-      this.sharepointVersion = '2013';
-      return fetchSiteUser(this.instance, searchValue);
-    },
-    searchUser: (input: string, filter?: string): Promise<PersonField> => {
-      this.sharepointVersion = '2013';
-      return typeAhead(this.instance, input, filter);
-    },
-    current: () => {
-      this.endpoint = '_api/web/currentUser';
-      this.sharepointVersion = '2013';
-      return {
-        get: (): Promise<CurrentUser> => getOnly(this.instance, this.endpoint),
-      };
-    },
     currentPermission: () => ({
-      get: (): Promise<UserPermision> => {
-        this.sharepointVersion = '2013';
-        return resolveCurrentUserPermissions(this.getContext());
-      },
+      get: (): Promise<UserPermision> =>
+        resolveCurrentUserPermissions(
+          this.createContext<'2013'>({
+            endpoint: '_api/web/effectiveBasePermissions',
+            listName: '',
+            sharepointVersion: '2013',
+          })
+        ),
     }),
   };
+
+  public getCurrentUser() {
+    return this.user.current().get();
+  }
+
+  public currentUserProperties() {
+    return this.user.properties().get();
+  }
+
+  public currentUserPermission() {
+    return this.user.currentPermission().get();
+  }
 }
 
 export default HTTPSharePointRequests;

package/src/root/instance.ts

@@ -7,6 +7,13 @@ const defaultConfig: AxiosConfig = {
   },
   timeout: 15000,
   withCredentials: true,
+  paramsSerializer: {
+    serialize: (params: Record<string, string | number | undefined>) =>
+      Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${k}=${String(v)}`)
+        .join('&'),
+  },
 };
 
 export const instance = (baseURL: string, config?: AxiosConfig) => {

package/src/root/internal/context.ts

@@ -1,9 +1,8 @@
-import type { AxiosInstance } from 'axios';
-import type { SHAREPOINT_VER } from '../../types';
+import { AxiosInstance } from 'axios';
+import { SHAREPOINT_VER } from '../../types';
 
 export interface RequestContext<V extends SHAREPOINT_VER = '2013'> {
   instance: AxiosInstance;
-  baseURL: string;
   endpoint: string;
   listName: string;
   sharepointVersion: V;

package/src/root/internal/digest.ts

@@ -1,22 +1,29 @@
-import type { AxiosInstance } from 'axios';
+import { AxiosInstance } from 'axios';
 
-export async function fetchDigest(
-  instance: AxiosInstance,
-  baseURL: string
-): Promise<string> {
-  try {
-    const response = await instance.post(`${baseURL}_api/contextinfo`);
+type DigestEntry = { value: string; expiresAt: number };
+const cache = new WeakMap<AxiosInstance, DigestEntry>();
 
-    const formDigestValue =
-      response.data?.d?.GetContextWebInformation?.FormDigestValue;
+export async function fetchDigest(instance: AxiosInstance): Promise<string> {
+  const cached = cache.get(instance);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.value;
+  }
+
+  try {
+    const response = await instance.post('_api/contextinfo');
+    const info = response.data?.d?.GetContextWebInformation;
+    const formDigestValue = info?.FormDigestValue;
 
     if (!formDigestValue) {
       throw new Error('Invalid response structure: Missing FormDigestValue');
     }
 
+    const ttl = (info?.FormDigestTimeoutSeconds ?? 1800) - 60;
+    cache.set(instance, { value: formDigestValue, expiresAt: Date.now() + ttl * 1000 });
+
     return formDigestValue;
   } catch (error) {
-    console.error('Failed to retrieve the Form Digest Value:', error);
-    throw new Error(`Error retrieving Form Digest Value`);
+    const cause = error instanceof Error ? error.message : 'Unknown contextinfo error';
+    throw new Error(`Error retrieving Form Digest Value: ${cause}`);
   }
 }

package/src/root/internal/emailRequests.ts

@@ -1,7 +1,7 @@
-import type { AxiosResponse } from 'axios';
-import type { EmailProps } from '../../types';
+import { AxiosResponse } from 'axios';
+import { EmailProps } from '../../types';
 import { fetchDigest } from './digest';
-import type { RequestContext } from './context';
+import { RequestContext } from './context';
 
 type SendEmailResponse = AxiosResponse<{
   d: {
@@ -13,17 +13,11 @@ export async function sendEmail(
   context: RequestContext,
   { From, To, Subject, Body }: EmailProps
 ): Promise<SendEmailResponse> {
-  const httpRequest = '_api/SP.Utilities.Utility.SendEmail';
-
   const response = await context.instance({
-    url: httpRequest,
+    url: '_api/SP.Utilities.Utility.SendEmail',
     method: 'POST',
     headers: {
-      'X-RequestDigest': await fetchDigest(
-        context.instance,
-        context.baseURL
-      ),
-      'X-Http-Method': 'POST',
+      'X-RequestDigest': await fetchDigest(context.instance),
       'Content-Type': 'application/json;odata=verbose',
     },
     data: JSON.stringify({

package/src/root/internal/listRequests/createAttachment.ts

@@ -1,17 +1,28 @@
-import type { CreateFileProps, SHAREPOINT_VER } from '../../../types';
+import { CreateFileProps, SHAREPOINT_VER } from '../../../types';
 import { fetchDigest } from '../digest';
-import type { RequestContext } from '../context';
+import { RequestContext } from '../context';
+import { buildListByTitleEndpoint } from '../sharepointUrl';
+import { encodeFileName } from './utils';
 
 export async function createAttachment<V extends SHAREPOINT_VER = '2013'>(
   context: RequestContext<V>,
   { file, itemId }: CreateFileProps
 ) {
-  const requestUrl = `_api/lists/getbytitle('${context.listName}')/items(${itemId})/AttachmentFiles/add(FileName='${file.name}')`;
+  if (context.sharepointVersion !== '2013') {
+    throw new Error(
+      'createAttachment is only supported for SharePoint 2013 REST endpoints.'
+    );
+  }
+
+  const encodedFileName = encodeFileName(file.name);
+  const requestUrl = `${buildListByTitleEndpoint(
+    context.listName
+  )}/items(${itemId})/AttachmentFiles/add(FileName='${encodedFileName}')`;
+
   const response = await context.instance.post(requestUrl, file, {
     headers: {
-      'X-RequestDigest': await fetchDigest(context.instance, context.baseURL),
+      'X-RequestDigest': await fetchDigest(context.instance),
     },
-    withCredentials: true,
   });
 
   return response;