autnam 1.0.0

package/packages/arcgis-rest-portal/src/sharing/is-item-shared-with-group.ts

@@ -0,0 +1,42 @@
+import { IGroupSharingOptions } from "./helpers.js";
+import { searchItems } from "../items/search.js";
+import { ISearchOptions } from "../util/search.js";
+
+/**
+ * ```js
+ * import { isItemSharedWithGroup } from "@esri/arcgis-rest-portal";
+ * //
+ * isItemSharedWithGroup({
+ *   groupId: 'bc3,
+ *   itemId: 'f56,
+ *   authentication
+ * })
+ * .then(isShared => {})
+ * ```
+ * Find out whether or not an item is already shared with a group.
+ *
+ * @param requestOptions - Options for the request. NOTE: `rawResponse` is not supported by this operation.
+ * @returns Promise that will resolve with true/false
+ */
+export function isItemSharedWithGroup(
+  requestOptions: IGroupSharingOptions
+): Promise<boolean> {
+  const searchOpts = {
+    q: `id: ${requestOptions.id} AND group: ${requestOptions.groupId}`,
+    start: 1,
+    num: 10,
+    sortField: "title",
+    authentication: requestOptions.authentication,
+    httpMethod: "POST"
+  } as ISearchOptions;
+
+  return searchItems(searchOpts).then((searchResponse) => {
+    let result = false;
+    if (searchResponse.total > 0) {
+      result = searchResponse.results.some((itm: any) => {
+        return itm.id === requestOptions.id;
+      });
+      return result;
+    }
+  });
+}

package/packages/arcgis-rest-portal/src/sharing/share-item-with-group.ts

