@zxncij2390/monorepo3 3.18.0

package/docs/sp/sites.md

@@ -0,0 +1,269 @@
+# @pnp/sp/site - Site properties
+
+Site collection are one of the fundamental entry points while working with SharePoint. Sites serve as container for webs, lists, features and other entity types.
+
+## Get context information for the current site collection
+
+Using the library, you can get the context information of the current site collection
+
+```Typescript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+import { IContextInfo } from "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const oContext: IContextInfo = await sp.site.getContextInfo();
+console.log(oContext.FormDigestValue);
+```
+
+## Get document libraries of a web
+
+Using the library, you can get a list of the document libraries present in the a given web.
+
+**Note:** Works only in SharePoint online
+
+```Typescript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+import { IDocumentLibraryInformation } from "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const docLibs: IDocumentLibraryInformation[] = await sp.site.getDocumentLibraries("https://tenant.sharepoint.com/sites/test/subsite");
+
+//we got the array of document library information
+docLibs.forEach((docLib: IDocumentLibraryInformation) => {
+    // do something with each library
+});
+```
+
+## Open Web By Id
+
+Because this method is a POST request you can chain off it directly. You will get back the full web properties in the data property of the return object. You can also chain directly off the returned Web instance on the web property.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const w = await sp.site.openWebById("111ca453-90f5-482e-a381-cee1ff383c9e");
+
+//we got all the data from the web as well
+console.log(w.data);
+
+// we can chain
+const w2 = await w.web.select("Title")();
+```
+
+## Get absolute web url from page url
+
+Using the library, you can get the absolute web url by providing a page url
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const d: string = await sp.site.getWebUrlFromPageUrl("https://tenant.sharepoint.com/sites/test/Pages/test.aspx");
+
+console.log(d); //https://tenant.sharepoint.com/sites/test
+```
+
+## Access the root web
+
+There are two methods to access the root web. The first, using the rootWeb property, is best for directly accessing information about that web. If you want to chain multiple operations off of the web, better to use the getRootWeb method that will ensure the web instance is created using its own Url vs. "_api/sites/rootweb" which does not work for all operations.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+// use for rootweb information access
+const rootwebData = await sp.site.rootWeb();
+
+// use for chaining
+const rootweb = await sp.site.getRootWeb();
+const listData = await rootWeb.lists.getByTitle("MyList")();
+```
+
+## Create a modern communication site
+
+**Note:** Works only in SharePoint online
+
+Creates a modern communication site.
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| Title | string | yes | The title of the site to create. |
+| lcid | number | yes | The default language to use for the site. |
+| shareByEmailEnabled | boolean | yes | If set to true, it will enable sharing files via Email. By default it is set to false |
+| url | string | yes | The fully qualified URL (e.g. `https://yourtenant.sharepoint.com/sites/mysitecollection`) of the site. |
+| description | string | no | The description of the communication site. |
+| classification | string | no | The Site classification to use. For instance "Contoso Classified". See [https://www.youtube.com/watch?v=E-8Z2ggHcS0](https://www.youtube.com/watch?v=E-8Z2ggHcS0) for more information
+| siteDesignId | string | no | The Guid of the site design to be used.
+||||You can use the below default OOTB GUIDs:
+||||Topic: null
+||||                               Showcase: 6142d2a0-63a5-4ba0-aede-d9fefca2c767
+||||                               Blank: f6cc5403-0d63-442e-96c0-285923709ffc
+| hubSiteId | string | no | The Guid of the already existing Hub site
+| Owner| string | no | Required when using app-only context. Owner principal name e.g. user@tenant.onmicrosoft.com
+|
+
+```TypeScript
+
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const result = await sp.site.createCommunicationSite(
+            "Title",
+            1033,
+            true,
+            "https://tenant.sharepoint.com/sites/commSite",
+            "Description",
+            "HBI",
+            "f6cc5403-0d63-442e-96c0-285923709ffc",
+            "a00ec589-ea9f-4dba-a34e-67e78d41e509",
+            "user@TENANT.onmicrosoft.com");
+
+```
+
+### Create from Props
+
+You may need to supply additional parameters such as WebTemplate, to do so please use the `createCommunicationSiteFromProps` method.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+// in this case you supply a single struct deinfing the creation props
+const result = await sp.site.createCommunicationSiteFromProps({
+  Owner: "patrick@three18studios.com",
+  Title: "A Test Site",
+  Url: "https://{tenant}.sharepoint.com/sites/commsite2",
+  WebTemplate: "STS#3",
+});
+```
+
+## Create a modern team site
+
+**Note:** Works only in SharePoint online. It wont work with App only tokens
+
+Creates a modern team site backed by O365 group.
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| displayName | string | yes | The title/displayName of the site to be created. |
+| alias | string | yes | Alias of the underlying Office 365 Group. |
+| isPublic | boolean | yes | Defines whether the Office 365 Group will be public (default), or private. |
+| lcid | number | yes | The language to use for the site. If not specified will default to English (1033). |
+| description | string | no | The description of the modern team site. |
+| classification | string | no | The Site classification to use. For instance "Contoso Classified". See [https://www.youtube.com/watch?v=E-8Z2ggHcS0](https://www.youtube.com/watch?v=E-8Z2ggHcS0) for more information
+| owners | string array (string[]) | no | The Owners of the site to be created
+|hubSiteId|string| no | The Guid of the already existing Hub site
+| siteDesignId | string | no | The Guid of the site design to be used.
+||||You can use the below default OOTB GUIDs:
+||||Topic: null
+||||                               Showcase: 6142d2a0-63a5-4ba0-aede-d9fefca2c767
+||||                               Blank: f6cc5403-0d63-442e-96c0-285923709ffc
+
+```TypeScript
+
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+const result = await sp.site.createModernTeamSite(
+        "displayName",
+        "alias",
+        true,
+        1033,
+        "description",
+        "HBI",
+        ["user1@tenant.onmicrosoft.com","user2@tenant.onmicrosoft.com","user3@tenant.onmicrosoft.com"],
+        "a00ec589-ea9f-4dba-a34e-67e78d41e509",
+        "f6cc5403-0d63-442e-96c0-285923709ffc"
+        );
+
+console.log(d);
+```
+
+### Create from Props
+
+You may need to supply additional parameters, to do so please use the `createModernTeamSiteFromProps` method.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+// in this case you supply a single struct deinfing the creation props
+const result = await sp.site.createModernTeamSiteFromProps({
+  alias: "JenniferGarner",
+  displayName: "A Test Site",
+  owners: ["patrick@three18studios.com"],
+});
+```
+
+## Delete a site collection
+
+Using the library, you can delete a specific site collection
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+import { Site } from "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+// Delete the current site
+await sp.site.delete();
+
+// Specify which site to delete
+const siteUrl = "https://tenant.sharepoint.com/sites/subsite";
+const site2 = Site(siteUrl);
+await site2.delete();
+```
+
+## Check if a Site Collection Exists
+
+Using the library, you can check if a specific site collection exist or not on your tenant
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+// Specify which site to verify
+const siteUrl = "https://tenant.sharepoint.com/sites/subsite";
+const exists = await sp.site.exists(siteUrl);
+console.log(exists);
+```
+
+## Set the site logo
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+import {ISiteLogoProperties, SiteLogoAspect, SiteLogoType} from "@pnp/sp/sites";
+
+const sp = spfi(...);
+
+//set the web's site logo
+const logoProperties: ISiteLogoProperties = {
+    relativeLogoUrl: "/sites/mySite/SiteAssets/site_logo.png", 
+    aspect: SiteLogoAspect.Rectangular, 
+    type: SiteLogoType.WebLogo
+};
+await sp.site.setSiteLogo(logoProperties);
+```

package/docs/sp/social.md

@@ -0,0 +1,182 @@
+# @pnp/sp/ - social
+
+[![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+The social API allows you to track followed sites, people, and docs. Note, many of these methods only work with the context of a logged in user, and not
+with app-only permissions.
+
+## getFollowedSitesUri
+
+Gets a URI to a site that lists the current user's followed sites.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/social";
+
+const sp = spfi(...);
+
+const uri = await sp.social.getFollowedSitesUri();
+```
+
+## getFollowedDocumentsUri
+
+Gets a URI to a site that lists the current user's followed documents.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/social";
+
+const sp = spfi(...);
+
+const uri = await sp.social.getFollowedDocumentsUri();
+```
+
+## follow
+
+Makes the current user start following a user, document, site, or tag
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { SocialActorType } from "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// follow a site
+const r1 = await sp.social.follow({
+    ActorType: SocialActorType.Site,
+    ContentUri: "htts://tenant.sharepoint.com/sites/site",
+});
+
+// follow a person
+const r2 = await sp.social.follow({
+    AccountName: "i:0#.f|membership|person@tenant.com",
+    ActorType: SocialActorType.User,
+});
+
+// follow a doc
+const r3 = await sp.social.follow({
+    ActorType: SocialActorType.Document,
+    ContentUri: "https://tenant.sharepoint.com/sites/dev/SitePages/Test.aspx",
+});
+
+// follow a tag
+// You need the tag GUID to start following a tag.
+// You can't get the GUID by using the REST service, but you can use the .NET client object model or the JavaScript object model.
+// See How to get a tag's GUID based on the tag's name by using the JavaScript object model.
+// https://docs.microsoft.com/en-us/sharepoint/dev/general-development/follow-content-in-sharepoint#bk_getTagGuid
+const r4 = await sp.social.follow({
+    ActorType: SocialActorType.Tag,
+    TagGuid: "19a4a484-c1dc-4bc5-8c93-bb96245ce928",
+});
+```
+
+## isFollowed
+
+Indicates whether the current user is following a specified user, document, site, or tag
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { SocialActorType } from "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// pass the same social actor struct as shown in follow example for each type
+const r = await sp.social.isFollowed({
+    AccountName: "i:0#.f|membership|person@tenant.com",
+    ActorType: SocialActorType.User,
+});
+```
+
+## stopFollowing
+
+Makes the current user stop following a user, document, site, or tag
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { SocialActorType } from "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// pass the same social actor struct as shown in follow example for each type
+const r = await sp.social.stopFollowing({
+    AccountName: "i:0#.f|membership|person@tenant.com",
+    ActorType: SocialActorType.User,
+});
+```
+
+## my
+
+### get
+
+Gets this user's social information
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/social";
+
+const sp = spfi(...);
+
+const r = await sp.social.my();
+```
+
+### followed
+
+Gets users, documents, sites, and tags that the current user is following based on the supplied flags.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { SocialActorType } from "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// get all the followed documents
+const r1 = await sp.social.my.followed(SocialActorTypes.Document);
+
+// get all the followed documents and sites
+const r2 = await sp.social.my.followed(SocialActorTypes.Document | SocialActorTypes.Site);
+
+// get all the followed sites updated in the last 24 hours
+const r3 = await sp.social.my.followed(SocialActorTypes.Site | SocialActorTypes.WithinLast24Hours);
+```
+
+### followedCount
+
+Works as followed but returns on the count of actors specified by the query
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { SocialActorType } from "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// get the followed documents count
+const r = await sp.social.my.followedCount(SocialActorTypes.Document);
+```
+
+### followers
+
+Gets the users who are following the current user.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// get the followed documents count
+const r = await sp.social.my.followers();
+```
+
+### suggestions
+
+Gets users who the current user might want to follow.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/social";
+
+const sp = spfi(...);
+
+// get the followed documents count
+const r = await sp.social.my.suggestions();
+```

package/docs/sp/sp-utilities-utility.md

@@ -0,0 +1,159 @@
+# @pnp/sp/utilities
+
+Through the REST api you are able to call a subset of the SP.Utilities.Utility methods. We have explicitly defined some of these methods and provided a method to call any others in a generic manner. These methods are exposed on pnp.sp.utility and support batching and caching.
+
+## sendEmail
+
+This methods allows you to send an email based on the supplied arguments. The method takes a single argument, a plain object defined by the EmailProperties interface (shown below).
+
+### EmailProperties
+
+```TypeScript
+export interface TypedHash<T> {
+    [key: string]: T;
+}
+
+export interface EmailProperties {
+
+    To: string[];
+    CC?: string[];
+    BCC?: string[];
+    Subject: string;
+    Body: string;
+    AdditionalHeaders?: TypedHash<string>;
+    From?: string;
+}
+```
+
+### Usage
+
+You must define the To, Subject, and Body values - the remaining are optional.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+import { IEmailProperties } from "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+const emailProps: IEmailProperties = {
+    To: ["user@site.com"],
+    CC: ["user2@site.com", "user3@site.com"],
+    BCC: ["user4@site.com", "user5@site.com"],
+    Subject: "This email is about...",
+    Body: "Here is the body. <b>It supports html</b>",
+    AdditionalHeaders: {
+        "content-type": "text/html"
+    }
+};
+
+await sp.utility.sendEmail(emailProps);
+console.log("Email Sent!");
+```
+
+## getCurrentUserEmailAddresses
+
+This method returns the current user's email addresses known to SharePoint.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let addressString: string = await sp.utility.getCurrentUserEmailAddresses();
+
+// and use it with sendEmail
+await sp.utility.sendEmail({
+    To: [addressString],
+    Subject: "This email is about...",
+    Body: "Here is the body. <b>It supports html</b>",
+    AdditionalHeaders: {
+        "content-type": "text/html"
+    },
+});
+```
+
+## resolvePrincipal
+
+Gets information about a principal that matches the specified Search criteria
+
+```TypeScript
+import { spfi, SPFx, IPrincipalInfo, PrincipalType, PrincipalSource } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let principal : IPrincipalInfo = await sp.utility.resolvePrincipal("user@site.com", PrincipalType.User, PrincipalSource.All, true, false, true);
+
+console.log(principal);
+```
+
+## searchPrincipals
+
+Gets information about the principals that match the specified Search criteria.
+
+```TypeScript
+import { spfi, SPFx, IPrincipalInfo, PrincipalType, PrincipalSource } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let principals : IPrincipalInfo[] = await sp.utility.searchPrincipals("john", PrincipalType.User, PrincipalSource.All,"", 10);
+
+console.log(principals);
+```
+
+## createEmailBodyForInvitation
+
+Gets the external (outside the firewall) URL to a document or resource in a site.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let url : string = await sp.utility.createEmailBodyForInvitation("https://contoso.sharepoint.com/sites/dev/SitePages/DevHome.aspx");
+console.log(url);
+```
+
+## expandGroupsToPrincipals
+
+Resolves the principals contained within the supplied groups
+
+```TypeScript
+import { spfi, SPFx, IPrincipalInfo } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let principals : IPrincipalInfo[] = await sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"]);
+console.log(principals);
+
+// optionally supply a max results count. Default is 30.
+let principals : IPrincipalInfo[] = await sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"], 10);
+console.log(principals);
+```
+
+## createWikiPage
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sputilities";
+import { ICreateWikiPageResult } from "@pnp/sp/sputilities";
+
+const sp = spfi(...);
+
+let newPage : ICreateWikiPageResult = await sp.utility.createWikiPage({
+    ServerRelativeUrl: "/sites/dev/SitePages/mynewpage.aspx",
+    WikiHtmlContent: "This is my <b>page</b> content. It supports rich html.",
+});
+
+// newPage contains the raw data returned by the service
+console.log(newPage.data);
+
+// newPage contains a File instance you can use to further update the new page
+let file = await newPage.file();
+console.log(file);
+```

package/docs/sp/subscriptions.md

@@ -0,0 +1,79 @@
+# @pnp/sp/subscriptions
+
+Webhooks on a SharePoint list are used to notify any change in the list, to other applications using a push model. This module provides methods to add, update or delete webhooks on a particular SharePoint list or library.
+
+## ISubscriptions
+
+[![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)  
+
+### Add a webhook
+
+Using this library, you can add a webhook to a specified list within the SharePoint site.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+
+import { Subscriptions, ISubscriptions} from "@pnp/sp/subscriptions";
+import "@pnp/sp/subscriptions/list";
+
+const sp = spfi(...);
+
+// This is the URL which will be called by SharePoint when there is a change in the list
+const notificationUrl = "<notification-url>";
+
+// Set the expiry date to 180 days from now, which is the maximum allowed for the webhook expiry date.
+const expiryDate = dateAdd(new Date(), "day" , 180).toISOString();
+
+// Adds a webhook to the Documents library
+var res = await sp.web.lists.getByTitle("Documents").subscriptions.add(notificationUrl,expiryDate);
+```
+
+### Get all webhooks added to a list
+
+Read all the webhooks' details which are associated to the list
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/subscriptions";
+
+const sp = spfi(...);
+
+const res = await sp.web.lists.getByTitle("Documents").subscriptions();
+```
+
+## ISubscription
+
+This interface provides the methods for managing a particular webhook.
+
+[![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   | import "@pnp/sp/webs";<br />import "@pnp/sp/lists";<br />import { Subscriptions, ISubscriptions, Subscription, ISubscription} from "@pnp/sp/subscriptions";<br />import "@pnp/sp/subscriptions/list" |
+| Preset: All | import { sp, Webs, IWebs, Lists, ILists, Subscriptions, ISubscriptions, Subscription, ISubscription } from "@pnp/sp/presets/all";                                                                                                                       |
+
+### Managing a webhook
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/subscriptions";
+
+const sp = spfi(...);
+
+// Get details of a webhook based on its ID
+const webhookId = "1f029e5c-16e4-4941-b46f-67895118763f";
+const webhook = await sp.web.lists.getByTitle("Documents").subscriptions.getById(webhookId)();
+
+// Update a webhook
+const newDate = dateAdd(new Date(), "day" , 150).toISOString();
+const updatedWebhook = await sp.web.lists.getByTitle("Documents").subscriptions.getById(webhookId).update(newDate);
+
+// Delete a webhook
+await sp.web.lists.getByTitle("Documents").subscriptions.getById(webhookId).delete();
+```