@lindle/sharepoint_requests 0.1.10 → 0.1.11

package/src/root/index.ts

@@ -25,6 +25,11 @@ class HTTPSharePointRequests<
   private listName: string;
   private instance: AxiosInstance;
 
+  /**
+   * Creates an HTTP SharePoint requester bound to the provided base URL.
+   *
+   * @param baseURL The root SharePoint site URL (with or without trailing slash).
+   */
   constructor(baseURL: string) {
     this.baseURL = baseURL.endsWith('/') ? baseURL : `${baseURL}/`;
     this.endpoint = '/api';
@@ -33,6 +38,12 @@ class HTTPSharePointRequests<
     this.instance = instance(this.baseURL);
   }
 
+  /**
+   * Converts array values in a payload to the `Collection(Edm.String)` structure
+   * expected by SharePoint REST endpoints.
+   *
+   * @param data The list item payload to harmonise in-place.
+   */
   private transformArraysToEdmStrings(data: ListData) {
     for (const key in data) {
       if (Array.isArray(data[key])) {
@@ -53,12 +64,24 @@ class HTTPSharePointRequests<
     return this;
   }
   public readonly lists = {
+    /**
+     * Fetches all SharePoint lists available to the current site.
+     *
+     * @returns Promise resolving to the list collection response payload.
+     */
     get: () => {
       this.endpoint = '_api/web/lists';
       return this.get_v2();
     },
   };
 
+  /**
+   * Selects a SharePoint list and exposes list-scoped CRUD helpers.
+   *
+   * @param listName Logical list key configured in the generic type map.
+   * @param sharepoint_ver SharePoint version used to choose the correct REST endpoint.
+   * @returns Chainable helpers bound to the selected list.
+   */
   from<K extends Extract<keyof T['LISTS'], string>>(
     listName: K,
     sharepoint_ver: SHAREPOINT_VER = '2013'
@@ -89,12 +112,23 @@ class HTTPSharePointRequests<
   }
 
   public folders = {
+    /**
+     * Retrieves SharePoint folders from the default folders endpoint.
+     *
+     * @returns A promise resolving with folder metadata.
+     */
     get: () => {
       this.endpoint = '_api/web/folders';
       this.get_v2();
     },
   };
 
+  /**
+   * Targets a SharePoint folder path and exposes file retrieval helpers.
+   *
+   * @param folderName Optional folder path relative to `Shared Documents`.
+   * @returns Helper exposing `get` to fetch files or sub-folders.
+   */
   public folder(folderName?: string | string[]) {
     let filePath = ['Shared Documents'];
 
@@ -107,6 +141,12 @@ class HTTPSharePointRequests<
       '/'
     )}')`;
     return {
+      /**
+       * Fetches files or folders from the targeted path.
+       *
+       * @param options Optional REST query options to refine the result set.
+       * @returns Promise resolving to folder contents and metadata.
+       */
       get: (options?: Folder_Options<any>) => {
         if (!options?.type) {
           this.endpoint += '/Files';
@@ -119,9 +159,20 @@ class HTTPSharePointRequests<
     };
   }
 
+  /**
+   * Retrieves user list items and exposes a get helper with optional query parameters.
+   *
+   * @param options Optional REST query options.
+   * @returns Helper exposing `get` returning SharePoint user rows.
+   */
   public users(options?: Options<any>) {
     this.endpoint = '_api/web/SiteUserInfoList/items';
     return {
+      /**
+       * Executes the user list request using the specified options.
+       *
+       * @returns Promise resolving to the SharePoint user list response.
+       */
       get: () => this.get_v2(options),
     };
   }
@@ -148,6 +199,12 @@ class HTTPSharePointRequests<
     '';
   }
 
+  /**
+   * Executes a GET request without additional metadata wrapping.
+   *
+   * @param options Optional REST query options.
+   * @returns SharePoint response payload or undefined when empty.
+   */
   private async get_only(options?: any) {
     const { expand, orderBy, limit, filter, cols, skip } = options || {};
 
@@ -165,6 +222,12 @@ class HTTPSharePointRequests<
     }
   }
 
