aspernaturalias 1.0.0

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

@@ -0,0 +1,193 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+import { IItemAdd, IItemUpdate, IItem } from "@esri/arcgis-rest-types";
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+/**
+ * Base options interface for making authenticated requests for items.
+ */
+export interface IUserItemOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the item.
+   */
+  id: string;
+  /**
+   * Item owner username. If not present, `authentication.username` is utilized.
+   */
+  owner?: string;
+}
+
+export interface IFolderIdOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the folder.
+   */
+  folderId: string;
+  /**
+   * Item owner username. If not present, `authentication.username` is utilized.
+   */
+  owner?: string;
+}
+
+export type ItemRelationshipType =
+  | "Map2Service"
+  | "WMA2Code"
+  | "Map2FeatureCollection"
+  | "MobileApp2Code"
+  | "Service2Data"
+  | "Service2Service"
+  | "Map2AppConfig"
+  | "Item2Attachment"
+  | "Item2Report"
+  | "Listed2Provisioned"
+  | "Style2Style"
+  | "Service2Style"
+  | "Survey2Service"
+  | "Survey2Data"
+  | "Service2Route"
+  | "Area2Package"
+  | "Map2Area"
+  | "Service2Layer"
+  | "Area2CustomPackage";
+
+export interface IItemRelationshipOptions extends IRequestOptions {
+  /**
+   * Unique identifier of the item.
+   */
+  id: string;
+  /**
+   * The type of relationship between the two items.
+   */
+  relationshipType: ItemRelationshipType | ItemRelationshipType[];
+  /**
+   * The direction of the relationship. Either forward (from origin -> destination) or reverse (from destination -> origin).
+   */
+  direction?: "forward" | "reverse";
+}
+
+export interface IManageItemRelationshipOptions extends IUserRequestOptions {
+  originItemId: string;
+  destinationItemId: string;
+  relationshipType: ItemRelationshipType;
+}
+
+export interface IItemResourceOptions extends IUserItemOptions {
+  /**
+   * New resource filename.
+   */
+  name?: string;
+  /**
+   * Text input to be added as a file resource.
+   */
+  content?: string;
+  /**
+   * Controls whether access to the file resource is restricted to the owner or inherited from the sharing permissions set for the associated item.
+   */
+  private?: boolean;
+  /**
+   * Object to store
+   */
+  resource?: any;
+}
+
+export interface ICreateUpdateItemOptions extends IUserRequestOptions {
+  /**
+   * The owner of the item. If this property is not present, `item.owner` will be passed, or lastly `authentication.username`.
+   */
+  owner?: string;
+  /**
+   * Id of the folder to house the item.
+   */
+  folderId?: string;
+}
+
+export interface IItemDataOptions extends IRequestOptions {
+  /**
+   * Used to request binary data.
+   */
+  file?: boolean;
+}
+
+export interface IUpdateItemResponse {
+  success: boolean;
+  id: string;
+}
+
+export interface IItemResourceResponse {
+  success: boolean;
+  itemId: string;
+  owner: string;
+  folder: string;
+}
+
+export interface IAddFolderResponse {
+  /**
+   * Success or failure of request.
+   */
+  success: boolean;
+  /**
+   * Information about created folder: its alphanumeric id, name, and owner's name.
+   */
+  folder: {
+    id: string;
+    title: string;
+    username: string;
+  };
+}
+
+export interface IMoveItemResponse {
+  /**
+   * Success or failure of request.
+   */
+  success: boolean;
+  /**
+   * Alphanumeric id of moved item.
+   */
+  itemId: string;
+  /**
+   * Name of owner of item.
+   */
+  owner: string;
+  /**
+   * Alphanumeric id of folder now housing item.
+   */
+  folder: string;
+}
+
+/**
+ * Serialize an item and its data into a json format accepted by the Portal API for create and update operations
+ *
+ * @param item Item to be serialized
+ * @returns a formatted json object to be sent to Portal
+ */
+export function serializeItem(item: IItemAdd | IItemUpdate | IItem): any {
+  // create a clone so we're not messing with the original
+  const clone = JSON.parse(JSON.stringify(item));
+
+  // binary data needs POSTed as a `file`
+  // JSON object literals should be passed as `text`.
+  if (clone.data) {
+    (typeof Blob !== "undefined" && item.data instanceof Blob) ||
+    // Node.js doesn't implement Blob
+    item.data.constructor.name === "ReadStream"
+      ? (clone.file = item.data)
+      : (clone.text = item.data);
+    delete clone.data;
+  }
+  return clone;
+}
+
+/**
+ * requestOptions.owner is given priority, requestOptions.item.owner will be checked next. If neither are present, authentication.username will be assumed.
+ */
+export function determineOwner(requestOptions: any): string {
+  if (requestOptions.owner) {
+    return requestOptions.owner;
+  }
+  if (requestOptions.item && requestOptions.item.owner) {
+    return requestOptions.item.owner;
+  } else {
+    return requestOptions.authentication.username;
+  }
+}

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

