@empathyco/x-adapter-platform
v1.1.0-alpha.8
Published
A search client for the Empathy Platform API
Downloads
6,867
Readme
x-adapter-platform
Empathy Platform Adapter is a library to ease the communication with empathy.co Empathy Platform API. Built upon the x-adapter library, it contains a sample configuration for setup, global configurations, mappers and models.
It is used as the default adapter configuration in x-archetype, a standardised implementation of the x-components library, which imports it as a plugin.
Tech Stack
Installation
# or pnpm or yarn
npm install @empathyco/x-adapter-platform
Configuration & Usage
The PlatformAdapter
is an object containing several endpoint adapters.
Each EndpointAdapter
contains the configuration of an endpoint, including the URL, the mapper to
adapt the responses and the requests, the request options ...
export const platformAdapter: PlatformAdapter = {
search: searchEndpointAdapter,
popularSearches: popularSearchesEndpointAdapter,
recommendations: recommendationsEndpointAdapter,
nextQueries: nextQueriesEndpointAdapter,
querySuggestions: querySuggestionsEndpointAdapter,
relatedTags: relatedTagsEndpointAdapter,
identifierResults: identifierResultsEndpointAdapter,
tagging: taggingEndpointAdapter
};
Platform Endpoint Adapters & usage
The
Empathy Platform API
has the particularity of needing an env
, instance
and a language
to be passed in each endpoint
call (except the tagging).
In an x-archetype project context, which would be the recommended scenario to use this package, these parameters are configured through the snippetConfig.
If you are not using the x-platform-adapter
inside an x-archetype
based project, but you want to
use the Empathy Platform API, you can use the extraParams
field to specify the required
parameters to make it work, as shown in the examples below.
Search endpoint adapter
- endpoint:
/search/v1/query/{extraParams.instance}/search
- request:
SearchRequest
- response:
SearchResponse
The search endpoint will include an array of results in its response.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { results } = await platformAdapter.search({
query: 'trousers',
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Popular searches endpoint adapter
- endpoint:
/search/v1/query/{extraParams.instance}/empathize
- request:
PopularSearchesRequest
- response:
PopularSearchesResponse
The PopularSearches
endpoint will return top searched queries.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { suggestions } = await platformAdapter.popularSearches({
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Recommendations endpoint adapter
- endpoint:
/search/v1/query/{extraParams.instance}/topclicked
- request:
RecommendationsRequest
- response:
RecommendationsResponse
These recommendations are top clicked products based on user click interactions (note: no personal user data is collected).
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { results } = await platformAdapter.recommendations({
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Next Queries endpoint adapter
- endpoint:
/nextqueries/{extraParams.instance}
- request:
NextQueriesRequest
- response:
NextQueriesResponse
The NextQueries
endpoint returns recurring searches that users tend to do after searching for a
specific item. The aim is to suggest a new term that the user may be interested in.
The NextQueriesRequest
is usually done after a SearchRequest
has been made.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { nextQueries } = await platformAdapter.nextQueries({
query: 'trousers',
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Query suggestions endpoint adapter
- endpoint:
/search/v1/query/{extraParams.instance}/empathize
- request:
QuerySuggestionsRequest
- response:
QuerySuggestionsResponse
The QuerySuggestions
endpoint returns suggestions based on a query. For example, for the query
"trousers" we could have "denim trousers, cargo trousers, chino trousers, etc..." as query
suggestions.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { suggestions } = await platformAdapter.querySuggestions({
query: 'trousers',
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Related tags endpoint adapter
- endpoint:
/relatedtags/{extraParams.instance}
- request:
RelatedTagsRequest
- response:
RelatedTagsResponse
The RelatedTags
endpoint will return terms used to help refining a search query by adding more
specificity (e.g, adjectives: long, short, gluten-free; categories: kids, summer...).
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { relatedTags } = await platformAdapter.relatedTags({
query: 'trousers',
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Identifier results endpoint adapter
- endpoint:
/search/v1/query/{extraParams.instance}/skusearch
- request:
IdentifierResultsRequest
- response:
IdentifierResultsResponse
The IdentifierResults
endpoint will return the results whose
identifier
matches a given query
.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const { results } = await platformAdapter.identifierResults({
query: '1234',
extraParams: {
lang: 'en',
instance: 'empathy',
env: 'staging'
}
});
Tagging endpoint adapter
- endpoint:
({ url }) => url
- request:
TaggingRequest
- response:
void
The Tagging
endpoint allows sending events to a server to collect metrics about how the search is
performing (this won't collect user data, just the use of tools per session).
You can configure your tagging
object following the
Taggable
interface, which contains several user actions and the capability to include your own.
import { platformAdapter } from '@empathyco/x-adapter-platform';
const tagging = await platformAdapter.tagging({
// The tagging request will be sent to this URL
url: 'https://api.staging.empathy.co/tagging/v1/track/empathy/query',
// Info that will be sent along with the query event
params: {
filtered: 'false',
lang: 'en',
origin: 'customer:no_query',
page: '1',
q: 'trousers',
scope: 'desktop',
spellcheck: 'false',
totalHits: 700
}
});
Modifying the x-platform-adapter
Each request and response schemas are created as MutableSchemas
, so they can be modified using the
$extends
, $override
, $replace
methods accordingly. You can check the
x-adapter
's package
documentation for further details.
Example of overriding a response by adding a new parameter
import { PlatformResult, resultSchema } from '@empathyco/x-adapter-platform';
import { Result } from '@empathyco/x-types';
interface EmpathyDemoPlatformResult extends PlatformResult {
season: string;
}
declare module '@empathyco/x-types' {
export interface Result {
season: string;
}
}
resultSchema.$override<EmpathyDemoPlatformResult, Partial<Result>>({
season: 'season'
});
Test
Empathy Adapter Platform features are tested using Jest. You will find a
__tests__
folder inside the src
folder with tests for each of the endpoint calls, and also
inside each of the project's sections functionalities (endpoint-adapters
, mappers
and
schemas
).
npm run test
Changelog
Contributing
To start contributing to the project, please take a look at our
Contributing Guide. Take in
account that x-adapter-platform
is developed using Typescript,
so we recommend you to check it out.