Merge pull request #14 from AddSearch/indexing-api

Indexing api

Author: anttiai

README.md

@@ -7,7 +7,7 @@ with JavaScript on web browsers or from Node.js.
 ## Quick Start
 The library is available on the global CDN [jsDelivr:](https://www.jsdelivr.com/package/npm/addsearch-js-client)
 ```html
-<script src="https://cdn.jsdelivr.net/npm/addsearch-js-client@0.4/dist/addsearch-js-client.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/addsearch-js-client@0.5/dist/addsearch-js-client.min.js"></script>
 ```
 Or install the library locally to use it with Node.js:
 ```sh
@@ -40,9 +40,10 @@ var cb = function(res) {
 client.search('keyword', cb);
 ```
 
-## Publicly accessible functions
+## Search API
 
-The client provides the following functions.
+The client provides following functions to execute search queries. To use the client library for indexing, 
+see [Indexing API](https://github.com/AddSearch/js-client-library#indexing-api).
 
 #### Fetch search results
 ```js
@@ -301,18 +302,194 @@ client.setJWT(token);
 
 #### Set API throttling
 ```js
-// Set API call throttle time in milliseconds. Default is 200.
+// Set Search API throttle time in milliseconds. Default is 200.
 client.setThrottleTime(500);
 ```
 
-## Supported web browsers and node.js versions
+## Indexing API
+With the Indexing API, you can fetch, create, update, and delete single documents or
+batches of documents.
+
+Indexing API functions are meant to be used with Node.js. Never expose secret key in your 
+website code.
+
+```js
+// Create client with your keys
+var client = new AddSearchClient('YOUR PUBLIC SITEKEY', 'YOUR SECRET KEY');
+```
+
+The secret key can be found from AddSearch Dashboard's "Setup" > "Keys and installation" page.
+Always keep the key secret.
+
+All Indexing API functions are Promise-based.
+
+### Document structure
+Documents can contain a set of pre-defined fields, as well as any number of custom fields
+defined under the **custom_fields** key.
+
+Using pre-defined fields is optional, but default [Search UI](https://github.com/AddSearch/search-ui) components 
+display them by default, so pre-defined field give you visible results a bit faster.
+
+Pre-defined fields are: url, title, and main_content.
+
+Example document:
+```js
+const doc = {
+  id: '1234',
+  url: 'https://www.example-store.com/product-x',
+  title: 'Example product',
+  main_content: 'Lorem ipsum',
+  custom_fields: {
+    'name': 'Example product',
+    'description': 'Description for the example product',
+    'price_cents': 599,
+    'average_customer_rating': 4.5,
+    'release_date': 1589200255
+  }
+}
+```
+
+Data types for custom fields are automatically detected from the content. Supported data types are:
+
+- text
+- integer
+- double
+
+Dates should be defined as UNIX timestamps with integer values.
+
+### Document ID
+
+If the **id** is not defined in the document at indexing time, it is generated automatically either randomly
+or from the **url** field.
+
+```js
+// ID defined by the user
+const docWithDefinedId = {
+  id: '1234',
+  custom_fields: {}
+}
+```
+```js
+// ID created from the URL field (md5 of the url)
+const docWithURL= {
+  url: 'https://..',
+  custom_fields: {}
+}
+```
+```js
+// ID generated randomly
+const docWithAutogeneratedId = {
+  // No id or url fields
+  custom_fields: {}
+}
+```
+
+### Save document
+Add a document to the index, or update a document.
+
+```js
+const doc = {
+  id: '1234',
+  custom_fields: {
+    'name': 'Example product'
+  }
+};
+
+// Save document
+client.saveDocument(doc)
+  .then(response => {
+    console.log(response);
+  })
+  .catch(error => {
+    console.log(error);
+  });
+```
+
+
+### Get document by ID
+Fetch a specific document by ID.
+```js
+client.getDocument(id)
+  .then(response => {
+    console.log(response);
+  })
+  .catch(error => {
+    console.log(error);
+  });
+```
+
+
+### Delete document by ID
+Delete a specific document by ID.
+```js
+client.deleteDocument(id)
+  .then(response => {
+    console.log(response);
+  })
+  .catch(error => {
+    console.log(error);
+  });
+```
+
+
+### Save batch of documents
+Add or update bunch of documents defined in an array.
+```js
+const batch = {
+  documents: [
+    {
+      id: '1234',
+      custom_fields: {
+        'name': 'Product 1'
+      }
+    },
+    {
+      id: '5678',
+      custom_fields: {
+        'name': 'Product 2'
+      }
+    }
+  ]
+};
+
+// Save batch of documents
+client.saveDocumentsBatch(batch)
+  .then(response => {
+    console.log(response);
+  })
+  .catch(error => {
+    console.log(error);
+  });
+```
+
+
+### Delete batch of documents
+Delete multiple documents with an array of document IDs.
+```js
+// Array of document IDs
+const batch = {
+  documents: ["1234", "5678"]
+};
+
+// Delete batch of documents
+client.deleteDocumentsBatch(batch)
+  .then(response => {
+    console.log(response);
+  })
+  .catch(error => {
+    console.log(error);
+  });
+```
+
+
+## Supported browsers
 The client is tested on
 - Chrome
 - Firefox
 - Edge
 - Safari 6.1+
 - Internet Explorer 10+
-- Node.js 4+
+- Node.js
 
 
 ## Development

package.json

@@ -37,20 +37,21 @@
   "license": "MIT",
   "dependencies": {
     "es6-promise": "^4.2.8",
-    "isomorphic-fetch": "^2.2.1"
+    "isomorphic-fetch": "^2.2.1",
+    "js-base64": "^3.4.5"
   },
   "devDependencies": {
-    "@babel/cli": "^7.8.4",
-    "@babel/core": "^7.8.6",
-    "@babel/preset-env": "^7.8.6",
-    "@babel/register": "^7.8.6",
-    "babel-loader": "^8.0.6",
+    "@babel/cli": "^7.10.5",
+    "@babel/core": "^7.11.1",
+    "@babel/preset-env": "^7.11.0",
+    "@babel/register": "^7.10.5",
+    "babel-loader": "^8.1.0",
     "esm": "^3.2.25",
-    "fetch-mock": "^9.0.0",
-    "mocha": "^7.1.0",
+    "fetch-mock": "^9.10.6",
+    "mocha": "^8.1.1",
     "node-fetch": "^2.6.0",
-    "uglify-js": "^3.8.0",
-    "webpack": "^4.42.0",
-    "webpack-cli": "^3.3.11"
+    "uglify-js": "^3.10.1",
+    "webpack": "^4.44.1",
+    "webpack-cli": "^3.3.12"
   }
 }

src/index.js

@@ -1,15 +1,17 @@
 'use strict';
 
 var executeApiFetch = require('./apifetch');
+var indexingapi = require('./indexingapi');
 var sendStats = require('./stats');
 var Settings = require('./settings');
 var util = require('./util');
 var throttle = require('./throttle');
 
 var API_THROTTLE_TIME_MS = 200;
 
-var client = function(sitekey) {
+var client = function(sitekey, privatekey) {
   this.sitekey = sitekey;
+  this.privatekey = privatekey;
   this.settings = new Settings();
   this.sessionId = ('a-' + (Math.random() * 100000000)).substring(0, 10);
 
@@ -91,6 +93,38 @@ var client = function(sitekey) {
   }
 
 
+  /**
+   * Indexing API functions
+   */
+  this.getDocument = function(id) {
+    return indexingapi.getDocument(this.sitekey, this.privatekey, id);
+  }
+
+  this.saveDocument = function(document) {
+    return indexingapi.saveDocument(this.sitekey, this.privatekey, document);
+  }
+
+  this.saveDocumentsBatch = function(batch) {
+    if (!batch || !batch.documents || !Array.isArray(batch.documents)) {
+      throw "Please provide an array of documents: {documents: []}";
+    }
+    return indexingapi.saveDocumentsBatch(this.sitekey, this.privatekey, batch);
+  }
+
+  this.deleteDocument = function(id) {
+    return indexingapi.deleteDocument(this.sitekey, this.privatekey, id);
+  }
+
+  this.deleteDocumentsBatch = function(batch) {
+    if (!batch || !batch.documents || !Array.isArray(batch.documents)) {
+      throw "Please provide an array of document ids: {documents: []}";
+    }
+    return indexingapi.deleteDocumentsBatch(this.sitekey, this.privatekey, batch);
+  }
+
+
+
+
   /**
    * Public functions
    */