Official Coveo Cloud APIs JavaScript Client
The main goal of this package is to provide an easy to configure and straightforward way of querying Coveo Cloud APIs using JavaScript.
Getting started
Build
npm i
npm run build
Install
npm install @coveord/platform-client
# Typescript types are included in the package
Import
// using default import
import PlatformClient from '@coveord/platform-client';
// using named import
import {PlatformClient} from '@coveord/platform-client';
// using commonjs require
const PlatformClient = require('@coveord/platform-client').default;
Configure
const platform = new PlatformClient({
/* configuration options */
});
Use
platform.resource.action({
/* action dependant options */
});
Every action returns a Promise object.
Example
const platform = new PlatformClient({
organizationId: 'some-coveo-platform-organization-id',
accessToken: () => 'your-coveo-platform-access-token-or-api-key',
});
// List the organization catalogs
const catalogs = await platform.catalog.list({page: 0, pageSize: 10});
doSometing(catalogs);
Compatibility
The platform-client
package is built on top of the fetch
API and some related features such as the AbortController
which are not entirely supported by all JavaScript runtime environments. Consequently, we recommend including the following list of polyfills to your project before using it in production.
Node.js example
require('isomorphic-fetch');
require('abortcontroller-polyfill');
const PlatformClient = require('@coveord/platform-client').default;
const coveoPlatform = new PlatformClient({
/* options */
});
coveoPlatform.source
.list()
.then((res) => {
console.log(JSON.stringify(res));
})
.catch((e) => {
console.error(e);
});
Global Configuration
It is also possible to provide global request settings for all requests made by the client; Simply provide the configuration in the globalRequestSettings
property of the options. This can be useful for applying necessary headers or configurations for network requests. For example, you might include a proxy authorization header for requests routed through a proxy server using the Proxy-Authorization
header:
Node.js example
require('isomorphic-fetch');
require('abortcontroller-polyfill');
const PlatformClient = require('@coveord/platform-client').default;
const coveoPlatform = new PlatformClient({
globalRequestSettings: {
headers: {
'Proxy-Authorization': 'Basic YWxhZGRpbjpvcGVuc2VzYW1l',
},
},
});
coveoPlatform.source
.list()
.then((res) => {
console.log(JSON.stringify(res));
})
.catch((e) => {
console.error(e);
});
Documentation
This project is built using TypeScript and automatically generates relevant type declarations. Most IDEs with TypeScript integration will display those type declarations as autocompletions, so that you typically will not need to refer to external documentation. Hence, the decision has been made not to document any option, resource, or action, except for the main configuration options. For in-depth documentation on the APIs exposed by this package, please consult our official documentation portal.
Configuration Options
Option | Required | Default Value | Description |
---|---|---|---|
accessToken |
yes | undefined | The access token or API key. |
organizationId |
yes | undefined | The unique identifier of the target organization. |
environment |
optional | 'production' |
The target environment. If one of following: 'development' , 'stg' 'production' , 'hipaa' ; automatically targets the associated host. |
host |
optional | 'https://platform.cloud.coveo.com' |
The target host. Useful to target local hosts when testing. |
serverlessHost |
optional | 'https://api.cloud.coveo.com' |
The target host for serverless APIs. |
responseHandlers |
optional | [] | Custom server response handlers. See error handling section for detailed explanation. |
region |
optional | Region.US | The target region. |
Error handling
Each request made by the platform-client
, once resolved or rejected, gets processed by one (and only one) of the response handlers. Some very basic response handlers are used by default, but you can override their behavior by specifying your own in the responseHandlers
configuration option. The order in which they are specified defines their priority. Meaning that the first handler of the array that can process the response is used to do so.
A response handler is defined as such:
interface ResponseHandler {
canProcess(response: Response): boolean; // whether the handler should be used to process the response
process<T>(response: Response): Promise<T>; // defines how the handler processes the response
}
Example
const MySuccessResponseHandler: ResponseHandler = {
canProcess: (response: Response): boolean => response.ok;
process: async <T>(response: Response): Promise<T> => {
const data = await response.json();
console.log(data);
return data;
};
}
Ad hoc requests
Sometimes, a specific platform-client
configuration is required for a one-time task. In such use cases, we can leverage the withFeatures()
method on the platform-client
instance. This will prevent having to create a new PlatformClient
instance for just one usage.
A feature is defined as a function that returns a set of new configuration options to be used for the next request.
type Feature = (currentOptions: PlatformClientOptions) => PlatformClientOptions;
Where currentOptions
are the options currently used by the client instance to make requests.
Example
const europeRegion: Feature = (currentOptions) => ({
...currentOptions,
region: Region.EU,
});
const europeOrganizations = await platform.withFeatures(europeRegion).organization.list();
Multiple features can be used at once, each feature will override the options returned by the previous one.
const notifyOnSuccess = (message) => (currentOptions) => ({
...currentOptions,
responseHandlers: [
{
canProcess: (response) => response.ok,
process: async (response) => {
const result = await response.json();
showSuccessToast(message);
return result;
},
},
...currentOptions.responseHandlers,
],
});
const notifyOnError = (message) => (currentOptions) => ({
...currentOptions,
responseHandlers: [
...currentOptions.responseHandlers,
{
canProcess: () => true,
process: async (response) => {
const error = await response.json();
showErrorToast(message);
throw error;
},
},
],
});
platform.withFeatures(notifyOnSuccess('It worked!'), notifyOnError('It failed!')).field.delete('unwanted-field-id');
Contributing
Guidelines
- Make sure your changes are fully tested (when applicable).
- We tend to avoid comments in our code base, we strongly prefer good naming and code structure.
- Avoid pushing similar changes in different commits if it's within the same feature, because we want the changelogs to be clear and simple. To avoid that, there are at least 2 options:
- Squash the commits into one when merging (you need to edit the final commit message though)
- amend the previous commit when making related changes (
git commit --amend --no-edit
)
Commit messages
Every commit message must comply with the Angular Commit Message Conventions specification. We use the commit messages to automatically bump the package version according to the semantic versionning notation. Moreover, we generate changlogs for each version using those commit messages.
- You can either manually write a commit message that follows the convention using your favorite method.
- Or you can run
npm run commit-cli
. It will prompt you some questions about the nature of your changes, then it will commit your staged changes along with a generated message that follows our convention. - Commits containing breaking changes need to be marked as such in the commit footer. See BREAKING CHANGE convention.