impeditmaiores 1.0.0

package/packages/arcgis-rest-portal/src/sharing/access.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import {
+  ISharingOptions,
+  ISharingResponse,
+  isItemOwner,
+  getSharingUrl,
+  isOrgAdmin
+} from "./helpers";
+
+export interface ISetAccessOptions extends ISharingOptions {
+  /**
+   * "private" indicates that the item can only be accessed by the user. "public" means accessible to anyone. An item shared to the organization has an access level of "org".
+   */
+  access: "private" | "org" | "public";
+}
+
+/**
+ * ```js
+ * import { setItemAccess } from "@esri/arcgis-rest-portal";
+ * //
+ * setItemAccess({
+ *   id: "abc123",
+ *   access: "public", // 'org' || 'private'
+ *   authentication: session
+ * })
+ * ```
+ * Change who is able to access an item.
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function setItemAccess(
+  requestOptions: ISetAccessOptions
+): Promise<ISharingResponse> {
+  const url = getSharingUrl(requestOptions);
+
+  if (isItemOwner(requestOptions)) {
+    // if the user owns the item, proceed
+    return updateItemAccess(url, requestOptions);
+  } else {
+    // otherwise we need to check to see if they are an organization admin
+    return isOrgAdmin(requestOptions).then(admin => {
+      if (admin) {
+        return updateItemAccess(url, requestOptions);
+      } else {
+        // if neither, updating the sharing isnt possible
+        throw Error(
+          `This item can not be shared by ${requestOptions.authentication.username}. They are neither the item owner nor an organization admin.`
+        );
+      }
+    });
+  }
+}
+
+function updateItemAccess(
+  url: string,
+  requestOptions: ISetAccessOptions
+): Promise<any> {
+  requestOptions.params = {
+    org: false,
+    everyone: false,
+    ...requestOptions.params
+  };
+
+  // if the user wants to make the item private, it needs to be unshared from any/all groups as well
+  if (requestOptions.access === "private") {
+    requestOptions.params.groups = " ";
+  }
+  if (requestOptions.access === "org") {
+    requestOptions.params.org = true;
+  }
+  // if sharing with everyone, share with the entire organization as well.
+  if (requestOptions.access === "public") {
+    // this is how the ArcGIS Online Home app sets public access
+    // setting org = true instead of account = true will cancel out all sharing
+    requestOptions.params.account = true;
+    requestOptions.params.everyone = true;
+  }
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/sharing/helpers.ts

@@ -0,0 +1,81 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IGroup, IUser, GroupMembership } from "@esri/arcgis-rest-types";
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+import { getPortalUrl } from "../util/get-portal-url";
+import { getGroup } from "../groups/get";
+
+export interface ISharingOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier for the item.
+   */
+  id: string;
+  /**
+   * Item owner, if different from the authenticated user.
+   */
+  owner?: string;
+}
+
+export interface ISharingResponse {
+  notSharedWith?: string[];
+  notUnsharedFrom?: string[];
+  itemId: string;
+}
+
+export function getSharingUrl(requestOptions: ISharingOptions): string {
+  const username = requestOptions.authentication.username;
+  const owner = requestOptions.owner || username;
+  return `${getPortalUrl(requestOptions)}/content/users/${encodeURIComponent(
+    owner
+  )}/items/${requestOptions.id}/share`;
+}
+
+export function isItemOwner(requestOptions: ISharingOptions): boolean {
+  const username = requestOptions.authentication.username;
+  const owner = requestOptions.owner || username;
+  return owner === username;
+}
+
+/**
+ * Check it the user is a full org_admin
+ * @param requestOptions
+ * @returns Promise resolving in a boolean indicating if the user is an ArcGIS Organization administrator
+ */
+export function isOrgAdmin(
+  requestOptions: IUserRequestOptions
+): Promise<boolean> {
+  const session = requestOptions.authentication;
+
+  return session.getUser(requestOptions).then((user: IUser) => {
+      return user && user.role === "org_admin" && !user.roleId;
+  });
+}
+
+/**
+ * Get the User Membership for a particular group. Use this if all you have is the groupId.
+ * If you have the group object, check the `userMembership.memberType` property instead of calling this method.
+ *
+ * @param requestOptions
+ * @returns A Promise that resolves with "owner" | "admin" | "member" | "nonmember"
+ */
+export function getUserMembership(
+  requestOptions: IGroupSharingOptions
+): Promise<GroupMembership> {
+  // fetch the group...
+  return getGroup(requestOptions.groupId, requestOptions)
+    .then((group: IGroup) => {
+      return group.userMembership.memberType;
+    })
+    .catch(() => {
+      return "none" as GroupMembership;
+    });
+}
+
+export interface IGroupSharingOptions extends ISharingOptions {
+  /**
+   * Group identifier
+   */
+  groupId: string;
+  confirmItemControl?: boolean;
+}

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

@@ -0,0 +1,42 @@
+import { IGroupSharingOptions } from "./helpers";
+import { searchItems } from "../items/search";
+import { ISearchOptions } from "../util/search";
+
+/**
+ * ```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,319 @@
+import { request } from "@esri/arcgis-rest-request";
+import { IUser } from "@esri/arcgis-rest-types";
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  IGroupSharingOptions,
+  ISharingResponse,
+  getUserMembership
+} from "./helpers";
+import { getUser } from "../users/get-user";
+import { addGroupUsers, IAddGroupUsersResult } from "../groups/add-users";
+import { removeGroupUsers } from "../groups/remove-users";
+import { updateUserMemberships, IUpdateGroupUsersResult } from "../groups/update-user-membership";
+import { isItemSharedWithGroup } from "../sharing/is-item-shared-with-group";
+
+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.
+ *
+ * @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) {
+        // 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;
+            const 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);
+              })
+              .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
+): 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, we use a different path...
+  if (itemOwner === username) {
+    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,105 @@
+import { request } from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  IGroupSharingOptions,
+  ISharingResponse,
+  getUserMembership
+} from "./helpers";
+import { isItemSharedWithGroup } from "./is-item-shared-with-group";
+import { getUser } from "../users/get-user";
+
+/**
+ * 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";
+import { IGetUserOptions } from "./get-user";
+
+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);
+}