etincidunt 1.0.0

package/packages/arcgis-rest-groups/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@esri/arcgis-rest-groups",
+  "version": "1.6.0",
+  "description": "Portal Group helpers for @esri/arcgis-rest-request",
+  "main": "dist/node/index.js",
+  "browser": "dist/umd/groups.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "license": "Apache-2.0",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "tslib": "^1.7.1"
+  },
+  "peerDependencies": {
+    "@esri/arcgis-rest-auth": "^1.5.1",
+    "@esri/arcgis-rest-common-types": "^1.5.1",
+    "@esri/arcgis-rest-request": "^1.5.1"
+  },
+  "devDependencies": {
+    "@esri/arcgis-rest-auth": "^1.6.0",
+    "@esri/arcgis-rest-common-types": "^1.6.0",
+    "@esri/arcgis-rest-request": "^1.6.0"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "npm run build:node && npm run build:umd && npm run build:esm",
+    "build:esm": "tsc -p ./tsconfig.json --module es2015 --outDir ./dist/esm --declaration",
+    "build:umd": "rollup -c ../../umd-base-profile.js && rollup -c ../../umd-production-profile.js",
+    "build:node": "tsc -p ./tsconfig.json --module commonjs --outDir ./dist/node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esri/arcgis-rest-js.git"
+  },
+  "contributors": [
+    {
+      "name": "Dave Bouwman",
+      "email": "dbouwman@esri.com",
+      "url": "http://blog.davebouwman.com/"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/Esri/arcgis-rest-js/issues"
+  },
+  "homepage": "https://github.com/Esri/arcgis-rest-js#readme"
+}

package/packages/arcgis-rest-groups/src/groups.ts

