impeditmaiores 1.0.0

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

@@ -0,0 +1,184 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+import { IPagingParams, IGroup, IItem, IUser } from "@esri/arcgis-rest-types";
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IGroupCategorySchema {
+  categorySchema: IGroupCategory[];
+}
+
+export interface IGroupCategory {
+  title: string;
+  description?: string;
+  categories?: IGroupCategory[];
+}
+
+export interface IGetGroupContentOptions extends IRequestOptions {
+  paging: IPagingParams;
+}
+
+export interface IGroupContentResult {
+  total: number;
+  start: number;
+  num: number;
+  nextStart: number;
+  items: IItem[];
+}
+
+export interface IGroupUsersResult {
+  owner: string;
+  admins: string[];
+  users: string[];
+}
+
+/**
+ * ```js
+ * import { getGroup } from "@esri/arcgis-rest-portal";
+ * //
+ * getGroup("fxb988") // id
+ *   .then(response)
+ * ```
+ * Fetch a group using its id. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/group.htm) for more information.
+ *
+ * @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);
+}
+
+/**
+ * Gets the category schema set on a group
+ *
+ * @param id - Group Id
+ * @param requestOptions  - Options for the request
+ * @returns A promise that will resolve with JSON of group's category schema
+ * @see https://developers.arcgis.com/rest/users-groups-and-items/group-category-schema.htm
+ */
+export function getGroupCategorySchema(
+  id: string,
+  requestOptions?: IRequestOptions
+): Promise<IGroupCategorySchema> {
+  const url = `${getPortalUrl(
+    requestOptions
+  )}/community/groups/${id}/categorySchema`;
+
+  // 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?: IGetGroupContentOptions
+): 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 IGetGroupContentOptions;
+
+  // 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);
+}
+
+export interface ISearchGroupUsersOptions
+  extends IRequestOptions,
+    IPagingParams {
+  name?: string;
+  sortField?: string;
+  sortOrder?: string;
+  joined?: number | number[];
+  memberType?: string;
+  [key: string]: any;
+}
+
+export interface ISearchGroupUsersResult {
+  total: number;
+  start: number;
+  num: number;
+  nextStart: number;
+  owner: IUser;
+  users: any[];
+}
+
+/**
+ * ```js
+ * import { searchGroupUsers } from "@esri/arcgis-rest-portal";
+ * //
+ * searchGroupUsers('abc123')
+ *   .then(response)
+ * ```
+ * Search the users in a group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/group-users-list.htm) for more information.
+ *
+ * @param id - The group id
+ * @param searchOptions - Options for the request, including paging parameters.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function searchGroupUsers(
+  id: string,
+  searchOptions?: ISearchGroupUsersOptions
+): Promise<ISearchGroupUsersResult> {
+  const url = `${getPortalUrl(searchOptions)}/community/groups/${id}/userlist`;
+  const options = appendCustomParams<ISearchGroupUsersOptions>(
+    searchOptions || {},
+    ["name", "num", "start", "sortField", "sortOrder", "joined", "memberType"],
+    {
+      httpMethod: "GET"
+    }
+  );
+  return request(url, options);
+}

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

@@ -0,0 +1,14 @@
+/* Copyright (c) 2017-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+/**
+ * Base options interface for making authenticated requests for groups.
+ */
+export interface IUserGroupOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the group.
+   */
+  id: string;
+}

package/packages/arcgis-rest-portal/src/groups/invite-users.ts

