culparepellendus 1.0.0

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

@@ -0,0 +1,292 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions, ArcGISRequestError } 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 =
+  | "APIKey2Item"
+  | "Area2CustomPackage"
+  | "Area2Package"
+  | "Item2Attachment"
+  | "Item2Report"
+  | "Listed2Provisioned"
+  | "Map2AppConfig"
+  | "Map2Area"
+  | "Map2FeatureCollection"
+  | "Map2Service"
+  | "MobileApp2Code"
+  | "Service2Data"
+  | "Service2Layer"
+  | "Service2Route"
+  | "Service2Service"
+  | "Service2Style"
+  | "Solution2Item"
+  | "Style2Style"
+  | "Survey2Data"
+  | "Survey2Service"
+  | "SurveyAddIn2Data"
+  | "Theme2Story"
+  | "TrackView2Map"
+  | "WebStyle2DesktopStyle"
+  | "WMA2Code"
+  | "WorkforceMap2FeatureService"
+
+/**
+ * Names of methods for reading the body of a fetch response, see:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Body#Methods
+ */
+export type FetchReadMethodName =
+  | "arrayBuffer"
+  | "blob"
+  | "formData"
+  | "json"
+  | "text";
+
+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 IItemInfoOptions extends IUserItemOptions {
+  /**
+   * Subfolder for added information.
+   */
+  folderName?: string;
+  /**
+   * Object to store
+   */
+  file: any;
+}
+
+export interface IItemResourceOptions extends IUserItemOptions {
+  /**
+   * New resource filename.
+   */
+  name?: string;
+  /**
+   * Folder in which to store the new resource.
+   */
+  prefix?: 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 IRemoveItemResourceOptions extends IUserItemOptions {
+  /**
+   * Resource item to be removed. Resource prefix needs to be specified if the file resource has one.
+   */
+  resource?: string;
+
+  /**
+   * If true, all file resources are removed.
+   */
+  deleteAll?: boolean;
+}
+
+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;
+  /**
+   * The file to be uploaded. If uploading a file, the request must be a multipart request.
+   */
+  file?: any;
+  /**
+   * The URL where the item can be downloaded. The resource will be downloaded and stored as a file type. Similar to uploading a file to be added, but instead of transferring the contents of the file, the URL of the data file is referenced and creates a file item.
+   */
+  dataUrl?: string;
+  /**
+   * The text content for the item to be submitted.
+   */
+  text?: string;
+  /**
+   * If true, the file is uploaded asynchronously. If false, the file is uploaded synchronously.
+   */
+  async?: boolean;
+  /**
+   * If true, the file is uploaded in multiple parts.
+   */
+  multipart?: boolean;
+  /**
+   * The filename being uploaded in multipart mode. Required if multipart=true.
+   */
+  filename?: string;
+  /**
+   * If true, overwrite the existing file.
+   */
+  overwrite?: boolean;
+}
+
+export interface IItemDataOptions extends IRequestOptions {
+  /**
+   * Used to request binary data.
+   */
+  file?: boolean;
+}
+
+export interface IItemPartOptions extends IUserItemOptions {
+  /**
+   * The file part to be uploaded.
+   */
+  file: any;
+  /**
+   * Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being created. If you upload a new part using the same part number that was used with a previous part, the previously uploaded part is overwritten.
+   */
+  partNum: number;
+}
+
+export interface IUpdateItemResponse {
+  success: boolean;
+  id: string;
+}
+
+export interface IItemInfoResponse {
+  success: boolean;
+  itemId: string;
+  owner: string;
+  folder: 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.getUserName()` will be used instead.
+ */
+export function determineOwner(requestOptions: any): Promise<string> {
+  if (requestOptions.owner) {
+    return Promise.resolve(requestOptions.owner);
+  } else if (requestOptions.item && requestOptions.item.owner) {
+    return Promise.resolve(requestOptions.item.owner);
+  } else if (
+    requestOptions.authentication &&
+    requestOptions.authentication.getUsername
+  ) {
+    return requestOptions.authentication.getUsername();
+  } else {
+    return Promise.reject(
+      new Error(
+        "Could not determine the owner of this item. Pass the `owner`, `item.owner`, or `authentication` option."
+      )
+    );
+  }
+}

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,141 @@
+/* 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,
+  IRemoveItemResourceOptions,
+  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: IRemoveItemResourceOptions
+): 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
+    };
+
+    // only override the deleteAll param specified previously if it is passed explicitly
+    if (typeof requestOptions.deleteAll !== "undefined") {
+      requestOptions.params.deleteAll = requestOptions.deleteAll;
+    }
+
+    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");
+}