Read the section below for info on upgrading from v2 to v3.
This version of the library will only work with Elevate 4 Storefront API v3. Support for Elevate API v2 is limited to
v1.x.x
of this package. For information about upgrading to thev2
version, see the upgrade section
A helper library for making requests to the Elevate Storefront API v3. It includes type definitions for all HTTPS responses and the library API.
Install the package from npm:
npm install @apptus/esales-api
- Supports Browsers, Deno and Node v18+ by using
globalThis.fetch()
to send requests cross-platform - Ships code bundled into in ESM and CJS format
- Ships with modern ES2022 code - tooling like
esbuild
can be used to support older platforms/environments (see tooling) - See polyfills for required global API's
The full API and all options/return-values are described by the Typescript
definitions (dist/mod.d.ts
) that is bundled with this library.
import { elevate } from '@apptus/esales-api';
const api = elevate({
market: 'GB',
locale: 'en-GB',
clusterId: '<ID>',
touchpoint: 'desktop',
session: () => ({ customerKey: '<UUID>', sessionKey: '<UUID>' })
});
async function main() {
const result = await api.query.searchPage({ q: 'jeans', limit: 60 });
// Use the search result
}
main().catch(err => console.warn(err));
A CHANGELOG.md
is included in the package, but npm can't show
individual files from a package online. The changelog can be read
on e.g. esm.sh or unpkg.com, or any other npm mirror.
The CHANGELOG.md
includes the full list of changes. For integrators
using this package, the changes listed below are required when upgrading
to version 3.0.0
of the package:
-
A new property
session
is now required when initializing the API. Prior to v3, session information was automatically handled viaLocalStorage
. The same behavior as before can be achieved via the methodlocalStorageBackedSession()
.// Before import { esales } from '@apptus/esales-api'; const api = esales({ clusterId: 'wABCD1234', market: 'UK', locale: 'en-GB', touchpoint: 'desktop' }); // After import { esales, localStorageBackedSession } from '@apptus/esales-api'; const api = esales({ clusterId: 'wABCD1234', market: 'UK', locale: 'en-GB', touchpoint: 'desktop', session: localStorageBackedSession() });
-
The
session
property on the configured API object has been removed. Functionality related to reading/updating session metadata toLocalStorage
can be found on the object returned bylocalStorageBackedSession()
.// Before const api = esales({ ... }); api.session.sessionKey; api.session.customerKey; api.session.customerKey = user.id; api.session.reset(); // After const session = localStorageBackedSession(); const { customerKey, sessionKey } = session(); session.updateCustomerKey(user.id); session.reset();
-
All
esales().notify.*
methods are now returning promises, and should thus be handled to avoid uncaught promises. Previously, these POST messages were sent viaNavigator.sendBeacon()
. This has been replaced withfetch()
with thekeepalive
flag, to make the library supported cross platform.// Before try { api.notify.click(); } catch { // failed to queue POST request with notification } // After await api.notify.click().catch(() => {}); // to ignore errors, or: try { await api.notify.click(); } catch { // Network error or a non-OK HTTP status code }
The CHANGELOG.md
includes the full list of changes. For integrators
using this package, the changes listed below are required when upgrading
to version 2.0.0
of the package:
- A new property
locale
, must be added to the API initialization. This field should be one of the locales that is used together withmarket
when importing products with the Admin API.// Before const api = esales({ ..., market: 'SE' }); // After const api = esales({ ..., market: 'SE', locale: 'sv-SE' });
- Rename the paramater
pageId
topageReference
, for thequery.landingPage()
request.const api = esales(options); // Before api.query.landingPage({ ...params, pageId: id }); // After api.query.landingPage({ ...params, pageReference: id });
- Change
webApiId
toclusterId
for initialization configuration.// Before const api = esales({ ..., webApiId: 'w00000000' }); // After const api = esales({ ..., clusterId: 'w00000000' });
We've also cleaned up the public API surface of the package slightly, by removing some internal/private features. There should not be any reason for using them, and thus should not affect upgrades:
- Removed
@apptus/esales-api/mock
submodule. It exposed some helper functions for creating mocked objects of API responses. - Removed
api.query.settings()
method, which used a private/undocumented API endpoint - Removed
webApiUrl
. It's possible to provide a URL toclusterId
if necessary. Any Integrators should prefer using an ID over URL forclusterId
. When providing a URL toclusterId
there should not be a/api/v2/
suffix, but instead simply end the path with'/'
or''
.
This library is in active development. Highest on the agenda:
- Open source the repository on Github
- Make
CHANGELOG.md
more accessible (currently included in NPM package)
This library is packaged as an ES Module with zero dependencies. This requires the use of a pre-processor step since bare-imports are not natively supported in browsers (without import maps), but most build tools should handle this.
Additionally, in order to ship smallest possible bundle, the code is using a
modern ES2022
syntax. This may not work with the desired browser support
out of the box, and will likely require transpiling before use.
An example of how to transpile this library when building with Webpack is shown
below. Something similar can be done with Rollup by using the include
property with
@rollup/babel-plugin
.
// webpack.config.js
const { resolve } = require('path');
module.exports = {
module: {
rules: [
{
test: /\.m?js$/,
type: 'javascript/auto',
include: [resolve(__dirname, 'node_modules/@apptus/esales-api')],
use: ['babel-loader']
}
]
}
};
Depending on the level of required browser support, polyfills may need to be included before using this library. It is assumed that the following API's are available:
- All
ES2015
API's globalThis.fetch
globalThis.URL
-
globalThis.crypto.randomUUID()
(only whenlocalStorageBackedSession()
is used) Object.entries
Object.values
MIT