impeditmaiores 1.0.0

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

@@ -0,0 +1,41 @@
+/* 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 { IUserItemOptions, determineOwner } from "./helpers";
+
+/**
+ * Protect an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/protect.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to protect an item.
+ */
+export function protectItem(
+  requestOptions: IUserItemOptions
+): Promise<{ success: boolean }> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/protect`;
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * Unprotect an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/unprotect.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to unprotect an item.
+ */
+export function unprotectItem(
+  requestOptions: IUserItemOptions
+): Promise<{ success: boolean }> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/unprotect`;
+    return request(url, requestOptions);
+  });
+}

package/packages/arcgis-rest-portal/src/items/reassign.ts

@@ -0,0 +1,61 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+import { IItem } from "@esri/arcgis-rest-types";
+import { getPortalUrl } from "../util/get-portal-url";
+import { isOrgAdmin } from "../sharing/helpers";
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+interface IReassignItemOptions extends IUserRequestOptions {
+  id: string;
+  currentOwner: string;
+  targetUsername: string;
+  targetFolderName?: string;
+}
+
+interface IReassignItemResponse {
+  success: boolean;
+  itemId: string;
+}
+
+/**
+ * ```js
+ * import { reassignItem } from '@esri/arcgis-rest-portal';
+ * //
+ * reassignItem({
+ *   id: "abc123",
+ *   currentOwner: "charles",
+ *   targetUsername: "leslie",
+ *   authentication
+ * })
+ * ```
+ * Reassign an item from one user to another.
+ * Caller must be an org admin or the request will fail.
+ * `currentOwner` and `targetUsername` must be in the same
+ * organization or the request will fail
+ * @param reassignOptions - Options for the request
+ */
+export function reassignItem(
+  reassignOptions: IReassignItemOptions
+): Promise<IReassignItemResponse> {
+  return isOrgAdmin(reassignOptions).then(isAdmin => {
+    if (!isAdmin) {
+      throw Error(
+        `Item ${reassignOptions.id} can not be reassigned because current user is not an organization administrator.`
+      );
+    }
+    // we're operating as an org-admin
+    const url = `${getPortalUrl(reassignOptions)}/content/users/${
+      reassignOptions.currentOwner
+    }/items/${reassignOptions.id}/reassign`;
+
+    const opts = {
+      params: {
+        targetUsername: reassignOptions.targetUsername,
+        targetFolderName: reassignOptions.targetFolderName
+      },
+      authentication: reassignOptions.authentication
+    };
+    return request(url, opts);
+  });
+}

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

