Adding a group module and a few more utility portal methods

.gitignore

@@ -78,3 +78,6 @@ packages/*/debug/
 
 # no idea
 /packages/*/.rpt2_cache
+
+# packages in development
+packages/arcgis-rest-portal/

packages/arcgis-rest-common-types/src/index.ts

@@ -28,3 +28,33 @@ export interface IPoint {
   y: number;
   spatialReference?: ISpatialReference;
 }
+
+/**
+ * Params for paging operations
+ */
+export interface IPagingParams {
+  start?: number;
+  num?: number;
+}
+
+/**
+ * Portal Item
+ */
+export interface IItem {
+  id?: string;
+  owner: string;
+  title: string;
+  type: string;
+  tags: string[];
+  typeKeywords: string[];
+  description?: string;
+  snippet?: string;
+  documentation?: string;
+  extent?: number[][];
+  categories?: string[];
+  spatialReference?: any;
+  culture?: string;
+  properties?: any;
+  url?: string;
+  [key: string]: any;
+}

packages/arcgis-rest-groups/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@esri/arcgis-rest-groups",
+  "version": "1.0.0",
+  "description": "Portal Group helpers for @esri/arcgis-rest-request",
+  "main": "dist/node/index.js",
+  "browser": "dist/browser/arcgis-rest-groups.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "tslib": "^1.7.1"
+  },
+  "peerDependencies": {
+    "@esri/arcgis-rest-request": "^1.0.0",
+    "@esri/arcgis-rest-auth": "^1.0.0",
+    "@esri/arcgis-rest-common-types": "^1.0.0"
+  },
+  "devDependencies": {
+    "@esri/arcgis-rest-request": "^1.0.0",
+    "@esri/arcgis-rest-auth": "^1.0.0",
+    "@esri/arcgis-rest-common-types": "^1.0.0"
+  },
+  "scripts": {
+    "prepublish": "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 ../../rollup.config.umd.js",
+    "build:node": "tsc -p ./tsconfig.json --module commonjs --outDir ./dist/node"
+  },
+  "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"
+}

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

@@ -0,0 +1,268 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+import {
+  request,
+  IRequestOptions,
+  IParams,
+  getPortalUrl
+} from "@esri/arcgis-rest-request";
+
+import { IPagingParams, IItem } from "@esri/arcgis-rest-common-types";
+
+export interface IGroup {
+  id?: string;
+  owner: string;
+  title: string;
+  tags: string[];
+  description?: string;
+  categories?: string[];
+  culture?: string;
+  [key: string]: any;
+}
+
+export interface IGroupSearchRequest extends IPagingParams {
+  q: string;
+  sortField?: string;
+  sortOrder?: string;
+  [key: string]: any;
+}
+
+export interface IGroupSearchResult {
+  query: string; // matches the api's form param
+  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 request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+
+  // send the request
+  return request(url, searchForm, 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, null, 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 requestParams - Paging parameters 
+ * @param requestOptions  - Options for the request
+ * @returns  A Promise that will resolve with the content of the group.
+ */
+export function getGroupContent(
+  id: string,
+  requestParams?: IPagingParams,
+  requestOptions?: IRequestOptions
+): Promise<IGroup> {
+  const url = `${getPortalUrl(requestOptions)}/content/groups/${id}`;
+  const params: IPagingParams = {
+    ...{ start: 1, num: 100 },
+    ...requestParams
+  };
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+  return request(url, params, 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, null, options);
+}
+
+/**
+ * Serialize an group into a json format accepted by the Portal API
+ * for create and update operations
+ * 
+ * @param item IGroup to be serialized
+ * @returns a formatted json object to be sent to Portal
+ */
+function serializeGroup(group: 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;
+}
+
+/**
+ * Create a new Group. 
+ * Note: The name must be unique within the user's organization.
+ * @param group - Group to create
+ * @param requestOptions  - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function createGroup(
+  group: IGroup,
+  requestOptions: IRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/createGroup`;
+  // default to a POST request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "POST" },
+    ...requestOptions
+  };
+  // serialize the group into something Portal will accept
+  const requestParams = serializeGroup(group);
+  return request(url, requestParams, options);
+}
+
+/**
+ * Update the properties of a group - title, tags etc.
+ * @param group - Group to update
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function updateGroup(
+  group: IGroup,
+  requestOptions: IRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(
+    requestOptions
+  )}/community/groups/${group.id}/update`;
+  // default to a POST request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "POST" },
+    ...requestOptions
+  };
+  // serialize the group into something Portal will accept
+  const requestParams = serializeGroup(group);
+  return request(url, requestParams, options);
+}
+
+/**
+ * Delete a group.
+ * @param id - Group Id 
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function removeGroup(
+  id: string,
+  requestOptions: IRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${id}/delete`;
+  // default to a POST request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "POST" },
+    ...requestOptions
+  };
+  return request(url, null, options);
+}
+
+/**
+ * Protect a Group. This simply means a user must unprotect the group prior to deleting it
+ * @param id - Group Id
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function protectGroup(
+  id: string,
+  requestOptions: IRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${id}/protect`;
+  // default to a POST request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "POST" },
+    ...requestOptions
+  };
+  return request(url, null, options);
+}
+
+/**
+ * Unprotect a Group.
+ * @param id - Group Id
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function unprotectGroup(
+  id: string,
+  requestOptions: IRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(
+    requestOptions
+  )}/community/groups/${id}/unprotect`;
+  // default to a POST request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "POST" },
+    ...requestOptions
+  };
+  return request(url, null, options);
+}

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

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