ducimusipsa 1.0.0

package/packages/arcgis-rest-request/src/request.ts

@@ -0,0 +1,358 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { encodeFormData } from "./utils/encode-form-data";
+import { encodeQueryString } from "./utils/encode-query-string";
+import { requiresFormData } from "./utils/process-params";
+import { ArcGISRequestError } from "./utils/ArcGISRequestError";
+import { IRetryAuthError } from "./utils/retryAuthError";
+import { HTTPMethods, IParams, ITokenRequestOptions } from "./utils/params";
+
+/**
+ * Authentication can be supplied to `request` via [`UserSession`](../../auth/UserSession/) or [`ApplicationSession`](../../auth/ApplicationSession/). Both classes extend `IAuthenticationManager`.
+ * ```js
+ * const session = new UserSession({
+ *   username: "jsmith",
+ *   password: "123456",
+ *   // optional
+ *   portal: "https://[yourserver]/arcgis/sharing/rest"
+ * })
+ *
+ * request(url, { authentication: session })
+ * ```
+ */
+export interface IAuthenticationManager {
+  /**
+   * Defaults to 'https://www.arcgis.com/sharing/rest'.
+   */
+  portal: string;
+  getToken(url: string, requestOptions?: ITokenRequestOptions): Promise<string>;
+}
+
+/**
+ * Options for the `request()` method.
+ */
+export interface IRequestOptions {
+  /**
+   * Additional parameters to pass in the request.
+   */
+  params?: IParams;
+
+  /**
+   * The HTTP method to send the request with.
+   */
+  httpMethod?: HTTPMethods;
+
+  /**
+   * The instance of `IAuthenticationManager` to use to authenticate this request.
+   */
+  authentication?: IAuthenticationManager;
+
+  /**
+   * Base url for the portal you want to make the request to. Defaults to 'https://www.arcgis.com/sharing/rest'.
+   */
+  portal?: string;
+
+  /**
+   * The implementation of `fetch` to use. Defaults to a global `fetch`.
+   */
+  fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+
+  /**
+   * If the length of a GET request's URL exceeds `maxUrlLength` the request will use POST instead.
+   */
+  maxUrlLength?: number;
+}
+
+/**
+ * Generic method for making HTTP requests to ArcGIS REST API endpoints.
+ *
+ * ```js
+ * import { request } from '@esri/arcgis-rest-request';
+ *
+ * request('https://www.arcgis.com/sharing/rest')
+ *   .then((response) => {
+ *     console.log(response.currentVersion); // => 5.2
+ *   });
+ * ```
+ *
+ * ```js
+ * import { request, HTTPMethods } from '@esri/arcgis-rest-request';
+ *
+ * request('https://www.arcgis.com/sharing/rest', {
+ *   httpMethod: "GET"
+ * }).then((response) => {
+ *   console.log(response.currentVersion); // => 5.2
+ * });
+ * ```
+ *
+ * ```js
+ * import { request, HTTPMethods } from '@esri/arcgis-rest-request';
+ *
+ * request('https://www.arcgis.com/sharing/rest/search', {
+ *   params: { q: 'parks' }
+ * }).then((response) => {
+ *   console.log(response.total); // => 78379
+ * });
+ * ```
+ *
+ * @param url - The URL of the ArcGIS REST API endpoint.
+ * @param requestOptions - Options for the request, including parameters relevant to the endpoint.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function request(
+  url: string,
+  requestOptions: IRequestOptions = { params: { f: "json" } }
+): Promise<any> {
+  const options: IRequestOptions = {
+    httpMethod: "POST",
+    ...requestOptions
+  };
+
+  const missingGlobals: string[] = [];
+  const recommendedPackages: string[] = [];
+
+  // don't check for a global fetch if a custom implementation was passed through
+  if (!options.fetch && typeof fetch !== "undefined") {
+    options.fetch = fetch.bind(Function("return this")());
+  } else {
+    missingGlobals.push("`fetch`");
+    recommendedPackages.push("`isomorphic-fetch`");
+  }
+
+  if (typeof Promise === "undefined") {
+    missingGlobals.push("`Promise`");
+    recommendedPackages.push("`es6-promise`");
+  }
+
+  if (typeof FormData === "undefined") {
+    missingGlobals.push("`FormData`");
+    recommendedPackages.push("`isomorphic-form-data`");
+  }
+
+  if (
+    !options.fetch ||
+    typeof Promise === "undefined" ||
+    typeof FormData === "undefined"
+  ) {
+    throw new Error(
+      `\`arcgis-rest-request\` requires global variables for \`fetch\`, \`Promise\` and \`FormData\` to be present in the global scope. You are missing ${missingGlobals.join(
+        ", "
+      )}. We recommend installing the ${recommendedPackages.join(
+        ", "
+      )} modules at the root of your application to add these to the global scope. See https://bit.ly/2KNwWaJ for more info.`
+    );
+  }
+
+  const { httpMethod, authentication } = options;
+
+  const params: IParams = {
+    ...{ f: "json" },
+    ...requestOptions.params
+  };
+
+  const fetchOptions: RequestInit = {
+    method: httpMethod,
+    // ensures behavior mimics XMLHttpRequest. needed to support sending IWA cookies
+    credentials: "same-origin"
+  };
+
+  return (authentication
+    ? authentication.getToken(url, {
+        fetch: options.fetch
+      })
+    : Promise.resolve("")
+  )
+    .then(token => {
+      if (token.length) {
+        params.token = token;
+      }
+
+      if (fetchOptions.method === "GET") {
+        // encode the parameters into the query string
+        const queryParams = encodeQueryString(params);
+        // dont append a '?' unless parameters are actually present
+        const urlWithQueryString =
+          queryParams === "" ? url : url + "?" + encodeQueryString(params);
+
+        if (
+          options.maxUrlLength &&
+          urlWithQueryString.length > options.maxUrlLength
+        ) {
+          // the consumer specified a maximum length for URLs
+          // and this would exceed it, so use post instead
+          fetchOptions.method = "POST";
+        } else {
+          // just use GET
+          url = urlWithQueryString;
+        }
+      }
+
+      if (fetchOptions.method === "POST") {
+        fetchOptions.body = encodeFormData(params);
+      }
+
+      fetchOptions.headers = {};
+
+      /* istanbul ignore next - karma reports coverage on browser tests only */
+      if (typeof window === "undefined") {
+        fetchOptions.headers["referer"] = "@esri/arcgis-rest";
+      }
+
+      /* istanbul ignore else blob responses are difficult to make cross platform we will just have to trust the isomorphic fetch will do its job */
+      if (!requiresFormData(params)) {
+        fetchOptions.headers["Content-Type"] =
+          "application/x-www-form-urlencoded";
+      }
+
+      return options.fetch(url, fetchOptions);
+    })
+    .then(response => {
+      if (!response.ok) {
+        // server responded w/ an actual error (404, 500, etc)
+        const { status, statusText } = response;
+        throw new ArcGISRequestError(
+          statusText,
+          `HTTP ${status}`,
+          response,
+          url,
+          options
+        );
+      }
+      switch (params.f) {
+        case "json":
+          return response.json();
+        case "geojson":
+          return response.json();
+        case "html":
+          return response.text();
+        case "text":
+          return response.text();
+        /* istanbul ignore next blob responses are difficult to make cross platform we will just have to trust that isomorphic fetch will do its job */
+        case "image":
+          return response.blob();
+        /* istanbul ignore next */
+        case "zip":
+          return response.blob();
+        /* istanbul ignore next */
+        default:
+          // hopefully we never need to handle JSON payloads when no f= parameter is set
+          return response.blob();
+      }
+    })
+    .then(data => {
+      if (params.f === "json" || params.f === "geojson") {
+        return checkForErrors(data, url, params, options);
+      } else {
+        return data;
+      }
+    });
+}
+
+export class ArcGISAuthError extends ArcGISRequestError {
+  /**
+   * Create a new `ArcGISAuthError`  object.
+   *
+   * @param message - The error message from the API
+   * @param code - The error code from the API
+   * @param response - The original response from the API that caused the error
+   * @param url - The original url of the request
+   * @param options - The original options of the request
+   */
+  constructor(
+    message = "AUTHENTICATION_ERROR",
+    code: string | number = "AUTHENTICATION_ERROR_CODE",
+    response?: any,
+    url?: string,
+    options?: IRequestOptions
+  ) {
+    super(message, code, response, url, options);
+    this.name = "ArcGISAuthError";
+    this.message =
+      code === "AUTHENTICATION_ERROR_CODE" ? message : `${code}: ${message}`;
+  }
+
+  retry(getSession: IRetryAuthError, retryLimit = 3) {
+    let tries = 0;
+
+    const retryRequest = (resolve: any, reject: any) => {
+      getSession(this.url, this.options)
+        .then(session => {
+          const newOptions = {
+            ...this.options,
+            ...{ authentication: session }
+          };
+
+          tries = tries + 1;
+          return request(this.url, newOptions);
+        })
+        .then(response => {
+          resolve(response);
+        })
+        .catch(e => {
+          if (e.name === "ArcGISAuthError" && tries < retryLimit) {
+            retryRequest(resolve, reject);
+          } else if (e.name === "ArcGISAuthError" && tries >= retryLimit) {
+            reject(this);
+          } else {
+            reject(e);
+          }
+        });
+    };
+
+    return new Promise((resolve, reject) => {
+      retryRequest(resolve, reject);
+    });
+  }
+}
+
+/**
+ * Checks for errors in a JSON response from the ArcGIS REST API. If there are no errors, it will return the `data` passed in. If there is an error, it will throw an `ArcGISRequestError` or `ArcGISAuthError`.
+ *
+ * @param data The response JSON to check for errors.
+ * @param url The url of the original request
+ * @param params The parameters of the original request
+ * @param options The options of the original request
+ * @returns The data that was passed in the `data` parameter
+ */
+export function checkForErrors(
+  response: any,
+  url?: string,
+  params?: IParams,
+  options?: IRequestOptions
+): any {
+  // this is an error message from billing.arcgis.com backend
+  if (response.code >= 400) {
+    const { message, code } = response;
+    throw new ArcGISRequestError(message, code, response, url, options);
+  }
+
+  // error from ArcGIS Online or an ArcGIS Portal or server instance.
+  if (response.error) {
+    const { message, code, messageCode } = response.error;
+    const errorCode = messageCode || code || "UNKNOWN_ERROR_CODE";
+
+    if (code === 498 || code === 499 || messageCode === "GWM_0003") {
+      throw new ArcGISAuthError(message, errorCode, response, url, options);
+    }
+
+    throw new ArcGISRequestError(message, errorCode, response, url, options);
+  }
+
+  // error from a status check
+  if (response.status === "failed" || response.status === "failure") {
+    let message: string;
+    let code: string = "UNKNOWN_ERROR_CODE";
+
+    try {
+      message = JSON.parse(response.statusMessage).message;
+      code = JSON.parse(response.statusMessage).code;
+    } catch (e) {
+      message = response.statusMessage || response.message;
+    }
+
+    throw new ArcGISRequestError(message, code, response, url, options);
+  }
+
+  return response;
+}

