ducimusipsa 1.0.0

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

@@ -0,0 +1,211 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, getPortalUrl } from "@esri/arcgis-rest-request";
+import { IItem } from "@esri/arcgis-rest-common-types";
+
+import {
+  ISharingRequestOptions,
+  ISharingResponse,
+  isOrgAdmin,
+  getUserMembership
+} from "./helpers";
+
+export interface IGroupSharingRequestOptions extends ISharingRequestOptions {
+  /**
+   * Group identifier
+   */
+  groupId: string;
+  confirmItemControl?: boolean;
+}
+
+interface IGroupSharingUnsharingRequestOptions
+  extends IGroupSharingRequestOptions {
+  action: "share" | "unshare";
+}
+
+/**
+ * Share an item with a group.
+ *
+ * ```js
+ * import { shareItemWithGroup } from '@esri/arcgis-rest-sharing';
+ *
+ * shareItemWithGroup({
+ *   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 shareItemWithGroup(
+  requestOptions: IGroupSharingRequestOptions
+): Promise<ISharingResponse> {
+  return changeGroupSharing({ action: "share", ...requestOptions });
+}
+
+/**
+ * Stop sharing an item with a group.
+ *
+ * ```js
+ * import { unshareItemWithGroup } from '@esri/arcgis-rest-sharing';
+ *
+ * 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: IGroupSharingRequestOptions
+): 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: IGroupSharingUnsharingRequestOptions
+): 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 => {
+      // console.log(admin);
+      // 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 structure ArcGIS Online would
+        const response = { itemId: requestOptions.id, shortcut: true } as any;
+        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 orgAdmin or owner (and member of group) share using the owner url
+              if (owner === username || admin) {
+                return `${getPortalUrl(
+                  requestOptions
+                )}/content/users/${owner}/items/${requestOptions.id}/${
+                  requestOptions.action
+                }`;
+              } else {
+                // if they are a group admin/owner, use the bare item url
+                if (membership === "admin" || membership === "owner") {
+                  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.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+function isItemSharedWithGroup(
+  requestOptions: IGroupSharingRequestOptions
+): 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 };
+  // 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`;
+
+  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-sharing/src/helpers.ts

@@ -0,0 +1,82 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions, getPortalUrl } from "@esri/arcgis-rest-request";
+import { UserSession } from "@esri/arcgis-rest-auth";
+import { IGroup, IUser, GroupMembership } from "@esri/arcgis-rest-common-types";
+import { getGroup } from "@esri/arcgis-rest-groups";
+import { IGroupSharingRequestOptions } from "./group-sharing";
+
+export interface ISharingRequestOptions extends IRequestOptions {
+  /**
+   * Unique identifier for the item.
+   */
+  id: string;
+  /**
+   * Represents a user with privileges to update item sharing.
+   */
+  authentication: UserSession;
+  /**
+   * Item owner, if different from the authenticated user.
+   */
+  owner?: string;
+}
+
+export interface ISharingResponse {
+  notSharedWith?: string[];
+  notUnsharedFrom?: string[];
+  itemId: string;
+}
+
+export function getSharingUrl(requestOptions: ISharingRequestOptions): 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: ISharingRequestOptions): 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: ISharingRequestOptions
+): Promise<boolean> {
+  const session = requestOptions.authentication as UserSession;
+
+  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 IGroupIdRequestOptions options to pass through in the request
+ * @returns A Promise that resolves with "owner" | "admin" | "member" | "nonmember"
+ */
+export function getUserMembership(
+  requestOptions: IGroupSharingRequestOptions
+): Promise<GroupMembership> {
+  // fetch the group...
+  return getGroup(requestOptions.groupId, requestOptions)
+    .then((group: IGroup) => {
+      return group.userMembership.memberType;
+    })
+    .catch(() => {
+      return "nonmember" as GroupMembership;
+    });
+}

package/packages/arcgis-rest-sharing/src/index.ts

@@ -0,0 +1,5 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./access";
+export * from "./group-sharing";

package/packages/arcgis-rest-sharing/test/access.test.ts

@@ -0,0 +1,154 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { setItemAccess } from "../src/index";
+import * as fetchMock from "fetch-mock";
+import { MOCK_USER_SESSION } from "./mocks/sharing";
+import {
+  AnonUserResponse,
+  OrgAdminUserResponse
+} from "../../arcgis-rest-users/test/mocks/user";
+
+const SharingResponse = {
+  notSharedWith: [] as any,
+  itemId: "abc123"
+};
+
+describe("setItemAccess()", () => {
+  // make sure session doesnt cache metadata
+  beforeEach(function() {
+    MOCK_USER_SESSION._user = null;
+  });
+
+  afterEach(fetchMock.restore);
+
+  it("should share an item with everyone", done => {
+    fetchMock.once("*", SharingResponse);
+
+    setItemAccess({
+      authentication: MOCK_USER_SESSION,
+      id: "abc123",
+      access: "public"
+    })
+      .then(response => {
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://myorg.maps.arcgis.com/sharing/rest/content/users/jsmith/items/abc123/share"
+        );
+        expect(options.method).toBe("POST");
+        expect(response).toEqual(SharingResponse);
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("everyone=true");
+        expect(options.body).toContain("org=true");
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should share an item with an organization", done => {
+    fetchMock.once("*", SharingResponse);
+
+    setItemAccess({
+      authentication: MOCK_USER_SESSION,
+      id: "abc123",
+      access: "org"
+    })
+      .then(response => {
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://myorg.maps.arcgis.com/sharing/rest/content/users/jsmith/items/abc123/share"
+        );
+        expect(options.method).toBe("POST");
+        expect(response).toEqual(SharingResponse);
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("everyone=false");
+        expect(options.body).toContain("org=true");
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should stop sharing an item entirely", done => {
+    fetchMock.once("*", SharingResponse);
+
+    setItemAccess({
+      authentication: MOCK_USER_SESSION,
+      id: "abc123",
+      access: "private"
+    })
+      .then(response => {
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://myorg.maps.arcgis.com/sharing/rest/content/users/jsmith/items/abc123/share"
+        );
+        expect(options.method).toBe("POST");
+        expect(response).toEqual(SharingResponse);
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("everyone=false");
+        expect(options.body).toContain("org=false");
+        expect(options.body).toContain("groups=");
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should share another persons item if an org admin makes the request", done => {
+    fetchMock.once(
+      "https://myorg.maps.arcgis.com/sharing/rest/community/users/jsmith?f=json&token=fake-token",
+      OrgAdminUserResponse
+    );
+
+    fetchMock.once(
+      "begin:https://myorg.maps.arcgis.com/sharing/rest/content/users/casey/items/abc123/share",
+      SharingResponse
+    );
+
+    setItemAccess({
+      authentication: MOCK_USER_SESSION,
+      id: "abc123",
+      access: "private",
+      owner: "casey"
+    })
+      .then(response => {
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall();
+        expect(url).toEqual(
+          "https://myorg.maps.arcgis.com/sharing/rest/content/users/casey/items/abc123/share"
+        );
+        expect(options.method).toBe("POST");
+        expect(response).toEqual(SharingResponse);
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("everyone=false");
+        expect(options.body).toContain("org=false");
+        expect(options.body).toContain("groups=");
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should throw if the person trying to share doesnt own the item and is not an admin", done => {
+    fetchMock.once(
+      "https://myorg.maps.arcgis.com/sharing/rest/community/users/jsmith?f=json&token=fake-token",
+      AnonUserResponse
+    );
+
+    setItemAccess({
+      authentication: MOCK_USER_SESSION,
+      id: "abc123",
+      access: "private",
+      owner: "casey"
+    }).catch(e => {
+      expect(e.message).toEqual(
+        "This item can not be shared by jsmith. They are neither the item owner nor an organization admin."
+      );
+      done();
+    });
+  });
+});