@zxncij2390/monorepo3 3.18.0

package/docs/sp/navigation.md

@@ -0,0 +1,171 @@
+# @pnp/sp - navigation
+
+[![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+## Navigation Service
+
+### getMenuState
+
+The MenuState service operation returns a Menu-State (dump) of a SiteMapProvider on a site. It will return an exception if the SiteMapProvider cannot be found on the site, the SiteMapProvider does not implement the IEditableSiteMapProvider interface or the SiteMapNode key cannot be found within the provider hierarchy.
+
+The IEditableSiteMapProvider also supports Custom Properties which is an optional feature. What will be return in the custom properties is up to the IEditableSiteMapProvider implementation and can differ for for each SiteMapProvider implementation. The custom properties can be requested by providing a comma separated string of property names like: property1,property2,property3\\,containingcomma
+
+NOTE: the , separator can be escaped using the \ as escape character as done in the example above. The string above would split like:
+
+* property1
+* property2
+* property3,containingcomma
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/navigation";
+
+const sp = spfi(...);
+
+// Will return a menu state of the default SiteMapProvider 'SPSiteMapProvider' where the dump starts a the RootNode (within the site) with a depth of 10 levels.
+const state = await sp.navigation.getMenuState();
+
+// Will return the menu state of the 'SPSiteMapProvider', starting with the node with the key '1002' with a depth of 5
+const state2 = await sp.navigation.getMenuState("1002", 5);
+
+// Will return the menu state of the 'CurrentNavSiteMapProviderNoEncode' from the root node of the provider with a depth of 5
+const state3 = await sp.navigation.getMenuState(null, 5, "CurrentNavSiteMapProviderNoEncode");
+```
+
+### getMenuNodeKey
+
+Tries to get a SiteMapNode.Key for a given URL within a site collection. If the SiteMapNode cannot be found an Exception is returned. The method is using SiteMapProvider.FindSiteMapNodeFromKey(string rawUrl) to lookup the SiteMapNode. Depending on the actual implementation of FindSiteMapNodeFromKey the matching can differ for different SiteMapProviders.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/navigation";
+
+const sp = spfi(...);
+
+const key = await sp.navigation.getMenuNodeKey("/sites/dev/Lists/SPPnPJSExampleList/AllItems.aspx");
+```
+
+## Web Navigation
+
+[![Invokable Banner](https://img.shields.io/badge/Invokable-informational.svg)](../concepts/invokable.md) [![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+|Scenario|Import Statement|
+|--|--|
+|Selective 1|import "@pnp/sp/webs";<br />import "@pnp/sp/navigation";
+
+The navigation object contains two properties "quicklaunch" and "topnavigationbar". Both have the same set of methods so our examples below show use of only quicklaunch but apply equally to topnavigationbar.
+
+### Get navigation
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/navigation";
+
+const sp = spfi(...);
+
+const top = await sp.web.navigation.topNavigationBar();
+const quick = await sp.web.navigation.quicklaunch();
+```
+
+For the following examples we will refer to a variable named "nav" that is understood to be one of topNavigationBar or quicklaunch:
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/navigation";
+
+const sp = spfi(...);
+// note we are just getting a ref to the nav object, not executing a request
+const nav = sp.web.navigation.topNavigationBar;
+// -- OR -- 
+// note we are just getting a ref to the nav object, not executing a request
+const nav = sp.web.navigation.quicklaunch;
+```
+
+### getById
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+const node = await nav.getById(3)();
+```
+
+### add
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+const result = await nav.add("Node Title", "/sites/dev/pages/mypage.aspx", true);
+
+const nodeDataRaw = result.data;
+
+// request the data from the created node
+const nodeData = result.node();
+```
+
+### moveAfter
+
+Places a navigation node after another node in the tree
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+const node1result = await nav.add(`Testing - ${getRandomString(4)} (1)`, url, true);
+const node2result = await nav.add(`Testing - ${getRandomString(4)} (2)`, url, true);
+const node1 = await node1result.node();
+const node2 = await node2result.node();
+
+await nav.moveAfter(node1.Id, node2.Id);
+```
+
+### Delete
+
+Deletes a given node
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+const node1result = await nav.add(`Testing - ${getRandomString(4)}`, url, true);
+let nodes = await nav();
+// check we added a node
+let index = nodes.findIndex(n => n.Id === node1result.data.Id)
+// index >= 0
+
+// delete a node
+await nav.getById(node1result.data.Id).delete();
+
+nodes = await nav();
+index = nodes.findIndex(n => n.Id === node1result.data.Id)
+// index = -1
+```
+
+### Update
+You are able to update various properties of a given node, such as the the Title, Url, IsVisible.
+
+You may update the Audience Targeting value for the node by passing in Microsoft Group IDs in the AudienceIds array. Be aware, Audience Targeting must already be enabled on the navigation.
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+
+await nav.getById(4).update({
+    Title: "A new title",
+    AudienceIds:["d50f9511-b811-4d76-b20a-0d6e1c8095f7"],
+    Url:"/sites/dev/SitePages/home.aspx",
+    IsVisible:false
+});
+```
+
+### Children
+
+The children property of a Navigation Node represents a collection with all the same properties and methods available on topNavigationBar or quicklaunch.
+
+```TypeScript
+import "@pnp/sp/navigation";
+
+const childrenData = await nav.getById(1).children();
+
+// add a child
+await nav.getById(1).children.add("Title", "Url", true);
+```

package/docs/sp/permissions.md

@@ -0,0 +1,82 @@
+# @pnp/sp - permissions
+
+A common task is to determine if a user or the current user has a certain permission level. It is a great idea to check before performing a task such as creating a list to ensure a user can without getting back an error. This allows you to provide a better experience to the user.
+
+Permissions in SharePoint are assigned to the set of securable objects which include Site, Web, List, and List Item. These are the four level to which unique permissions can be assigned. As such @pnp/sp provides a set of methods defined in the QueryableSecurable class to handle these permissions. These examples all use the Web to get the values, however the methods work identically on all securables.
+
+## Get Role Assignments
+
+This gets a collection of all the role assignments on a given securable. The property returns a RoleAssignments collection which supports the OData collection operators.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import "@pnp/sp/security";
+
+const sp = spfi(...);
+
+const roles = await sp.web.roleAssignments();
+```
+
+## First Unique Ancestor Securable Object
+
+This method can be used to find the securable parent up the hierarchy that has unique permissions. If everything inherits permissions this will be the Site. If a sub web has unique permissions it will be the web, and so on.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import "@pnp/sp/security";
+
+const sp = spfi(...);
+
+const obj = await sp.web.firstUniqueAncestorSecurableObject();
+```
+
+## User Effective Permissions
+
+This method returns the BasePermissions for a given user or the current user. This value contains the High and Low values for a user on the securable you have queried.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import "@pnp/sp/security";
+
+const sp = spfi(...);
+
+const perms = await sp.web.getUserEffectivePermissions("i:0#.f|membership|user@site.com");
+
+const perms2 = await sp.web.getCurrentUserEffectivePermissions();
+```
+
+## User Has Permissions
+
+Because the High and Low values in the BasePermission don't obviously mean anything you can use these methods along with the PermissionKind enumeration to check actual rights on the securable.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import { PermissionKind } from "@pnp/sp/security";
+
+const sp = spfi(...);
+
+const perms = await sp.web.userHasPermissions("i:0#.f|membership|user@site.com", PermissionKind.ApproveItems);
+
+const perms2 = await sp.web.currentUserHasPermissions(PermissionKind.ApproveItems);
+```
+
+## Has Permissions
+
+If you need to check multiple permissions it can be more efficient to get the BasePermissions once and then use the hasPermissions method to check them as shown below.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import { PermissionKind } from "@pnp/sp/security";
+
+const sp = spfi(...);
+
+const perms = await sp.web.getCurrentUserEffectivePermissions();
+if (sp.web.hasPermissions(perms, PermissionKind.AddListItems) && sp.web.hasPermissions(perms, PermissionKind.DeleteVersions)) {
+    // ...
+}
+```

package/docs/sp/profiles.md

@@ -0,0 +1,407 @@
+# @pnp/sp/profiles
+
+The profile services allows you to work with the SharePoint User Profile Store.
+
+## Profiles
+
+Profiles is accessed directly from the root sp object.
+
+```typescript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/profiles";
+```
+
+## Get edit profile link for the current user
+
+```typescript
+getEditProfileLink(): Promise<string>
+```
+
+```typescript
+const sp = spfi(...);
+const editProfileLink = await sp.profiles.getEditProfileLink();
+```
+
+## Is My People List Public
+
+Provides a boolean that indicates if the current users "People I'm Following" list is public or not
+
+```typescript
+getIsMyPeopleListPublic(): Promise<boolean>
+```
+
+```typescript
+const sp = spfi(...);
+const isPublic = await sp.profiles.getIsMyPeopleListPublic();
+```
+
+## Find out if the current user is followed by another user
+
+Provides a boolean that indicates if the current users is followed by a specific user.
+
+```typescript
+amIFollowedBy(loginName: string): Promise<boolean>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const isFollowedBy = await sp.profiles.amIFollowedBy(loginName);
+```
+
+## Find out if I am following a specific user
+
+Provides a boolean that indicates if the current users is followed by a specific user.
+
+```typescript
+amIFollowing(loginName: string): Promise<boolean>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const following = await sp.profiles.amIFollowing(loginName);
+```
+
+## Get the tags I follow
+
+Gets the tags the current user is following. Accepts max count, default is 20.
+
+```typescript
+getFollowedTags(maxCount = 20): Promise<string[]>
+```
+
+```typescript
+const sp = spfi(...);
+const tags = await sp.profiles.getFollowedTags();
+```
+
+## Get followers for a specific user
+
+Gets the people who are following the specified user.
+
+```typescript
+getFollowersFor(loginName: string): Promise<any[]>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const followers = await sp.profiles.getFollowersFor(loginName);
+followers.forEach((value) => {
+  ...
+});
+```
+
+## Get followers for the current
+
+Gets the people who are following the current user.
+
+```typescript
+myFollowers(): ISPCollection
+```
+
+```typescript
+const sp = spfi(...);
+const folowers = await sp.profiles.myFollowers();
+```
+
+## Get the properties for the current user
+
+Gets user properties for the current user.
+
+```typescript
+myProperties(): ISPInstance
+```
+
+```typescript
+const sp = spfi(...);
+const profile = await sp.profiles.myProperties();
+console.log(profile.DisplayName);
+console.log(profile.Email);
+console.log(profile.Title);
+console.log(profile.UserProfileProperties.length);
+
+// Properties are stored in Key/Value pairs,
+// so parse into an object called userProperties
+var props = {};
+profile.UserProfileProperties.forEach((prop) => {
+  props[prop.Key] = prop.Value;
+});
+profile.userProperties = props;
+console.log("Account Name: " + profile.userProperties.AccountName);
+```
+
+```TypeScript
+// you can also select properties to return before
+const sp = spfi(...);
+const profile = await sp.profiles.myProperties.select("Title", "Email")();
+console.log(profile.Email);
+console.log(profile.Title);
+```
+
+## Gets people specified user is following
+
+```typescript
+getPeopleFollowedBy(loginName: string): Promise<any[]>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const folowers = await sp.profiles.getFollowersFor(loginName);
+followers.forEach((value) => {
+  ...
+});
+```
+
+## Gets properties for a specified user
+
+```typescript
+getPropertiesFor(loginName: string): Promise<any>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const profile = await sp.profiles.getPropertiesFor(loginName);
+console.log(profile.DisplayName);
+console.log(profile.Email);
+console.log(profile.Title);
+console.log(profile.UserProfileProperties.length);
+
+// Properties are stored in inconvenient Key/Value pairs,
+// so parse into an object called userProperties
+var props = {};
+profile.UserProfileProperties.forEach((prop) => {
+  props[prop.Key] = prop.Value;
+});
+
+profile.userProperties = props;
+console.log("Account Name: " + profile.userProperties.AccountName);
+```
+
+## Gets most popular tags
+
+Gets the 20 most popular hash tags over the past week, sorted so that the most popular tag appears first
+
+```typescript
+trendingTags(): Promise<IHashTagCollection>
+```
+
+```typescript
+const sp = spfi(...);
+const tags = await sp.profiles.trendingTags();
+tags.Items.forEach((tag) => {
+  ...
+});
+```
+
+## Gets specified user profile property for the specified user
+
+```typescript
+getUserProfilePropertyFor(loginName: string, propertyName: string): Promise<string>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const propertyName = "AccountName";
+const property = await sp.profiles.getUserProfilePropertyFor(loginName, propertyName);
+```
+
+## Hide specific user from list of suggested people
+
+Removes the specified user from the user's list of suggested people to follow.
+
+```typescript
+hideSuggestion(loginName: string): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+await sp.profiles.hideSuggestion(loginName);
+```
+
+## Is one user following another
+
+Indicates whether the first user is following the second user.
+First parameter is the account name of the user who might be following the followee.
+Second parameter is the account name of the user who might be followed by the follower.
+
+```typescript
+isFollowing(follower: string, followee: string): Promise<boolean>
+```
+
+```typescript
+const sp = spfi(...);
+const follower = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const followee = "i:0#.f|membership|testuser2@mytenant.onmicrosoft.com";
+const isFollowing = await sp.profiles.isFollowing(follower, followee);
+```
+
+## Set User Profile Picture
+
+Uploads and sets the user profile picture (Users can upload a picture to their own profile only). Not supported for batching.
+Accepts the profilePicSource Blob data representing the user's picture in BMP, JPEG, or PNG format of up to 4.76MB.
+
+![Batching Not Supported Banner](https://img.shields.io/badge/Batching%20Not%20Supported-important.svg)
+
+```typescript
+setMyProfilePic(profilePicSource: Blob): Promise<void>
+```
+
+```typescript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import "@pnp/sp/profiles";
+import "@pnp/sp/folders";
+import "@pnp/sp/files";
+
+const sp = spfi(...);
+
+// get the blob object through a request or from a file input
+const blob = await sp.web.lists.getByTitle("Documents").rootFolder.files.getByName("profile.jpg").getBlob();
+
+await sp.profiles.setMyProfilePic(blob);
+```
+
+## Sets single value User Profile property
+
+accountName The account name of the user
+propertyName Property name
+propertyValue Property value
+
+```typescript
+setSingleValueProfileProperty(accountName: string, propertyName: string, propertyValue: string): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+await sp.profiles.setSingleValueProfileProperty(loginName, "CellPhone", "(123) 555-1212");
+```
+
+## Sets a mult-value User Profile property
+
+accountName The account name of the user
+propertyName Property name
+propertyValues Property values
+
+```typescript
+setMultiValuedProfileProperty(accountName: string, propertyName: string, propertyValues: string[]): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+const loginName = "i:0#.f|membership|testuser@mytenant.onmicrosoft.com";
+const propertyName = "SPS-Skills";
+const propertyValues = ["SharePoint", "Office 365", "Architecture", "Azure"];
+await sp.profiles.setMultiValuedProfileProperty(loginName, propertyName, propertyValues);
+const profile = await sp.profiles.getPropertiesFor(loginName);
+var props = {};
+profile.UserProfileProperties.forEach((prop) => {
+  props[prop.Key] = prop.Value;
+});
+profile.userProperties = props;
+console.log(profile.userProperties[propertyName]);
+```
+
+## Create Personal Site for specified users
+
+Provisions one or more users' personal sites. (My Site administrator on SharePoint Online only)
+Emails The email addresses of the users to provision sites for
+
+```typescript
+createPersonalSiteEnqueueBulk(...emails: string[]): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+let userEmails: string[] = ["testuser1@mytenant.onmicrosoft.com", "testuser2@mytenant.onmicrosoft.com"];
+await sp.profiles.createPersonalSiteEnqueueBulk(userEmails);
+```
+
+## Get the user profile of the owner for the current site
+
+```typescript
+ownerUserProfile(): Promise<IUserProfile>
+```
+
+```typescript
+const sp = spfi(...);
+const profile = await sp.profiles.ownerUserProfile();
+```
+
+## Get the user profile of the current user
+
+```typescript
+userProfile(): Promise<any>
+```
+
+```typescript
+const sp = spfi(...);
+const profile = await sp.profiles.userProfile();
+```
+
+## Create personal site for current user
+
+```typescript
+createPersonalSite(interactiveRequest = false): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+await sp.profiles.createPersonalSite();
+```
+
+## Make all profile data public or private
+
+Set the privacy settings for all social data.
+
+```typescript
+shareAllSocialData(share: boolean): Promise<void>
+```
+
+```typescript
+const sp = spfi(...);
+await sp.profiles.shareAllSocialData(true);
+```
+
+## Resolve a user or group
+
+Resolves user or group using specified query parameters
+
+```typescript
+clientPeoplePickerResolveUser(queryParams: IClientPeoplePickerQueryParameters): Promise<IPeoplePickerEntity>
+```
+
+```typescript
+const sp = spfi(...);
+const result = await sp.profiles.clientPeoplePickerResolveUser({
+  AllowEmailAddresses: true,
+  AllowMultipleEntities: false,
+  MaximumEntitySuggestions: 25,
+  QueryString: 'mbowen@contoso.com'
+});
+```
+
+## Search a user or group
+
+Searches for users or groups using specified query parameters
+
+```typescript
+clientPeoplePickerSearchUser(queryParams: IClientPeoplePickerQueryParameters): Promise<IPeoplePickerEntity[]>
+```
+
+```typescript
+const sp = spfi(...);
+const result = await sp.profiles.clientPeoplePickerSearchUser({
+  AllowEmailAddresses: true,
+  AllowMultipleEntities: false,
+  MaximumEntitySuggestions: 25,
+  QueryString: 'John'
+});
+```

package/docs/sp/publishing-sitepageservice.md

@@ -0,0 +1,16 @@
+# @pnp/sp/publishing-sitepageservice
+
+[![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+Through the REST api you are able to call a SP.Publishing.SitePageService method GetCurrentUserMemberships. This method allows you to fetch identifiers of unified groups to which current user belongs. It's an alternative for using [graph.me.transitiveMemberOf()](../graph/users.md#user-properties) method from graph package. Note, method only works with the context of a logged in user, and not with app-only permissions.
+
+## Get current user's group memberships
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/publishing-sitepageservice";
+
+const sp = spfi(...);
+
+const groupIdentifiers = await sp.publishingSitePageService.getCurrentUserMemberships();
+```