-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Update overview README.md * Bold `apiKey` and `secret` * Initial recommendations doc * Routing BreinifySetup to overview * Routing BreinifySetup to overview * Link overview recommendations to readme * `useRecommendations` and `getRecommendations` examples * Format `tsx` examples * `useRecommendations` props * `getRecommendations` props * Require `recommendation` or `recommendations` * Combine blockquotes * README QA changes * Recommendations QA changes * Recommendations TOC * Update example * Recommendation response * Update rec notes * Update data returned response * `recommendations-1` url * Style `object` * `selector` docs
- Loading branch information
Showing
2 changed files
with
202 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,48 @@ | ||
| # brein-api-library-react | ||
| React Library for the Breinify API | ||
| # Breinify’s React API Library | ||
|
|
||
| <!-- TOC --> | ||
| * [Overview](#overview) | ||
| * [Getting Started](#getting-started) | ||
| * [Retrieving an API-Key](#retrieving-an-api-key) | ||
| * [Installing](#installing) | ||
| * [Configuring the Library](#configuring-the-library) | ||
| * [API](#api) | ||
| * [Further Links](#further-links) | ||
| <!-- TOC --> | ||
|
|
||
| ## Overview | ||
| Breinify’s React API library provides hooks, components, and type definitions to call Breinify’s API. | ||
|
|
||
| ## Getting Started | ||
| ### Retrieving an API-Key | ||
| You need a valid API-key, which you can get for free at [https://www.breinify.ai](https://www.breinify.ai/) . In the examples, we assume you have the following API key: | ||
| #### 938D-3120-64DD-413F-BB55-6573-90CE-473A | ||
| It is recommended to use signed messages when utilizing the react library. A signed messages ensures, that the request is authorized. To activate signed message ensure that `Verification Signature` is enabled for your key (see [Breinify’s API Docs](https://docs.breinify.com/#request-an-api-key) for further information). In this documentation we assume that the following secret is attached to the API key and used to sign a message. | ||
| #### utakxp7sm6weo5gvk7cytw== | ||
|
|
||
| ### Installing | ||
| The library is available on [npm](https://www.npmjs.com/package/brein-react-api-library-react) and can be added using: | ||
| ```bash | ||
| npm i brein-react-api-library-react --save | ||
| ``` | ||
|
|
||
| ### Configuring the Library | ||
| Whenever the library is used, it needs to be configured, i.e., the configuration defines which API key and which secret (if signed messages are enabled, i.e., `Verification Signature` is checked) to use. Please place `BreinifySetup` on the top most section of your application. | ||
| ```tsx | ||
| import { BreinifySetup } from 'brein-api-library-react'; | ||
|
|
||
| const apiKey = '938D-3120-64DD-413F-BB55-6573-90CE-473A'; | ||
| const secret = 'utakxp7sm6weo5gvk7cytw=='; | ||
|
|
||
| BreinifySetup({ apiKey, secret }); | ||
| ``` | ||
| > Note: API Key and Secret should not be shown publicly | ||
| ## API | ||
| * [Recommendations](/docs/recommendations.md) | ||
|
|
||
|
|
||
| ## Further Links | ||
| To understand all the capabilities of Breinify’s API, you can find further information here: | ||
| * [API Docs](https://docs.breinify.com/) | ||
| * [Breinify’s Website](https://home.breinify.ai/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| # Recommendations | ||
| Retrieves a list of recommended products for the user supplied in the user object of the body. To use the recommendations components, we’ve assumed that you’ve set up [BreinifySetup](/README.md#configuring-the-library). | ||
| We provide a toolkit for you to interact with the Breinify API. | ||
| * [Hooks](#hooks) | ||
| * [useRecommendations](#userecommendations) | ||
| * [Example](#example) | ||
| * [Utilities](#utilities) | ||
| * [getRecommendations](#getrecommendations) | ||
| * [Example](#example-1) | ||
| * [Response](#success-response) | ||
| * [recommendation](#recommendation) | ||
| * [recommendations](#recommendations-1) | ||
|
|
||
| ## Hooks | ||
| Provides a standard API wrapper that calls the `getRecommendation` fetch method. | ||
|
|
||
| ### useRecommendations | ||
| ```tsx | ||
| const { getRecs, data, isInit, isLoading, isSuccess, isFailure, error } = | ||
| useRecommendations(defaultDataState); | ||
| ``` | ||
| > During the initial render, the returned data is the same as the value passed as the first argument (defaultDataState). | ||
| | Name | Description | Type | Default | | ||
| |---------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|---------| | ||
| | **getRecs** | Call to get recommendations | `({user, unixTimestamp, signature, recommendation, recommendations}: RecommendationQuery, selector) => void ` | | | ||
| | **data** | Response from `getRecs` | [recommendation](#recommendation), [recommendations](#recommendations-1) | `null` | | ||
| | **isInit** | If true, the hook just initialized | `boolean` | `true` | | ||
| | **isLoading** | If true, the query is still in flight and results have not yet been returned. | `boolean` | `false` | | ||
| | **isSuccess** | If true, the query has succeeded and the response is passed to `data` | `boolean` | `false` | | ||
| | **isFailure** | If true, the query has failed and the response is passed to `error` | `boolean` | `false` | | ||
| | **error** | Response on why `getRecs` failed | `string`, `object` | `''` | | ||
|
|
||
| #### getRecs | ||
| ```tsx | ||
| getRecs({user, unixTimestamp, signature, recommendation, recommendations}: RecommendationQuery, selector) | ||
| ``` | ||
|
|
||
| ##### RecommendationQuery | ||
| | Name | Description | Type | | ||
| |------------------------------------------|--------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| | ||
| | **user** | Information about the user | [user](https://docs.breinify.com/?javascript--node#requesting-a-product-recommendation) | | ||
| | **unixTimestamp** | The number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. | `number` | | ||
| | **signature** | Signature to authenticate a request, is only available if the the secret for the Breinify API key is configured. | `string` | | ||
| | **recommendation**<br/>***required***** | Parameters set for making the recommendations. | [recommendation](https://docs.breinify.com/?javascript--node#requesting-a-product-recommendation) | | ||
| | **recommendations**<br/>***required***** | A list of `recommendation` | [[recommendations]](https://docs.breinify.com/?javascript--node#requesting-a-product-recommendation) | | ||
| > #### ** Either recommendation OR recommendations is required! | ||
| > Please check out the [Breinify Docs](https://docs.breinify.com/?javascript--node#requesting-a-product-recommendation) for more information about the props | ||
| ##### Selector | ||
| | Name | Description | Type | | ||
| |--------------|--------------------------------------------------------------------------------------------------|------------| | ||
| | **selector** | A function that allows the user to parse the response and use that parsed response in the `data` | `function` | | ||
|
|
||
| #### Example | ||
| ```tsx | ||
| import { useRecommendations } from "brein-api-library-react"; | ||
|
|
||
| export function TestContainer() { | ||
| const { getRecs, data, isInit, isLoading, isSuccess, isFailure, error } = | ||
| useRecommendations(); | ||
|
|
||
| function onButton() { | ||
| getRecs({ recommendation: {} }); | ||
| } | ||
|
|
||
| useEffect(() => { | ||
| getRecs({ recommendation: { numRecommendations: 10 } }); | ||
| }, []); | ||
|
|
||
| return ( | ||
| <div> | ||
| {isInit && <>INIT</>} | ||
| {isLoading && <>LOADING</>} | ||
| {isSuccess && <>{JSON.stringify(data, null, 2)}</>} | ||
| {isFailure && <>{JSON.stringify(error, null, 2)}</>} | ||
| <button onClick={onButton}>Click Here</button> | ||
| </div> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| ## Utilities | ||
| ### getRecommendations | ||
| We've also exposed the lower level utility that aids in calling our recommendation API. | ||
|
|
||
| #### Example | ||
| ```tsx | ||
| getRecommendations({ | ||
| user, | ||
| unixTimestamp, | ||
| signature, | ||
| recommendation, | ||
| recommendations, | ||
| }: RecommendationQuery) | ||
| .then((response) => {}) | ||
| .catch((error) => {}); | ||
| ``` | ||
| > [RecommendationQuery](#getrecs) | ||
| ### Success Response | ||
|
|
||
| #### recommendation | ||
| ```json | ||
| { | ||
| "additionalData": {}, | ||
| "result": [{ | ||
| "dataIdExternal": "123", | ||
| "recommendationWeight": 0.9, | ||
| "additionalData": { | ||
| "name": "some name", | ||
| "clientSuppliedField": "some meta data" | ||
| } | ||
| }, | ||
| { | ||
| "dataIdExternal": "234", | ||
| "recommendationWeight": 0.87, | ||
| "additionalData": { | ||
| "name": "another name", | ||
| "clientSuppliedField": "some meta data" | ||
| } | ||
| }, | ||
| { | ||
| "dataIdExternal": "345", | ||
| "recommendationWeight": 0.86, | ||
| "additionalData": { | ||
| "name": "third item name", | ||
| "clientSuppliedField": "some meta data" | ||
| } | ||
| } | ||
| ], | ||
| "message": "Successful execution with nothing to report.", | ||
| "statusCode": 200 | ||
| } | ||
| ``` | ||
|
|
||
| #### recommendations | ||
| ```json | ||
| { | ||
| "results": [ | ||
| recommendation | ||
| ], | ||
| "message": "Successful execution with nothing to report.", | ||
| "statusCode": 200 | ||
| } | ||
| ``` | ||
| > [recommendation](#recommendation) in `results` | ||
| #### Result response | ||
| | Name | Description | Type | | ||
| |----------------------|------------------------------------------|----------| | ||
| | dataIdExternal | The client’s id for the recommended item | `string` | | ||
| | recommendationWeight | The recommender’s weight for the item | `float` | | ||
| | additionalData | Additional data supplied by the client | `object` | |