@@ -0,0 +1,135 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, appendCustomParams } from "@esri/arcgis-rest-request";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  IUserItemOptions,
+  IItemResourceOptions,
+  IFolderIdOptions,
+  determineOwner,
+  IManageItemRelationshipOptions
+} from "./helpers";
+
+/**
+ * ```js
+ * import { removeItem } from "@esri/arcgis-rest-portal";
+ * //
+ * removeItem({
+ *   id: "3ef",
+ *   authentication
+ * })
+ * ```
+ * Delete an item from the portal. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/delete-item.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that deletes an item.
+ */
+export function removeItem(
+  requestOptions: IUserItemOptions
+): Promise<{ success: boolean; itemId: string }> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/delete`;
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { removeItemRelationship } from "@esri/arcgis-rest-portal";
+ * //
+ * removeItemRelationship({
+ *   originItemId: '3ef',
+ *   destinationItemId: 'ae7',
+ *   relationshipType: 'Service2Layer',
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Remove a relationship between two items. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/delete-relationship.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to add item resources.
+ */
+export function removeItemRelationship(
+  requestOptions: IManageItemRelationshipOptions
+): Promise<{ success: boolean }> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(
+      requestOptions
+    )}/content/users/${owner}/deleteRelationship`;
+
+    const options = appendCustomParams<IManageItemRelationshipOptions>(
+      requestOptions,
+      ["originItemId", "destinationItemId", "relationshipType"],
+      { params: { ...requestOptions.params } }
+    );
+
+    return request(url, options);
+  });
+}
+
+/**
+ * Remove a resource associated with an item
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that deletes an item resource.
+ */
+export function removeItemResource(
+  requestOptions: IItemResourceOptions
+): Promise<{ success: boolean }> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/removeResources`;
+
+    // mix in user supplied params
+    requestOptions.params = {
+      ...requestOptions.params,
+      resource: requestOptions.resource
+    };
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { removeFolder } from "@esri/arcgis-rest-portal";
+ * //
+ * removeFolder({
+ *   folderId: "fe4",
+ *   owner: "c@sey",
+ *   authentication
+ * })
+ *   .then(response)
+ *
+ * ```
+ * Delete a non-root folder and all the items it contains. See the [REST
+ * Documentation](https://developers.arcgis.com/rest/users-groups-and-items/delete-folder.htm) for
+ * more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that deletes a folder
+ */
+export function removeFolder(
+  requestOptions: IFolderIdOptions
+): Promise<{
+  success: boolean;
+  folder: {
+    username: string;
+    id: string;
+    title: string;
+  };
+}> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(
+      requestOptions
+    )}/content/users/${encodeURIComponent(owner)}/${
+      requestOptions.folderId
+    }/delete`;
+    return request(url, requestOptions);
+  });
+}

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

@@ -0,0 +1,25 @@
+/* Copyright (c) 2018-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IItem } from "@esri/arcgis-rest-types";
+import { SearchQueryBuilder } from "../util/SearchQueryBuilder";
+import { ISearchOptions, ISearchResult } from "../util/search";
+import { genericSearch } from "../util/generic-search";
+
+/**
+ * ```js
+ * import { searchItems } from "@esri/arcgis-rest-portal";
+ * //
+ * searchItems('water')
+ *   .then(response) // response.total => 355
+ * ```
+ * Search a portal for items. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/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 searchItems(
+  search: string | ISearchOptions | SearchQueryBuilder
+): Promise<ISearchResult<IItem>> {
+  return genericSearch<IItem>(search, "item");
+}

package/packages/arcgis-rest-portal/src/items/update.ts

@@ -0,0 +1,184 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+import { IItemUpdate } from "@esri/arcgis-rest-types";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  ICreateUpdateItemOptions,
+  IMoveItemResponse,
+  IItemInfoOptions,
+  IItemResourceOptions,
+  IItemInfoResponse,
+  IItemResourceResponse,
+  IUpdateItemResponse,
+  serializeItem,
+  determineOwner
+} from "./helpers";
+
+export interface IUpdateItemOptions extends ICreateUpdateItemOptions {
+  item: IItemUpdate;
+}
+
+export interface IMoveItemOptions extends ICreateUpdateItemOptions {
+  /**
+   * Alphanumeric id of item to be moved.
+   */
+  itemId: string;
+  /**
+   * Alphanumeric id of folder to house moved item. If null, empty, or "/", the destination is the
+   * root folder.
+   */
+  folderId?: string;
+}
+
+/**
+ * ```js
+ * import { updateItem } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItem({
+ *   item: {
+ *     id: "3ef",
+ *     description: "A three hour tour"
+ *   },
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update an Item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-item.htm) for more information.
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that updates an item.
+ */
+export function updateItem(
+  requestOptions: IUpdateItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = requestOptions.folderId
+      ? `${getPortalUrl(requestOptions)}/content/users/${owner}/${requestOptions.folderId}/items/${requestOptions.item.id}/update`
+      : `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${requestOptions.item.id}/update`;
+
+    // serialize the item into something Portal will accept
+    requestOptions.params = {
+      ...requestOptions.params,
+      ...serializeItem(requestOptions.item)
+    };
+
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { updateItemInfo } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItemInfo({
+ *   id: '3ef',
+ *   file: file,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update an info file associated with an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-info.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that updates an item info file.
+ */
+export function updateItemInfo(
+  requestOptions: IItemInfoOptions
+): Promise<IItemInfoResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(
+      requestOptions as IRequestOptions
+    )}/content/users/${owner}/items/${requestOptions.id}/updateinfo`;
+
+    // mix in user supplied params
+    requestOptions.params = {
+      folderName: requestOptions.folderName,
+      file: requestOptions.file,
+      ...requestOptions.params
+    };
+
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { updateItemResource } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItemResource({
+ *   id: '3ef',
+ *   resource: file,
+ *   name: 'bigkahuna.jpg',
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update a resource associated with an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-resources.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that updates an item resource.
+ */
+export function updateItemResource(
+  requestOptions: IItemResourceOptions
+): Promise<IItemResourceResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(
+      requestOptions as IRequestOptions
+    )}/content/users/${owner}/items/${requestOptions.id}/updateResources`;
+
+    // mix in user supplied params
+    requestOptions.params = {
+      file: requestOptions.resource,
+      fileName: requestOptions.name,
+      text: requestOptions.content,
+      ...requestOptions.params
+    };
+
+    // only override the access specified previously if 'private' is passed explicitly
+    if (typeof requestOptions.private !== "undefined") {
+      requestOptions.params.access = requestOptions.private
+        ? "private"
+        : "inherit";
+    }
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { moveItem } from "@esri/arcgis-rest-portal";
+ * //
+ * moveItem({
+ *   itemId: "3ef",
+ *   folderId: "7c5",
+ *   authentication: userSession
+ * })
+ * ```
+ * Move an item to a folder. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/move-item.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that resolves with owner and folder details once the move has been completed
+ */
+export function moveItem(
+  requestOptions: IMoveItemOptions
+): Promise<IMoveItemResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.itemId
+    }/move`;
+
+    let folderId = requestOptions.folderId;
+    if (!folderId) {
+      folderId = "/";
+    }
+    requestOptions.params = {
+      folder: folderId,
+      ...requestOptions.params
+    };
+
+    return request(url, requestOptions);
+  });
+}