@@ -0,0 +1,335 @@
+import { request, IUser } from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url.js";
+import {
+  IGroupSharingOptions,
+  ISharingResponse,
+  getUserMembership
+} from "./helpers.js";
+import { getUser } from "../users/get-user.js";
+import { addGroupUsers, IAddGroupUsersResult } from "../groups/add-users.js";
+import { removeGroupUsers } from "../groups/remove-users.js";
+import {
+  updateUserMemberships,
+  IUpdateGroupUsersResult
+} from "../groups/update-user-membership.js";
+import { isItemSharedWithGroup } from "../sharing/is-item-shared-with-group.js";
+
+interface IEnsureMembershipResult {
+  promise: Promise<IAddGroupUsersResult>;
+  revert: (sharingResults: ISharingResponse) => Promise<ISharingResponse>;
+}
+
+/**
+ * ```js
+ * import { shareItemWithGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * shareItemWithGroup({
+ *   id: "abc123",
+ *   groupId: "xyz987",
+ *   owner: "some-owner",
+ *   authentication
+ * })
+ * ```
+ * Share an item with a group, either as an
+ * [item owner](https://developers.arcgis.com/rest/users-groups-and-items/share-item-as-item-owner-.htm),
+ * [group admin](https://developers.arcgis.com/rest/users-groups-and-items/share-item-as-group-admin-.htm) or
+ * organization admin.
+ *
+ * Note: Sharing the item as an Admin will use the `/content/users/:ownername/items/:itemid/share` end-point
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function shareItemWithGroup(
+  requestOptions: IGroupSharingOptions
+): Promise<ISharingResponse> {
+  return isItemSharedWithGroup(requestOptions)
+    .then((isShared) => {
+      if (isShared) {
+        // already shared, exit early with success response
+        return {
+          itemId: requestOptions.id,
+          shortcut: true,
+          notSharedWith: []
+        } as ISharingResponse;
+      }
+
+      const {
+        authentication: { username },
+        owner,
+        confirmItemControl
+      } = requestOptions;
+      const itemOwner = owner || username;
+
+      // non-item owner
+      if (itemOwner !== username) {
+        // need to track if the user is an admin
+        let isAdmin = false;
+        // next perform any necessary membership adjustments for
+        // current user and/or item owner
+        return Promise.all([
+          getUser({
+            username,
+            authentication: requestOptions.authentication
+          }),
+          getUser({
+            username: itemOwner,
+            authentication: requestOptions.authentication
+          }),
+          getUserMembership(requestOptions)
+        ])
+          .then(([currentUser, ownerUser, membership]) => {
+            const isSharedEditingGroup = !!confirmItemControl;
+            isAdmin = currentUser.role === "org_admin" && !currentUser.roleId;
+            return getMembershipAdjustments(
+              currentUser,
+              isSharedEditingGroup,
+              membership,
+              isAdmin,
+              ownerUser,
+              requestOptions
+            );
+          })
+          .then((membershipAdjustments) => {
+            const [
+              { revert } = {
+                promise: Promise.resolve({ notAdded: [] }),
+                revert: (sharingResults: ISharingResponse) => {
+                  return Promise.resolve(sharingResults);
+                }
+              } as IEnsureMembershipResult
+            ] = membershipAdjustments;
+            // perform all membership adjustments
+            return Promise.all(
+              membershipAdjustments.map(({ promise }) => promise)
+            )
+              .then(() => {
+                // then attempt the share
+                return shareToGroup(requestOptions, isAdmin);
+              })
+              .then((sharingResults) => {
+                // lastly, if the admin user was added to the group,
+                // remove them from the group. this is a no-op that
+                // immediately resolves the sharingResults when no
+                // membership adjustment was needed
+                return revert(sharingResults);
+              });
+          });
+      }
+
+      // item owner, let it call through
+      return shareToGroup(requestOptions);
+    })
+    .then((sharingResponse) => {
+      if (sharingResponse.notSharedWith.length) {
+        throw Error(
+          `Item ${requestOptions.id} could not be shared to group ${requestOptions.groupId}.`
+        );
+      } else {
+        // all is well
+        return sharingResponse;
+      }
+    });
+}
+
+function getMembershipAdjustments(
+  currentUser: IUser,
+  isSharedEditingGroup: boolean,
+  membership: string,
+  isAdmin: boolean,
+  ownerUser: IUser,
+  requestOptions: IGroupSharingOptions
+) {
+  const membershipGuarantees = [];
+  if (requestOptions.groupId !== currentUser.favGroupId) {
+    if (isSharedEditingGroup) {
+      if (!isAdmin) {
+        // abort and reject promise
+        throw Error(
+          `This item can not be shared to shared editing group ${requestOptions.groupId} by ${currentUser.username} as they not the item owner or org admin.`
+        );
+      }
+
+      membershipGuarantees.push(
+        // admin user must be a group member to share, should be reverted afterwards
+        ensureMembership(
+          currentUser,
+          currentUser,
+          false,
+          `Error adding ${currentUser.username} as member to edit group ${requestOptions.groupId}. Consequently item ${requestOptions.id} was not shared to the group.`,
+          requestOptions
+        ),
+        // item owner must be a group admin
+        ensureMembership(
+          currentUser,
+          ownerUser,
+          true,
+          membership === "none"
+            ? `Error adding user ${ownerUser.username} to edit group ${requestOptions.groupId}. Consequently item ${requestOptions.id} was not shared to the group.`
+            : `Error promoting user ${ownerUser.username} to admin in edit group ${requestOptions.groupId}. Consequently item ${requestOptions.id} was not shared to the group.`,
+          requestOptions
+        )
+      );
+    } else if (isAdmin) {
+      // admin user must be a group member to share, should be reverted afterwards
+      membershipGuarantees.push(
+        ensureMembership(
+          currentUser,
+          currentUser,
+          false,
+          `Error adding ${currentUser.username} as member to view group ${requestOptions.groupId}. Consequently item ${requestOptions.id} was not shared to the group.`,
+          requestOptions
+        )
+      );
+    } else if (membership === "none") {
+      // all other non-item owners must be a group member
+      throw new Error(
+        `This item can not be shared by ${currentUser.username} as they are not a member of the specified group ${requestOptions.groupId}.`
+      );
+    }
+  }
+
+  return membershipGuarantees;
+}
+
+function shareToGroup(
+  requestOptions: IGroupSharingOptions,
+  isAdmin = false
+): Promise<ISharingResponse> {
+  const username = requestOptions.authentication.username;
+  const itemOwner = requestOptions.owner || username;
+  // decide what url to use
+  // default to the non-owner url...
+  let url = `${getPortalUrl(requestOptions)}/content/items/${
+    requestOptions.id
+  }/share`;
+
+  // but if they are the owner, or org_admin, use this route
+  // Note: When using this end-point as an admin, apparently the admin does not need to be a member of the group (the itemOwner does)
+  // Have not validated this but came up in conversations w/ Sharing API team
+  if (itemOwner === username || isAdmin) {
+    url = `${getPortalUrl(requestOptions)}/content/users/${itemOwner}/items/${
+      requestOptions.id
+    }/share`;
+  }
+
+  // now its finally time to do the sharing
+  requestOptions.params = {
+    groups: requestOptions.groupId,
+    confirmItemControl: requestOptions.confirmItemControl
+  };
+
+  return request(url, requestOptions);
+}
+
+export function ensureMembership(
+  currentUser: IUser,
+  ownerUser: IUser,
+  shouldPromote: boolean,
+  errorMessage: string,
+  requestOptions: IGroupSharingOptions
+): IEnsureMembershipResult {
+  const ownerGroups = ownerUser.groups || [];
+  const group = ownerGroups.find((g) => {
+    return g.id === requestOptions.groupId;
+  });
+
+  // if they are in different orgs, eject
+  if (currentUser.orgId !== ownerUser.orgId) {
+    throw Error(
+      `User ${ownerUser.username} is not a member of the same org as ${currentUser.username}. Consequently they can not be added added to group ${requestOptions.groupId} nor can item ${requestOptions.id} be shared to the group.`
+    );
+  }
+
+  // if owner is not a member, and has 512 groups
+  if (!group && ownerGroups.length > 511) {
+    throw Error(
+      `User ${ownerUser.username} already has 512 groups, and can not be added to group ${requestOptions.groupId}. Consequently item ${requestOptions.id} can not be shared to the group.`
+    );
+  }
+
+  let promise: Promise<IAddGroupUsersResult>;
+  let revert: (sharingResults: ISharingResponse) => Promise<ISharingResponse>;
+
+  // decide if we need to add them or upgrade them
+  if (group) {
+    // they are in the group...
+    // check member type
+    if (shouldPromote && group.userMembership.memberType === "member") {
+      // promote them
+      promise = updateUserMemberships({
+        id: requestOptions.groupId,
+        users: [ownerUser.username],
+        newMemberType: "admin",
+        authentication: requestOptions.authentication
+      })
+        .then((results: IUpdateGroupUsersResult) => {
+          // convert the result into the right type
+          const notAdded = results.results.reduce((acc: any[], entry: any) => {
+            if (!entry.success) {
+              acc.push(entry.username);
+            }
+            return acc;
+          }, []);
+          // and return it
+          return Promise.resolve({ notAdded });
+        })
+        .catch(() => ({ notAdded: [ownerUser.username] }));
+      revert = (sharingResults) =>
+        updateUserMemberships({
+          id: requestOptions.groupId,
+          users: [ownerUser.username],
+          newMemberType: "member",
+          authentication: requestOptions.authentication
+        })
+          .then(() => sharingResults)
+          .catch(() => sharingResults);
+    } else {
+      // they are already an admin in the group
+      // return the same response the API would if we added them
+      promise = Promise.resolve({ notAdded: [] });
+      revert = (sharingResults) => Promise.resolve(sharingResults);
+    }
+  } else {
+    // attempt to add user to group
+    const userType = shouldPromote ? "admins" : "users";
+    // can't currently determine if the group is within the admin's
+    // org without performing a search, so attempt to add and handle
+    // the api error
+    promise = addGroupUsers({
+      id: requestOptions.groupId,
+      [userType]: [ownerUser.username],
+      authentication: requestOptions.authentication
+    })
+      .then((results) => {
+        // results.errors includes an ArcGISAuthError when the group
+        // is in a different org, but notAdded is empty, throw here
+        // to normalize the results in below catch
+        if (results.errors && results.errors.length) {
+          throw results.errors[0];
+        }
+        return results;
+      })
+      .catch(() => ({ notAdded: [ownerUser.username] }));
+    revert = (sharingResults) => {
+      return removeGroupUsers({
+        id: requestOptions.groupId,
+        users: [ownerUser.username],
+        authentication: requestOptions.authentication
+      }).then(() => {
+        // always resolves, suppress any resolved errors
+        return sharingResults;
+      });
+    };
+  }
+
+  return {
+    promise: promise.then((membershipResponse) => {
+      if (membershipResponse.notAdded.length) {
+        throw new Error(errorMessage);
+      }
+      return membershipResponse;
+    }),
+    revert
+  };
+}

package/packages/arcgis-rest-portal/src/sharing/unshare-item-with-group.ts

@@ -0,0 +1,114 @@
+import { request } from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url.js";
+import {
+  IGroupSharingOptions,
+  ISharingResponse,
+  getUserMembership
+} from "./helpers.js";
+import { isItemSharedWithGroup } from "./is-item-shared-with-group.js";
+import { getUser } from "../users/get-user.js";
+
+/**
+ * Stop sharing an item with a group, either as an
+ * [item owner](https://developers.arcgis.com/rest/users-groups-and-items/unshare-item-as-item-owner-.htm),
+ * [group admin](https://developers.arcgis.com/rest/users-groups-and-items/unshare-item-as-group-admin-.htm) or
+ * organization admin.
+ *
+ * ```js
+ * import { unshareItemWithGroup } from '@esri/arcgis-rest-portal';
+ *
+ * unshareItemWithGroup({
+ *   id: "abc123",
+ *   groupId: "xyz987",
+ *   owner: "some-owner",
+ *   authentication: session
+ * })
+ * ```
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function unshareItemWithGroup(
+  requestOptions: IGroupSharingOptions
+): Promise<ISharingResponse> {
+  return isItemSharedWithGroup(requestOptions).then((isShared) => {
+    // not shared
+    if (!isShared) {
+      // exit early with success response
+      return Promise.resolve({
+        itemId: requestOptions.id,
+        shortcut: true,
+        notUnsharedFrom: []
+      } as ISharingResponse);
+    }
+
+    const {
+      authentication: { username },
+      owner
+    } = requestOptions;
+
+    // next check if the user is a member of the group
+    return Promise.all([
+      getUserMembership(requestOptions),
+      getUser({
+        username,
+        authentication: requestOptions.authentication
+      })
+    ])
+      .then(([membership, currentUser]) => {
+        const itemOwner = owner || username;
+        const isItemOwner = itemOwner === username;
+        const isAdmin = currentUser.role === "org_admin" && !currentUser.roleId;
+
+        if (
+          !isItemOwner &&
+          !isAdmin &&
+          ["admin", "owner"].indexOf(membership) < 0
+        ) {
+          // abort and reject promise
+          throw Error(
+            `This item can not be unshared from group ${requestOptions.groupId} by ${username} as they not the item owner, an org admin, group admin or group owner.`
+          );
+        }
+
+        // let the sharing call go
+        return unshareFromGroup(requestOptions);
+      })
+      .then((sharingResponse) => {
+        if (sharingResponse.notUnsharedFrom.length) {
+          throw Error(
+            `Item ${requestOptions.id} could not be unshared to group ${requestOptions.groupId}`
+          );
+        } else {
+          // all is well
+          return sharingResponse;
+        }
+      });
+  });
+}
+
+function unshareFromGroup(
+  requestOptions: IGroupSharingOptions
+): Promise<ISharingResponse> {
+  const username = requestOptions.authentication.username;
+  const itemOwner = requestOptions.owner || username;
+  // decide what url to use
+  // default to the non-owner url...
+  let url = `${getPortalUrl(requestOptions)}/content/items/${
+    requestOptions.id
+  }/unshare`;
+
+  // but if they are the owner, we use a different path...
+  if (itemOwner === username) {
+    url = `${getPortalUrl(requestOptions)}/content/users/${itemOwner}/items/${
+      requestOptions.id
+    }/unshare`;
+  }
+
+  // now its finally time to do the sharing
+  requestOptions.params = {
+    groups: requestOptions.groupId
+  };
+
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/users/get-user-tags.ts

@@ -0,0 +1,52 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url.js";
+import { IGetUserOptions } from "./get-user.js";
+
+export interface ITagCount {
+  /**
+   * the name of a tag
+   */
+  tag: string;
+  /**
+   * a count that reports the number of times the tag was used
+   */
+  count: number;
+}
+
+export interface IGetUserTagsResponse {
+  /**
+   * Array of user item tag objects
+   */
+  tags: ITagCount[];
+}
+
+/**
+ * ```js
+ * import { getUserTags } from '@esri/arcgis-rest-portal';
+ * //
+ * getUserTags({
+ *   username: "jsmith",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ *  Users tag the content they publish in their portal via the add and update item calls. This resource lists all the tags used by the user along with the number of times the tags have been used. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/user-tags.htm) for more information.
+ *
+ * @param IGetUserOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the user tag array
+ */
+export function getUserTags(
+  requestOptions: IGetUserOptions
+): Promise<IGetUserTagsResponse> {
+  const username =
+    requestOptions.username || requestOptions.authentication.username;
+  const url = `${getPortalUrl(
+    requestOptions
+  )}/community/users/${encodeURIComponent(username)}/tags`;
+
+  // send the request
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/users/get-user-url.ts

@@ -0,0 +1,18 @@
+/* Copyright (c) 2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url.js";
+
+/**
+ * Helper that returns the [user](https://developers.arcgis.com/rest/users-groups-and-items/user.htm) for a given portal.
+ *
+ * @param session
+ * @returns User url to be used in API requests.
+ */
+export function getUserUrl(session: ArcGISIdentityManager): string {
+  return `${getPortalUrl(session)}/community/users/${encodeURIComponent(
+    session.username
+  )}`;
+}

package/packages/arcgis-rest-portal/src/users/get-user.ts

@@ -0,0 +1,60 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  ArcGISIdentityManager,
+  IUser
+} from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url.js";
+
+export interface IGetUserOptions extends IRequestOptions {
+  /**
+   * A session representing a logged in user.
+   */
+  authentication?: ArcGISIdentityManager;
+  /**
+   * Supply a username if you'd like to fetch information about a different user than is being used to authenticate the request.
+   */
+  username?: string;
+}
+
+/**
+ * ```js
+ * import { getUser } from '@esri/arcgis-rest-portal';
+ * //
+ * getUser("jsmith")
+ *   .then(response)
+ * // => { firstName: "John", lastName: "Smith",tags: ["GIS Analyst", "City of Redlands"] }
+ * ```
+ * Get information about a user. This method has proven so generically useful that you can also call [`ArcGISIdentityManager.getUser()`](/arcgis-rest-js/api/auth/ArcGISIdentityManager#getUser-summary).
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with metadata about the user
+ */
+export function getUser(
+  requestOptions?: string | IGetUserOptions
+): Promise<IUser> {
+  let url;
+  let options = { httpMethod: "GET" } as IGetUserOptions;
+
+  // if a username is passed, assume ArcGIS Online
+  if (typeof requestOptions === "string") {
+    url = `https://www.arcgis.com/sharing/rest/community/users/${requestOptions}`;
+  } else {
+    // if an authenticated session is passed, default to that user/portal unless another username is provided manually
+    const username =
+      requestOptions.username || requestOptions.authentication.username;
+    url = `${getPortalUrl(requestOptions)}/community/users/${encodeURIComponent(
+      username
+    )}`;
+    options = {
+      ...requestOptions,
+      ...options
+    };
+  }
+  // send the request
+  return request(url, options);
+}