feat(answers): add findAnswers

index.d.ts

@@ -171,6 +171,28 @@ declare namespace algoliasearchHelper {
       ) => void
     ): void;
 
+    /**
+     * Start the search for answers with the parameters set in the state.
+     * This method returns a promise.
+     * @param {Object} options - the options for answers API call
+     * @param {string[]} options.attributesForPrediction - Attributes to use for predictions. If empty, `searchableAttributes` is used instead.
+     * @param {string[]} options.queryLanguages - The languages in the query. Currently only supports ['en'].
+     * @param {number} options.nbHits - Maximum number of answers to retrieve from the Answers Engine. Cannot be greater than 1000.
+     */
+    findAnswers(options: {
+      attributesForPrediction: string[];
+      queryLanguages: string[];
+      nbHits: number;
+    }): Promise<{
+      hits: Array<any & {
+        _answer: {
+          extract: string;
+          extractAttribute: string;
+          score: number;
+        }
+      }>
+    }>;
+
     /**
      * Search for facet values based on an query and the name of a faceted attribute. This
      * triggers a search and will return a promise. On top of using the query, it also sends

src/algoliasearch.helper.js

@@ -8,6 +8,8 @@ var requestBuilder = require('./requestBuilder');
 var events = require('events');
 var inherits = require('./functions/inherits');
 var objectHasKeys = require('./functions/objectHasKeys');
+var omit = require('./functions/omit');
+var merge = require('./functions/merge');
 
 var version = require('./version');
 
@@ -248,6 +250,75 @@ AlgoliaSearchHelper.prototype.searchOnce = function(options, cb) {
   });
 };
 
+/**
+ * @typedef Answer
+ * @type {object}
+ * @property {string} extract the extracted value with highlights
+ * @property {string} extractAttribute the attribute used to extract the answer
+ * @property {number} score the score indicating how well it was matched
+ */
+
+/**
+ * @typedef AnswerHit
+ * @type {object}
+ * @property {Answer} _answer the object describing why the hit was chosen
+ */
+
+/**
+ * @typedef AnswersResult
+ * @type {object}
+ * @property {AnswerHit[]} hits the answer hits
+ */
+
+ /**
+ * Start the search for answers with the parameters set in the state.
+ * This method returns a promise.
+ * @param {Object} options - the options for answers API call
+ * @param {string[]} options.attributesForPrediction - Attributes to use for predictions. If empty, `searchableAttributes` is used instead.
+ * @param {string[]} options.queryLanguages - The languages in the query. Currently only supports ['en'].
+ * @param {number} options.nbHits - Maximum number of answers to retrieve from the Answers Engine. Cannot be greater than 1000.
+ *
+ * @return {AlgoliaSearchHelper}
+ * @return {promise.<AnswersResult>} the answer results
+ */
+AlgoliaSearchHelper.prototype.findAnswers = function(options) {
+  var state = this.state;
+  var derivedHelper = this.derivedHelpers[0];
+  if (!derivedHelper) {
+    return Promise.resolve([]);
+  }
+  var derivedState = derivedHelper.getModifiedState(state);
+  var data = merge(
+    {
+      attributesForPrediction: options.attributesForPrediction,
+      nbHits: options.nbHits
+    },
+    {
+      params: omit(requestBuilder._getHitsSearchParams(derivedState), [
+        'attributesToSnippet',
+        'hitsPerPage',
+        'restrictSearchableAttributes',
+        'snippetEllipsisText' // FIXME remove this line once the engine is fixed.
+      ])
+    }
+  );
+
+  if (
+    typeof this.client.initIndex !== 'function'
+  ) {
+    throw new Error(
+      'search for answers was called, but this client does not have a function client.initIndex'
+    );
+  }
+  var index = this.client.initIndex(derivedState.index);
+  if (typeof index.findAnswers !== 'function') {
+    throw new Error(
+      'search for answers was called, but this client does not have a function client.initIndex(index).findAnswers'
+    );
+  }
+  return index.findAnswers(derivedState.query, options.queryLanguages, data);
+};
+
 /**
  * Structure of each result when using
  * [`searchForFacetValues()`](reference.html#AlgoliaSearchHelper#searchForFacetValues)

test/spec/algoliasearch.helper/findAnswers.js

@@ -0,0 +1,103 @@
+'use strict';
+
+var algoliasearchHelper = require('../../../index');
+
+function makeFakeFindAnswersResponse() {
+  return {
+    exhaustiveFacetsCount: true,
+    facetHits: [],
+    processingTimeMS: 3
+  };
+}
+
+function setupTestEnvironment(helperOptions) {
+  var findAnswers = jest.fn(function() {
+    return Promise.resolve([makeFakeFindAnswersResponse()]);
+  });
+
+  var fakeClient = {
+    initIndex: function() {
+      return {
+        findAnswers: findAnswers
+      };
+    }
+  };
+
+  var helper = algoliasearchHelper(fakeClient, 'index', helperOptions);
+
+  return {
+    findAnswers: findAnswers,
+    helper: helper
+  };
+}
+
+test('returns an empty array with no derived helper', function() {
+  var env = setupTestEnvironment();
+  var helper = env.helper;
+  var findAnswers = env.findAnswers;
+
+  return helper
+    .findAnswers({
+      attributesForPrediction: ['description'],
+      queryLanguages: ['en'],
+      nbHits: 1
+    })
+    .then(function(result) {
+      expect(findAnswers).toHaveBeenCalledTimes(0);
+      expect(result).toEqual([]);
+    });
+});
+
+test('returns a correct result with one derivation', function() {
+  var env = setupTestEnvironment();
+  var helper = env.helper;
+  var findAnswers = env.findAnswers;
+
+  helper.derive(function(state) {
+    return state;
+  });
+
+  return helper
+    .findAnswers({
+      attributesForPrediction: ['description'],
+      queryLanguages: ['en'],
+      nbHits: 1
+    })
+    .then(function(result) {
+      expect(findAnswers).toHaveBeenCalledTimes(1);
+      expect(result).toEqual([makeFakeFindAnswersResponse()]);
+    });
+});
+
+test('runs findAnswers with facets', function() {
+  var env = setupTestEnvironment({facets: ['facet1']});
+  var helper = env.helper;
+  var findAnswers = env.findAnswers;
+  helper.addFacetRefinement('facet1', 'facetValue');
+
+  helper.derive(function(state) {
+    return state;
+  });
+
+  helper.setQuery('hello');
+
+  return helper
+    .findAnswers({
+      attributesForPrediction: ['description'],
+      queryLanguages: ['en'],
+      nbHits: 1
+    })
+    .then(function() {
+      expect(findAnswers).toHaveBeenCalledTimes(1);
+      expect(findAnswers).toHaveBeenCalledWith('hello', ['en'], {
+        attributesForPrediction: ['description'],
+        nbHits: 1,
+        params: {
+          facetFilters: ['facet1:facetValue'],
+          facets: ['facet1'],
+          query: 'hello',
+          tagFilters: ''
+        }
+      });
+    });
+});