package/packages/arcgis-rest-portal/src/items/upload.ts

@@ -0,0 +1,125 @@
+/* Copyright (c) 2017-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, appendCustomParams } from "@esri/arcgis-rest-request";
+import { IItemAdd } from "@esri/arcgis-rest-types";
+
+import { getPortalUrl } from "../util/get-portal-url";
+import {
+  IUserItemOptions,
+  IUpdateItemResponse,
+  determineOwner,
+  IItemPartOptions,
+  serializeItem
+} from "./helpers";
+
+export interface ICommitItemOptions extends IUserItemOptions {
+  item: IItemAdd;
+}
+
+/**
+ * ```js
+ * import { addItemPart } from "@esri/arcgis-rest-portal";
+ * //
+ * addItemPart({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   file: data,
+ *   partNum: 1,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Add Item Part allows the caller to upload a file part when doing an add or update item operation in multipart mode. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/add-item-part.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to add the item part status.
+ */
+export function addItemPart(
+  requestOptions?: IItemPartOptions
+): Promise<IUpdateItemResponse> {
+  const partNum = requestOptions.partNum;
+
+  if (!Number.isInteger(partNum) || partNum < 1 || partNum > 10000) {
+    return Promise.reject(new Error('The part number must be an integer between 1 to 10000, inclusive.'))
+  }
+
+  return determineOwner(requestOptions).then(owner => {
+    // AGO adds the "partNum" parameter in the query string, not in the body
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/addPart?partNum=${partNum}`;
+
+    const options = appendCustomParams<IItemPartOptions>(
+      requestOptions,
+      ["file"],
+      { params: { ...requestOptions.params } }
+    );
+
+    return request(url, options);
+  });
+}
+
+/**
+ * ```js
+ * import { commitItemUpload } from "@esri/arcgis-rest-portal";
+ * //
+ * commitItemUpload({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Commit is called once all parts are uploaded during a multipart Add Item or Update Item operation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/commit.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to get the commit result.
+ */
+export function commitItemUpload(
+  requestOptions?: ICommitItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/commit`;
+
+    const options = appendCustomParams<ICommitItemOptions>(
+      requestOptions,
+      [],
+      {
+        params: {
+          ...requestOptions.params,
+          ...serializeItem(requestOptions.item)
+        }
+      }
+    );
+
+    return request(url, options);
+  });
+}
+
+/**
+ * ```js
+ * import { cancelItemUpload } from "@esri/arcgis-rest-portal";
+ * //
+ * cancelItemUpload({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Cancels a multipart upload on an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/cancel.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to get the commit result.
+ */
+export function cancelItemUpload(
+  requestOptions?: IUserItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then(owner => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/cancel`;
+
+    return request(url, requestOptions);
+  });
+}

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

@@ -0,0 +1,131 @@
+import {
+  request,
+  IRequestOptions,
+  ArcGISRequestError
+} from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url";
+import { chunk } from "../util/array";
+
+export interface ICreateOrgNotificationOptions extends IRequestOptions {
+  /**
+   * 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 email or builtin. 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?: string;
+
+  /**
+   * How many emails should be sent at a time. Defaults to the max possible (25)
+   */
+  batchSize?: number
+}
+
+export interface ICreateOrgNotificationResult {
+  /**
+   * Whether the operation was successful
+   */
+  success: boolean;
+  /**
+   * An array of request errors
+   */
+  errors?: ArcGISRequestError[];
+}
+
+/**
+ * Send a notification to members of the requesting user's org.
+ * 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: ['larry', 'curly', 'moe'],
+ *  notificationChannelType: 'email',
+ *  expiration: 20160,
+ *  authentication
+ * }
+ * //
+ * const result = await createOrgNotification(options);
+ * //
+ * const if_success_result_looks_like = {
+ *  success: true
+ * }
+ * //
+ * const if_failure_result_looks_like = {
+ *  success: false,
+ *  errors: [ArcGISRequestError]
+ * }
+ * ```
+ * @param {ICreateOrgNotificationOptions} options
+ *
+ * @returns {ICreateOrgNotificationResult}
+ */
+export function createOrgNotification (options: ICreateOrgNotificationOptions) {
+  const url = `${getPortalUrl(options)}/portals/self/createNotification`;
+  const batches = _generateBatchRequests(options);
+  const promises = batches.map(batch => _sendSafeRequest(url, batch));
+
+  return Promise.all(promises).then(_combineResults);
+}
+
+/**
+ * @private
+ */
+function _generateBatchRequests(options: ICreateOrgNotificationOptions): IRequestOptions[] {
+  const userBatches: string[][] = chunk<string>(options.users, options.batchSize || 25);
+  return userBatches.map(users => _generateRequestOptions(users, options));
+}
+
+/**
+ * @private
+ */
+function _generateRequestOptions(users: string[], baseOptions: ICreateOrgNotificationOptions): IRequestOptions {
+  const requestOptions: ICreateOrgNotificationOptions = Object.assign({}, baseOptions);
+
+  requestOptions.params = {
+    ...requestOptions.params,
+    users,
+    subject: baseOptions.subject,
+    message: baseOptions.message,
+    notificationChannelType: requestOptions.notificationChannelType,
+  }
+  
+  return requestOptions;
+}
+
+/**
+ * @private 
+ */
+function _sendSafeRequest(url: string,requestOptions: IRequestOptions): Promise<ICreateOrgNotificationResult> {
+  return request(url, requestOptions)
+    .catch(error => ({ errors: [error] }));
+}
+
+/**
+ * @private 
+ */
+function _combineResults(responses: ICreateOrgNotificationResult[]): ICreateOrgNotificationResult {
+  const success = responses.every(res => res.success);
+  const errors: ArcGISRequestError[] = responses.reduce((collection, res) => collection.concat(res.errors || []), []);
+  const combined: ICreateOrgNotificationResult = { success };
+
+  if (errors.length > 0) {
+    combined.errors = errors;
+  }
+
+  return combined;
+}
+