@@ -0,0 +1,272 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  // IParams,
+  getPortalUrl
+} from "@esri/arcgis-rest-request";
+
+import {
+  IPagingParams,
+  IItem,
+  IItemUpdate,
+  IGroupAdd,
+  IGroup
+} from "@esri/arcgis-rest-common-types";
+
+export interface IPagingParamsRequestOptions extends IRequestOptions {
+  paging: IPagingParams;
+}
+
+export interface IGroupIdRequestOptions extends IRequestOptions {
+  id: string;
+}
+
+export interface IGroupAddRequestOptions extends IRequestOptions {
+  group: IGroupAdd;
+}
+
+export interface IGroupUpdateRequestOptions extends IRequestOptions {
+  group: IItemUpdate;
+}
+
+export interface IGroupSearchRequest extends IPagingParams {
+  q: string;
+  sortField?: string;
+  sortOrder?: string;
+  [key: string]: any;
+}
+
+export interface IGroupSearchResult {
+  /**
+   * Matches the REST APIs form param
+   */
+  query: string;
+  total: number;
+  start: number;
+  num: number;
+  nextStart: number;
+  results: IGroup[];
+}
+
+export interface IGroupContentResult {
+  total: number;
+  start: number;
+  num: number;
+  nextStart: number;
+  items: IItem[];
+}
+
+export interface IGroupUsersResult {
+  owner: string;
+  admins: string[];
+  users: string[];
+}
+
+/**
+ * Search for groups via the portal api
+ *
+ * ```js
+ * import { searchGroups } from '@esri/arcgis-rest-groups';
+ *
+ * searchgroups({q:'water'})
+ * .then((results) => {
+ *  console.log(response.results.total); // 355
+ * })
+ * ```
+ *
+ * @param searchForm - Search request
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function searchGroups(
+  searchForm: IGroupSearchRequest,
+  requestOptions?: IRequestOptions
+): Promise<IGroupSearchResult> {
+  // construct the search url
+  const url = `${getPortalUrl(requestOptions)}/community/groups`;
+
+  // default to a GET
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+
+  options.params = { ...searchForm };
+
+  // send the request
+  return request(url, options);
+}
+
+/**
+ *
+ * @param id - Group Id
+ * @param requestOptions  - Options for the request
+ * @returns  A Promise that will resolve with the data from the response.
+ */
+export function getGroup(
+  id: string,
+  requestOptions?: IRequestOptions
+): Promise<IGroup> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${id}`;
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Returns the content of a Group. Since the group may contain 1000s of items
+ * the requestParams allow for paging.
+ * @param id - Group Id
+ * @param requestOptions  - Options for the request, including paging parameters.
+ * @returns  A Promise that will resolve with the content of the group.
+ */
+export function getGroupContent(
+  id: string,
+  requestOptions?: IPagingParamsRequestOptions
+): Promise<IGroup> {
+  const url = `${getPortalUrl(requestOptions)}/content/groups/${id}`;
+
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    params: { start: 1, num: 100 },
+    ...requestOptions
+  } as IPagingParamsRequestOptions;
+
+  // is this the most concise way to mixin with the defaults above?
+  if (requestOptions && requestOptions.paging) {
+    options.params = { ...requestOptions.paging };
+  }
+
+  return request(url, options);
+}
+
+/**
+ * Get the usernames of the admins and members. Does not return actual 'User' objects. Those must be
+ * retrieved via separate calls to the User's API.
+ * @param id - Group Id
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with arrays of the group admin usernames and the member usernames
+ */
+export function getGroupUsers(
+  id: string,
+  requestOptions?: IRequestOptions
+): Promise<IGroupUsersResult> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${id}/users`;
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Create a new Group.
+ * Note: The group name must be unique within the user's organization.
+ * @param requestOptions  - Options for the request, including a group object
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function createGroup(
+  requestOptions: IGroupAddRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/createGroup`;
+  const options: IGroupAddRequestOptions = {
+    ...requestOptions
+  };
+  // serialize the group into something Portal will accept
+  options.params = serializeGroup(requestOptions.group);
+  return request(url, options);
+}
+
+/**
+ * Update the properties of a group - title, tags etc.
+ * @param requestOptions - Options for the request, including the group
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function updateGroup(
+  requestOptions: IGroupUpdateRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.group.id
+  }/update`;
+
+  const options: IGroupUpdateRequestOptions = {
+    ...requestOptions
+  };
+  // serialize the group into something Portal will accept
+  options.params = serializeGroup(requestOptions.group);
+  return request(url, options);
+}
+
+/**
+ * Delete a group.
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function removeGroup(
+  requestOptions: IGroupIdRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/delete`;
+  const options: IGroupIdRequestOptions = {
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Protect a Group. This simply means a user must unprotect the group prior to deleting it
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function protectGroup(
+  requestOptions: IGroupIdRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/protect`;
+  const options: IGroupIdRequestOptions = {
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Unprotect a Group.
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function unprotectGroup(
+  requestOptions: IGroupIdRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/unprotect`;
+  const options: IGroupIdRequestOptions = {
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Serialize a group into a json format accepted by the Portal API
+ * for create and update operations
+ *
+ * @param group IGroup to be serialized
+ * @returns a formatted JSON object to be sent to Portal
+ */
+function serializeGroup(group: IGroupAdd | IItemUpdate | IGroup): any {
+  // create a clone so we're not messing with the original
+  const clone = JSON.parse(JSON.stringify(group));
+  // join and tags...
+  clone.tags = clone.tags.join(", ");
+  return clone;
+}

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

@@ -0,0 +1 @@
+export * from "./groups";

package/packages/arcgis-rest-groups/test/groups.test.ts

