Merge pull request #2972 from juliemturner/version-4

V4 Update: Permissions and Shares

.vscode/launch.json

@@ -37,7 +37,7 @@
       "args": [
         "--verbose",
         "--logging",
-        "Error",
+        "verbose",
         "--record",
         "write"
       ],

debug/launch/graph.ts

@@ -1,17 +1,52 @@
 import { Logger, LogLevel } from "@pnp/logging";
 import { graphSetup } from "./setup.js";
+import { getRandomString, stringIsNullOrEmpty } from "@pnp/core";
 import "@pnp/graph/users";
+import "@pnp/graph/files";
+import { IDriveItemAdd, IDriveItemAddFolder, IFileUploadOptions, IItemOptions, IBundleDef } from "@pnp/graph/files";
 
 declare var process: { exit(code?: number): void };
 
 export async function Example(settings: any) {
 
     const graph = graphSetup(settings);
 
-    const users = await graph.users();
+    const fileOptions: IFileUploadOptions = {
+        content: "This is some test content",
+        filePathName: "pnpTest.txt",
+        contentType: "text/plain;charset=utf-8",
+    };
+
+    const testUserName = settings.testing.testUser.substring(settings.testing.testUser.lastIndexOf("|") + 1);
+    const drives = await graph.users.getById(testUserName).drives();
+    let driveId = "";
+    if (drives.length > 0) {
+        driveId = drives[0].id;
+    }
+
+    // Create sample files
+    let folderId = "";
+    let child1Id = "";
+    let child2Id = "";
+    const testFolderName = `TestFolder_${getRandomString(4)}`;
+    const driveItemAdd: IDriveItemAddFolder = {
+        name: testFolderName,
+    };
+    const folder = await graph.users.getById(testUserName).drives.getById(driveId).root.children.addFolder(driveItemAdd);
+    if (folder != null) {
+        folderId = folder.id;
+        const testFileName = `TestFile_${getRandomString(4)}.json`;
+        const fo = JSON.parse(JSON.stringify(fileOptions));
+        fo.filePathName = testFileName;
+        const child1 = await graph.users.getById(testUserName).drives.getById(driveId).getItemById(folderId).upload(fo);
+        child1Id = child1.id;
+        fo.filePathName = `TestFile_${getRandomString(4)}.json`;
+        const child2 = await graph.users.getById(testUserName).drives.getById(driveId).getItemById(folderId).upload(fo);
+        child2Id = child2.id;
+    }
 
     Logger.log({
-      data: users,
+      data: folder,
       level: LogLevel.Info,
       message: "List of Users Data",
     });

docs/graph/files.md

@@ -129,7 +129,7 @@ const shared = await graph.me.drives.getById({drive id}).sharedWithMe(options);
 
 ```
 
-## Get the following drive item
+## Get the drive item being followed
 
 List the items that have been followed by the signed in user.
 
@@ -208,9 +208,9 @@ const rootChildren = await graph.users.getById({user id}).drives.getById({drive
 
 const rootChildren = await graph.me.drives.getById({drive id}).root.children();
 
-const itemChildren = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").children();
+const itemChildren = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").children();
 
-const itemChildren = await graph.me.drives.getById({drive id}).root.items.getById("{item id}").children();
+const itemChildren = await graph.me.drives.getById({drive id}).root.getItemById("{item id}").children();
 
 ```
 
@@ -368,9 +368,9 @@ import "@pnp/graph/files";
 
 const graph = graphfi(...);
 
-const item = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}")();
+const item = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}")();
 
-const item = await graph.me.drives.getById({drive id}).items.getById("{item id}")();
+const item = await graph.me.drives.getById({drive id}).getItemById("{item id}")();
 
 ```
 
@@ -462,9 +462,9 @@ import "@pnp/graph/files";
 
 const graph = graphfi(...);
 
-const thumbs = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").thumbnails();
+const thumbs = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").thumbnails();
 
-const thumbs = await graph.me.drives.getById({drive id}).items.getById("{item id}").thumbnails();
+const thumbs = await graph.me.drives.getById({drive id}).getItemById("{item id}").thumbnails();
 
 ```
 
