feat(portal): add the function to get user tags (#614)

* feat(portal): add a new function to get user tags
* export the function
* rename IUserItemTag to ITagCount

AFFECTS PACKAGES:
@esri/arcgis-rest-portal

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 * New Features
    * **portal**: new functions and parameters to support async and multiple upload during item creation [#611](https://github.com/Esri/arcgis-rest-js/issues/611)
+   * **portal**: `getUserTags` function to get tags used by the given user
 
 ## [2.3.0] - August 8th 2019
 

packages/arcgis-rest-portal/src/index.ts

@@ -22,6 +22,7 @@ export * from "./groups/update";
 export * from "./groups/join";
 
 export * from "./users/get-user";
+export * from "./users/get-user-tags";
 export * from "./users/get-user-url";
 export * from "./users/invitation";
 export * from "./users/notification";

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);
+}

packages/arcgis-rest-portal/test/mocks/users/user-tags.ts

@@ -0,0 +1,5 @@
+import { IGetUserTagsResponse } from "../../../src/users/get-user-tags";
+
+export const UserTagsResponse: IGetUserTagsResponse = {
+  tags: [{ tag: "test", count: 1 }]
+};

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

@@ -0,0 +1,71 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { getUserTags } from "../../src/users/get-user-tags";
+import { UserTagsResponse } from "../mocks/users/user-tags";
+import { encodeParam } from "@esri/arcgis-rest-request";
+import { UserSession } from "@esri/arcgis-rest-auth";
+import * as fetchMock from "fetch-mock";
+
+const TOMORROW = (function() {
+  const now = new Date();
+  now.setDate(now.getDate() + 1);
+  return now;
+})();
+
+describe("users", () => {
+  afterEach(fetchMock.restore);
+
+  describe("getUserTags", () => {
+    const session = new UserSession({
+      username: "c@sey",
+      password: "123456",
+      token: "fake-token",
+      tokenExpires: TOMORROW,
+      portal: "https://myorg.maps.arcgis.com/sharing/rest"
+    });
+
+    it("should make an authenticated request for tags used by a user", done => {
+      fetchMock.once("*", UserTagsResponse);
+
+      getUserTags({ authentication: session })
+        .then(() => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/users/c%40sey/tags"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain("f=json");
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+
+    it("should make an authenticated request for tags used by a different user", done => {
+      fetchMock.once("*", UserTagsResponse);
+
+      getUserTags({
+        username: "jsmith",
+        authentication: session
+      })
+        .then(() => {
+          expect(fetchMock.called()).toEqual(true);
+          const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+          expect(url).toEqual(
+            "https://myorg.maps.arcgis.com/sharing/rest/community/users/jsmith/tags"
+          );
+          expect(options.method).toBe("POST");
+          expect(options.body).toContain("f=json");
+          expect(options.body).toContain(encodeParam("token", "fake-token"));
+          done();
+        })
+        .catch(e => {
+          fail(e);
+        });
+    });
+  });
+});