docs(ago node-cli): add node-cli demo to search ago

AFFECTS PACKAGES:
node-cli

demos/ago-node-cli/README.md

@@ -0,0 +1,29 @@
+# Node CLI Examples
+
+This demo shows how to create a command-line application that interacts with the ArcGIS Online API.
+
+At this point, the commands are very simple and intended to demonstrate how to build up tooling.
+
+This project uses the `commander` module, which streamlines the creation of node cli applications. Check out the [README](https://github.com/tj/commander.js/blob/master/Readme.md) for more details.
+
+### Installing
+
+Like all the other demo apps, run `npm run bootstrap` from the root.
+
+### Running
+If you use this demo as a starting point for your own command line package, you would publish it to npm, then on the target systems run `npm install <your-cli-package>`, and it would be available as a command.
+
+But, this is demo code, and thus the package is not "installed" via `npm install ...`, before we can call it as `ago <command> <query>` we need to run `npm link` in the `/demos/node-cli` folder. After you do that, the command should work.
+
+Here is a post with information on creating node command line tools: [A Guide to Creating a NodeJs Command](https://x-team.com/blog/a-guide-to-creating-a-nodejs-command/)
+
+### Commands
+
+| command | description | example |
+| --- | --- | --- |
+| `ago search <query>` | search for items | `ago search water` |
+| `ago export <id> <file>` | export an item to a json file | `ago export a62cb9d894f145cc89531c096d0012b1 pa.json` |
+
+## Building your own tooling
+
+If you want to build out some commands of your own, you can also clone a stand-alone version of this repo from https://github.com/dbouwman/arcgis-rest-js-commands

demos/ago-node-cli/ago.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+require('isomorphic-fetch');
+require('isomorphic-form-data');
+/**
+ * This demo uses the commander module, which streamlines the creation of command-line-applications
+ */
+const program = require('commander');
+
+program
+  .version('0.0.1');
+
+/**
+ * Bring in the search command...
+ */
+const itemSearchCommand = require('./lib/item-search-command');
+
+program
+  .command('search <query>')
+  .description('Search for items')
+  .action(function (query) {
+    itemSearchCommand.execute(query);
+  });
+
+  const itemExportCommand = require('./lib/item-export-command');
+  program
+  .command('export <itemId> <filename>')
+  .description('Export an item to a json file')
+  .action(function (id, filename) {
+    itemExportCommand.execute(id, filename);
+  });
+
+program.parse(process.argv);

demos/ago-node-cli/index.js

@@ -0,0 +1,11 @@
+/**
+ * Re-export the commands so they can be used in other contexts
+ */
+const itemSearchCommand = require('./lib/item-search-command');
+const itemExportCommand = require('./lib/item-export-command');
+
+// just re-export the commands so they can be run in another scropt
+module.exports = {
+  search: itemSearchCommand,
+  export: itemExportCommand
+};

demos/ago-node-cli/lib/item-export-command.js

@@ -0,0 +1,48 @@
+const { getItem, getItemData } = require("@esri/arcgis-rest-items");
+const jsonfile = require('jsonfile');
+
+module.exports = {
+  /**
+   * Execute the command
+   */
+  execute: function (id, fileName) {
+    console.info(`Exporting item ${id} to file ${fileName}`);
+    // construct the search call..
+    let model = {};
+    return getItem(id)
+    .then((item) => {
+      model.item = item;
+      if (this.shouldFetchData(item.type)){
+        console.info(`...Fetching ./data for item of type ${item.type}`);
+        return getItemData(id);
+      } else {
+        console.info(`...Items of type ${item.type} do not have json ./data - skipping`);
+        return Promise.resolve();
+      }
+    })
+    .then((maybeData) => {
+      if (maybeData) {
+        model.data = maybeData;
+      }
+      // now write out the file...
+      jsonfile.writeFileSync(fileName, model,  {spaces: 2});
+      console.info(`Done. Exported "${model.item.title}" to ${fileName}`);
+    })
+    .catch((err) => {
+      console.error(err);
+    });
+  },
+
+  /**
+   * Not all item types have json /data
+   */
+  shouldFetchData (type) {
+    let result = false;
+    let exportables = ['Web Map', 'Web Mapping Application', 'Hub Page', 'Hub Initiative', 'Hub Site Application'];
+    // if the type is in this list, we can export it...
+    if (exportables.indexOf(type) > -1) {
+      result = true;
+    }
+    return result;
+  }
+}

demos/ago-node-cli/lib/item-search-command.js

@@ -0,0 +1,35 @@
+
+/**
+ * Bring in searchItems fn
+ */
+const { searchItems } = require("@esri/arcgis-rest-items");
+
+module.exports = {
+  /**
+   * Execute the command
+   */
+  execute: function (query) {
+    // construct the search call..
+    return searchItems({ 
+      searchForm: {
+        q: query,
+        start: 1,
+        num: 10
+      }
+    })
+    .then((response) => {
+      // if we got results
+      if (Array.isArray(response.results) && response.results.length)  {
+        console.info(`${response.total} items found for "${query}".`);
+        response.results.forEach((entry) => {
+          console.info(`${entry.id} | ${entry.title}`);
+        })
+      } else {
+        console.info(`No results found for "${query}".`);
+      }
+    })
+    .catch((err) => {
+      console.error(err);
+    });
+  }
+}

demos/ago-node-cli/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "node-cli",
+  "version": "1.0.2",
+  "description": "arcgis-rest-js node command-line item search example",
+  "main": "ago.js",
+  "scripts": {
+    "start": "echo \"CLI - node index.js <search>\" && exit 1"
+  },
+  "bin": {
+    "ago":"./ago.js"
+  },
+  "private": true,
+  "keywords": [
+    "arcgis",
+    "node",
+    "arcgis-rest-js"
+  ],
+  "author": "Dave Bouwman <dbouwman@esri.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@esri/arcgis-rest-auth": "^1.0.2",
+    "@esri/arcgis-rest-request": "^1.0.2",
+    "@esri/arcgis-rest-items": "^1.0.2",
+    "isomorphic-fetch": "^2.2.1",
+    "isomorphic-form-data": "^1.0.0",
+    "chalk": "^2.3.0",
+    "jsonfile": "^4.0.0",
+    "commander": "^2.12.2"
+  }
+}