sintfacilis 1.0.0

package/notes/README.md

@@ -0,0 +1,68 @@
+# Testing
+
+* Use `npm test` as normal to run all tests.
+* `npm test` will run `lerna run test` which will in turn will execute `npm test` in each package if it exists with the root of the package as the `process.cwd()`
+* Browser based tests are setup to run with Karma as a test runner as Jasmine as the testing framework. There is a common config that all packages can use in the root folder called `karma.conf.js`.
+* Node tests use the `jasmine` CLI tool. Each package will require a `jasmine.json` to tell jasmine where the test files are for that package. The `jasmine.json` should register the `support/register-tsnode.js` helper so TypeScript files are compiled before the tests execute.
+* Currently the Node tests take quite awhile. I think this is becuase the `ignore` param isn't being respected and thus the entirety of `node_modules` get processed by TypeScript. This needs to happen in order to make `lodash-es` work.
+
+# Build
+
+The build system currently builds for 3 seperate targets:
+
+* Common JS bundle for Node.js
+* A UMD bundle for CommonJS, AMD and a global variable for browsers
+* ES5 files in the ES2015 module syntax for use with Rollup and Webpack 2.
+
+Like with tests running `npm run build` will run `lerna run build` which will run `npm run build` in each package. Currently `npm run build:node` and `npm run build:umd` both use the shared rollup configurations in `rollup.config.*.js`. `npm run build:esm` uses a `tsconfig.json` file in the root of hte repo that extends the base `tsconfig.json` file. This `tsconfig.json` tells the Typescript compiler where to out the output files and generated `.d.ts` type declarations.
+
+These 4 outputs (2, rollup builds, ES2015 modules and type declarations) are referenced by their respective fields in `package.json`:
+
+```js
+{
+  // ...
+
+  "main": "dist/node/bundle.cjs.js",
+  "browser": "dist/browser/bundle.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+
+  // ...
+}
+```
+
+Currently we are bundling Node in order to use `lodash-es` as a utility library which needs to be bundled in.
+
+The ES2015 build also has the references to `form-data` and `url-search-params` removed. Rollup handles ignoring these in the UMD and CJS builds but TypeScript is not a bundler so these needed to be removed some other way. If we run into issues with sourcemaps this replacement process might need to be replaced by a custom script with [`magic-string`](https://github.com/Rich-Harris/magic-string).
+
+# Support files
+
+There are several general support files needed for various operations of the Typescript compiler to prevent errors:
+
+* `support/json.d.ts` - make the typescript compiler happy when you `import` JSON files `import * as sharingRestInfo from './mocks/sharing-rest-info.json';`
+* `support/lodash-es.d.ts` - currently `@types/lodash-es` has issues https://github.com/DefinitelyTyped/DefinitelyTyped/issues/15227 so this is an alternate typings file
+* `register-tsnode.js` - enables on-the-fly compilation of Typescript in Node.js, used by the Jasmine tests
+* `url-search-params.d.ts` - typings for the `url-search-params` module which is used to emulate `URLSearchParams` in Node.js
+
+# Doc system
+
+[Typedoc](https://github.com/TypeStrong/typedoc) leaves much to be desired figuring out how TypeDoc is organizing the source files is next to impossible and there is almost no doc. It does appear to be usable since project like Dojo 2 and Maquette use it however figuring out how to generate the docs in a struture that looks good is pretty beyond me after looking at it for a few hours.
+
+A potentially better option might be to just use JSDoc and work from the compiled ES2015 source. I will look into this later.
+
+# Release system
+
+This has moved to [RELEASE.md](../RELEASE.md).
+
+# Potential improvements
+
+* Finding a decent alternative to `lodash/defaults` without broken typings would be ideal. This forces all kinds of weirdness on us.
+* Figure out why the Node tests take so long (might be becuase of hacks needed for `lodash-es`) `lerna run test:node`
+* Since we are importing `lodash-es` we need to use `karma-typescript-es6-transform` to transform the ES2015 module syntax into CommonJS. We should look into if this is necessary at all (i.e. replace `lodash-es`) or think about replacing it with https://github.com/jlmakes/karma-rollup-preprocessor.
+
+# Thoughts
+
+Basic utility libraries are going to be a problem. Most recommendation are to use something like `import defaults = require('lodash/defaults')` because you are importing a common JS module. However if you use this syntax you cannot have Typescript compile ES2015 modules which is goal for us. Not every library publishes itself as ES2015 modules.
+
+We need to make a call on what we bundle into the library (`Promise`, `fetch`) ect... Do we ask people to bring their own polyfills or do we bundle them ourselves for simplicity. If we want to do both it will likely complicate the builds a great deal.

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "sintfacilis",
+  "version": "1.0.0",
+  "description": "Compact, modular JavaScript wrappers for the ArcGIS REST API that run in Node.js and modern browsers.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "npm": ">=7.0.0",
+    "node": ">=12.20.0"
+  },
+  "eslintIgnore": [
+    "packages/**/test",
+    "packages/**/dist"
+  ],
+  "lint-staged": {
+    "**/*/package.json": [
+      "prettier-package-json --write",
+      "git add"
+    ],
+    "*.ts": [
+      "prettier --write --parser typescript --tab-width 2 --use-tabs false",
+      "eslint",
+      "git add"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
+      "pre-commit": "npm run precommit"
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^11.0.0",
+    "@commitlint/config-conventional": "^11.0.0",
+    "@commitlint/config-lerna-scopes": "^11.0.0",
+    "@commitlint/prompt": "^11.0.0",
+    "@rollup/plugin-node-resolve": "^13.0.4",
+    "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^8.0.0",
+    "@skypack/package-check": "^0.2.2",
+    "@types/fetch-mock": "^6.0.6",
+    "@types/jasmine": "^2.8.2",
+    "@types/node": "^12.20.4",
+    "@typescript-eslint/eslint-plugin": "^4.4.0",
+    "@typescript-eslint/parser": "^4.31.0",
+    "acetate": "^2.0.8",
+    "acetate-cli": "^1.0.1",
+    "browser-sync": "^2.27.5",
+    "cheerio": "^1.0.0-rc.3",
+    "concurrently": "^3.5.1",
+    "cpx": "^1.5.0",
+    "cross-spawn": "^5.1.0",
+    "date-fns": "^1.29.0",
+    "dotenv": "^8.2.0",
+    "eslint": "^7.11.0",
+    "eslint-config-prettier": "^6.12.0",
+    "eslint-import-resolver-typescript": "^2.4.0",
+    "eslint-plugin-import": "^2.24.2",
+    "fetch-mock": "^5.13.1",
+    "gh-pages": "^1.1.0",
+    "gh-release": "^3.4.0",
+    "glob": "^7.1.7",
+    "globby": "^12.0.2",
+    "husky": "^4.3.0",
+    "jasmine": "^3.9.0",
+    "jasmine-core": "^3.9.0",
+    "karma": "^5.2.2",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-firefox-launcher": "^2.1.1",
+    "karma-jasmine": "^4.0.1",
+    "karma-jasmine-diff-reporter": "^2.0.0",
+    "karma-safari-launcher": "^1.0.0",
+    "karma-typescript": "^5.5.0",
+    "karma-typescript-es6-transform": "^5.5.0",
+    "lint-staged": "^4.3.0",
+    "minimatch": "^3.0.4",
+    "multi-semantic-release": "^2.11.0",
+    "npm-run-all": "^4.1.5",
+    "onchange": "^3.3.0",
+    "prettier": "^2.3.1",
+    "prettier-package-json": "^2.6.0",
+    "resolve": "^1.5.0",
+    "rimraf": "^2.6.2",
+    "rollup": "^2.56.3",
+    "rollup-plugin-filesize": "^9.0.2",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-typescript": "^1.0.1",
+    "sass": "^1.41.0",
+    "shelljs": "^0.7.8",
+    "slug": "^0.9.1",
+    "sri-toolbox": "0.2.0",
+    "trash-cli": "^4.0.0",
+    "ts-node": "^10.3.1",
+    "typedoc": "^0.21.0",
+    "typescript": "^4.0.0",
+    "ultra-runner": "^3.10.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EribertoLang/sintfacilis.git"
+  },
+  "workspaces": [
+    "packages/arcgis-rest-request",
+    "packages/arcgis-rest-auth",
+    "packages/arcgis-rest-demographics",
+    "packages/arcgis-rest-feature-service",
+    "packages/arcgis-rest-geocoding",
+    "packages/arcgis-rest-portal",
+    "packages/arcgis-rest-routing",
+    "packages/arcgis-rest-fetch",
+    "packages/arcgis-rest-form-data",
+    "./demos/*"
+  ],
+  "volta": {
+    "node": "16.13.0",
+    "npm": "8.1.2"
+  },
+  "release": {
+    "branches": [
+      "master",
+      {
+        "name": "beta",
+        "prerelease": true
+      }
+    ],
+    "tagFormat": "${name}@${version}",
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/git"
+    ]
+  },
+  "author": "AlannaDuBuque",
+  "bugs": {
+    "url": "https://github.com/EribertoLang/sintfacilis.git/issues"
+  },
+  "homepage": "https://github.com/EribertoLang/sintfacilis.git"
+}

