promoted-nodejs-client v1.0.1
promoted-nodejs-client
A Node.js client for Promoted APIs.
Creating a PromotedClient
We recommend creating a PromotedClient in a separate file so (1) it can be shared between files and (2) hides some of the configuration.
PromotedClient avoids having direct dependencies to certain implementation details so we can support customization and keep the binary small.
promotedClient.js
import { logOnError, newPromotedClient, throwOnError } from 'promoted-nodejs-client';
import { v5 as uuid } from 'uuid';
import axios from 'axios';
const axiosApiClient = <Req, Res>(url: string, apiKey: string, timeout: number) => (request: Req): Promise<Res> =>
axios.post(
url,
request,
{
headers: {
"x-api-key": apiKey,
},
timeout: 3000,
});
// These values will vary depending on dev vs prod.
const deliveryApi = 'https://....com/...';
const deliveryApiKey = 'AbCSomeRLongString1';
const deliveryTimeoutMillis = 250;
const metricsApi = 'https://....com/...';
const metricsApiKey = 'AbCSomeRLongString2';
const metricsTimeoutMillis = 3000;
// NextJS example. Throw in dev. Console log in prod.
const throwError =
process?.env?.NODE_ENV !== 'production' ||
(typeof location !== "undefined" && location?.hostname === "localhost");
export const promotedClient = newPromotedClient({
handleError: throwError ? throwOnError : logOnError;
deliveryClient: axiosApiClient(deliveryApi, deliveryApiKey, deliveryTimeoutMillis),
metricsClient: axiosApiClient(metricsApi, metricsApiKey, metricsTimeoutMillis),
uuid,
deliveryTimeoutMillis,
metricsTimeoutMillis,
});
Calling our Delivery API
Let's say the previous code looks like this:
static async getProducts(req: any, res: Response) {
const products = ...; // Logic to get products from DB, apply filtering, etc.
sendSuccessToClient(res, { products });
}
We would modify to something like this:
static async getProducts(req: any, res: Response) {
const products = ...;
const response = await promotedClient.deliver({
request: {
userInfo: {
logUserId: req.logUserId,
},
useCase: 'FEED',
sessionId: req.sessionId,
viewId: req.viewId,
insertion: products.map(product => ({
contentId: product.id,
properties: {
struct: {
product,
},
},
})),
},
});
// Change the result Product list to use the values in the returned Insertions.
sendSuccessToClient(res, {
products: response.insertion.map(insertion => insertion.properties.struct),
});
await response.finishAfterResponse();
}
There are a bunch of additional options.
When modifying this library.
Features
Uses
- TypeScript support
- React support
- ESLint (with React and Prettier)
- Unit tests (Jest and Testing Library)
- Minified output with Terser
- Bundle size validation with size-limit
- Flexible builds with Rollup
- CHANGELOG.md template
Scripts
- Run most commands:
npm run finish
- Build the project:
npm run build
- Validate output bundle size with
npm run size
- Validate output bundle size with
- Lint the project:
npm run lint
- Run unit tests:
npm test
ornpm test
When developing locally
If you want to test local changes in an actual deployment, use npm link
.
- Run
npm run updateLink
. - Go to client directory and run
npm link promoted-nodejs-client
.
When you update promoted-nodejs-client
, run npm run updateLink
.
When you want to undo, use npm unlink
in promoted-nodejs-client/dist
and npm unlink promoted-nodejs-client
in the client directory.
Deploy
We use a GitHub action that runs semantic-release to determine how to update versions. Just do a normal code review and this should work. Depending on the message prefixes (e.g. feat:
, fix:
, clean:
, docs:
), it'll update the version appropriately.
Resources
The base of this repository is a combination of the following repos: