@pnp/cli-microsoft365 8.0.0 → 8.1.0-beta.3a80e6f

package/dist/utils/drive.js

@@ -0,0 +1,61 @@
+import request from "../request.js";
+export const drive = {
+    /**
+     * Retrieves the Drive associated with the specified site and URL.
+     * @param siteId Site ID
+     * @param url Drive URL
+     * @param logger The logger object
+     * @param verbose Set for verbose logging
+     * @returns The Drive associated with the drive URL.
+     */
+    async getDriveByUrl(siteId, url, logger, verbose) {
+        if (verbose && logger) {
+            await logger.logToStderr(`Retrieving drive information for URL: ${url.href}`);
+        }
+        const requestOptions = {
+            url: `https://graph.microsoft.com/v1.0/sites/${siteId}/drives?$select=webUrl,id`,
+            headers: {
+                accept: 'application/json;odata.metadata=none'
+            },
+            responseType: 'json'
+        };
+        const drives = await request.get(requestOptions);
+        const lowerCaseFolderUrl = url.href.toLowerCase();
+        const drive = drives.value
+            .sort((a, b) => b.webUrl.localeCompare(a.webUrl))
+            .find((d) => {
+            const driveUrl = d.webUrl.toLowerCase();
+            return lowerCaseFolderUrl.startsWith(driveUrl) &&
+                (driveUrl.length === lowerCaseFolderUrl.length ||
+                    lowerCaseFolderUrl[driveUrl.length] === '/');
+        });
+        if (!drive) {
+            throw new Error(`Drive '${url.href}' not found`);
+        }
+        return drive;
+    },
+    /**
+     * Retrieves the ID of a drive item (file, folder, etc.) associated with the given drive and item URL.
+     * @param drive The Drive object containing the item
+     * @param itemUrl Item URL
+     * @param logger The logger object
+     * @param verbose Set for verbose logging
+     * @returns Drive item ID
+     */
+    async getDriveItemId(drive, itemUrl, logger, verbose) {
+        const relativeItemUrl = itemUrl.href.replace(new RegExp(`${drive.webUrl}`, 'i'), '').replace(/\/+$/, '');
+        if (verbose && logger) {
+            await logger.logToStderr(`Retrieving drive item ID for URL: ${relativeItemUrl}`);
+        }
+        const requestOptions = {
+            url: `https://graph.microsoft.com/v1.0/drives/${drive.id}/root${relativeItemUrl ? `:${relativeItemUrl}` : ''}?$select=id`,
+            headers: {
+                accept: 'application/json;odata.metadata=none'
+            },
+            responseType: 'json'
+        };
+        const driveItem = await request.get(requestOptions);
+        return driveItem?.id;
+    }
+};
+//# sourceMappingURL=drive.js.map

package/dist/utils/formatting.js