package/packages/arcgis-rest-auth/README.md

@@ -0,0 +1,71 @@
+[![npm version][npm-img]][npm-url]
+[![build status][travis-img]][travis-url]
+[![gzip bundle size][gzip-image]][npm-url]
+[![Coverage Status][coverage-img]][coverage-url]
+[![apache licensed](https://img.shields.io/badge/license-Apache-green.svg?style=flat-square)](https://raw.githubusercontent.com/Esri/arcgis-rest-js/master/LICENSE)
+
+[npm-img]: https://img.shields.io/npm/v/@esri/arcgis-rest-auth.svg?style=flat-square
+[npm-url]: https://www.npmjs.com/package/@esri/arcgis-rest-auth
+[travis-img]: https://img.shields.io/travis/Esri/arcgis-rest-js/master.svg?style=flat-square
+[travis-url]: https://travis-ci.org/Esri/arcgis-rest-js
+[gzip-image]: https://img.badgesize.io/https://unpkg.com/@esri/arcgis-rest-auth/dist/umd/auth.umd.min.js?compression=gzip
+[coverage-img]: https://codecov.io/gh/Esri/arcgis-rest-js/branch/master/graph/badge.svg
+[coverage-url]: https://codecov.io/gh/Esri/arcgis-rest-js
+
+# @esri/arcgis-rest-auth
+
+> Authentication helpers for [`@esri/arcgis-rest-*`](https://github.com/Esri/arcgis-rest-js).
+
+### Example
+
+```bash
+npm install @esri/arcgis-rest-request
+npm install @esri/arcgis-rest-auth
+```
+
+```js
+import { UserSession } from '@esri/arcgis-rest-auth';
+
+const session = new UserSession({
+    username: "casey",
+    password: "123456"
+});
+```
+
+### [API Reference](https://esri.github.io/arcgis-rest-js/api/auth/)
+
+### Issues
+
+If something isn't working the way you expected, please take a look at [previously logged issues](https://github.com/Esri/arcgis-rest-js/issues) first.  Have you found a new bug?  Want to request a new feature?  We'd [**love**](https://github.com/Esri/arcgis-rest-js/issues/new) to hear from you.
+
+If you're looking for help you can also post issues on [GIS Stackexchange](http://gis.stackexchange.com/questions/ask?tags=esri-oss).
+
+### Versioning
+
+For transparency into the release cycle and in striving to maintain backward compatibility, @esri/arcgis-rest-js is maintained under Semantic Versioning guidelines and will adhere to these rules whenever possible.
+
+For more information on SemVer, please visit <http://semver.org/>.
+
+### Contributing
+
+Esri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](CONTRIBUTING.md).
+
+### [Changelog](https://github.com/Esri/arcgis-rest-js/blob/master/CHANGELOG.md)
+
+### License
+
+Copyright &copy; 2017-2019 Esri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+> http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+A copy of the license is available in the repository's [LICENSE](../../LICENSE) file.

package/packages/arcgis-rest-auth/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@esri/arcgis-rest-auth",
+  "version": "3.3.0",
+  "description": "Authentication helpers for @esri/arcgis-rest-js.",
+  "main": "dist/node/index.js",
+  "unpkg": "dist/umd/auth.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "sideEffects": false,
+  "types": "dist/esm/index.d.ts",
+  "license": "Apache-2.0",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "@esri/arcgis-rest-types": "^3.3.0",
+    "tslib": "^1.13.0"
+  },
+  "devDependencies": {
+    "@esri/arcgis-rest-request": "^3.3.0"
+  },
+  "peerDependencies": {
+    "@esri/arcgis-rest-request": "^3.0.0"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "prebuild": "rimraf dist",
+    "build": "npm run build:node && npm run build:umd && npm run build:esm",
+    "build:esm": "tsc --module es2015 --outDir ./dist/esm --declaration",
+    "build:umd": "rollup -c ../../umd-base-profile.js && rollup -c ../../umd-production-profile.js",
+    "build:node": "tsc --module commonjs --outDir ./dist/node",
+    "dev:esm": "tsc -w --module es2015 --outDir ./dist/esm --declaration",
+    "dev:umd": "rollup -w -c ../../umd-base-profile.js",
+    "dev:node": "tsc -w --module commonjs --outDir ./dist/node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esri/arcgis-rest-js.git",
+    "directory": "packages/arcgis-rest-auth"
+  },
+  "contributors": [
+    {
+      "name": "Patrick Arlt",
+      "email": "parlt@esri.com",
+      "url": "http://patrickarlt.com/"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/Esri/arcgis-rest-js/issues"
+  },
+  "homepage": "https://github.com/Esri/arcgis-rest-js#readme",
+  "keywords": [
+    "typescript",
+    "promise",
+    "fetch",
+    "arcgis",
+    "esri",
+    "ES6"
+  ],
+  "esri": {
+    "keyExports": [
+      "UserSession",
+      "ApplicationSession"
+    ]
+  }
+}

package/packages/arcgis-rest-auth/post-message-auth-spec.md

@@ -0,0 +1,70 @@
+# Post Message Authentication Specification
+
+The general idea is that the HOST application will only respond when the following conditions are true:
+
+- the event.origin is a location that the HOST trusts
+- the message type is `arcgis:auth:requestCredential`
+
+Under any other conditions, the HOST application will not send any response.
+
+## Message Types
+
+Messages send via `postMessage` can be any object, but by convention usually have a `type` property that describes what sort of message it is.
+
+| Type                            | Description                                                                                                        |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `arcgis:auth:requestCredential` | Request credential from host app. Request will be rejected if the `event.origin` is not in the `validOrigins` list |
+| `arcgis:auth:credential`        | Returning the credential in `event.credential`                                                                     |
+| `arcgis:auth:error`             | Returned if the host declines to send credentials. `event.message` will contain the reason                         |
+
+# Message Details
+
+## `arcgis:auth:requestCredential`
+
+Sent from an embedded app, to the parent.
+
+Message Object
+
+```json
+{
+  "type": "arcgis:auth:requestCredential"
+}
+```
+
+## `arcgis:auth:credential`
+
+Send from the host app to the embedded app.
+
+- Embedded application is responsible for calling `exchangeToken` or `validateAppAccess`
+
+Message Object
+
+```json
+{
+  "type": "arcgis:auth:credential",
+  "credential": {
+    "token": "thetoken",
+    "userId": "jsmith",
+    "server": "https://www.arcgis.com",
+    "ssl": true,
+    "expires": 1599831467093
+  }
+}
+```
+
+## `arcgis:auth:error`
+
+Sent from an host app, to an embedded app, with an error indicating why.
+This will only be sent if the HOST app has some issue getting the credential.
+
+Message Object
+
+```json
+{
+  "type": "arcgis:auth:error",
+  "error": {
+    "name": "<error name>",
+    "message": "<reason etc>"
+  }
+}
+```

package/packages/arcgis-rest-auth/src/ApiKey.ts

@@ -0,0 +1,41 @@
+/* Copyright (c) 2017-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  IAuthenticationManager,
+} from "@esri/arcgis-rest-request";
+
+/**
+ * Options for the `ApiKey` constructor.
+ */
+export interface IApiKeyOptions {
+  key: string;
+}
+
+/**
+ * ```js
+ * import { ApiKey } from '@esri/arcgis-rest-auth';
+ * const apiKey = new ApiKey("...");
+ * ```
+ * Used to authenticate with API Keys.
+ */
+export class ApiKey implements IAuthenticationManager {
+
+  /**
+   * The current portal the user is authenticated with.
+   */
+  public readonly portal: string;
+
+  private key: string;
+
+  constructor(options: IApiKeyOptions) {
+    this.key = options.key;
+  }
+
+  /**
+   * Gets a token (the API Key).
+   */
+  public getToken(url: string) {
+    return Promise.resolve(this.key);
+  }
+}

package/packages/arcgis-rest-auth/src/ApplicationSession.ts

@@ -0,0 +1,122 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  IAuthenticationManager,
+  ITokenRequestOptions
+} from "@esri/arcgis-rest-request";
+import { fetchToken } from "./fetch-token";
+
+export interface IApplicationSessionOptions {
+  /**
+   * Client ID of your application. Can be obtained by registering an application
+   * on [ArcGIS for Developers](https://developers.arcgis.com/documentation/core-concepts/security-and-authentication/signing-in-arcgis-online-users/#registering-your-application),
+   * [ArcGIS Online](http://doc.arcgis.com/en/arcgis-online/share-maps/add-items.htm#ESRI_SECTION1_0D1B620254F745AE84F394289F8AF44B) or on your instance of ArcGIS Enterprise.
+   */
+  clientId: string;
+
+  /**
+   * A Client Secret is also obtained by registering an application
+   * on [ArcGIS for Developers](https://developers.arcgis.com/documentation/core-concepts/security-and-authentication/signing-in-arcgis-online-users/#registering-your-application),
+   * [ArcGIS Online](http://doc.arcgis.com/en/arcgis-online/share-maps/add-items.htm#ESRI_SECTION1_0D1B620254F745AE84F394289F8AF44B) or on your instance of ArcGIS Enterprise. Treat it like a password.
+   */
+  clientSecret: string;
+
+  /**
+   * OAuth 2.0 access token from a previous application session.
+   */
+  token?: string;
+
+  /**
+   * Expiration date for the `token`
+   */
+  expires?: Date;
+
+  /**
+   * URL of ArcGIS REST base, defaults to "https://www.arcgis.com/sharing/rest"
+   */
+  portal?: string;
+
+  /**
+   * Duration of requested tokens in minutes. defaults to 7200 (5 days).
+   */
+  duration?: number;
+}
+
+/**
+ * ```js
+ * import { ApplicationSession } from '@esri/arcgis-rest-auth';
+ * const session = new ApplicationSession({
+ *   clientId: "abc123",
+ *   clientSecret: "sshhhhhh"
+ * })
+ * // visit https://developers.arcgis.com to generate your own clientid and secret
+ * ```
+ * You can use [App Login](/arcgis-rest-js/guides/node/) to access premium content and services in ArcGIS Online.
+ *
+ */
+export class ApplicationSession implements IAuthenticationManager {
+  public portal: string;
+  private clientId: string;
+  private clientSecret: string;
+  private token: string;
+  private expires: Date;
+  private duration: number;
+
+  /**
+   * Internal object to keep track of pending token requests. Used to prevent
+   *  duplicate token requests.
+   */
+  private _pendingTokenRequest: Promise<string>;
+
+  constructor(options: IApplicationSessionOptions) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.token = options.token;
+    this.expires = options.expires;
+    this.portal = options.portal || "https://www.arcgis.com/sharing/rest";
+    this.duration = options.duration || 7200;
+  }
+
+  // URL is not actually read or passed through.
+  public getToken(
+    url: string,
+    requestOptions?: ITokenRequestOptions
+  ): Promise<string> {
+    if (this.token && this.expires && this.expires.getTime() > Date.now()) {
+      return Promise.resolve(this.token);
+    }
+
+    if (this._pendingTokenRequest) {
+      return this._pendingTokenRequest;
+    }
+
+    this._pendingTokenRequest = this.refreshToken(requestOptions);
+
+    return this._pendingTokenRequest;
+  }
+
+  public refreshToken(requestOptions?: ITokenRequestOptions): Promise<string> {
+    const options = {
+      params: {
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
+        grant_type: "client_credentials",
+        expiration: this.duration
+      },
+      ...requestOptions
+    };
+    return fetchToken(`${this.portal}/oauth2/token/`, options).then(
+      response => {
+        this._pendingTokenRequest = null;
+        this.token = response.token;
+        this.expires = response.expires;
+        return response.token;
+      }
+    );
+  }
+
+  public refreshSession() {
+    return this.refreshToken().then(() => this);
+  }
+}