aspernaturalias 1.0.0

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

@@ -0,0 +1,210 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IItem } from "@esri/arcgis-rest-types";
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  IGroupSharingOptions,
+  ISharingResponse,
+  isOrgAdmin,
+  getUserMembership
+} from "./helpers";
+
+interface IGroupSharingUnsharingOptions extends IGroupSharingOptions {
+  action: "share" | "unshare";
+}
+
+/**
+ * ```js
+ * import { shareItemWithGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * shareItemWithGroup({
+ *   id: "abc123",
+ *   groupId: "xyz987",
+ *   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 changeGroupSharing({ action: "share", ...requestOptions });
+}
+
+/**
+ * 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",
+ *   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 changeGroupSharing({ action: "unshare", ...requestOptions });
+}
+
+/**
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+function changeGroupSharing(
+  requestOptions: IGroupSharingUnsharingOptions
+): Promise<ISharingResponse> {
+  const username = requestOptions.authentication.username;
+  const owner = requestOptions.owner || username;
+
+  return isOrgAdmin(requestOptions).then(admin => {
+    const resultProp =
+      requestOptions.action === "share" ? "notSharedWith" : "notUnsharedFrom";
+    // check if the item has already been shared with the group...
+    return isItemSharedWithGroup(requestOptions).then(result => {
+      // if we are sharing and result is true OR we are unsharing and result is false... short circuit
+      if (
+        (requestOptions.action === "share" && result === true) ||
+        (requestOptions.action === "unshare" && result === false)
+      ) {
+        // and send back the same response ArcGIS Online would
+        const response = {
+          itemId: requestOptions.id,
+          shortcut: true
+        } as ISharingResponse;
+        response[resultProp] = [];
+        return response;
+      } else {
+        // next check to ensure the user is a member of the group
+        return getUserMembership(requestOptions)
+          .then(membership => {
+            if (membership === "nonmember") {
+              // abort and reject promise
+              throw Error(
+                `This item can not be ${
+                  requestOptions.action
+                }d by ${username} as they are not a member of the specified group ${
+                  requestOptions.groupId
+                }.`
+              );
+            } else {
+              // if owner (and member of group) share using the owner url
+              if (owner === username) {
+                return `${getPortalUrl(
+                  requestOptions
+                )}/content/users/${owner}/items/${requestOptions.id}/${
+                  requestOptions.action
+                }`;
+              } else {
+                // if org admin, group admin/owner, use the bare item url
+                if (membership === "admin" || membership === "owner" || admin) {
+                  return `${getPortalUrl(requestOptions)}/content/items/${
+                    requestOptions.id
+                  }/${requestOptions.action}`;
+                } else {
+                  // otherwise abort
+                  throw Error(
+                    `This item can not be ${
+                      requestOptions.action
+                    }d by ${username} as they are neither the owner, a groupAdmin of ${
+                      requestOptions.groupId
+                    }, nor an org_admin.`
+                  );
+                }
+              }
+            }
+          })
+          .then(url => {
+            // now its finally time to do the sharing
+            requestOptions.params = {
+              groups: requestOptions.groupId,
+              confirmItemControl: requestOptions.confirmItemControl
+            };
+            // dont mixin to ensure that old query parameters from the search request arent included
+            return request(url, requestOptions);
+          })
+          .then(sharingResponse => {
+            if (sharingResponse[resultProp].length) {
+              throw Error(
+                `Item ${requestOptions.id} could not be ${
+                  requestOptions.action
+                }d to group ${requestOptions.groupId}.`
+              );
+            } else {
+              // all is well
+              return sharingResponse;
+            }
+          });
+      } // else
+    }); // then
+  });
+}
+
+/**
+ * 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 A Promise that will resolve with the data from the response.
+ */
+function isItemSharedWithGroup(
+  requestOptions: IGroupSharingOptions
+): Promise<boolean> {
+  const query = {
+    q: `id: ${requestOptions.id} AND group: ${requestOptions.groupId}`,
+    start: 1,
+    num: 10,
+    sortField: "title"
+  };
+
+  // we need to append some params into requestOptions, so make a clone
+  // instead of mutating the params on the inbound requestOptions object
+  const options = { ...requestOptions, rawResponse: false };
+  // instead of calling out to "@esri/arcgis-rest-items, make the request manually to forgoe another dependency
+  options.params = {
+    ...query,
+    ...requestOptions.params
+  };
+
+  const url = `${getPortalUrl(options)}/search`;
+
+  // to do: just call searchItems now that its in the same package
+  return request(url, options).then(searchResponse => {
+    // if there are no search results at all, we know the item hasnt already been shared with the group
+    if (searchResponse.total === 0) {
+      return false;
+    } else {
+      let sharedItem: IItem;
+      // otherwise loop through and search for the id
+      searchResponse.results.some((item: IItem) => {
+        const matchedItem = item.id === requestOptions.id;
+        if (matchedItem) {
+          sharedItem = item;
+        }
+        return matchedItem;
+      });
+
+      if (sharedItem) {
+        return true;
+      } else {
+        return false;
+      }
+    }
+  });
+}

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

