autnam 1.0.0

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

@@ -0,0 +1,59 @@
+import { HTTPMethods } from "./HTTPMethods.js";
+import { IParams } from "./IParams.js";
+import { IAuthenticationManager } from "./IAuthenticationManager.js";
+
+/**
+ * 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;
+  /**
+   * Return the raw [response](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+   */
+  rawResponse?: boolean;
+  /**
+   * The instance of {@linkcode ApiKey}, {@linkcode ArcGISIdentityManager} or {@linkcode ApplicationSession} to use to authenticate this request. A token may also be passed directly as a string however using the built in authentication managers is encouraged.
+   */
+  authentication?: IAuthenticationManager | string;
+  /**
+   * Prevents the token from being passed in a URL Query param that is saved in browser history.
+   * Instead, the token will be passed in POST request body or through X-Esri-Authorization header.
+   * NOTE: This will force POST requests in browsers since auth header is not yet supported by preflight OPTIONS check with CORS.
+   */
+  hideToken?: boolean;
+  /**
+   * Base url for the portal you want to make the request to. Defaults to authentication.portal if authentication
+   * exists, otherwise 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>;
+  /**
+   * A string indicating whether credentials (cookies) will be sent with the request. Used internally for authentication workflows.
+   */
+  credentials?: RequestCredentials;
+  /**
+   * If the length of a GET request's URL exceeds `maxUrlLength` the request will use POST instead.
+   */
+  maxUrlLength?: number;
+  /**
+   * Additional [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) to pass into the request.
+   */
+  headers?: {
+    [key: string]: any;
+  };
+
+  /**
+   * Suppress any ArcGIS REST JS related warnings for this request.
+   */
+  suppressWarnings?: boolean;
+}

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