@@ -0,0 +1,127 @@
+import {
+  request,
+  IRequestOptions,
+  ArcGISRequestError
+} from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import { chunk } from "../util/array";
+
+export interface IInviteGroupUsersOptions extends IRequestOptions {
+  /**
+   * Group ID
+   */
+  id: string;
+  /**
+   * An array of usernames to be added to the group as group members
+   */
+  users: string[];
+  /**
+   * What role the users should be invited as ('group_member' | 'group_admin')
+   */
+  role: string;
+  /**
+   * Expiration date on the invitation can be set for one day, three days, one week, or two weeks, in minutes.
+   */
+  expiration: number
+}
+
+export interface IInviteGroupUsersResult {
+  /**
+   * Whether the operation was successful
+   */
+  success: boolean;
+  /**
+   * An array of request errors
+   */
+  errors?: ArcGISRequestError[];
+}
+
+/**
+ * Invites users to join a group. Operation success
+ * will be indicated by a flag on the return
+ * object. If there are any errors, they will be
+ * placed in an errors array on the return object
+ * 
+ * ```js
+ * const authentication: IAuthenticationManager; // Typically passed into to the function
+ * //
+ * const options: IInviteGroupUsersOptions = {
+ *  id: 'group_id',
+ *  users: ['ed', 'edd', 'eddy'],
+ *  role: 'group-member',
+ *  expiration: 20160,
+ *  authentication
+ * }
+ * //
+ * const result = await inviteGroupUsers(options);
+ * //
+ * const if_success_result_looks_like = {
+ *  success: true
+ * }
+ * //
+ * const if_failure_result_looks_like = {
+ *  success: false,
+ *  errors: [ArcGISRequestError]
+ * }
+ * ```
+ * @param {IInviteGroupUsersOptions} options
+ *
+ * @returns {Promise<IAddGroupUsersResult>} 
+ */
+export function inviteGroupUsers(options: IInviteGroupUsersOptions): Promise<IInviteGroupUsersResult> {
+  const id = options.id;
+  const url = `${getPortalUrl(options)}/community/groups/${id}/invite`;
+  const batches = _generateBatchRequests(options);
+  const promises = batches.map(batch => _sendSafeRequest(url, batch));
+
+  return Promise.all(promises).then(_combineResults);
+}
+
+/**
+ * @private
+ */
+function _generateBatchRequests(options: IInviteGroupUsersOptions) {
+  const userBatches: string[][] = chunk<string>(options.users, 25);
+  return userBatches.map(users => _generateRequestOptions(users, options));
+}
+
+/**
+ * @private
+ */
+function _generateRequestOptions(users: string[], baseOptions: IInviteGroupUsersOptions): IRequestOptions {
+  const requestOptions: IInviteGroupUsersOptions = Object.assign({}, baseOptions);
+
+  requestOptions.params = {
+    ...requestOptions.params,
+    users,
+    role: requestOptions.role,
+    expiration: requestOptions.expiration,
+  }
+  
+  return requestOptions;
+}
+
+/**
+ * @private 
+ */
+function _sendSafeRequest(url: string,requestOptions: IRequestOptions): Promise<IInviteGroupUsersResult> {
+  return request(url, requestOptions)
+    .catch(error => ({ errors: [error] }));
+}
+
+/**
+ * @private 
+ */
+function _combineResults(responses: IInviteGroupUsersResult[]): IInviteGroupUsersResult {
+  const success = responses.every(res => res.success);
+  const errors: ArcGISRequestError[] = responses.reduce((collection, res) => collection.concat(res.errors || []), []);
+  const combined: IInviteGroupUsersResult = { success };
+
+  if (errors.length > 0) {
+    combined.errors = errors;
+  }
+
+  return combined;
+}
+

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

