autnam 1.0.0

package/demos/webmap-checker-sapper/src/routes/auth/authorize.js

@@ -0,0 +1,18 @@
+import { UserSession } from "@esri/arcgis-rest-request";
+
+// setup config variables
+require("dotenv").config();
+const { CLIENT_ID, REDIRECT_URI } = process.env;
+
+// when a user access /auth/authorize we will allow
+// UserSession.authorize to handle the response and
+// redirect a user to the oAuth sign in page.
+export function get(request, response, next) {
+  UserSession.authorize(
+    {
+      clientId: CLIENT_ID,
+      redirectUri: REDIRECT_URI
+    },
+    response
+  );
+}

package/demos/webmap-checker-sapper/src/routes/auth/exchange-token.js

@@ -0,0 +1,20 @@
+// if a token expires on the client side we don't have to ask then to log in
+// again. Instead we can maek a request to /auth/exchange-token. Since this
+// request will be same-domain this request will get the session cookie and
+// can hydrate request.session.userSession which we can then refresh getting a
+// new token which can be used on the client.
+export function get(request, response, next) {
+  request.session.userSession
+    .refreshSession()
+    .then(newSession => {
+      request.session.userSession = newSession;
+      const serializedSession = newSession.toJSON();
+      delete serializedSession.refreshToken;
+      delete serializedSession.refreshTokenExpires;
+      response.json(serializedSession);
+    })
+    .catch(error => {
+      console.error(error);
+      response.json(error);
+    });
+}

package/demos/webmap-checker-sapper/src/routes/auth/post-sign-in.js

@@ -0,0 +1,24 @@
+import { UserSession } from "@esri/arcgis-rest-request";
+
+// setup config variables
+require("dotenv").config();
+const { CLIENT_ID, REDIRECT_URI } = process.env;
+debugger;
+// a user will be redirected to /auth/post-sign-in after completing the sign in
+// form in ArcGIS Online. We will allow UserSession.exchangeAuthorizationCode to
+// trade the oAuth authorization code for a token and create a user session.
+// We can then add that user session to the request.
+export async function get(request, response, next) {
+  // exchange the auth token for a full `UserSession`
+  request.session.userSession = await UserSession.exchangeAuthorizationCode(
+    {
+      clientId: CLIENT_ID,
+      redirectUri: REDIRECT_URI
+    },
+    request.query.code
+  );
+
+  // once we have the session set redirect the user to the /webmaps
+  // route so they can use the app.
+  response.redirect("/webmaps");
+}

package/demos/webmap-checker-sapper/src/routes/auth/sign-out.js

@@ -0,0 +1,10 @@
+// to sign a user out we have to destroy their session which will
+// remove the encrypted file from disk and clear the session cookie
+export function get(request, response, next) {
+  request.session.destroy(function(err) {
+    response.cookie("webmap-checker-session", { maxAge: 2592000000 });
+
+    // redirect user user to the homepag when we are done.
+    response.redirect("/");
+  });
+}

package/demos/webmap-checker-sapper/src/routes/index.html