@@ -479,10 +479,10 @@ import "@pnp/graph/files";
 
 const graph = graphfi(...);
 
-await graph.me.drives.getById({drive id}).items.getById({item id}).delete();
-await graph.me.drives.getById({drive id}).items.getById({item id}).permanentDelete();
-await graph.users.getById({user id}).drives.getById({drive id}).items.getById({item id}).delete();
-await graph.users.getById({user id}).drives.getById({drive id}).items.getById({item id}).permanentDelete();
+await graph.me.drives.getById({drive id}).getItemById({item id}).delete();
+await graph.me.drives.getById({drive id}).getItemById({item id}).permanentDelete();
+await graph.users.getById({user id}).drives.getById({drive id}).getItemById({item id}).delete();
+await graph.users.getById({user id}).drives.getById({drive id}).getItemById({item id}).permanentDelete();
 ```
 
 ## Update drive item metadata
@@ -496,9 +496,9 @@ import "@pnp/graph/files";
 
 const graph = graphfi(...);
 
-const update = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").update({name: "New Name"});
+const update = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").update({name: "New Name"});
 
-const update = await graph.me.drives.getById({drive id}).items.getById("{item id}").update({name: "New Name"});
+const update = await graph.me.drives.getById({drive id}).getItemById("{item id}").update({name: "New Name"});
 
 ```
 
@@ -522,9 +522,9 @@ const moveOptions: IItemOptions = {
   name?: {newName};
 };
 
-const move = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").move(moveOptions);
+const move = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").move(moveOptions);
 
-const move = await graph.me.drives.getById({drive id}).items.getById("{item id}").move(moveOptions);
+const move = await graph.me.drives.getById({drive id}).getItemById("{item id}").move(moveOptions);
 
 ```
 
@@ -548,9 +548,9 @@ const copyOptions: IItemOptions = {
   name?: {newName};
 };
 
-const copy = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").copy(copyOptions);
+const copy = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").copy(copyOptions);
 
-const copy = await graph.me.drives.getById({drive id}).items.getById("{item id}").copy(copyOptions);
+const copy = await graph.me.drives.getById({drive id}).getItemById("{item id}").copy(copyOptions);
 
 ```
 
@@ -590,16 +590,16 @@ import { ItemPreviewInfo } from "@microsoft/microsoft-graph-types"
 
 const graph = graphfi(...);
 
-const preview: ItemPreviewInfo = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").preview();
+const preview: ItemPreviewInfo = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").preview();
 
-const preview: ItemPreviewInfo = await graph.me.drives.getById({drive id}).items.getById("{item id}").preview();
+const preview: ItemPreviewInfo = await graph.me.drives.getById({drive id}).getItemById("{item id}").preview();
 
 const previewOptions: IPreviewOptions = {
     page: 1,
     zoom: 90
 }
 
-const preview2: ItemPreviewInfo = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").preview(previewOptions);
+const preview2: ItemPreviewInfo = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").preview(previewOptions);
 
 ```
 
@@ -640,16 +640,57 @@ import { IAnalyticsOptions } from "@pnp/graph/files";
 const graph = graphfi(...);
 
 // Defaults to lastSevenDays
-const analytics = await graph.users.getById({user id}).drives.getById({drive id}).items.getById("{item id}").analytics()();
+const analytics = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").analytics()();
 
-const analytics = await graph.me.drives.getById({drive id}).items.getById("{item id}").analytics()();
+const analytics = await graph.me.drives.getById({drive id}).getItemById("{item id}").analytics()();
 
 const analyticOptions: IAnalyticsOptions = {
     timeRange: "allTime"
 };
 
-const analyticsAllTime = await graph.me.drives.getById({drive id}).items.getById("{item id}").analytics(analyticOptions)();
+const analyticsAllTime = await graph.me.drives.getById({drive id}).getItemById("{item id}").analytics(analyticOptions)();
 ```
 
 For more information on:
 [Sensitivity and Retention Labels (Premium Endpoint)](./files-labels.md)