@@ -0,0 +1,57 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import { IUserGroupOptions } from "./helpers";
+
+/**
+ * ```js
+ * import { joinGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * joinGroup({
+ *   id: groupId,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Make a request as the authenticated user to join a Group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/join-group.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request and the groupId.
+ */
+export function joinGroup(
+  requestOptions: IUserGroupOptions
+): Promise<{ success: boolean; groupId: string }> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/join`;
+
+  return request(url, requestOptions);
+}
+
+/**
+ * ```js
+ * import { leaveGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * leaveGroup({
+ *   id: groupId,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Make a request as the authenticated user to leave a Group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/leave-group.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request and the groupId.
+ */
+export function leaveGroup(
+  requestOptions: IUserGroupOptions
+): Promise<{ success: boolean; groupId: string }> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/leave`;
+
+  return request(url, requestOptions);
+}

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

@@ -0,0 +1,77 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IUserGroupOptions } from "./helpers";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export type NotificationChannelType = "push" | "email" | "builtin";
+
+export interface ICreateGroupNotificationOptions extends IUserGroupOptions {
+  /**
+   * Subject of the notification. This only applies to email and builtin notifications. For push notifications, subject/title is provided as a part of the message payload.
+   */
+  subject?: string;
+  /**
+   * Message to be sent. For builtin and email notifications this is a string. For push notifications, this will be JSON.
+   */
+  message: string | object;
+  /**
+   * Array of usernames of the users in the group to whom the message should be sent. If not provided, the message will be sent to all users in the group if the user is an admin. Only group admins will be able to send notifications to a list of users. Group users will be able to send notifications to only one user at a time.
+   */
+  users?: string[];
+  /**
+   * The channel through which the notification is to be delivered. Supported values are push, email, or builtin. If push is chosen, a message will be delivered only to those group members that have registered their devices to receive push notifications. If the user has registered more than one device for the app, then message will be sent to all the registered devices. Email will be sent when the email option is chosen. If the builtin option is chosen, a notification will be added to the notifications list that the user can see when logged into the home app.
+   */
+  notificationChannelType?: NotificationChannelType;
+  /**
+   * ClientId of the application through which user receives messages on the mobile device. This only applies to push notifications.
+   */
+  clientId?: string;
+  /**
+   * This only applies to push notifications. When set to true, message will be delivered to the app and it will not show as an alert to the user.
+   */
+  silentNotification?: boolean;
+}
+
+/**
+ * ```js
+ * import { createGroupNotification } from '@esri/arcgis-rest-portal';
+ * // send an email to an entire group
+ * createGroupNotification({
+ *   authentication: UserSession,
+ *   subject: "hello",
+ *   message: "world!",
+ *   id: groupId
+ * })
+ * ```
+ * Create a group notification.
+ *
+ * @param requestOptions - Options for the request
+ *
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function createGroupNotification(
+  requestOptions: ICreateGroupNotificationOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/createNotification`;
+
+  const options: ICreateGroupNotificationOptions = {
+    params: {
+      subject: requestOptions.subject,
+      message: requestOptions.message,
+      users: requestOptions.users,
+      notificationChannelType:
+        requestOptions.notificationChannelType || "email",
+      clientId: requestOptions.clientId,
+      silentNotification: requestOptions.silentNotification,
+      notifyAll: !requestOptions.users || requestOptions.users.length === 0,
+      ...requestOptions.params
+    },
+    ...requestOptions
+  };
+  return request(url, options);
+}

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

@@ -0,0 +1,56 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import { IUserGroupOptions } from "./helpers";
+
+/**
+ * ```js
+ * import { protectGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * protectGroup({
+ *   id: groupId,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Protect a group to avoid accidental deletion. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/protect-group.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 protectGroup(
+  requestOptions: IUserGroupOptions
+): Promise<{ success: boolean }> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/protect`;
+
+  return request(url, requestOptions);
+}
+
+/**
+ * ```js
+ * import { unprotectGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * unprotectGroup({
+ *   id: groupId,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Unprotect a Group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/unprotect-group.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 unprotectGroup(
+  requestOptions: IUserGroupOptions
+): Promise<{ success: boolean }> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/unprotect`;
+
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/groups/remove-users.ts

@@ -0,0 +1,76 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IRequestOptions,
+  ArcGISRequestError
+} from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url";
+import { chunk } from "../util/array";
+
+export interface IRemoveGroupUsersOptions extends IRequestOptions {
+  /**
+   * Group ID
+   */
+  id: string;
+  /**
+   * An array of usernames to be removed from the group
+   */
+  users?: string[];
+}
+
+export interface IRemoveGroupUsersResult {
+  /**
+   * An array of usernames that were not removed
+   */
+  notRemoved?: string[];
+  /**
+   * An array of request errors
+   */
+  errors?: ArcGISRequestError[];
+}
+
+/**
+ * ```js
+ * import { removeGroupUsers } from "@esri/arcgis-rest-portal";
+ * //
+ * removeGroupUsers({
+ *   id: groupId,
+ *   users: ["username1", "username2"],
+ *   authentication
+ * })
+ * .then(response);
+ * ```
+ * Add users to a group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/remove-users-from-group.htm) for more information.
+ *
+ * @param requestOptions  - Options for the request
+ * @returns A Promise
+ */
+export function removeGroupUsers (
+  requestOptions: IRemoveGroupUsersOptions
+): Promise<IRemoveGroupUsersResult> {
+  const { id, users: usersToRemove } = requestOptions;
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${id}/removeUsers`;
+  const safeSend = (users: string[]) => {
+    const options: IRemoveGroupUsersOptions = {
+      ...requestOptions,
+      users,
+      params: { users }
+    };
+    return request(url, options)
+      .catch(error => ({ errors: [error] }));
+  };
+  // the ArcGIS REST API only allows to add no more than 25 users per request,
+  // see https://developers.arcgis.com/rest/users-groups-and-items/remove-users-from-group.htm
+  const promises = chunk(usersToRemove, 25).map(usersChunk => safeSend(usersChunk));
+  return Promise.all(promises)
+    .then(results => {
+      const filtered = (propName: string) => results
+        .filter(result => result[propName])
+        .reduce((collection, result) => collection.concat(result[propName]), []);
+      const errors = filtered('errors');
+      const consolidated: IRemoveGroupUsersResult = { notRemoved: filtered('notRemoved') };
+      return errors.length ? { ...consolidated, errors } : consolidated;
+    });
+}

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

@@ -0,0 +1,32 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import { IUserGroupOptions } from "./helpers";
+
+/**
+ * ```js
+ * import { removeGroup } from '@esri/arcgis-rest-portal';
+ * //
+ * removeGroup({
+ *   id: groupId,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Delete a group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/delete-group.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 removeGroup(requestOptions: IUserGroupOptions): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/community/groups/${
+    requestOptions.id
+  }/delete`;
+  const options: IUserGroupOptions = {
+    ...requestOptions
+  };
+  return request(url, options);
+}

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

@@ -0,0 +1,47 @@
+/* Copyright (c) 2018-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IItem, IGroup } from "@esri/arcgis-rest-types";
+import { SearchQueryBuilder } from "../util/SearchQueryBuilder";
+import {
+  ISearchOptions,
+  ISearchGroupContentOptions,
+  ISearchResult
+} from "../util/search";
+import { genericSearch } from "../util/generic-search";
+
+/**
+ * ```js
+ * import { searchGroups } from "@esri/arcgis-rest-portal";
+ * //
+ * searchGroups('water')
+ *   .then(response) // response.total => 355
+ * ```
+ * Search a portal for groups. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/group-search.htm) for more information.
+ *
+ * @param search - A string or RequestOptions object to pass through to the endpoint.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function searchGroups(
+  search: string | ISearchOptions | SearchQueryBuilder
+): Promise<ISearchResult<IGroup>> {
+  return genericSearch<IGroup>(search, "group");
+}
+
+/**
+ * ```js
+ * import { searchGroupContent } from "@esri/arcgis-rest-portal";
+ * //
+ * searchGroupContent('water')
+ *   .then(response) // response.total => 355
+ * ```
+ * Search a portal for items in a group. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/group-content-search.htm) for more information.
+ *
+ * @param options - RequestOptions object amended with search parameters.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function searchGroupContent(
+  options: ISearchGroupContentOptions
+): Promise<ISearchResult<IItem>> {
+  return genericSearch<IItem>(options, "groupContent");
+}