@zxncij2390/monorepo3 3.18.0

package/docs/sp/security.md

@@ -0,0 +1,196 @@
+# @pnp/sp/security
+
+There are four levels where you can break inheritance and assign security: Site, Web, List, Item. All four of these objects share a common set of methods. Because of this we are showing in the examples below usage of these methods for an IList instance, but they apply across all four securable objects. In addition to the shared methods, some types have unique methods which are listed below.
+
+> Site permissions are managed on the root web of the site collection.
+
+## A Note on Selective Imports for Security
+
+Because the method are shared you can opt to import only the methods for one of the instances.
+
+```TypeScript
+import "@pnp/sp/security/web";
+import "@pnp/sp/security/list";
+import "@pnp/sp/security/item";
+```
+
+Possibly useful if you are trying to hyper-optimize for bundle size but it is just as easy to import the whole module:
+
+```TypeScript
+import "@pnp/sp/security";
+```
+
+## Securable Methods
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/security/list";
+import "@pnp/sp/site-users/web";
+import { IList } from "@pnp/sp/lists";
+import { PermissionKind } from "@pnp/sp/security";
+
+const sp = spfi(...);
+
+// ensure we have a list
+const ler = await sp.web.lists.ensure("SecurityTestingList");
+const list: IList = ler.list;
+
+// role assignments (see section below)
+await list.roleAssignments();
+
+// data will represent one of the possible parents Site, Web, or List
+const data = await list.firstUniqueAncestorSecurableObject();
+
+// getUserEffectivePermissions
+const users = await sp.web.siteUsers.top(1).select("LoginName")();
+const perms = await list.getUserEffectivePermissions(users[0].LoginName);
+
+// getCurrentUserEffectivePermissions
+const perms2 = list.getCurrentUserEffectivePermissions();
+
+// userHasPermissions
+const v: boolean = list.userHasPermissions(users[0].LoginName, PermissionKind.AddListItems)
+
+// currentUserHasPermissions
+const v2: boolean = list.currentUserHasPermissions(PermissionKind.AddListItems)
+
+// breakRoleInheritance
+await list.breakRoleInheritance();
+// copy existing permissions
+await list.breakRoleInheritance(true);
+// copy existing permissions and reset all child securables to the new permissions
+await list.breakRoleInheritance(true, true);
+
+// resetRoleInheritance
+await list.resetRoleInheritance();
+```
+
+## Web Specific methods
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/security/web";
+
+const sp = spfi(...);
+
+// role definitions (see section below)
+const defs = await sp.web.roleDefinitions();
+```
+
+## Role Assignments
+
+Allows you to list and manipulate the set of role assignments for the given securable. Again we show usage using list, but the examples apply to web and item as well.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/security/web";
+import "@pnp/sp/site-users/web";
+import { IList } from "@pnp/sp/lists";
+import { PermissionKind } from "@pnp/sp/security";
+
+const sp = spfi(...);
+
+// ensure we have a list
+const ler = await sp.web.lists.ensure("SecurityTestingList");
+const list: IList = ler.list;
+
+// list role assignments
+const assignments = await list.roleAssignments();
+
+// add a role assignment
+const defs = await sp.web.roleDefinitions();
+const user = await sp.web.currentUser();
+const r = await list.roleAssignments.add(user.Id, defs[0].Id);
+
+// remove a role assignment
+const { Id: fullRoleDefId } = await list.roleDefinitions.getByName('Full Control')();
+const ras = await list.roleAssignments();
+// filter/find the role assignment you want to remove
+// here we just grab the first
+const ra = ras.find(v => true);
+const r = await list.roleAssignments.remove(ra.PrincipalId, fullRoleDefId);
+
+// read role assignment info
+const info = await list.roleAssignments.getById(ra.Id)();
+
+// get the groups
+const info2 = await list.roleAssignments.getById(ra.Id).groups();
+
+// get the bindings
+const info3 = await list.roleAssignments.getById(ra.Id).bindings();
+
+// delete a role assignment (same as remove)
+const ras = await list.roleAssignments();
+// filter/find the role assignment you want to remove
+// here we just grab the first
+const ra = ras.find(v => true);
+
+// delete it
+await list.roleAssignments.getById(ra.Id).delete();
+```
+
+## Role Definitions
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/security/web";
+
+const sp = spfi(...);
+
+// read role definitions
+const defs = await sp.web.roleDefinitions();
+
+// get by id
+const def = await sp.web.roleDefinitions.getById(5)();
+const def = await sp.web.roleDefinitions.getById(5).select("Name", "Order")();
+
+// get by name
+const def = await sp.web.roleDefinitions.getByName("Full Control")();
+const def = await sp.web.roleDefinitions.getByName("Full Control").select("Name", "Order")();
+
+// get by type
+const def = await sp.web.roleDefinitions.getByType(5)();
+const def = await sp.web.roleDefinitions.getByType(5).select("Name", "Order")();
+
+// add
+// name The new role definition's name
+// description The new role definition's description
+// order The order in which the role definition appears
+// basePermissions The permissions mask for this role definition
+const rdar = await sp.web.roleDefinitions.add("title", "description", 99, { High: 1, Low: 2 });
+
+
+
+// the following methods work on a single role def, you can use any of the three getBy methods, here we use getById as an example
+
+// delete
+await sp.web.roleDefinitions.getById(5).delete();
+
+// update
+const res = sp.web.roleDefinitions.getById(5).update({ Name: "New Name" });
+```
+
+## Get List Items with Unique Permissions
+
+In order to get a list of items that have unique permissions you have to specifically select the '' field and then filter on the client.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/items";
+import "@pnp/sp/security/items";
+
+const sp = spfi(...);
+
+const listItems = await sp.web.lists.getByTitle("pnplist").items.select("Id, HasUniqueRoleAssignments")();
+
+//Loop over list items filtering for HasUniqueRoleAssignments value
+
+```

package/docs/sp/sharing.md

@@ -0,0 +1,273 @@
+# @pnp/sp/sharing
+
+> **_Note: This API is still considered "beta" meaning it may change and some behaviors may differ across tenants by version. It is also supported only in SharePoint Online._**
+
+One of the newer abilities in SharePoint is the ability to share webs, files, or folders with both internal and external folks. It is important to remember that these settings are managed at the tenant level and ? override anything you may supply as an argument to these methods. If you receive an _InvalidOperationException_ when using these methods please check your tenant sharing settings to ensure sharing is not blocked before ?submitting an issue.
+
+## Imports
+
+In previous versions of this library the sharing methods were part of the inheritance stack for SharePointQueryable objects. Starting with v2 this is no longer the case and they are now selectively importable. There are four objects within the SharePoint hierarchy that support sharing: Item, File, Folder, and Web. You can import the sharing methods for all of them, or for individual objects.
+
+### Import All
+
+To import and attach the sharing methods to all four of the sharable types include all of the sharing sub module:
+
+```TypeScript
+import "@pnp/sp/sharing";
+import "@pnp/sp/webs";
+import "@pnp/sp/site-users/web";
+import { spfi } from "@pnp/sp";
+
+const sp = spfi(...);
+
+const user = await sp.web.siteUsers.getByEmail("user@site.com")();
+const r = await sp.web.shareWith(user.LoginName);
+```
+
+### Selective Import
+
+Import only the web's sharing methods into the library
+
+```TypeScript
+import "@pnp/sp/sharing/web";
+import "@pnp/sp/webs";
+import "@pnp/sp/site-users/web";
+import { spfi } from "@pnp/sp";
+
+const sp = spfi(...);
+
+const user = await sp.web.siteUsers.getByEmail("user@site.com")();
+const r = await sp.web.shareWith(user.LoginName);
+```
+
+## getShareLink
+
+**Applies to: Item, Folder, File**
+
+Creates a sharing link for the given resource with an optional expiration.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import { SharingLinkKind, IShareLinkResponse } from "@pnp/sp/sharing";
+import { dateAdd } from "@pnp/core";
+
+const sp = spfi(...);
+
+const result = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").getShareLink(SharingLinkKind.AnonymousView);
+
+console.log(JSON.stringify(result, null, 2));
+
+
+const result2 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").getShareLink(SharingLinkKind.AnonymousView, dateAdd(new Date(), "day", 5));
+
+console.log(JSON.stringify(result2, null, 2));
+```
+
+## shareWith
+
+**Applies to: Item, Folder, File, Web**
+
+Shares the given resource with the specified permissions (View or Edit) and optionally sends an email to the users. You can supply a single string for the `loginnames` parameter or an array of `loginnames`. The folder method takes an optional parameter "shareEverything" which determines if the shared permissions are pushed down to all items in the folder, even those with unique permissions.
+
+![Batching Not Supported Banner](https://img.shields.io/badge/Batching%20Not%20Supported-important.svg)
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders/web";
+import "@pnp/sp/files/web";
+import { ISharingResult, SharingRole } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+const result = await sp.web.shareWith("i:0#.f|membership|user@site.com");
+
+console.log(JSON.stringify(result, null, 2));
+
+// Share and allow editing
+const result2 = await sp.web.shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit);
+
+console.log(JSON.stringify(result2, null, 2));
+
+
+// share folder
+const result3 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/folder1").shareWith("i:0#.f|membership|user@site.com");
+
+// Share folder with edit permissions, and provide params for requireSignin and propagateAcl (apply to all children)
+await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit, true, true);
+
+// Share a file
+await sp.web.getFileByServerRelativeUrl("/sites/dev/Shared Documents/test.txt").shareWith("i:0#.f|membership|user@site.com");
+
+// Share a file with edit permissions
+await sp.web.getFileByServerRelativeUrl("/sites/dev/Shared Documents/test.txt").shareWith("i:0#.f|membership|user@site.com", SharingRole.Edit);
+```
+
+## shareObject & shareObjectRaw
+
+**Applies to: Web**
+
+Allows you to share any shareable object in a web by providing the appropriate parameters. These two methods differ in that shareObject will try and fix up your query based on the supplied parameters where shareObjectRaw will send your supplied json object directly to the server. The later method is provided for the greatest amount of flexibility.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import { ISharingResult, SharingRole } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+// Share an object in this web
+const result = await sp.web.shareObject("https://mysite.sharepoint.com/sites/dev/Docs/test.txt", "i:0#.f|membership|user@site.com", SharingRole.View);
+
+// Share an object with all settings available
+await sp.web.shareObjectRaw({
+    url: "https://mysite.sharepoint.com/sites/dev/Docs/test.txt",
+    peoplePickerInput: [{ Key: "i:0#.f|membership|user@site.com" }],
+    roleValue: "role: 1973741327",
+    groupId: 0,
+    propagateAcl: false,
+    sendEmail: true,
+    includeAnonymousLinkInEmail: false,
+    emailSubject: "subject",
+    emailBody: "body",
+    useSimplifiedRoles: true,
+});
+```
+
+## unshareObject
+
+**Applies to: Web**
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import { ISharingResult } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+const result = await sp.web.unshareObject("https://mysite.sharepoint.com/sites/dev/Docs/test.txt");
+```
+
+## checkSharingPermissions
+
+**Applies to: Item, Folder, File**
+
+Checks Permissions on the list of Users and returns back role the users have on the Item.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing/folders";
+import "@pnp/sp/folders/web";
+import { SharingEntityPermission } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+// check the sharing permissions for a folder
+const perms = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").checkSharingPermissions([{ alias: "i:0#.f|membership|user@site.com" }]);
+```
+
+## getSharingInformation
+
+**Applies to: Item, Folder, File**
+
+Get Sharing Information.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders";
+import { ISharingInformation } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+// Get the sharing information for a folder
+const info = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getSharingInformation();
+
+// get sharing informaiton with a request object
+const info2 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getSharingInformation({
+    maxPrincipalsToReturn: 10,
+    populateInheritedLinks: true,
+});
+
+// get sharing informaiton using select and expand, NOTE expand comes first in the API signature
+const info3 = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getSharingInformation({}, ["permissionsInformation"], ["permissionsInformation","anyoneLinkTrackUsers"]);
+```
+
+## getObjectSharingSettings
+
+**Applies to: Item, Folder, File**
+
+Gets the sharing settings
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders";
+import { IObjectSharingSettings } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+// Gets the sharing object settings
+const settings: IObjectSharingSettings = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").getObjectSharingSettings();
+```
+
+## unshare
+
+**Applies to: Item, Folder, File**
+
+Unshares a given resource
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders";
+import { ISharingResult } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+const result: ISharingResult = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshare();
+```
+
+## deleteSharingLinkByKind
+
+**Applies to: Item, Folder, File**
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders";
+import { ISharingResult, SharingLinkKind } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+const result: ISharingResult = await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").deleteSharingLinkByKind(SharingLinkKind.AnonymousEdit);
+```
+
+## unshareLink
+
+**Applies to: Item, Folder, File**
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/sharing";
+import "@pnp/sp/folders";
+import { SharingLinkKind } from "@pnp/sp/sharing";
+
+const sp = spfi(...);
+
+await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshareLink(SharingLinkKind.AnonymousEdit);
+
+// specify the sharing link id if available
+await sp.web.getFolderByServerRelativeUrl("/sites/dev/Shared Documents/test").unshareLink(SharingLinkKind.AnonymousEdit, "12345");
+```

package/docs/sp/site-designs.md

@@ -0,0 +1,117 @@
+# @pnp/sp/site-designs
+
+You can create site designs to provide reusable lists, themes, layouts, pages, or custom actions so that your users can quickly build new SharePoint sites with the features they need.
+Check out [SharePoint site design and site script overview](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-design-overview) for more information.
+
+## Site Designs
+
+[![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)
+
+## Create a new site design
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+// WebTemplate: 64 Team site template, 68 Communication site template
+const siteDesign = await sp.siteDesigns.createSiteDesign({
+    SiteScriptIds: ["884ed56b-1aab-4653-95cf-4be0bfa5ef0a"],
+    Title: "SiteDesign001",
+    WebTemplate: "64",
+});
+
+console.log(siteDesign.Title);
+```
+
+## Applying a site design to a site
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+// Limited to 30 actions in a site script, but runs synchronously
+await sp.siteDesigns.applySiteDesign("75b9d8fe-4381-45d9-88c6-b03f483ae6a8","https://contoso.sharepoint.com/sites/teamsite-pnpjs001");
+
+// Better use the following method for 300 actions in a site script
+const task = await sp.web.addSiteDesignTask("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+```
+
+## Retrieval
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+// Retrieving all site designs
+const allSiteDesigns = await sp.siteDesigns.getSiteDesigns();
+console.log(`Total site designs: ${allSiteDesigns.length}`);
+
+// Retrieving a single site design by Id
+const siteDesign = await sp.siteDesigns.getSiteDesignMetadata("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+console.log(siteDesign.Title);
+```
+
+## Update and delete
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+// Update
+const updatedSiteDesign = await sp.siteDesigns.updateSiteDesign({ Id: "75b9d8fe-4381-45d9-88c6-b03f483ae6a8", Title: "SiteDesignUpdatedTitle001" });
+
+// Delete
+await sp.siteDesigns.deleteSiteDesign("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+```
+
+## Setting Rights/Permissions
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+// Get
+const rights = await sp.siteDesigns.getSiteDesignRights("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+console.log(rights.length > 0 ? rights[0].PrincipalName : "");
+
+// Grant
+await sp.siteDesigns.grantSiteDesignRights("75b9d8fe-4381-45d9-88c6-b03f483ae6a8", ["user@contoso.onmicrosoft.com"]);
+
+// Revoke
+await sp.siteDesigns.revokeSiteDesignRights("75b9d8fe-4381-45d9-88c6-b03f483ae6a8", ["user@contoso.onmicrosoft.com"]);
+
+// Reset all view rights
+const rights = await sp.siteDesigns.getSiteDesignRights("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+await sp.siteDesigns.revokeSiteDesignRights("75b9d8fe-4381-45d9-88c6-b03f483ae6a8", rights.map(u => u.PrincipalName));
+```
+
+## Get a history of site designs that have run on a web
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/site-designs";
+
+const sp = spfi(...);
+
+const runs = await sp.web.getSiteDesignRuns();
+const runs2 = await sp.siteDesigns.getSiteDesignRun("https://TENANT.sharepoint.com/sites/mysite");
+
+// Get runs specific to a site design
+const runs3 = await sp.web.getSiteDesignRuns("75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+const runs4 = await sp.siteDesigns.getSiteDesignRun("https://TENANT.sharepoint.com/sites/mysite", "75b9d8fe-4381-45d9-88c6-b03f483ae6a8");
+
+// For more information about the site script actions
+const runStatus = await sp.web.getSiteDesignRunStatus(runs[0].ID);
+const runStatus2 = await sp.siteDesigns.getSiteDesignRunStatus("https://TENANT.sharepoint.com/sites/mysite", runs[0].ID);
+
+```