@@ -0,0 +1,20 @@
+<svelte:head>
+  <title>Web Map Dependency Checker</title>
+</svelte:head>
+<!-- The $ prefix tells sapper to load this from the global store-->
+{#if $session}
+<p>
+  Signed in as {$session.username}
+  <a
+    href="webmaps"
+    class="inline-block px-6 py-3 leading-none border rounded text-teal border-teal hover:border-dark-teal hover:text-dark-teal hover:bg-white mt-1"
+    >View web maps</a
+  >
+</p>
+{:else}
+<a
+  href="/auth/authorize"
+  class="inline-block px-6 py-3 leading-none border rounded text-teal border-teal hover:border-dark-teal hover:text-dark-teal hover:bg-white mt-1"
+  >Sign in to get started</a
+>
+{/if}

package/demos/webmap-checker-sapper/src/routes/webmaps/[webmapId].html

@@ -0,0 +1,83 @@
+<a href="./webmaps" class="text-blue">Back to list</a>
+
+<h2>{item.title}</h2>
+<p class="mb-4">Sharing Status: {item.access}</p>
+
+<!-- show a preview of the webmap -->
+{#if item}
+  <WebMap itemId="{item.id}" />
+{/if}
+
+<ul class="list-reset">
+  {#each layers as layer}
+  <li class="py-2">
+    <!-- show a list of layers and their statuses -->
+    <LayerStatus title="{layer.title}" itemId="{layer.itemId}" url="{layer.url}" serviceStatus="unknown" />
+  </li>
+  {/each}
+</ul>
+
+<pre class="max-w p-6 border border-grey-light rounded overflow-scroll shadow-lg">{webmapText}</pre>
+
+<script>
+  import { UserSession } from "@esri/arcgis-rest-auth";
+  import { getItem, getItemData } from "@esri/arcgis-rest-portal";
+  import { retryWithNewSession } from "../../utils.js";
+  import LayerStatus from "../../components/LayerStatus.html";
+  import WebMap from "../../components/WebMap.html";
+
+  export default {
+    components: {
+      LayerStatus,
+      WebMap
+    },
+    // preload runs on the server to generate the inital state of the page and
+    // when a user navigates on the client to create the new view of the page.
+    // We can use arcgis-rest-js here to preload data.
+    preload({ params }) {
+      const { session } = this.store.get();
+
+      // redirect to the homepage unless the user is signed in
+      if (!session) {
+        this.redirect(302, "/");
+        return;
+      }
+
+      const { webmapId } = params;
+
+      // if we are on the server we won't have an actual UserSession just a
+      // JSON representation of one. So we need to hydrate a UserSession.
+      const userSession = process.browser ? session : new UserSession(session);
+
+      // next we can request both the webmap item and the webmap data (the JSON)
+      // and process the data to get a list of layers.
+      return Promise.all([
+        getItem(webmapId, {
+          authentication: userSession
+        }).catch(error => {
+          return retryWithNewSession(error, this.fetch);
+        }),
+        getItemData(webmapId, {
+          authentication: userSession
+        }).catch(error => {
+          return retryWithNewSession(error, this.fetch);
+        })
+      ]).then(([item, webmap]) => {
+        const layers = webmap.operationalLayers
+          .concat(webmap.baseMap.baseMapLayers)
+          .map(layer => {
+            return {
+              title: layer.title || layer.id,
+              url: layer.url,
+              itemId: layer.itemId
+            };
+          });
+        return {
+          item,
+          webmapText: JSON.stringify(webmap, null, 2),
+          layers: layers
+        };
+      });
+    }
+  };
+</script>

package/demos/webmap-checker-sapper/src/routes/webmaps/index.html

@@ -0,0 +1,59 @@
+<h1>Webmaps</h1>
+
+<ul class="list-reset">
+  {#each webmaps as webmap}
+  <li class="py-2">
+    <a href="webmaps/{webmap.id}" class="text-blue">{webmap.title}</a>
+  </li>
+  {/each}
+</ul>
+
+<script>
+  import { UserSession } from "@esri/arcgis-rest-request";
+  import { searchItems } from "@esri/arcgis-rest-portal";
+  import { retryWithNewSession } from "../../utils.js";
+
+  export default {
+    // preload runs on the server to generate the inital state of the page and
+    // when a user navigates on the client to create the new view of the page.
+    // We can use arcgis-rest-js here to preload data.
+    preload() {
+      const { session } = this.store.get();
+
+      // redirect to the homepage unless the user is signed in
+      if (!session) {
+        this.redirect(302, "/");
+        return;
+      }
+
+      // if we are on the server we won't have an actuall UserSession just a
+      // JSON representation of one. So we need to hydrate a UserSession.
+      const userSession = process.browser ? session : new UserSession(session);
+
+      // now we can search for webmaps. Sapper will wait until this promise
+      // resolves before rendering the page.
+      return (
+        searchItems({
+          q: `owner:${session.username} type:"Web Map"`,
+          num: 100,
+          authentication: userSession
+        })
+          // if there is an error we can retry the request with a fresh session
+          // from /auth/exchange-token
+          .catch(error => {
+            return retryWithNewSession(error, this.fetch);
+          })
+          // then we can process out response.
+          .then(response => {
+            return {
+              webmaps: response.results
+            };
+          })
+
+          .catch(error => {
+            console.error(error);
+          })
+      );
+    }
+  };
+</script>

package/demos/webmap-checker-sapper/src/server.js

@@ -0,0 +1,102 @@
+import sirv from "sirv";
+import express from "express";
+import session from "express-session";
+import compression from "compression";
+import * as sapper from "../__sapper__/server.js";
+import SessionFileStore from "session-file-store";
+
+import { UserSession } from "@esri/arcgis-rest-request";
+import { Store } from "svelte/store.js";
+import { userInfoMiddleware } from "./userInfoMiddleware";
+
+// setup file storeage for user sessions
+const FileStore = SessionFileStore(session);
+
+// load and setup our config variables from out .env file
+require("dotenv").config();
+const { PORT, NODE_ENV, ENCRYPTION_KEY, SESSION_SECRET } = process.env;
+const dev = NODE_ENV === "development";
+
+// start express
+express()
+  // configure express middleware
+  .use(
+    // compress responses
+    compression({ threshold: 0 }),
+
+    // serve static assets like images, css ect...
+    sirv("static", { dev }),
+
+    // setup sessions, express will set a cookie on the client
+    // to keep track of a session id and rehydrate the
+    // correstponding session on the server.
+    session({
+      name: "webmap-checker-session",
+      secret: SESSION_SECRET,
+      resave: false,
+      saveUninitialized: false,
+      cookie: {
+        maxAge: 2592000000 // 30 days in milliseconds
+      },
+
+      // store session data in a secure, encrypted file
+      // sessions will be loaded from these files and decrypted
+      // at the end of every request the state of `request.session`
+      // will be saved back to disk.
+      store: new FileStore({
+        ttl: 2592000000 / 1000, // 30 days in seconds
+        retries: 1,
+        secret: ENCRYPTION_KEY,
+
+        // custom encoding and decoding for sessions means we can
+        // initalize a single `UserSession` object for use with rest js
+        encoder: (sessionObj) => {
+          sessionObj.userSession = sessionObj.userSession.serialize();
+          return JSON.stringify(sessionObj);
+        },
+        decoder: (sessionContents) => {
+          const sessionObj = JSON.parse(sessionContents);
+          if (sessionObj.userSession) {
+            sessionObj.userSession = UserSession.deserialize(
+              sessionObj.userSession
+            );
+          }
+
+          return sessionObj;
+        }
+      })
+    }),
+
+    // next check for a session and if we have one fetch additional information
+    // the rest api for use in our app.
+    userInfoMiddleware,
+
+    // finally we can setup sapper by creating a Store that will syncronize
+    // server side data with the client
+    sapper.middleware({
+      store: (request) => {
+        let userSession;
+
+        // since the store is shared between the client and server
+        // we dont want to put refresh tokens in it. The store also needs to be
+        // in a serializable format so sapper and send it to the client.
+        if (request.session && request.session.userSession) {
+          userSession = request.session.userSession.toJSON();
+          delete userSession.refreshToken;
+          delete userSession.refreshTokenExpires;
+        }
+
+        // now we can initalize the store with our session (from the encrypted
+        // file) and the org and user info which userInfoMiddleware attached to
+        // the request object.
+        return new Store({
+          session: userSession,
+          user: request.session ? request.session.userInfo : undefined,
+          org: request.session ? request.session.orgInfo : undefined
+        });
+      }
+    })
+  )
+  .listen(PORT, (err) => {
+    if (err) console.log("error", err);
+  });

package/demos/webmap-checker-sapper/src/service-worker.js

@@ -0,0 +1,82 @@
+import { timestamp, files, shell, routes } from '../__sapper__/service-worker.js';
+
+const ASSETS = `cache${timestamp}`;
+
+// `shell` is an array of all the files generated by the bundler,
+// `files` is an array of everything in the `static` directory
+const to_cache = shell.concat(files);
+const cached = new Set(to_cache);
+
+self.addEventListener('install', event => {
+	event.waitUntil(
+		caches
+			.open(ASSETS)
+			.then(cache => cache.addAll(to_cache))
+			.then(() => {
+				self.skipWaiting();
+			})
+	);
+});
+
+self.addEventListener('activate', event => {
+	event.waitUntil(
+		caches.keys().then(async keys => {
+			// delete old caches
+			for (const key of keys) {
+				if (key !== ASSETS) await caches.delete(key);
+			}
+
+			self.clients.claim();
+		})
+	);
+});
+
+self.addEventListener('fetch', event => {
+	if (event.request.method !== 'GET' || event.request.headers.has('range')) return;
+
+	const url = new URL(event.request.url);
+
+	// don't try to handle e.g. data: URIs
+	if (!url.protocol.startsWith('http')) return;
+
+	// ignore dev server requests
+	if (url.hostname === self.location.hostname && url.port !== self.location.port) return;
+
+	// always serve static files and bundler-generated assets from cache
+	if (url.host === self.location.host && cached.has(url.pathname)) {
+		event.respondWith(caches.match(event.request));
+		return;
+	}
+
+	// for pages, you might want to serve a shell `index.html` file,
+	// which Sapper has generated for you. It's not right for every
+	// app, but if it's right for yours then uncomment this section
+	/*
+	if (url.origin === self.origin && routes.find(route => route.pattern.test(url.pathname))) {
+		event.respondWith(caches.match('/index.html'));
+		return;
+	}
+	*/
+
+	if (event.request.cache === 'only-if-cached') return;
+
+	// for everything else, try the network first, falling back to
+	// cache if the user is offline. (If the pages never change, you
+	// might prefer a cache-first approach to a network-first one.)
+	event.respondWith(
+		caches
+			.open(`offline${timestamp}`)
+			.then(async cache => {
+				try {
+					const response = await fetch(event.request);
+					cache.put(event.request, response.clone());
+					return response;
+				} catch(err) {
+					const response = await cache.match(event.request);
+					if (response) return response;
+
+					throw err;
+				}
+			})
+	);
+});

package/demos/webmap-checker-sapper/src/template.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html>
+<head>
+	<meta charset='utf-8'>
+	<meta name='viewport' content='width=device-width'>
+	<meta name='theme-color' content='#aa1e1e'>
+
+	%sapper.base%
+
+	<link rel='stylesheet' href='global.css'>
+	<link rel='manifest' href='manifest.json'>
+	<link rel='icon' type='image/png' href='favicon.png'>
+
+	<!-- Sapper generates a <style> tag containing critical CSS
+	     for the current page. CSS for the rest of the app is
+	     lazily loaded when it precaches secondary pages -->
+	%sapper.styles%
+
+	<!-- This contains the contents of the <svelte:head> component, if
+	     the current page has one -->
+	%sapper.head%
+</head>
+<body>
+	<!-- The application will be rendered inside this element,
+	     because `app/client.js` references it -->
+	<div id='app'>%sapper.html%</div>
+
+	<!-- Sapper creates a <script> tag containing `app/client.js`
+	     and anything else it needs to hydrate the app and
+	     initialise the router -->
+	%sapper.scripts%
+</body>
+</html>

package/demos/webmap-checker-sapper/src/userInfoMiddleware.js

@@ -0,0 +1,21 @@
+// we could use UserSession.getUser() instead
+import { getSelf, getUser } from "@esri/arcgis-rest-portal";
+
+// this middleware checks for a session and if we find a session add
+// additional info to that session from the getUser and getSelf calls
+// request here is the incoming request in express.
+export function userInfoMiddleware(incomingRequest, outgoingResponse, next) {
+  if (incomingRequest.session && incomingRequest.session.userSession) {
+    Promise.all([
+      getUser({ authentication: incomingRequest.session.userSession }),
+      getSelf({ authentication: incomingRequest.session.userSession })
+    ]).then(([userInfo, orgInfo]) => {
+      // add information to the request so the next middleware can access it
+      incomingRequest.session.userInfo = userInfo;
+      incomingRequest.session.orgInfo = orgInfo;
+      next(); // run the next middleware
+    });
+  } else {
+    next(); // run the next middleware
+  }
+}

package/demos/webmap-checker-sapper/src/utils.js

@@ -0,0 +1,33 @@
+import { UserSession } from "@esri/arcgis-rest-auth";
+import { loadModules } from "esri-loader";
+
+export function retryWithNewSession(error, fetch) {
+  if (error.name === "ArcGISAuthError") {
+    return fetch("/auth/exchange-token")
+      .then(exchangeTokenResponse => {
+        return exchangeTokenResponse.json();
+      })
+      .then(sessionInfo => {
+        console.log(sessionInfo);
+        const newSession = new UserSession(session);
+
+        // if we are in a browser (client side) we are working with an instance
+        // of `UserSession` otherwise (server side) we are working with a JSON
+        // representation of a session.
+        if (process.browser) {
+          this.store.set({ session: newSession });
+
+          // if we are in a browser we should also update IdentityManager
+          loadModules(["esri/identity/IdentityManager"]).then(([esriId]) => {
+            esriId.registerToken(session.toCredential());
+          });
+        } else {
+          this.store.set({ session: sessionInfo });
+        }
+
+        return error.retry(newSession, 1);
+      });
+  }
+
+  throw error;
+}

package/demos/webmap-checker-sapper/static/global.css

@@ -0,0 +1,36 @@
+body {
+	margin: 0;
+	font-family: Roboto, -apple-system, BlinkMacSystemFont, Segoe UI, Oxygen, Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+	font-size: 14px;
+	line-height: 1.5;
+	color: #333;
+}
+
+h1, h2, h3, h4, h5, h6 {
+	margin: 0 0 0.5em 0;
+	font-weight: 400;
+	line-height: 1.2;
+}
+
+h1 {
+	font-size: 2em;
+}
+
+a {
+	color: inherit;
+}
+
+code {
+	font-family: menlo, inconsolata, monospace;
+	font-size: calc(1em - 2px);
+	color: #555;
+	background-color: #f0f0f0;
+	padding: 0.2em 0.4em;
+	border-radius: 2px;
+}
+
+@media (min-width: 400px) {
+	body {
+		font-size: 16px;
+	}
+}

package/demos/webmap-checker-sapper/static/manifest.json

@@ -0,0 +1,20 @@
+{
+	"background_color": "#ffffff",
+	"theme_color": "#aa1e1e",
+	"name": "TODO",
+	"short_name": "TODO",
+	"display": "minimal-ui",
+	"start_url": "/",
+	"icons": [
+		{
+			"src": "svelte-logo-192.png",
+			"sizes": "192x192",
+			"type": "image/png"
+		},
+		{
+			"src": "svelte-logo-512.png",
+			"sizes": "512x512",
+			"type": "image/png"
+		}
+	]
+}

package/docs/.eslintrc.js

@@ -0,0 +1,12 @@
+/* eslint-env node */
+module.exports = {
+    root: true,
+    env: {
+      node: true,
+      es6: true
+    },
+    extends: [
+      'eslint:recommended',
+      'prettier',
+    ]
+  };

package/docs/FAQ.md

@@ -0,0 +1,48 @@
+## Is this a _supported_ Esri product?
+
+With the release of ArcGIS Platform in January 2021, Esri is now officially supporting ArcGIS REST JS. Documentation is available on [ArcGIS Developer](https://developers.arcgis.com/arcgis-rest-js/) and [Esri Technical Support](https://support.esri.com/en/contact-tech-support) will respond to support incidents for developers with a technical support plan.
+
+This project is still an open source collaboration between developers from a variety of teams at Esri that was initially developed to scratch an itch of our own. We welcome outside contributors and fully expect that the tools here will be useful to any developer looking to integrate ArcGIS Platform services into their apps.
+
+## Comparison with the ArcGIS API for JavaScript
+
+The [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/) is Esri's flagship product for building web applications to visualize, edit, map and analyze geospatial data. It is a feature complete client side API for working with the REST services based on ArcGIS Platform.
+The ArcGIS API for JavaScript includes significant client side functionality including smart mapping, 3D rendering, geometric analysis and feature editing as well as full support for working with web maps and web scenes.
+
+The goal of this project on the other hand is to provide a convenient binding to the underlying REST APIs for those who need to work directly with it from JavaScript. This project includes functional equivalents of the low-level request methods and identity management in the ArcGIS API for JavaScript, along with additional thin wrappers to assist developers in scripting against the ArcGIS REST APIs directly in Node.js and browser applications that do _not_ render a map.
+
+We aim to make interacting with the platform as intuitive as possible, but the surface area of the project currently does not nearly encompass the entirety of the ArcGIS REST APIs.
+
+## Comparison with the ArcGIS API for Python
+
+This project is similar to the [ArcGIS API for Python](https://developers.arcgis.com/python/) in many ways. Like the ArcGIS API for Python, this library aims to be a scripting tool that simplifies interacting with the ArcGIS REST API, but where the ArcGIS API for Python highlights integration with dataframes and Jupyter Notebooks for visualization and sharing this project provides only generic tools for JavaScript applications running on a server, CLI, in a browser or as a script.
+
+## Who is using these packages?
+
+REST JS is trusted in ArcGIS applications serving **many** thousands of users.
+
+* ArcGIS [Hub](https://hub.arcgis.com)
+* ArcGIS [Developer](https://developers.arcgis.com)
+* ArcGIS [Storymaps](https://storymaps.arcgis.com/en/)
+* ArcGIS [Solutions](https://solutions.arcgis.com/)
+* ArcGIS Enterprise
+* ArcGIS [Urban](https://www.esri.com/en-us/landing-page/product/2018/arcgis-urban)
+* ArcGIS [Analytics for IoT](https://www.esri.com/en-us/landing-page/product/2018/arcgis-analytics-for-iot)
+
+And since its on GitHub, Esri developers are _far_ from the only ones using ArcGIS REST JS. Besides the usual culprits, we've seen the library running in:
+
+* [Chrome Extensions](https://chrome.google.com/webstore/detail/echo-for-arcgis/mkeckgendkgcofhhenfkknonnkoboobm?hl=en-US)
+* [Lambda Functions](https://medium.com/@adamjpfister/know-your-apis-6dc6ea3d084c)
+* [Web Components](https://github.com/esridc/hub-components)
+* [React Components](https://twitter.com/oppoudel/status/1022209378378805249)
+* [Observable](https://observablehq.com/@jgravois/introduction-to-esri-arcgis-rest-js)
+
+## Why TypeScript
+
+Using TypeScript allows us to add type information to request params and response structures. This vastly simplifies development. TypeScript also has excellent support for newer `async`/`await` patterns and for generating API documentation with [TypeDoc](http://typedoc.org/).
+
+TypeScript compiles to JavaScript so you can use @esri/arcgis-rest-js in any JavaScript project. However if you use TypeScript you will get the benefits of type checking for free.
+
+We also _really_ like TypeScript because it supports exporting to both [ES 2015 modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) (use `import`/`export`) and [UMD](http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/) modules. This allows us to support a wide variety of module loaders and bundlers, including Browserify, Webpack, RequireJS, and Dojo 1 and 2.
+
+We include [`tslib`](https://www.npmjs.com/package/tslib) as a dependency of individual npm packages to make usage of `_extends` and `_assign` in our compiled code more concise.