package/packages/arcgis-rest-request/src/utils/ArcGISRequestError.ts

@@ -0,0 +1,76 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "../request";
+
+// TypeScript 2.1 no longer allows you to extend built in types. See https://github.com/Microsoft/TypeScript/issues/12790#issuecomment-265981442
+// and https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
+//
+// This code is from MDN https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Custom_Error_Types.
+export class ArcGISRequestError {
+  /**
+   * The name of this error. Will always be `"ArcGISRequestError"` to conform with the [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) class.
+   */
+  name: string;
+
+  /**
+   * Formatted error message. See the [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) class for more details.
+   */
+  message: string;
+
+  /**
+   * The errror message return from the request.
+   */
+  originalMessage: string;
+
+  /**
+   * The error code returned from the request.
+   */
+  code: string | number;
+
+  /**
+   * The original JSON response the caused the error.
+   */
+  response: any;
+
+  /**
+   * The URL of the original request that caused the error
+   */
+  url: string;
+
+  /**
+   * The options of the original request that caused the error
+   */
+  options: IRequestOptions;
+
+  /**
+   * Create a new `ArcGISRequestError`  object.
+   *
+   * @param message - The error message from the API
+   * @param code - The error code from the API
+   * @param response - The original response from the API that caused the error
+   * @param url - The original url of the request
+   * @param options - The original options and parameters of the request
+   */
+  constructor(
+    message?: string,
+    code?: string | number,
+    response?: any,
+    url?: string,
+    options?: IRequestOptions
+  ) {
+    message = message || "UNKNOWN_ERROR";
+    code = code || "UNKNOWN_ERROR_CODE";
+
+    this.name = "ArcGISRequestError";
+    this.message =
+      code === "UNKNOWN_ERROR_CODE" ? message : `${code}: ${message}`;
+    this.originalMessage = message;
+    this.code = code;
+    this.response = response;
+    this.url = url;
+    this.options = options;
+  }
+}
+ArcGISRequestError.prototype = Object.create(Error.prototype);
+ArcGISRequestError.prototype.constructor = ArcGISRequestError;