@@ -0,0 +1,280 @@
+import {
+  searchGroups,
+  getGroup,
+  getGroupContent,
+  getGroupUsers,
+  createGroup,
+  updateGroup,
+  removeGroup,
+  protectGroup,
+  unprotectGroup
+} from "../src/index";
+
+import {
+  GroupSearchResponse,
+  GroupEditResponse,
+  GroupResponse,
+  GroupContentResponse,
+  GroupUsersResponse
+} from "./mocks/responses";
+import { encodeParam } from "@esri/arcgis-rest-request";
+import * as fetchMock from "fetch-mock";
+
+describe("groups", () => {
+  afterEach(fetchMock.restore);
+
+  describe("searchGroups", () => {
+    it("should make a simple, unauthenticated group search request", done => {
+      fetchMock.once("*", GroupSearchResponse);
+
+      searchGroups({ q: "water" })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://www.arcgis.com/sharing/rest/community/groups?f=json&q=water"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+
+    it("should take num, start, sortField, sortOrder and construct the request", done => {
+      fetchMock.once("*", GroupSearchResponse);
+      searchGroups({
+        q: "water",
+        start: 4,
+        num: 7,
+        sortField: "owner",
+        sortOrder: "desc"
+      })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://www.arcgis.com/sharing/rest/community/groups?f=json&q=water&start=4&num=7&sortField=owner&sortOrder=desc"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+  });
+  describe("getGroup", () => {
+    it("should return a group", done => {
+      fetchMock.once("*", GroupResponse);
+      getGroup("3ef")
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://www.arcgis.com/sharing/rest/community/groups/3ef?f=json"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+  });
+  describe("getGroupContent", () => {
+    it("should return group content", done => {
+      fetchMock.once("*", GroupContentResponse);
+      getGroupContent("3ef")
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://www.arcgis.com/sharing/rest/content/groups/3ef?f=json&start=1&num=100"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should return group content, paged", done => {
+      fetchMock.once("*", GroupContentResponse);
+      getGroupContent("3ef", { paging: { start: 4, num: 7 } })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://www.arcgis.com/sharing/rest/content/groups/3ef?f=json&start=4&num=7"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+  });
+
+  describe("authenticted methods", () => {
+    const MOCK_AUTH = {
+      getToken() {
+        return Promise.resolve("fake-token");
+      },
+      portal: "https://myorg.maps.arcgis.com/sharing/rest"
+    };
+    const MOCK_REQOPTS = {
+      authentication: MOCK_AUTH
+    };
+
+    it("should make a simple, authenticated group search request", done => {
+      fetchMock.once("*", GroupSearchResponse);
+
+      searchGroups({ q: "water" }, MOCK_REQOPTS)
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups?f=json&q=water&token=fake-token"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should create a group", done => {
+      fetchMock.once("*", GroupEditResponse);
+      const fakeGroup = {
+        title: "fake group",
+        owner: "fakeUser",
+        tags: ["foo", "bar"],
+        description: "my fake group"
+      };
+      createGroup({ group: fakeGroup, ...MOCK_REQOPTS })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/createGroup"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain(encodeParam("f", "json"));
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          expect(options.body).toContain(encodeParam("owner", "fakeUser"));
+          // ensure the array props are serialized into strings
+          expect(options.body).toContain(encodeParam("tags", "foo, bar"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should update a group", done => {
+      fetchMock.once("*", GroupEditResponse);
+      const fakeGroup = {
+        id: "5bc",
+        title: "fake group",
+        owner: "fakeUser",
+        tags: ["foo", "bar"],
+        description: "my fake group"
+      };
+      updateGroup({ group: fakeGroup, ...MOCK_REQOPTS })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups/5bc/update"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain(encodeParam("f", "json"));
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          expect(options.body).toContain(encodeParam("owner", "fakeUser"));
+          // ensure the array props are serialized into strings
+          expect(options.body).toContain(encodeParam("tags", "foo, bar"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should remove a group", done => {
+      fetchMock.once("*", GroupEditResponse);
+
+      removeGroup({ id: "5bc", ...MOCK_REQOPTS })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups/5bc/delete"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain(encodeParam("f", "json"));
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should protect a group", done => {
+      fetchMock.once("*", GroupEditResponse);
+
+      protectGroup({ id: "5bc", ...MOCK_REQOPTS })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups/5bc/protect"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain(encodeParam("f", "json"));
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should unprotect a group", done => {
+      fetchMock.once("*", GroupEditResponse);
+
+      unprotectGroup({ id: "5bc", ...MOCK_REQOPTS })
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups/5bc/unprotect"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain(encodeParam("f", "json"));
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    it("should return group users", done => {
+      fetchMock.once("*", GroupUsersResponse);
+
+      getGroupUsers("5bc", MOCK_REQOPTS)
+        .then(response => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/groups/5bc/users?f=json&token=fake-token"
+          );
+          expect(options.method).toBe("GET");
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+    // it('should make authenticated call to get the group content', done => {})
+  });
+});