@@ -0,0 +1,9 @@
+import { HTTPMethods } from "./HTTPMethods.js";
+import { IGenerateTokenParams } from "./IGenerateTokenParams.js";
+import { IFetchTokenParams } from "./IFetchTokenParams.js";
+
+export interface ITokenRequestOptions {
+  params?: IGenerateTokenParams | IFetchTokenParams;
+  httpMethod?: HTTPMethods;
+  fetch?: (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Valid response formats for the `f` parameter.
+ */
+export type ResponseFormats =
+  | "json"
+  | "geojson"
+  | "text"
+  | "html"
+  | "image"
+  | "zip";

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

@@ -0,0 +1,46 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "./IRequestOptions.js";
+
+/**
+ * Helper for methods with lots of first order request options to pass through as request parameters.
+ */
+export function appendCustomParams<T extends IRequestOptions>(
+  customOptions: T,
+  keys: Array<keyof T>,
+  baseOptions?: Partial<T>
+): IRequestOptions {
+  const requestOptionsKeys = [
+    "params",
+    "httpMethod",
+    "rawResponse",
+    "authentication",
+    "portal",
+    "fetch",
+    "maxUrlLength",
+    "headers",
+  ];
+
+  const options: T = {
+    ...{ params: {} },
+    ...baseOptions,
+    ...customOptions,
+  };
+
+  // merge all keys in customOptions into options.params
+  options.params = keys.reduce((value, key) => {
+    if (customOptions[key] || typeof customOptions[key] === "boolean") {
+      value[key as any] = customOptions[key];
+    }
+    return value;
+  }, options.params);
+
+  // now remove all properties in options that don't exist in IRequestOptions
+  return requestOptionsKeys.reduce((value, key) => {
+    if ((options as any)[key]) {
+      (value as any)[key] = (options as any)[key];
+    }
+    return value;
+  }, {} as IRequestOptions);
+}

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

@@ -0,0 +1,20 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+/**
+ * Helper method to ensure that user supplied urls don't include whitespace or a trailing slash.
+ */
+export function cleanUrl(url: string) {
+  // Guard so we don't try to trim something that's not a string
+  if (typeof url !== "string") {
+    return url;
+  }
+  // trim leading and trailing spaces, but not spaces inside the url
+  url = url.trim();
+
+  // remove the trailing slash to the url if one was included
+  if (url[url.length - 1] === "/") {
+    url = url.slice(0, -1);
+  }
+  return url;
+}

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

@@ -0,0 +1,27 @@
+/* Copyright (c) 2017-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export function decodeParam(param: string): { key: string; value: string } {
+  const [key, value] = param.split("=");
+  return { key: decodeURIComponent(key), value: decodeURIComponent(value) };
+}
+
+/**
+ * Decodes the passed query string as an object.
+ *
+ * @param query A string to be decoded.
+ * @returns A decoded query param object.
+ */
+export function decodeQueryString(query: string): { [key: string]: string } {
+  return query
+    .replace(/^#/, "")
+    .split("&")
+    .reduce(
+      (acc, entry) => {
+        const { key, value } = decodeParam(entry);
+        acc[key] = value;
+        return acc;
+      },
+      {} as any
+    );
+}

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

@@ -0,0 +1,41 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { processParams, requiresFormData } from "./process-params.js";
+import { encodeQueryString } from "./encode-query-string.js";
+import { FormData } from "@esri/arcgis-rest-form-data";
+
+/**
+ * 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,
+  forceFormData?: boolean
+): FormData | string {
+  // see https://github.com/Esri/arcgis-rest-js/issues/499 for more info.
+  const useFormData = requiresFormData(params) || forceFormData;
+  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,37 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { processParams } from "./process-params.js";
+
+/**
+ * Encodes keys and parameters for use in a URL's query string.
+ *
+ * @param key Parameter's key
+ * @param value Parameter's value
+ * @returns Query string with key and value pairs separated by "&"
+ */
+export function encodeParam(key: string, value: any): string {
+  // For array of arrays, repeat key=value for each element of containing array
+  if (Array.isArray(value) && value[0] && Array.isArray(value[0])) {
+    return value
+      .map((arrayElem: string) => encodeParam(key, arrayElem))
+      .join("&");
+  }
+
+  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/process-params.ts

@@ -0,0 +1,109 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+/**
+ * Checks parameters to see if we should use FormData to send the request
+ * @param params The object whose keys will be encoded.
+ * @return A boolean indicating if FormData will be required.
+ */
+export function requiresFormData(params: any) {
+  return Object.keys(params).some(key => {
+    let value = params[key];
+
+    if (!value) {
+      return false;
+    }
+
+    if (value && value.toParam) {
+      value = value.toParam();
+    }
+
+    const type = value.constructor.name;
+
+    switch (type) {
+      case "Array":
+        return false;
+      case "Object":
+        return false;
+      case "Date":
+        return false;
+      case "Function":
+        return false;
+      case "Boolean":
+        return false;
+      case "String":
+        return false;
+      case "Number":
+        return false;
+      default:
+        return true;
+    }
+  });
+}
+
+/**
+ * Converts parameters to the proper representation to send to the ArcGIS REST API.
+ * @param params The object whose keys will be encoded.
+ * @return A new object with properly encoded values.
+ */
+export function processParams(params: any): any {
+  const newParams: any = {};
+
+  Object.keys(params).forEach(key => {
+    let param = params[key];
+
+    if (param && param.toParam) {
+      param = param.toParam();
+    }
+
+    if (
+      !param &&
+      param !== 0 &&
+      typeof param !== "boolean" &&
+      typeof param !== "string"
+    ) {
+      return;
+    }
+
+    const type = param.constructor.name;
+
+    let value: any;
+
+    // properly encodes objects, arrays and dates for arcgis.com and other services.
+    // ported from https://github.com/Esri/esri-leaflet/blob/master/src/Request.js#L22-L30
+    // also see https://github.com/Esri/arcgis-rest-js/issues/18:
+    // null, undefined, function are excluded. If you want to send an empty key you need to send an empty string "".
+    switch (type) {
+      case "Array":
+        // Based on the first element of the array, classify array as an array of arrays, an array of objects
+        // to be stringified, or an array of non-objects to be comma-separated
+        // eslint-disable-next-line no-case-declarations
+        const firstElementType = param[0]?.constructor?.name;
+        value =
+          firstElementType === "Array" ? param : // pass thru array of arrays
+          firstElementType === "Object" ? JSON.stringify(param) : // stringify array of objects
+          param.join(","); // join other types of array elements
+        break;
+      case "Object":
+        value = JSON.stringify(param);
+        break;
+      case "Date":
+        value = param.valueOf();
+        break;
+      case "Function":
+        value = null;
+        break;
+      case "Boolean":
+        value = param + "";
+        break;
+      default:
+        value = param;
+        break;
+    }
+    if (value || value === 0 || typeof value === "string" || Array.isArray(value)) {
+      newParams[key] = value;
+    }
+  });
+
+  return newParams;
+}

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

@@ -0,0 +1,10 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "./IRequestOptions.js";
+import { IAuthenticationManager } from "./IAuthenticationManager.js";
+
+export type IRetryAuthError = (
+  url: string,
+  options: IRequestOptions
+) => Promise<IAuthenticationManager>;

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

@@ -0,0 +1,11 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+/**
+ * Method used internally to surface messages to developers.
+ */
+export function warn(message: string) {
+  if (console && console.warn) {
+    console.warn.apply(console, [message]);
+  }
+}

package/packages/arcgis-rest-request/src/utils/with-options.ts

@@ -0,0 +1,48 @@
+import { IRequestOptions } from "../utils/IRequestOptions.js";
+
+/**
+ * Allows you to wrap individual methods with a default set of request options. This is useful to avoid setting the same option more then once and allows for interacting and setting defaults in a functional manner.
+ *
+ * ```js
+ * import { withOptions } from "@esri/arcgis-rest-request";
+ * import { queryFeatures } from '@esri/arcgis-rest-feature-service';
+ *
+ * const queryTrails = withOptions({
+ *   url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0/"}, queryFeatures);
+ *
+ * queryTrails({
+ *   where: "ELEV_FT > 1000"
+ * }).then(result);
+ *
+ * const queryTrailsAsUser = withOptions({
+ *   authentication: ArcGISIdentityManager
+ * }, queryTrails);
+ *
+ * queryTrailsAsUser({
+ *   where: "TRL_NAME LIKE '%backbone%'"
+ * }).then(result);
+ * ```
+ *
+ * @param defaultOptions The options to pass into to the `func`.
+ * @param func Any function that accepts anything extending `IRequestOptions` as its last parameter.
+ * @returns A copy of `func` with the `defaultOptions` passed in as defaults.
+ */
+export function withOptions<
+  K extends IRequestOptions,
+  T extends (...args: any[]) => any
+>(
+  defaultOptions: IRequestOptions,
+  func: T
+): (...funcArgs: Parameters<T>) => ReturnType<T> {
+  return (...args: Parameters<T>): ReturnType<T> => {
+    const options: K =
+      typeof args[args.length - 1] === "object"
+        ? {
+            ...defaultOptions,
+            ...args.pop()
+          }
+        : defaultOptions;
+
+    return func(...[...args, options]);
+  };
+}

package/packages/arcgis-rest-request/src/validate-app-access.ts

@@ -0,0 +1,69 @@
+/* Copyright (c) 2018-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "./request.js";
+import { IRequestOptions } from "./utils/IRequestOptions.js";
+
+export interface IAppAccess {
+  /**
+   * Verifies that the token is valid and the user has access to
+   * the specified app (clientId)
+   */
+  valid: boolean;
+  /**
+   * Should the app present the current user with a "View Only" mode
+   */
+  viewOnlyUserTypeApp: boolean;
+}
+
+/**
+ * Validates that the user has access to the application
+ * and if they user should be presented a "View Only" mode
+ *
+ * This is only needed/valid for Esri applications that are "licensed"
+ * and shipped in ArcGIS Online or ArcGIS Enterprise. Most custom applications
+ * should not need or use this.
+ *
+ * ```js
+ * import { validateAppAccess } from '@esri/arcgis-rest-auth';
+ *
+ * return validateAppAccess('your-token', 'theClientId')
+ * .then((result) => {
+ *    if (!result.value) {
+ *      // redirect or show some other ui
+ *    } else {
+ *      if (result.viewOnlyUserTypeApp) {
+ *        // use this to inform your app to show a "View Only" mode
+ *      }
+ *    }
+ * })
+ * .catch((err) => {
+ *  // two possible errors
+ *  // invalid clientId: {"error":{"code":400,"messageCode":"GWM_0007","message":"Invalid request","details":[]}}
+ *  // invalid token: {"error":{"code":498,"message":"Invalid token.","details":[]}}
+ * })
+ * ```
+ *
+ * Note: This is only usable by Esri applications hosted on *arcgis.com, *esri.com or within
+ * an ArcGIS Enterprise installation. Custom applications can not use this.
+ *
+ * @param token platform token
+ * @param clientId application client id
+ * @param portal Optional
+ */
+export function validateAppAccess(
+  token: string,
+  clientId: string,
+  portal = "https://www.arcgis.com/sharing/rest"
+): Promise<IAppAccess> {
+  const url = `${portal}/oauth2/validateAppAccess`;
+  const ro = {
+    method: "POST",
+    params: {
+      f: "json",
+      client_id: clientId,
+      token
+    }
+  } as IRequestOptions;
+  return request(url, ro);
+}

package/packages/arcgis-rest-request/test/ApiKey.test.ts

@@ -0,0 +1,53 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ApiKeyManager } from "../src/index.js";
+import fetchMock from "fetch-mock";
+
+describe("ApiKeyManager", () => {
+  afterEach(fetchMock.restore);
+
+  describe(".getToken()", () => {
+    it("should return the Api Key", (done) => {
+      const session = new ApiKeyManager({
+        key: "123456"
+      });
+
+      Promise.all([
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self"),
+        session.getToken(
+          "https://services1.arcgis.com/MOCK_ORG/arcgis/rest/services/Private_Service/FeatureServer"
+        )
+      ])
+        .then(([token1, token2]) => {
+          expect(token1).toBe("123456");
+          expect(token2).toBe("123456");
+          done();
+        })
+        .catch((e) => {
+          fail(e);
+        });
+    });
+  });
+
+  describe(".fromKey()", () => {
+    it("should create a new ApiKeyManager", (done) => {
+      const session = ApiKeyManager.fromKey("123456");
+
+      Promise.all([
+        session.getToken("https://www.arcgis.com/sharing/rest/portals/self"),
+        session.getToken(
+          "https://services1.arcgis.com/MOCK_ORG/arcgis/rest/services/Private_Service/FeatureServer"
+        )
+      ])
+        .then(([token1, token2]) => {
+          expect(token1).toBe("123456");
+          expect(token2).toBe("123456");
+          done();
+        })
+        .catch((e) => {
+          fail(e);
+        });
+    });
+  });
+});