package/packages/arcgis-rest-request/src/utils/ErrorTypes.ts

@@ -0,0 +1,29 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+/**
+ * Enum describing the different errors that might be thrown by a request.
+ *
+ * ```ts
+ * import { request, ErrorTypes } from '@esri/arcgis-rest-request';
+ *
+ * request("...").catch((e) => {
+ *   switch(e.name) {
+ *     case ErrorType.ArcGISRequestError:
+ *     // handle a general error from the API
+ *     break;
+ *
+ *     case ErrorType.ArcGISAuthError:
+ *     // handle an authentication error
+ *     break;
+ *
+ *     default:
+ *     // handle some other error (usually a network error)
+ *   }
+ * });
+ * ```
+ */
+export enum ErrorTypes {
+  ArcGISRequestError = "ArcGISRequestError",
+  ArcGISAuthError = "ArcGISAuthError"
+}

package/packages/arcgis-rest-request/src/utils/append-custom-params.ts

@@ -0,0 +1,29 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "../request";
+
+/**
+ * Helper for methods with lots of first order request options to pass them through as request parameters.
+ */
+export function appendCustomParams(
+  oldOptions: IRequestOptions,
+  newOptions: IRequestOptions
+) {
+  // only pass query parameters through in the request, not generic IRequestOptions props
+  Object.keys(oldOptions).forEach(function(key: string) {
+    if (
+      key !== "url" &&
+      key !== "params" &&
+      key !== "authentication" &&
+      key !== "httpMethod" &&
+      key !== "fetch" &&
+      key !== "portal" &&
+      key !== "maxUrlLength" &&
+      key !== "endpoint" &&
+      key !== "decodeValues"
+    ) {
+      newOptions.params[key] = (oldOptions as { [key: string]: any })[key];
+    }
+  });
+}