+
+## Permissions
+
+### List/Get/Add/Update/Delete Drive Item Permissions
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/users";
+import "@pnp/graph/files";
+import "@pnp/graph/permissions/drive-item";
+import {IPermissionsInviteInfo} from "@pnp/graph/permissions/drive-item";
+
+const graph = graphfi(...);
+
+const newPermissions: IPermissionsInviteInfo = {
+    recipients: [{email: "[email protected]"}],
+    requireSignIn: true,
+    sendInvitation: true,
+    roles: ["read"]
+};
+
+// List permissions
+const permissions = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").permissions();
+
+// Add permissions
+const permissions = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").addPermissions(newPermissions);
+
+// Get permissions
+const itemPermissions = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").permissions.getById(permissions.id)();
+
+// Update permissions
+const updatedPermissions = await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").permissions.getById(permissions.id).update({roles: ["write"]});
+
+// Delete permissions
+await graph.users.getById({user id}).drives.getById({drive id}).getItemById("{item id}").permissions.getById(permissions.id).delete();
+
+```
+
+## Sharing
+
+[Shares](./shares.md)

docs/graph/permissions.md

@@ -46,8 +46,10 @@ const graph = graphfi(...);
 const permissions = await graph.sites.getById("{site id}").permissions.add({
   roles: ["fullcontrol"],
   grantedToIdentities: [{
-    id: "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
-    displayName: "Contoso Time Manager App",
+    application: {
+      id: "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
+      displayName: "Contoso Time Manager App",
+    }
   }],
 });
 ```

docs/graph/shares.md

@@ -46,3 +46,74 @@ const graph = graphfi(...);
 
 const driveItemInfo = await graph.shares.getById("{shareId}").driveItem();
 ```
+
+## Convert sharing URL to a sharing token
+
+To use a sharing URL with this API, your app needs to transform the URL into a sharing token.
+
+```TS
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/shares";
+import {IShareLinkInfo} from "@pnp/graph/shares";
+
+const graph = graphfi(...);
+
+// Use ShareId
+const shareLinkInfo: IShareLinkInfo = {
+    shareId: shareId,
+    redeemSharingLink: false,
+};
+const sharedDriveItem = await graph.shares.useSharingLink(shareLinkInfo);
+
+// Use Encoded Sharing Link
+const shareLink: string = graph.shares.encodeSharingLink("https://{tenant}.sharepoint.com/sites/dev/Shared%20Documents/new.pptx");
+const shareLinkInfo = {
+    encodedSharingUrl: shareLink,
+    redeemSharingLink: false
+};
+const sharedDriveItem = await graph.shares.useSharingLink(shareLinkInfo);
+```
+
+## Create Sharing Link
+
+You can use createLink action to share a DriveItem via a sharing link.
+
+The createLink action will create a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, the existing sharing link will be returned.
+
+```TS
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/shares";
+import "@pnp/graph/users";
+import "@pnp/graph/files";
+
+const graph = graphfi(...);
+
+const sharingLinkInfo: ICreateShareLinkInfo = {
+    type: "view",
+    scope: "anonymous",
+};
+const sharingLink = await graph.users.getById({userId}).drives.getById({driveId}).getItemById({itemId}).createSharingLink(sharingLinkInfo);
+
+```
+
+## Grant Sharing Link Access
+
+Grant users access to a link represented by a permission.
+
+```TS
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/shares";
+
+const graph = graphfi(...);
+
+const shareLink: string = graph.shares.encodeSharingLink("https://{tenant}.sharepoint.com/sites/dev/Shared%20Documents/new.pptx");
+const sharingLinkAccess = {
+    encodedSharingUrl: shareLink,
+    recipients: [{email: "[email protected]"}],
+    roles: ["read"]
+};
+
+// 
+const permissions = await graph.shares.grantSharingLinkAccess(sharingLinkAccess);
+
+```