@@ -0,0 +1,39 @@
+/* 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 }> {
+  const owner = determineOwner(requestOptions);
+  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 }> {
+  const owner = determineOwner(requestOptions);
+  const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+    requestOptions.id
+  }/unprotect`;
+  return request(url, requestOptions);
+}

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

@@ -0,0 +1,131 @@
+/* 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 }> {
+  const owner = determineOwner(requestOptions);
+  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 }> {
+  const owner = determineOwner(requestOptions);
+  const url = `${getPortalUrl(
+    requestOptions
+  )}/content/users/${owner}/removeRelationship`;
+
+  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 }> {
+  const owner = determineOwner(requestOptions);
+  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;
+  };
+}> {
+  const owner = determineOwner(requestOptions);
+  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,145 @@
+/* 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,
+  IItemResourceOptions,
+  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 item - The item to update.
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that updates an item.
+ */
+export function updateItem(
+  requestOptions: IUpdateItemOptions
+): Promise<IUpdateItemResponse> {
+  const owner = determineOwner(requestOptions);
+  const url = `${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 { 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> {
+  const owner = determineOwner(requestOptions);
+  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> {
+  const owner = determineOwner(requestOptions);
+  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/sharing/access.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import {
+  ISharingOptions,
+  ISharingResponse,
+  isItemOwner,
+  getSharingUrl,
+  isOrgAdmin
+} from "./helpers";
+
+export interface ISetAccessOptions extends ISharingOptions {
+  /**
+   * "private" indicates that the item can only be accessed by the user. "public" means accessible to anyone. An item shared to the organization has an access level of "org".
+   */
+  access: "private" | "org" | "public";
+}
+
+/**
+ * ```js
+ * import { setItemAccess } from "@esri/arcgis-rest-portal";
+ * //
+ * setItemAccess({
+ *   id: "abc123",
+ *   access: "public", // 'org' || 'private'
+ *   authentication: session
+ * })
+ * ```
+ * Change who is able to access an item.
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function setItemAccess(
+  requestOptions: ISetAccessOptions
+): Promise<ISharingResponse> {
+  const url = getSharingUrl(requestOptions);
+
+  if (isItemOwner(requestOptions)) {
+    // if the user owns the item, proceed
+    return updateItemAccess(url, requestOptions);
+  } else {
+    // otherwise we need to check to see if they are an organization admin
+    return isOrgAdmin(requestOptions).then(admin => {
+      if (admin) {
+        return updateItemAccess(url, requestOptions);
+      } else {
+        // if neither, updating the sharing isnt possible
+        throw Error(
+          `This item can not be shared by ${
+            requestOptions.authentication.username
+          }. They are neither the item owner nor an organization admin.`
+        );
+      }
+    });
+  }
+}
+
+function updateItemAccess(
+  url: string,
+  requestOptions: ISetAccessOptions
+): Promise<any> {
+  requestOptions.params = {
+    org: false,
+    everyone: false,
+    ...requestOptions.params
+  };
+
+  // if the user wants to make the item private, it needs to be unshared from any/all groups as well
+  if (requestOptions.access === "private") {
+    requestOptions.params.groups = " ";
+  }
+  if (requestOptions.access === "org") {
+    requestOptions.params.org = true;
+  }
+  // if sharing with everyone, share with the entire organization as well.
+  if (requestOptions.access === "public") {
+    requestOptions.params.org = true;
+    requestOptions.params.everyone = true;
+  }
+  return request(url, requestOptions);
+}