+  /**
+   * Retrieves folder contents with optional filtering and returns the payload with metadata.
+   *
+   * @param options REST options describing expand/filter/order conditions.
+   * @returns Folder data and the fully resolved request URL.
+   */
   private async get_files(options?: Folder_Options<any>) {
     const { expand, orderBy, limit, filter, cols, skip } = options || {};
     const params = {
@@ -198,6 +261,12 @@ class HTTPSharePointRequests<
     return { data, meta };
   }
 
+  /**
+   * Performs a typed list read against the current endpoint.
+   *
+   * @param options Optional REST query options governing expand, filter, ordering and pagination.
+   * @returns SharePoint list items alongside the fully-resolved request URL.
+   */
   private async get_v2<K = any>(
     options?: Options<K>
   ): Promise<{ data: (K & Partial<SPItem>)[]; meta: { url: URL } }> {
@@ -235,6 +304,14 @@ class HTTPSharePointRequests<
     return { data, meta };
   }
 
+  /**
+   * Updates an item in the currently selected list.
+   *
+   * @param id Target list item identifier.
+   * @param data Payload with fields to update.
+   * @param digest Optional pre-fetched form digest to reuse.
+   * @returns Axios response of the update request.
+   */
   private async update_2(id: ItemID, data: ListData, digest?: string) {
     const formDigestValue = digest || (await this.getDigest());
 
@@ -255,6 +332,12 @@ class HTTPSharePointRequests<
     return response;
   }
 
+  /**
+   * Creates a new item within the active list.
+   *
+   * @param listData SharePoint list item payload.
+   * @returns Axios response resolved from the create request.
+   */
   private async create_v2(listData: ListData) {
     this.transformArraysToEdmStrings(listData);
     listData.__metadata = {
@@ -272,6 +355,12 @@ class HTTPSharePointRequests<
     return response;
   }
 
+  /**
+   * Uploads an attachment file to an existing list item.
+   *
+   * @param props File payload and target item identifier.
+   * @returns Axios response describing the upload result.
+   */
   private async createFile({ file, itemId }: CreateFileProps) {
     const requestUrl = `_api/lists/getbytitle('${this.listName}')/items(${itemId})/AttachmentFiles/add(FileName='${file.name}')`;
     const res = await this.instance.post(requestUrl, file, {
@@ -284,6 +373,12 @@ class HTTPSharePointRequests<
     return res;
   }
 
+  /**
+   * Deletes an item using the current endpoint.
+   *
+   * @param ID Identifier of the entity to remove.
+   * @returns Axios response from the delete call.
+   */
   private async delete(ID: string | number) {
     const response = await this.instance.delete(`${this.endpoint!}(${ID})`);
     return response;
@@ -356,6 +451,13 @@ class HTTPSharePointRequests<
     return response;
   }
 
+  /**
+   * Queries SharePoint's people picker endpoint for matching users.
+   *
+   * @param input Free-text search term.
+   * @param filter Optional additional filter condition.
+   * @returns Promise with type-ahead results payload.
+   */
   private async typeAhead(input: string, filter?: string) {
     const filterValue = filter ? ` and ${filter}` : '';
     const response = await this.instance.get(
@@ -364,6 +466,11 @@ class HTTPSharePointRequests<
     return response.data.d;
   }
 
+  /**
+   * Retrieves the current user profile and flattens selected properties.
+   *
+   * @returns Promise containing the current user's profile information.
+   */
   private async currentUserProperties() {
     const requestUrl = '_api/sp.userprofiles.peoplemanager/getmyproperties';
     let profile: any = await this.instance.get(requestUrl);
@@ -389,20 +496,48 @@ class HTTPSharePointRequests<
     return profile as Promise<UserProfile>;
   }
   public user = {
+    /**
+     * Provides accessors for the current user's profile information.
+     *
+     * @returns Helper exposing a `get` function to retrieve profile details.
+     */
     properties: () => {
       return {
         get: () => this.currentUserProperties(),
       };
     },
+    /**
+     * Searches across site users and their groups.
+     *
+     * @param searchValue Query string to match site users.
+     * @returns Promise resolving to matching site users.
+     */
     searchSiteUser: (searchValue: string) => this.getSiteUser(searchValue),
+    /**
+     * Performs a people-picker search scoped to the current site collection.
+     *
+     * @param input Search prefix.
+     * @param filter Optional additional filter condition.
+     * @returns Promise with type-ahead person results.
+     */
     searchUser: (input: string, filter?: string): Promise<PersonField> =>
       this.typeAhead(input, filter),
+    /**
+     * Fetches the currently authenticated SharePoint user.
+     *
+     * @returns Helper exposing `get` that resolves to the current user payload.
+     */
     current: () => {
       this.endpoint = '_api/web/currentUser';
       return {
         get: (): Promise<CurrentUser> => this.get_only(),
       };
     },
+    /**
+     * Retrieves calculated permission level for the current user.
+     *
+     * @returns Helper exposing `get` resolving to the user's permission definition.
+     */
     currentPermission: () => {
       return {
         get: () => this.currentUserPermissions(),
@@ -410,24 +545,45 @@ class HTTPSharePointRequests<
     },
   };
 
+  /**
+   * Searches site users based on a substring match across common fields.
+   *
+   * @param searchValue Term to match against the SharePoint user directory.
+   * @returns Promise with matching site users and their groups.
+   */
   private async getSiteUser(searchValue: string) {
     const requestUrl = `_api/web/siteusers?&$filter=substringof('${searchValue}', Title) or substringof('${searchValue}', LoginName) or substringof('${searchValue}', Email)&$top=50&$expand=Groups`;
     const response = await this.instance.get(requestUrl);
     return response.data.d;
   }
 
+  /**
+   * Retrieves all available role definitions for the current site.
+   *
+   * @returns Promise resolving to an array of role definitions.
+   */
   private async roleDefinitions() {
     const requestUrl = `_api/Web/RoleDefinitions`;
     const response = await this.instance.get(requestUrl);
     return response.data.d.results;
   }
 
+  /**
+   * Fetches the bit-encoded permissions of the current user.
+   *
+   * @returns Promise resolving to the `EffectiveBasePermissions` object.
+   */
   private async getEffectiveBasePermissions() {
     const requestUrl = `_api/Web/effectiveBasePermissions`;
     const response = await this.instance.get(requestUrl);
     return response.data.d.EffectiveBasePermissions;
   }
 
+  /**
+   * Matches the current user's effective permissions against known role definitions.
+   *
+   * @returns The matching SharePoint role definition as a structured permission object.
+   */
   private async currentUserPermissions() {
     const { High } = await this.getEffectiveBasePermissions();
     const roleDefinitions = await this.roleDefinitions();

package/src/root/instance.ts

@@ -7,7 +7,7 @@ export const instance = (
       Accept: 'application/json; odata=verbose',
       'Content-Type': 'application/json; odata=verbose',
     },
-    timeout: 1000,
+    timeout: 15000,
     withCredentials: true,
   }
 ) => {