@@ -0,0 +1,84 @@
+/* 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: ISharingOptions): Promise<boolean> {
+  const session = requestOptions.authentication;
+
+  return session.getUser(requestOptions).then((user: IUser) => {
+    if (!user || user.role !== "org_admin") {
+      return false;
+    } else {
+      return true;
+    }
+  });
+}
+
+/**
+ * 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 "nonmember" as GroupMembership;
+    });
+}
+
+export interface IGroupSharingOptions extends ISharingOptions {
+  /**
+   * Group identifier
+   */
+  groupId: string;
+  confirmItemControl?: boolean;
+}

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 { UserSession } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+/**
+ * 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: UserSession): string {
+  return `${getPortalUrl(session)}/community/users/${encodeURIComponent(
+    session.username
+  )}`;
+}

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

@@ -0,0 +1,58 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+import { IUser } from "@esri/arcgis-rest-types";
+
+import { UserSession } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IGetUserOptions extends IRequestOptions {
+  /**
+   * A session representing a logged in user.
+   */
+  authentication?: UserSession;
+  /**
+   * 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 [`UserSession.getUser()`](/arcgis-rest-js/api/auth/UserSession#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);
+}

package/packages/arcgis-rest-portal/src/users/invitation.ts

@@ -0,0 +1,162 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IGroup } from "@esri/arcgis-rest-types";
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IInvitation {
+  id: string;
+  targetType: string;
+  targetId: string;
+  received: number;
+  accepted: boolean;
+  mustApprove: boolean;
+  email: string;
+  role: string;
+  type: string;
+  dateAccepted: number;
+  expiration: number;
+  created: number;
+  username: string;
+  fromUsername: {
+    username: string;
+    fullname?: string;
+  };
+  group?: IGroup;
+  groupId?: string;
+}
+
+export interface IInvitationResult {
+  userInvitations: IInvitation[];
+}
+
+/**
+ * ```js
+ * import { getUserInvitations } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserInvitations({ authentication })
+ *   .then(response) // response.userInvitations.length => 3
+ * ```
+ * Get all invitations for a user. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/user-invitations.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the user's invitations
+ */
+export function getUserInvitations(
+  requestOptions: IUserRequestOptions
+): Promise<IInvitationResult> {
+  let options = { httpMethod: "GET" } as IUserRequestOptions;
+
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations`;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+export interface IGetUserInvitationOptions extends IUserRequestOptions {
+  invitationId: string;
+}
+
+/**
+ * ```js
+ * import { getUserInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response) // => response.accepted => true
+ * ```
+ * Get an invitation for a user by id. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/user-invitation.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the invitation
+ */
+export function getUserInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<IInvitation> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${
+    requestOptions.invitationId
+  }`;
+
+  let options = { httpMethod: "GET" } as IGetUserInvitationOptions;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+/**
+ * ```js
+ * import { acceptInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * acceptInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Accept an invitation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/accept-invitation.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function acceptInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<{
+  success: boolean;
+  username: string;
+  groupId: string;
+  id: string;
+}> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${
+    requestOptions.invitationId
+  }/accept`;
+
+  const options: IGetUserInvitationOptions = { ...requestOptions };
+  return request(url, options);
+}
+
+/**
+ * ```js
+ * import { declineInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * declineInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Decline an invitation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/decline-invitation.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function declineInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<{
+  success: boolean;
+  username: string;
+  groupId: string;
+  id: string;
+}> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${
+    requestOptions.invitationId
+  }/decline`;
+
+  const options: IGetUserInvitationOptions = { ...requestOptions };
+  return request(url, options);
+}

package/packages/arcgis-rest-portal/src/users/notification.ts

@@ -0,0 +1,70 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface INotification {
+  id: string;
+  type: string;
+  target: string;
+  targetType: string;
+  received: number;
+  data: { [key: string]: any };
+}
+
+export interface IRemoveNotificationOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the item.
+   */
+  id: string;
+}
+export interface INotificationResult {
+  notifications: INotification[];
+}
+
+/**
+ * ```js
+ * import { getUserNotifications } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserNotifications({ authentication })
+ *   .then(results) // results.notifications.length) => 3
+ * ```
+ * Get notifications for a user.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the user's notifications
+ */
+export function getUserNotifications(
+  requestOptions: IUserRequestOptions
+): Promise<INotificationResult> {
+  let options = { httpMethod: "GET" } as IUserRequestOptions;
+
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/notifications`;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+/**
+ * Delete a notification.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function removeNotification(
+  requestOptions: IRemoveNotificationOptions
+): Promise<{ success: boolean; notificationId: string }> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/notifications/${
+    requestOptions.id
+  }/delete`;
+
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/users/update.ts

@@ -0,0 +1,66 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IUser } from "@esri/arcgis-rest-types";
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IUpdateUserOptions extends IUserRequestOptions {
+  /**
+   * The user properties to be updated.
+   */
+  user: IUser;
+}
+
+export interface IUpdateUserResponse {
+  success: boolean;
+  username: string;
+}
+
+/**
+ * ```js
+ * import { updateUser } from '@esri/arcgis-rest-portal';
+ * // any user can update their own profile
+ * updateUser({
+ *   authentication,
+ *   user: { description: "better than the last one" }
+ * })
+ *   .then(response)
+ * // org administrators must declare the username that will be updated explicitly
+ * updateUser({
+ *   authentication,
+ *   user: { username: "c@sey", description: "" }
+ * })
+ *   .then(response)
+ * // => { "success": true, "username": "c@sey" }
+ * ```
+ * Update a user profile. The username will be extracted from the authentication session unless it is provided explicitly. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-user.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with metadata about the user
+ */
+export function updateUser(
+  requestOptions?: IUpdateUserOptions
+): Promise<IUpdateUserResponse> {
+  // default to the authenticated username unless another username is provided manually
+  const username =
+    requestOptions.user.username || requestOptions.authentication.username;
+
+  const updateUrl = `${getPortalUrl(
+    requestOptions
+  )}/community/users/${encodeURIComponent(username)}/update`;
+
+  // mixin custom params and the user information, then drop the user info
+  requestOptions.params = {
+    ...requestOptions.user,
+    ...requestOptions.params
+  };
+
+  delete requestOptions.user;
+
+  // send the request
+  return request(updateUrl, requestOptions);
+}