@@ -39,6 +39,22 @@ export const formatting = {
     parseJsonWithBom(s) {
         return JSON.parse(s.replace(/^\uFEFF/, ''));
     },
+    /**
+     * Tries to parse a string as JSON. If it fails, returns the original string.
+     * @param value JSON string to parse.
+     * @returns JSON object or the original string if parsing fails.
+     */
+    tryParseJson(value) {
+        try {
+            if (typeof value !== 'string') {
+                return value;
+            }
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    },
     filterObject(obj, propertiesToInclude) {
         const objKeys = Object.keys(obj);
         return propertiesToInclude

package/dist/utils/spo.js

@@ -454,15 +454,46 @@ export const spo = {
         const res = await request.get(requestOptions);
         return res.AadObjectId.NameId;
     },
+    /**
+     * Ensure a user exists on a specific SharePoint site.
+     * @param webUrl URL of the SharePoint site.
+     * @param logonName Logon name of the user to ensure on the SharePoint site.
+     * @returns SharePoint user object.
+     */
+    async ensureUser(webUrl, logonName) {
+        const requestOptions = {
+            url: `${webUrl}/_api/web/EnsureUser`,
+            headers: {
+                accept: 'application/json;odata=nometadata'
+            },
+            responseType: 'json',
+            data: {
+                logonName: logonName
+            }
+        };
+        return request.post(requestOptions);
+    },
+    /**
+     * Ensure a Microsoft Entra ID group exists on a specific SharePoint site.
+     * @param webUrl URL of the SharePoint site.
+     * @param group Microsoft Entra ID group.
+     * @returns SharePoint user object.
+     */
+    async ensureEntraGroup(webUrl, group) {
+        if (!group.securityEnabled) {
+            throw new Error('Cannot ensure a Microsoft Entra ID group that is not security enabled.');
+        }
+        return this.ensureUser(webUrl, group.mailEnabled ? `c:0o.c|federateddirectoryclaimprovider|${group.id}` : `c:0t.c|tenant|${group.id}`);
+    },
     /**
    * Retrieves the spo user by email.
    * @param webUrl Web url
    * @param email The email of the user
    * @param logger the Logger object
-   * @param debug set if debug logging should be logged
+   * @param verbose set if verbose logging should be logged
    */
-    async getUserByEmail(webUrl, email, logger, debug) {
-        if (debug) {
+    async getUserByEmail(webUrl, email, logger, verbose) {
+        if (verbose) {
             await logger.logToStderr(`Retrieving the spo user by email ${email}`);
         }
         const requestUrl = `${webUrl}/_api/web/siteusers/GetByEmail('${formatting.encodeQueryParameter(email)}')`;
@@ -533,10 +564,10 @@ export const spo = {
     * @param webUrl Web url
     * @param name The name of the group
     * @param logger the Logger object
-    * @param debug set if debug logging should be logged
+    * @param verbose set if verbose logging should be logged
     */
-    async getGroupByName(webUrl, name, logger, debug) {
-        if (debug) {
+    async getGroupByName(webUrl, name, logger, verbose) {
+        if (verbose) {
             await logger.logToStderr(`Retrieving the group by name ${name}`);
         }
         const requestUrl = `${webUrl}/_api/web/sitegroups/GetByName('${formatting.encodeQueryParameter(name)}')`;
@@ -1374,6 +1405,38 @@ export const spo = {
         const site = await request.get(requestOptions);
         return site.id;
     },
+    /**
+     * Retrieves the server-relative URL of a folder.
+     * @param webUrl Web URL
+     * @param folderUrl Folder URL
+     * @param folderId Folder ID
+     * @param logger The logger object
+     * @param verbose Set for verbose logging
+     * @returns The server-relative URL of the folder
+     */
+    async getFolderServerRelativeUrl(webUrl, folderUrl, folderId, logger, verbose) {
+        if (verbose && logger) {
+            await logger.logToStderr(`Retrieving server-relative URL for folder ${folderUrl ? `URL: ${folderUrl}` : `ID: ${folderId}`}`);
+        }
+        let requestUrl = `${webUrl}/_api/web/`;
+        if (folderUrl) {
+            const folderServerRelativeUrl = urlUtil.getServerRelativePath(webUrl, folderUrl);
+            requestUrl += `GetFolderByServerRelativePath(decodedUrl='${formatting.encodeQueryParameter(folderServerRelativeUrl)}')`;
+        }
+        else {
+            requestUrl += `GetFolderById('${folderId}')`;
+        }
+        requestUrl += '?$select=ServerRelativeUrl';
+        const requestOptions = {
+            url: requestUrl,
+            headers: {
+                accept: 'application/json;odata=nometadata'
+            },
+            responseType: 'json'
+        };
+        const res = await request.get(requestOptions);
+        return res.ServerRelativeUrl;
+    },
     /**
      * Retrieves the ObjectIdentity from a SharePoint site
      * @param webUrl web url

package/dist/utils/zod.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+function parseEffect(def, _options, _currentOption) {
+    return def.schema._def;
+}
+function parseIntersection(def, _options, _currentOption) {
+    if (def.left._def.typeName !== z.ZodFirstPartyTypeKind.ZodAny) {
+        return def.left._def;
+    }
+    if (def.right._def.typeName !== z.ZodFirstPartyTypeKind.ZodAny) {
+        return def.right._def;
+    }
+    return;
+}
+function parseObject(def, options, _currentOption) {
+    const properties = def.shape();
+    for (const key in properties) {
+        const property = properties[key];
+        const option = {
+            name: key,
+            long: key,
+            short: property._def.alias,
+            required: true,
+            type: 'string'
+        };
+        parseDef(property._def, options, option);
+        options.push(option);
+    }
+    return;
+}
+function parseString(_def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.type = 'string';
+    }
+    return;
+}
+function parseNumber(_def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.type = 'number';
+    }
+    return;
+}
+function parseBoolean(_def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.type = 'boolean';
+    }
+    return;
+}
+function parseOptional(def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.required = false;
+    }
+    return def.innerType._def;
+}
+function parseDefault(def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.required = false;
+    }
+    return def.innerType._def;
+}
+function parseEnum(def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.type = 'string';
+        currentOption.autocomplete = def.values;
+    }
+    return;
+}
+function parseNativeEnum(def, _options, currentOption) {
+    if (currentOption) {
+        currentOption.type = 'string';
+        currentOption.autocomplete = Object.getOwnPropertyNames(def.values);
+    }
+    return;
+}
+function getParseFn(typeName) {
+    switch (typeName) {
+        case z.ZodFirstPartyTypeKind.ZodEffects:
+            return parseEffect;
+        case z.ZodFirstPartyTypeKind.ZodObject:
+            return parseObject;
+        case z.ZodFirstPartyTypeKind.ZodOptional:
+            return parseOptional;
+        case z.ZodFirstPartyTypeKind.ZodString:
+            return parseString;
+        case z.ZodFirstPartyTypeKind.ZodNumber:
+            return parseNumber;
+        case z.ZodFirstPartyTypeKind.ZodBoolean:
+            return parseBoolean;
+        case z.ZodFirstPartyTypeKind.ZodEnum:
+            return parseEnum;
+        case z.ZodFirstPartyTypeKind.ZodNativeEnum:
+            return parseNativeEnum;
+        case z.ZodFirstPartyTypeKind.ZodDefault:
+            return parseDefault;
+        case z.ZodFirstPartyTypeKind.ZodIntersection:
+            return parseIntersection;
+        default:
+            return;
+    }
+}
+function parseDef(def, options, currentOption) {
+    let parsedDef = def;
+    do {
+        const parse = getParseFn(parsedDef.typeName);
+        if (!parse) {
+            break;
+        }
+        parsedDef = parse(parsedDef, options, currentOption);
+        if (!parsedDef) {
+            break;
+        }
+    } while (parsedDef);
+}
+export const zod = {
+    alias(alias, type) {
+        type._def.alias = alias;
+        return type;
+    },
+    schemaToOptions(schema) {
+        const options = [];
+        parseDef(schema._def, options);
+        return options;
+    }
+};
+//# sourceMappingURL=zod.js.map

package/docs/docs/cmd/connection/connection-use.mdx

@@ -15,7 +15,7 @@ m365 connection use [options]
 ## Options
 
 ```md definition-list
-`-n, --name <name>`
+`-n, --name [name]`
 : The name of the connection to switch to.
 ```
 
@@ -23,7 +23,13 @@ m365 connection use [options]
 
 ## Remarks
 
-The value for `--name` can be found by running [m365 connection list](connection-list.mdx). You can update the name of a connection by running [m365 connection set](connection-set.mdx). 
+:::tip
+
+If you haven't disabled the "prompt" setting, running this command without options will show a list of available connections. You can then select the connection to activate it.
+
+:::
+
+You can update the name of a connection by running [m365 connection set](connection-set.mdx).
 
 ## Examples
 

package/docs/docs/cmd/entra/m365group/m365group-user-add.mdx

@@ -26,13 +26,25 @@ m365 teams user add
 
 ```md definition-list
 `-i, --groupId [groupId]`
-: The ID of the Microsoft 365 Group to which to add the user
+: The ID of the Microsoft 365 group. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`--groupName [groupName]`
+: The display name of the Microsoft 365 group. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
 
 `--teamId [teamId]`
-: The ID of the Teams team to which to add the user
+: The ID of the Teams team. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`--teamName [teamName]`
+: The display name of the Microsoft Teams team. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`-n, --userName [userName]`
+: (deprecated) User's UPN (User Principal Name), e.g. johndoe@example.com.
+
+`--ids [ids]`
+: Microsoft Entra IDs of users. You can also pass a comma-separated list of IDs. Specify either `ids` or `userNames` but not both.
 
-`-n, --userName <userName>`
-: User's UPN (user principal name, eg. johndoe@example.com)
+`--userNames [userNames]`
+: The user principal names of users. You can also pass a comma-separated list of UPNs. Specify either `ids` or `userNames` but not both.
 
 `-r, --role [role]`
 : The role to be assigned to the new user: `Owner,Member`. Default `Member`
@@ -42,22 +54,28 @@ m365 teams user add
 
 ## Examples
 
-Add a new member to the specified Microsoft 365 Group
+Add a new member with the userNames parameter to the specified Microsoft 365 Group
+
+```sh
+m365 entra m365group user add --groupId '00000000-0000-0000-0000-000000000000' --userNames 'anne.matthews@contoso.onmicrosoft.com'
+```
+
+Add multiple new owners with the userNames parameter to the specified Microsoft 365 Group
 
 ```sh
-m365 entra m365group user add --groupId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com'
+m365 entra m365group user add --groupName 'Contoso' --userNames 'anne.matthews@contoso.onmicrosoft.com, john.doe@contoso.onmicrosoft.com' --role Owner
 ```
 
-Add a new owner to the specified Microsoft 365 Group
+Add a new member with the userNames parameter to the specified Microsoft Teams team
 
 ```sh
-m365 entra m365group user add --groupId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com' --role Owner
+m365 entra m365group member add --teamId '00000000-0000-0000-0000-000000000000' --userNames 'anne.matthews@contoso.onmicrosoft.com' --role Member
 ```
 
-Add a new member to the specified Microsoft Teams team
+Add multiple new members with the ids parameter to the specified Microsoft Teams team
 
 ```sh
-m365 teams user add --teamId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com'
+m365 entra m365group user add --teamName 'Engineering' --ids '74a3b772-3122-447b-b9da-10895e238219,dd3d21e4-a142-46b9-8482-bca8fe9596b3' --role Member
 ```
 
 ## Response

package/docs/docs/cmd/entra/m365group/m365group-user-set.mdx

@@ -2,7 +2,7 @@ import Global from '/docs/cmd/_global.mdx';
 
 # entra m365group user set
 
-Updates role of the specified user in the specified Microsoft 365 Group or Microsoft Teams team
+Updates role of the specified users in the specified Microsoft 365 Group or Microsoft Teams team
 
 ## Usage
 
@@ -24,13 +24,25 @@ m365 aad teams user set
 
 ```md definition-list
 `-i, --groupId [groupId]`
-: The ID of the Microsoft 365 group for which to update user
+: The ID of the Microsoft 365 group. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`--groupName [groupName]`
+: The display name of the Microsoft 365 group. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
 
 `--teamId [teamId]`
-: The ID of the Microsoft Teams team for which to update user
+: The ID of the Teams team. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`--teamName [teamName]`
+: The display name of the Microsoft Teams team. Specify only one of the following: `groupId`, `groupName`, `teamId`, or `teamName`.
+
+`-n, --userName [userName]`
+: (deprecated) User's UPN (User Principal Name), e.g. johndoe@example.com.
 
-`-n, --userName <userName>`
-: UPN of the user for whom to update the role (eg. johndoe@example.com)
+`--ids [ids]`
+: Microsoft Entra IDs of users. You can also pass a comma-separated list of IDs. Specify only one of the following `userName`, `ids` or `userNames`.
+
+`--userNames [userNames]`
+: The user principal names of users. You can also pass a comma-separated list of UPNs. Specify only one of the following `userName`, `ids` or `userNames`.
 
 `-r, --role <role>`
 : Role to set for the given user in the specified Microsoft 365 Group or Microsoft Teams team. Allowed values: `Owner`, `Member`
@@ -44,28 +56,40 @@ The command will return an error if the user already has the specified role in t
 
 ## Examples
 
-Promote the specified user to owner of the given Microsoft 365 Group
+Promote a single user to Owner of the given Microsoft 365 Group
 
 ```sh
 m365 entra m365group user set --groupId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com' --role Owner
 ```
 
-Demote the specified user from owner to member in the given Microsoft 365 Group
+Promote multiple users specified by the userNames parameter to Owner of the given Microsoft 365 Group
+
+```sh
+m365 entra m365group user set --groupName 'Contoso' --userNames 'anne.matthews@contoso.onmicrosoft.com,john.doe@contoso.onmicrosoft.com' --role Owner
+```
+
+Promote multiple users specified by the ids parameter to Owner of the given Microsoft 365 Group
+
+```sh
+m365 entra m365group user set --groupId '00000000-0000-0000-0000-000000000000' --ids '74a3b772-3122-447b-b9da-10895e238219,dd3d21e4-a142-46b9-8482-bca8fe9596b3' --role Owner
+```
+
+Demote a single user from Owner to Member in the given Microsoft 365 Group
 
 ```sh
 m365 entra m365group user set --groupId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com' --role Member
 ```
 
-Promote the specified user to owner of the given Microsoft Teams team
+Demote multiple users specified by the userNames parameter from Owner to Member of the given Microsoft Teams team
 
 ```sh
-m365 entra teams user set --teamId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com' --role Owner
+m365 entra teams user set --teamId '00000000-0000-0000-0000-000000000000' --userNames 'anne.matthews@contoso.onmicrosoft.com,john.doe@contoso.onmicrosoft.com' --role Member
 ```
 
-Demote the specified user from owner to member in the given Microsoft Teams team
+Demote multiple users specified by the ids parameter from Owner to Member in the given Microsoft Teams team
 
 ```sh
-m365 entra teams user set --teamId '00000000-0000-0000-0000-000000000000' --userName 'anne.matthews@contoso.onmicrosoft.com' --role Member
+m365 entra teams user set --teamName 'Engineering' --ids '74a3b772-3122-447b-b9da-10895e238219,dd3d21e4-a142-46b9-8482-bca8fe9596b3' --role Member
 ```
 
 ## Response

package/docs/docs/cmd/entra/multitenant/multitenant-add.mdx

@@ -0,0 +1,107 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# entra multitenant add
+
+Creates a new multitenant organization
+
+## Usage
+
+```sh
+m365 entra multitenant add [options]
+```
+
+## Options
+
+```md definition-list
+`-n, --displayname <displayName>`
+: Display name for the multitenant organization.
+
+`-d, --description [description]`
+: Description for the multitenant organiztion.
+```
+
+<Global />
+
+## Remarks
+
+:::info
+
+To use this command you must be at least **Security Administrator**.
+
+:::
+
+## Examples
+
+Create a new multitenant organization with display name only.
+
+```sh
+m365 entra multitenant add --displayName 'Contoso organization'
+```
+
+Create a new multitenant organization with display name and description.
+
+```sh
+m365 entra multitenant add --displayName 'Contoso organization' --description 'Multitenant organization between Contoso, Fabrikam, and Woodgrove Bank'
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  {
+    "id": "c231d4a5-138f-4bdf-9fee-f26a90ea3ad0",
+    "createdDateTime": "2024-05-05T05:05:05Z",
+    "state": "active",
+    "displayName": "Contoso organization",
+    "description": "Multitenant organization between Contoso, Fabrikam, and Woodgrove Bank"
+  }
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  createdDateTime: 2024-05-05T05:05:05Z
+  description    : Multitenant organization between Contoso, Fabrikam, and Woodgrove Bank
+  displayName    : Contoso organization
+  id             : c231d4a5-138f-4bdf-9fee-f26a90ea3ad0
+  state          : active
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  id,createdDateTime,state,displayName,description
+  c231d4a5-138f-4bdf-9fee-f26a90ea3ad0,2024-05-05T05:05:05Z,active,Contoso organization,"Multitenant organization between Contoso, Fabrikam, and Woodgrove Bank"
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # entra multitenant add
+
+  Date: 5/5/2024
+
+  ## Contoso organization (c231d4a5-138f-4bdf-9fee-f26a90ea3ad0)
+
+  Property | Value
+  ---------|-------
+  id | c231d4a5-138f-4bdf-9fee-f26a90ea3ad0
+  createdDateTime | 2024-05-05T05:05:05Z
+  state | active
+  displayName | Contoso organization
+  description | Multitenant organization between Contoso, Fabrikam, and Woodgrove Bank
+  ```
+
+  </TabItem>
+</Tabs>
+
+## More information
+
+- Multitenant organization: https://learn.microsoft.com/entra/identity/multi-tenant-organizations/overview

package/docs/docs/cmd/entra/multitenant/multitenant-remove.mdx

@@ -0,0 +1,58 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# entra multitenant remove
+
+Removes a multitenant organization
+
+## Usage
+
+```sh
+m365 entra multitenant remove [options]
+```
+
+## options
+
+```md definition-list
+`-f, --force`
+: Don't prompt for confirmation.
+```
+
+<Global />
+
+## Remarks
+
+:::info
+
+To use this command you must be at least **Security Administrator**.
+
+:::
+
+:::info
+
+When removing a Multi-Tenant Organization, all associations with other tenants will be removed too.
+
+The removing process can take up to 2 hours to complete.
+
+:::
+
+## Examples
+
+Remove the multitenant organization.
+
+```sh
+m365 entra multitenant remove
+```
+
+Remove the multitenant organization without prompting for confirmation.
+
+```sh
+m365 entra multitenant remove --force
+```
+
+## Response
+
+The command won't return a response on success
+
+## More information
+
+- Multitenant organization: https://learn.microsoft.com/entra/identity/multi-tenant-organizations/overview