geocodio-library-node 1.4.0 → 1.5.0

package/README.md

@@ -1,4 +1,4 @@
-# geocod.io Node library [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url]
+# geocod.io Node library [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]
 > Library for performing forward and reverse address geocoding for addresses or coordinates in the US and Canada.
 
 <!-- toc -->
@@ -10,6 +10,12 @@
   * [Field appends](#field-appends)
   * [Address components](#address-components)
   * [Limit results](#limit-results)
+  * [Lists](#lists)
+     * [Create A List](#create-a-list)
+     * [Get List Status](#get-list-status)
+     * [Get All Lists](#get-all-lists)
+     * [Download A List](#download-a-list)
+     * [Delete A List](#delete-a-list)
 - [Testing](#testing)
 - [Changelog](#changelog)
 - [Security](#security)
@@ -225,6 +231,68 @@ geocoder.reverse('38.9002898,-76.9990361', ['timezone'], 5)
   .catch(err => { ... });
 ```
 
+### Lists
+
+List methods are nested within `.list`. To access list methods, be sure to to run `geocoder.list` and then include the task method you would like to utilize. 
+
+#### Create A List
+
+To create and upload a new list using an existing .CSV file, run `geocoder.list.create(...)` and pass in your filename/file path.
+
+You may also need to pass in some additional parameters:
+* Direction: Use the default string `"forward"`.
+* Format: Use the default string `"{{A}} {{B}} {{C}} {{D}}"`
+* Callback: A callback URL. 
+
+```javascript
+geocoder.list.create(
+  `${__dirname}/stubs/sample_list.csv`,
+  "forward",
+  "{{A}} {{B}} {{C}} {{D}}",
+  "https://example.com/my-callback"
+)
+```
+
+#### Get List Status
+
+To retrieve the current status of your list, pass your list's ID into `geocoder.list.status(...)`. 
+
+```javascript
+geocoder.list.status(1234567)
+  .then(response => { ... })
+  .catch(err => { ... });
+```
+
+#### Get All Lists
+
+To retrieve all available lists, run `geocoder.list.all()`. You do not need to pass anything into this function. 
+
+```javascript
+geocoder.list.all()
+  .then(response => { ... })
+  .catch(err => { ... });
+```
+
+#### Download A List
+
+To download a list, run `geocoder.list.download(...)` and pass in the ID of the list you'd like to download, as well as a string that includes a filename. Be sure to include a `.csv` file extension. 
+
+```javascript
+geocoder.list.download(1234567, "geocoded_file.csv")
+   .then(response => { ...})
+   .catch(err => { ... });
+```
+
+#### Delete A List
+
+To delete a list, run `geocoder.list.deleteList(...)` and pass in the ID of the list you'd like to delete. 
+
+```javascript
+geocoder.list.delete(1234567)
+  .then(response => { ... })
+  .catch(err => { ... });
+```
+
 ## Testing
 
 ```bash
@@ -247,5 +315,3 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
 [npm-url]: https://npmjs.org/package/geocodio-library-node
 [travis-image]: https://travis-ci.org/Geocodio/geocodio-library-node.svg?branch=master
 [travis-url]: https://travis-ci.org/Geocodio/geocodio-library-node
-[daviddm-image]: https://david-dm.org/Geocodio/geocodio-library-node.svg?theme=shields.io
-[daviddm-url]: https://david-dm.org/Geocodio/geocodio-library-node

package/lib/__tests__/geocodioLibraryNode.test.js

@@ -200,4 +200,40 @@ describe("geocoder", () => {
       expect(response.results.length).toEqual(1);
     });
   });
+
+  // LIST TESTS
+
+  it("Can create a new list, check status, download list and delete list", () => {
+    expect.assertions(1);
+
+    // Upload and create list
+    let newList = geocoder.list
+      .create(
+        `${__dirname}/stubs/sample_list.csv`,
+        "forward",
+        "{{A}} {{B}} {{C}} {{D}}",
+        "https://example.com/my-callback"
+      )
+      .then(response => {
+        expect(response.file.filename).toEqual("sample_list.csv");
+
+        geocoder.list.status(response.id).then(
+          setTimeout(resp => {
+            expect(resp.id).toEqual(response.id);
+
+            geocoder.list
+              .download(response.id, "geocoded_file.csv")
+              .then(resp => {
+                expect(resp.file.filename).toEqual("geocoded_file.csv");
+
+                geocoder.list.delete(response.id).then(resp => {
+                  expect(resp.id).toEqual(null);
+                });
+              });
+          }, 3000)
+        );
+      });
+
+    return newList;
+  });
 });

package/lib/__tests__/stubs/sample_list.csv

@@ -0,0 +1,25 @@
+address,city,state,zip
+660 Pennsylvania Ave SE,Washington,DC,20003
+1718 14th St NW,Washington,DC,20009
+1309 5th St NE,,,20002
+2150 P St NW,,,20037
+201 F Street NE,,,20002
+1001 2nd St SE,,,20003
+1645 Wisconsin Avenue NW,Washington,DC,20007
+820 East Baltimore Street,Baltimore,MD,21202
+800 F St NW,Washington,DC,20001
+700 Constitution Avenue NW,Washington,DC,20565
+1123 Pennsylvania Ave SE,Washington,DC,20003
+621 Pennsylvania Ave SE,Washington,DC,20003
+1702 G Street NW,Washington,DC,20006
+701 8th St SE,Washington,DC,20003
+12187 Darnestown Rd,Gaithersburg,MD,20878
+4961 Elm Street,Bethesda,MD,
+3064 Mount Pleasant St NW,Washington,DC,
+1052 Thomas Jefferson Street NW,Washington,DC,
+475 H St NW,Washington,DC,
+1301 U St NW,Washington,DC,
+"1726 20th Street, NW",Washington,DC,
+"1916 I Street, NW",Washington,DC,
+107 Church St NE,Vienna,VA,
+4817 Bethesda Ave,Bethesda,MD,20814

package/lib/index.js

@@ -1,6 +1,8 @@
 "use strict";
 
 const axios = require("axios");
+const fs = require("fs");
+const FormData = require("form-data");
 
 class Geocodio {
   constructor(apiKey, hostname, apiVersion) {
@@ -23,6 +25,8 @@ class Geocodio {
       "postal_code",
       "country"
     ];
+
+    this.list = this.list();
   }
 
   geocode(query, fields = [], limit = null) {
@@ -55,11 +59,16 @@ class Geocodio {
       response = this.performBatchRequest(url, query, queryParameters);
     }
 
+    return this.handleResponse(response);
+  }
+
+  handleResponse(response) {
     return response
       .then(response => response.data)
       .catch(error => {
         if (error.response) {
-          const errorMessage = error.response.data.error || "Error";
+          const errorMessage =
+            error.response.data.message || error.response.data.error || "Error";
           const code = error.response.status || 0;
 
           const decoratedError = new Error(errorMessage);
@@ -144,6 +153,94 @@ class Geocodio {
   isNumeric(n) {
     return !isNaN(parseFloat(n)) && isFinite(n);
   }
+
+  list() {
+    const create = (filename, direction, format, callback) => {
+      const form = new FormData();
+      form.append("file", fs.createReadStream(filename));
+
+      return this.handleResponse(
+        axios.post(this.formatUrl("lists"), form, {
+          params: {
+            api_key: this.apiKey,
+            direction,
+            format,
+            callback
+          },
+          headers: form.getHeaders()
+        })
+      );
+    };
+
+    const status = listId => {
+      return this.handleResponse(
+        axios.get(this.formatUrl(`lists/${listId}`), {
+          params: {
+            api_key: this.apiKey
+          }
+        })
+      );
+    };
+
+    const all = () => {
+      return this.handleRequest(
+        axios.get(this.formatUrl(`lists`), {
+          params: {
+            api_key: this.apiKey
+          }
+        })
+      );
+    };
+
+    const download = (listId, output) => {
+      const writer = fs.createWriteStream(output);
+
+      return this.handleRequest(
+        axios({
+          method: "get",
+          url: this.formatUrl(`lists/${listId}/download`),
+          params: {
+            api_key: this.apiKey
+          },
+          responseType: "stream"
+        }).then(response => {
+          return new Promise((resolve, reject) => {
+            response.data.pipe(writer);
+            let error = null;
+            writer.on("error", err => {
+              error = err;
+              writer.close();
+              reject(err);
+            });
+            writer.on("close", () => {
+              if (!error) {
+                resolve(true);
+              }
+            });
+          });
+        })
+      );
+    };
+
+    const deleteList = listId => {
+      return this.handleRequest(
+        axios.delete(this.formatUrl(`lists/${listId}`), {
+          params: {
+            api_key: this.apiKey
+          }
+        })
+      );
+    };
+
+    return {
+      create,
+      status,
+      all,
+      download,
+      deleteList, // Kept for backwards compatibility
+      delete: deleteList
+    };
+  }
 }
 
 module.exports = Geocodio;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geocodio-library-node",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "geocod.io geocoding API library",
   "homepage": "https://github.com/Geocodio/geocodio-library-node",
   "author": {
@@ -73,6 +73,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "axios": "^0.21.1"
+    "axios": "^0.27.2",
+    "form-data": "^4.0.0"
   }
 }