package/packages/arcgis-rest-request/src/utils/encode-form-data.ts

@@ -0,0 +1,34 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { processParams, requiresFormData } from "./process-params";
+import { encodeQueryString } from "./encode-query-string";
+/**
+ * Encodes parameters in a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object in browsers or in a [FormData](https://github.com/form-data/form-data) in Node.js
+ *
+ * @param params An object to be encoded.
+ * @returns The complete [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object.
+ */
+export function encodeFormData(params: any): FormData | string {
+  const useFormData = requiresFormData(params);
+  const newParams = processParams(params);
+  if (useFormData) {
+    const formData = new FormData();
+    Object.keys(newParams).forEach((key: any) => {
+      if (typeof Blob !== "undefined" && newParams[key] instanceof Blob) {
+        /* To name the Blob:
+         1. look to an alternate request parameter called 'fileName'
+         2. see if 'name' has been tacked onto the Blob manually
+         3. if all else fails, use the request parameter
+        */
+        const filename = newParams["fileName"] || newParams[key].name || key;
+        formData.append(key, newParams[key], filename);
+      } else {
+        formData.append(key, newParams[key]);
+      }
+    });
+    return formData;
+  } else {
+    return encodeQueryString(params);
+  }
+}

package/packages/arcgis-rest-request/src/utils/encode-query-string.ts

