@lindle/sharepoint_requests 0.1.10 → 0.1.11

package/dist/root/index.d.ts

@@ -8,13 +8,29 @@ declare class HTTPSharePointRequests<T extends {
     private endpoint;
     private listName;
     private instance;
+    /**
+     * 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);
+    /**
+     * 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;
     /**
      * @deprecated Use `from` instead.
      */
     list(listName: IListName<T>): this;
     readonly lists: {
+        /**
+         * Fetches all SharePoint lists available to the current site.
+         *
+         * @returns Promise resolving to the list collection response payload.
+         */
         get: () => Promise<{
             data: any[];
             meta: {
@@ -22,6 +38,13 @@ declare class HTTPSharePointRequests<T extends {
             };
         }>;
     };
+    /**
+     * 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): {
         create: (data: ListData) => Promise<AxiosResponse<any, any, {}>>;
         get: (options?: Options<T['LISTS'][K]>) => Promise<{
@@ -38,9 +61,26 @@ declare class HTTPSharePointRequests<T extends {
         };
     };
     folders: {
+        /**
+         * Retrieves SharePoint folders from the default folders endpoint.
+         *
+         * @returns A promise resolving with folder metadata.
+         */
         get: () => void;
     };
+    /**
+     * 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.
+     */
     folder(folderName?: string | string[]): {
+        /**
+         * 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>) => Promise<{
             data: any;
             meta: {
@@ -48,7 +88,18 @@ declare class HTTPSharePointRequests<T extends {
             };
         }>;
     };
+    /**
+     * 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.
+     */
     users(options?: Options<any>): {
+        /**
+         * Executes the user list request using the specified options.
+         *
+         * @returns Promise resolving to the SharePoint user list response.
+         */
         get: () => Promise<{
             data: any[];
             meta: {
@@ -63,12 +114,56 @@ declare class HTTPSharePointRequests<T extends {
      * @throws {Error} If the HTTP request fails or the response does not contain the expected data.
      */
     private getDigest;
+    /**
+     * Executes a GET request without additional metadata wrapping.
+     *
+     * @param options Optional REST query options.
+     * @returns SharePoint response payload or undefined when empty.
+     */
     private get_only;
+    /**
+     * 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 get_files;
+    /**
+     * 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 get_v2;
+    /**
+     * 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 update_2;
+    /**
+     * Creates a new item within the active list.
+     *
+     * @param listData SharePoint list item payload.
+     * @returns Axios response resolved from the create request.
+     */
     private create_v2;
+    /**
+     * 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 createFile;
+    /**
+     * Deletes an item using the current endpoint.
+     *
+     * @param ID Identifier of the entity to remove.
+     * @returns Axios response from the delete call.
+     */
     private delete;
     email: {
         /**
@@ -102,24 +197,85 @@ declare class HTTPSharePointRequests<T extends {
         }, any, {}>>;
     };
     private sendEmail;
+    /**
+     * 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 typeAhead;
+    /**
+     * Retrieves the current user profile and flattens selected properties.
+     *
+     * @returns Promise containing the current user's profile information.
+     */
     private currentUserProperties;
     user: {
+        /**
+         * Provides accessors for the current user's profile information.
+         *
+         * @returns Helper exposing a `get` function to retrieve profile details.
+         */
         properties: () => {
             get: () => Promise<UserProfile>;
         };
+        /**
+         * 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) => Promise<any>;
+        /**
+         * 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>;
+        /**
+         * Fetches the currently authenticated SharePoint user.
+         *
+         * @returns Helper exposing `get` that resolves to the current user payload.
+         */
         current: () => {
             get: () => Promise<CurrentUser>;
         };
+        /**
+         * Retrieves calculated permission level for the current user.
+         *
+         * @returns Helper exposing `get` resolving to the user's permission definition.
+         */
         currentPermission: () => {
             get: () => Promise<UserPermision>;
         };
     };
+    /**
+     * 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 getSiteUser;
+    /**
+     * Retrieves all available role definitions for the current site.
+     *
+     * @returns Promise resolving to an array of role definitions.
+     */
     private roleDefinitions;
+    /**
+     * Fetches the bit-encoded permissions of the current user.
+     *
+     * @returns Promise resolving to the `EffectiveBasePermissions` object.
+     */
     private getEffectiveBasePermissions;
+    /**
+     * Matches the current user's effective permissions against known role definitions.
+     *
+     * @returns The matching SharePoint role definition as a structured permission object.
+     */
     private currentUserPermissions;
 }
 export default HTTPSharePointRequests;

package/dist/sharepoint_requests.cjs.development.js

@@ -156,7 +156,7 @@ var instance = function instance(baseURL, config) {
         Accept: 'application/json; odata=verbose',
         'Content-Type': 'application/json; odata=verbose'
       },
-      timeout: 1000,
+      timeout: 15000,
       withCredentials: true
     };
   }
@@ -166,15 +166,30 @@ var instance = function instance(baseURL, config) {
 };
 
 var HTTPSharePointRequests = /*#__PURE__*/function () {
+  /**
+   * Creates an HTTP SharePoint requester bound to the provided base URL.
+   *
+   * @param baseURL The root SharePoint site URL (with or without trailing slash).
+   */
   function HTTPSharePointRequests(baseURL) {
     var _this = this;
     this.lists = {
+      /**
+       * Fetches all SharePoint lists available to the current site.
+       *
+       * @returns Promise resolving to the list collection response payload.
+       */
       get: function get() {
         _this.endpoint = '_api/web/lists';
         return _this.get_v2();
       }
     };
     this.folders = {
+      /**
+       * Retrieves SharePoint folders from the default folders endpoint.
+       *
+       * @returns A promise resolving with folder metadata.
+       */
       get: function get() {
         _this.endpoint = '_api/web/folders';
         _this.get_v2();
@@ -210,6 +225,11 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       }
     };
     this.user = {
+      /**
+       * Provides accessors for the current user's profile information.
+       *
+       * @returns Helper exposing a `get` function to retrieve profile details.
+       */
       properties: function properties() {
         return {
           get: function get() {
@@ -217,12 +237,30 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
           }
         };
       },
+      /**
+       * Searches across site users and their groups.
+       *
+       * @param searchValue Query string to match site users.
+       * @returns Promise resolving to matching site users.
+       */
       searchSiteUser: function searchSiteUser(searchValue) {
         return _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: function searchUser(input, filter) {
         return _this.typeAhead(input, filter);
       },
+      /**
+       * Fetches the currently authenticated SharePoint user.
+       *
+       * @returns Helper exposing `get` that resolves to the current user payload.
+       */
       current: function current() {
         _this.endpoint = '_api/web/currentUser';
         return {
@@ -231,6 +269,11 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
           }
         };
       },
+      /**
+       * Retrieves calculated permission level for the current user.
+       *
+       * @returns Helper exposing `get` resolving to the user's permission definition.
+       */
       currentPermission: function currentPermission() {
         return {
           get: function get() {
@@ -244,6 +287,12 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
     this.listName = '';
     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.
+   */
   var _proto = HTTPSharePointRequests.prototype;
   _proto.transformArraysToEdmStrings = function transformArraysToEdmStrings(data) {
     for (var key in data) {
@@ -264,7 +313,14 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
     this.listName = listName;
     this.endpoint = "_vti_bin/ListData.svc/" + listName;
     return this;
-  };
+  }
+  /**
+   * 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.
+   */;
   _proto.from = function from(listName, sharepoint_ver) {
     var _this2 = this;
     if (sharepoint_ver === void 0) {
@@ -298,7 +354,13 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
         };
       }
     };
-  };
+  }
+  /**
+   * 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.
+   */;
   _proto.folder = function folder(folderName) {
     var _this3 = this;
     var filePath = ['Shared Documents'];
@@ -307,6 +369,12 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
     }
     this.endpoint = "_api/web/GetFolderByServerRelativeUrl('" + filePath.join('/') + "')";
     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: function get(options) {
         if (!(options != null && options.type)) {
           _this3.endpoint += '/Files';
@@ -316,11 +384,22 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
         return _this3.get_files(options);
       }
     };
-  };
+  }
+  /**
+   * 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.
+   */;
   _proto.users = function users(options) {
     var _this4 = this;
     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: function get() {
         return _this4.get_v2(options);
       }
@@ -366,8 +445,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _getDigest.apply(this, arguments);
     }
     return getDigest;
-  }();
-  _proto.get_only = /*#__PURE__*/function () {
+  }()
+  /**
+   * Executes a GET request without additional metadata wrapping.
+   *
+   * @param options Optional REST query options.
+   * @returns SharePoint response payload or undefined when empty.
+   */
+  ;
+  _proto.get_only =
+  /*#__PURE__*/
+  function () {
     var _get_only = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(options) {
       var _ref, expand, orderBy, limit, filter, cols, skip, params, _yield$this$instance$, data;
       return _regenerator().w(function (_context2) {
@@ -403,8 +491,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _get_only.apply(this, arguments);
     }
     return get_only;
-  }();
-  _proto.get_files = /*#__PURE__*/function () {
+  }()
+  /**
+   * 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.
+   */
+  ;
+  _proto.get_files =
+  /*#__PURE__*/
+  function () {
     var _get_files = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(options) {
       var _ref2, expand, orderBy, limit, filter, cols, skip, params, url, response, data, meta;
       return _regenerator().w(function (_context3) {
@@ -450,8 +547,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _get_files.apply(this, arguments);
     }
     return get_files;
-  }();
-  _proto.get_v2 = /*#__PURE__*/function () {
+  }()
+  /**
+   * 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.
+   */
+  ;
+  _proto.get_v2 =
+  /*#__PURE__*/
+  function () {
     var _get_v = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(options) {
       var _ref4, expand, orderBy, limit, filter, cols, skip, params, url, response, data, meta;
       return _regenerator().w(function (_context4) {
@@ -497,8 +603,19 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _get_v.apply(this, arguments);
     }
     return get_v2;
-  }();
-  _proto.update_2 = /*#__PURE__*/function () {
+  }()
+  /**
+   * 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.
+   */
+  ;
+  _proto.update_2 =
+  /*#__PURE__*/
+  function () {
     var _update_ = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(id, data, digest) {
       var formDigestValue, url, response, _t2;
       return _regenerator().w(function (_context5) {
@@ -540,8 +657,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _update_.apply(this, arguments);
     }
     return update_2;
-  }();
-  _proto.create_v2 = /*#__PURE__*/function () {
+  }()
+  /**
+   * Creates a new item within the active list.
+   *
+   * @param listData SharePoint list item payload.
+   * @returns Axios response resolved from the create request.
+   */
+  ;
+  _proto.create_v2 =
+  /*#__PURE__*/
+  function () {
     var _create_v = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee6(listData) {
       var response, _t3, _t4, _t5, _t6, _t7;
       return _regenerator().w(function (_context6) {
@@ -579,8 +705,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _create_v.apply(this, arguments);
     }
     return create_v2;
-  }();
-  _proto.createFile = /*#__PURE__*/function () {
+  }()
+  /**
+   * Uploads an attachment file to an existing list item.
+   *
+   * @param props File payload and target item identifier.
+   * @returns Axios response describing the upload result.
+   */
+  ;
+  _proto.createFile =
+  /*#__PURE__*/
+  function () {
     var _createFile = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee7(_ref6) {
       var file, itemId, requestUrl, res, _t8, _t9, _t0, _t1, _t10;
       return _regenerator().w(function (_context7) {
@@ -613,8 +748,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _createFile.apply(this, arguments);
     }
     return createFile;
-  }();
-  _proto["delete"] = /*#__PURE__*/function () {
+  }()
+  /**
+   * Deletes an item using the current endpoint.
+   *
+   * @param ID Identifier of the entity to remove.
+   * @returns Axios response from the delete call.
+   */
+  ;
+  _proto["delete"] =
+  /*#__PURE__*/
+  function () {
     var _delete2 = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee8(ID) {
       var response;
       return _regenerator().w(function (_context8) {
@@ -682,8 +826,18 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _sendEmail.apply(this, arguments);
     }
     return sendEmail;
-  }();
-  _proto.typeAhead = /*#__PURE__*/function () {
+  }()
+  /**
+   * 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.
+   */
+  ;
+  _proto.typeAhead =
+  /*#__PURE__*/
+  function () {
     var _typeAhead = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee0(input, filter) {
       var filterValue, response;
       return _regenerator().w(function (_context0) {
@@ -702,8 +856,16 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _typeAhead.apply(this, arguments);
     }
     return typeAhead;
-  }();
-  _proto.currentUserProperties = /*#__PURE__*/function () {
+  }()
+  /**
+   * Retrieves the current user profile and flattens selected properties.
+   *
+   * @returns Promise containing the current user's profile information.
+   */
+  ;
+  _proto.currentUserProperties =
+  /*#__PURE__*/
+  function () {
     var _currentUserProperties = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee1() {
       var requestUrl, profile;
       return _regenerator().w(function (_context1) {
@@ -737,8 +899,17 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _currentUserProperties.apply(this, arguments);
     }
     return currentUserProperties;
-  }();
-  _proto.getSiteUser = /*#__PURE__*/function () {
+  }()
+  /**
+   * 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.
+   */
+  ;
+  _proto.getSiteUser =
+  /*#__PURE__*/
+  function () {
     var _getSiteUser = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee10(searchValue) {
       var requestUrl, response;
       return _regenerator().w(function (_context10) {
@@ -757,8 +928,16 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _getSiteUser.apply(this, arguments);
     }
     return getSiteUser;
-  }();
-  _proto.roleDefinitions = /*#__PURE__*/function () {
+  }()
+  /**
+   * Retrieves all available role definitions for the current site.
+   *
+   * @returns Promise resolving to an array of role definitions.
+   */
+  ;
+  _proto.roleDefinitions =
+  /*#__PURE__*/
+  function () {
     var _roleDefinitions = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee11() {
       var requestUrl, response;
       return _regenerator().w(function (_context11) {
@@ -777,8 +956,16 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _roleDefinitions.apply(this, arguments);
     }
     return roleDefinitions;
-  }();
-  _proto.getEffectiveBasePermissions = /*#__PURE__*/function () {
+  }()
+  /**
+   * Fetches the bit-encoded permissions of the current user.
+   *
+   * @returns Promise resolving to the `EffectiveBasePermissions` object.
+   */
+  ;
+  _proto.getEffectiveBasePermissions =
+  /*#__PURE__*/
+  function () {
     var _getEffectiveBasePermissions = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee12() {
       var requestUrl, response;
       return _regenerator().w(function (_context12) {
@@ -797,8 +984,16 @@ var HTTPSharePointRequests = /*#__PURE__*/function () {
       return _getEffectiveBasePermissions.apply(this, arguments);
     }
     return getEffectiveBasePermissions;
-  }();
-  _proto.currentUserPermissions = /*#__PURE__*/function () {
+  }()
+  /**
+   * Matches the current user's effective permissions against known role definitions.
+   *
+   * @returns The matching SharePoint role definition as a structured permission object.
+   */
+  ;
+  _proto.currentUserPermissions =
+  /*#__PURE__*/
+  function () {
     var _currentUserPermissions = /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee13() {
       var _yield$this$getEffect, High, roleDefinitions, result;
       return _regenerator().w(function (_context13) {