chore(items): break out item methods into individual files

for legibility

AFFECTS PACKAGES:
@esri/arcgis-rest-items

packages/arcgis-rest-items/src/add.ts

@@ -0,0 +1,75 @@
+import { request, getPortalUrl } from "@esri/arcgis-rest-request";
+
+import {
+  IItemIdRequestOptions,
+  IItemResourceRequestOptions,
+  IItemAddResponse,
+  IItemResourceResponse,
+  determineOwner
+} from "./helpers";
+
+export interface IItemDataAddRequestOptions extends IItemIdRequestOptions {
+  /**
+   * Object to store
+   */
+  data: any;
+}
+
+export interface IItemResourceAddRequestOptions
+  extends IItemResourceRequestOptions {
+  /**
+   * Object to store
+   */
+  resource: any;
+}
+
+/**
+ * Send json to an item to be stored as the `/data` resource
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with an object reporting
+ *        success/failure and echoing the item id.
+ */
+export function addItemJsonData(
+  requestOptions: IItemDataAddRequestOptions
+): Promise<IItemAddResponse> {
+  const owner = determineOwner(requestOptions);
+  const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+    requestOptions.id
+  }/update`;
+
+  // Portal API requires that the 'data' be stringified and POSTed in
+  // a `text` form field. It can also be sent with the `.create` call by sending
+  // a `.data` property.
+  requestOptions.params = {
+    text: JSON.stringify(requestOptions.data),
+    ...requestOptions.params
+  };
+
+  return request(url, requestOptions);
+}
+
+/**
+ * Send a file or blob to an item to be stored as the `/data` resource
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with an object reporting
+ *        success/failure and echoing the item id.
+ */
+export function addItemData(
+  requestOptions: IItemDataAddRequestOptions
+): Promise<IItemAddResponse> {
+  const owner = determineOwner(requestOptions);
+
+  const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+    requestOptions.id
+  }/update`;
+
+  // Portal API requires that the 'data' be POSTed in a `file` form field.
+  requestOptions.params = {
+    file: requestOptions.data,
+    ...requestOptions.params
+  };
+
+  return request(url, requestOptions);
+}

packages/arcgis-rest-items/src/create.ts

@@ -0,0 +1,69 @@
+import { request, getPortalUrl } from "@esri/arcgis-rest-request";
+
+import { IItemAdd } from "@esri/arcgis-rest-common-types";
+
+import {
+  IItemAddResponse,
+  IItemCrudRequestOptions,
+  serializeItem,
+  determineOwner
+} from "./helpers";
+
+export interface IItemAddRequestOptions extends IItemCrudRequestOptions {
+  item: IItemAdd;
+}
+
+/**
+ * Create an item in a folder
+ *
+ * @param requestOptions = Options for the request
+ */
+export function createItemInFolder(
+  requestOptions: IItemAddRequestOptions
+): Promise<IItemAddResponse> {
+  const owner = determineOwner(requestOptions);
+
+  const baseUrl = `${getPortalUrl(requestOptions)}/content/users/${owner}`;
+  let url = `${baseUrl}/addItem`;
+
+  if (requestOptions.folder) {
+    url = `${baseUrl}/${requestOptions.folder}/addItem`;
+  }
+
+  // serialize the item into something Portal will accept
+  requestOptions.params = {
+    ...requestOptions.params,
+    ...serializeItem(requestOptions.item)
+  };
+
+  return request(url, requestOptions);
+}
+
+/**
+ * Create an Item in the user's root folder
+ *
+ * ```js
+ * import { createItem } from '@esri/arcgis-rest-items';
+ *
+ * createItem({
+ *   authentication: userSession,
+ *   item: {
+ *     title: "The Amazing Voyage",
+ *     type: "Web Map"
+ *   }
+ * })
+ * ```
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that creates an item.
+ */
+export function createItem(
+  requestOptions: IItemAddRequestOptions
+): Promise<IItemAddResponse> {
+  // delegate to createItemInFolder placing in the root of the filestore
+  const options = {
+    folder: null,
+    ...requestOptions
+  } as IItemAddRequestOptions;
+  return createItemInFolder(options);
+}