@@ -0,0 +1,23 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { processParams } from "./process-params";
+
+export function encodeParam(key: string, value: any) {
+  return encodeURIComponent(key) + "=" + encodeURIComponent(value);
+}
+
+/**
+ * Encodes the passed object as a query string.
+ *
+ * @param params An object to be encoded.
+ * @returns An encoded query string.
+ */
+export function encodeQueryString(params: any): string {
+  const newParams = processParams(params);
+  return Object.keys(newParams)
+    .map((key: any) => {
+      return encodeParam(key, newParams[key]);
+    })
+    .join("&");
+}

package/packages/arcgis-rest-request/src/utils/get-portal-url.ts

@@ -0,0 +1,25 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+import { IRequestOptions } from "../request";
+
+/**
+ * Helper that returns the appropriate portal url for a given request. `requestOptions.portal` is given
+ * precedence over `authentication.portal`. If neither are present, `www.arcgis.com/sharing/rest` is returned.
+ *
+ * @param requestOptions - Request options that may have authentication manager
+ * @returns Portal url to be used in API requests
+ */
+export function getPortalUrl(requestOptions: IRequestOptions = {}): string {
+  // use portal in options if specified
+  if (requestOptions.portal) {
+    return requestOptions.portal;
+  }
+
+  // if auth was passed, use that portal
+  if (requestOptions.authentication) {
+    return requestOptions.authentication.portal;
+  }
+
+  // default to arcgis.com
+  return "https://www.arcgis.com/sharing/rest";
+}

package/packages/arcgis-rest-request/src/utils/get-portal.ts

@@ -0,0 +1,45 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "../request";
+
+import { getPortalUrl } from "./get-portal-url";
+
+export interface IPortal {
+  id: string;
+  isPortal: boolean;
+  name: string;
+  [key: string]: any;
+}
+
+/**
+ * Get the portal
+ * @param requestOptions
+ */
+export function getSelf(requestOptions?: IRequestOptions): Promise<IPortal> {
+  // just delegate to getPortal w/o an id
+  return getPortal(null, requestOptions);
+}
+
+/**
+ * Get a portal by id. If no id is passed, it will call portals/self
+ * @param id
+ * @param requestOptions
+ */
+export function getPortal(
+  id?: string,
+  requestOptions?: IRequestOptions
+): Promise<IPortal> {
+  // construct the search url
+  const idOrSelf = id ? id : "self";
+  const url = `${getPortalUrl(requestOptions)}/portals/${idOrSelf}`;
+
+  // default to a GET request
+  const options: IRequestOptions = {
+    ...{ httpMethod: "GET" },
+    ...requestOptions
+  };
+
+  // send the request
+  return request(url, options);
+}

package/packages/arcgis-rest-request/src/utils/params.ts

@@ -0,0 +1,52 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+* Apache-2.0 */
+
+/**
+ * HTTP methods used by the ArcGIS REST API.
+ */
+export type HTTPMethods = "GET" | "POST";
+
+/**
+ * Valid response formats for the `f` parameter.
+ */
+export type ResponseFormats =
+  | "json"
+  | "geojson"
+  | "text"
+  | "html"
+  | "image"
+  | "zip";
+
+export type GrantTypes =
+  | "authorization_code"
+  | "refresh_token"
+  | "client_credentials"
+  | "exchange_refresh_token";
+
+export interface IParams {
+  f?: ResponseFormats;
+  [key: string]: any;
+}
+
+export interface IGenerateTokenParams extends IParams {
+  username?: string;
+  password?: string;
+  expiration?: number;
+  token?: string;
+  serverUrl?: string;
+}
+
+export interface IFetchTokenParams extends IParams {
+  client_id: string;
+  client_secret?: string;
+  grant_type: GrantTypes;
+  redirect_uri?: string;
+  refresh_token?: string;
+  code?: string;
+}
+
+export interface ITokenRequestOptions {
+  params?: IGenerateTokenParams | IFetchTokenParams;
+  httpMethod?: HTTPMethods;
+  fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+}