packages/arcgis-rest-items/src/get.ts

@@ -0,0 +1,76 @@
+import {
+  request,
+  IRequestOptions,
+  getPortalUrl
+} from "@esri/arcgis-rest-request";
+
+import { IItem } from "@esri/arcgis-rest-common-types";
+
+import { IItemIdRequestOptions, IItemDataRequestOptions } from "./helpers";
+
+/**
+ * Get an item by id
+ *
+ * @param id - Item Id
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function getItem(
+  id: string,
+  requestOptions?: IRequestOptions
+): Promise<IItem> {
+  const url = `${getPortalUrl(requestOptions)}/content/items/${id}`;
+
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+  return request(url, options);
+}
+
+/**
+ * Get the /data for an item.
+ * @param id - Item Id
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the json data for the item.
+ */
+export function getItemData(
+  id: string,
+  requestOptions?: IItemDataRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/content/items/${id}/data`;
+  // default to a GET request
+  const options: IItemDataRequestOptions = {
+    ...{ httpMethod: "GET", params: {} },
+    ...requestOptions
+  };
+
+  if (options.file) {
+    options.params.f = null;
+  }
+
+  return request(url, options);
+}
+
+/**
+ * Get the resources associated with an item
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to get some item resources.
+ */
+export function getItemResources(
+  requestOptions: IItemIdRequestOptions
+): Promise<any> {
+  const url = `${getPortalUrl(requestOptions)}/content/items/${
+    requestOptions.id
+  }/resources`;
+
+  // mix in user supplied params
+  requestOptions.params = {
+    ...requestOptions.params,
+    num: 1000
+  };
+
+  return request(url, requestOptions);
+}

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

@@ -0,0 +1,109 @@
+/* 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-common-types";
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+export interface IItemRequestOptions extends IUserRequestOptions {
+  item: IItem;
+}
+
+export interface IItemIdRequestOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the item.
+   */
+  id: string;
+  /**
+   * Item owner username. If not present, `authentication.username` is utilized.
+   */
+  owner?: string;
+}
+
+export interface IItemResourceRequestOptions extends IItemIdRequestOptions {
+  /**
+   * New resource filename.
+   */
+  name?: string;
+  /**
+   * Text input to be added as a file resource.
+   */
+  content?: string;
+  resource?: any;
+}
+
+export interface IItemCrudRequestOptions 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.
+   */
+  folder?: string;
+}
+
+export interface IItemDataRequestOptions extends IRequestOptions {
+  /**
+   * Used to request binary data.
+   */
+  file?: boolean;
+}
+
+export interface IItemUpdateResponse {
+  success: boolean;
+  id: string;
+}
+
+export interface IItemAddResponse extends IItemUpdateResponse {
+  folder: string;
+}
+
+export interface IItemResourceResponse {
+  success: boolean;
+  itemId: string;
+  owner: string;
+  folder: string;
+}
+
+/**
+ * Serialize an item 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));
+  // join keywords and tags...
+  const { typeKeywords = [], tags = [] } = item;
+  clone.typeKeywords = typeKeywords.join(", ");
+  clone.tags = tags.join(", ");
+  // convert .data to .text
+  if (clone.data) {
+    clone.text = JSON.stringify(clone.data);
+    delete clone.data;
+  }
+  // Convert properties to a string
+  if (clone.properties) {
+    clone.properties = JSON.stringify(clone.properties);
+  }
+  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;
+  }
+}

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

@@ -1 +1,8 @@
-export * from "./items";
+export * from "./add";
+export * from "./create";
+export * from "./get";
+export * from "./protect";
+export * from "./remove";
+export * from "./search";
+export * from "./update";
+export * from "./helpers";