Access the Crossing Minds recommendation API from your application. This client helps manage authentication, and provides strongly typed inputs and outputs.
Documentation for the API itself can be found here: https://docs.api.crossingminds.com/. Most API endpoints have a corresponding command in this client.
Add this library to your front-end, backend, or script using the package manager CLI of your choice (we like pnpm). Typescript types are included.
npm install @crossingminds/recommendation-client
import {
RecommendationClient,
GetRelatedItemRecommendationsCommand,
} from "@crossingminds/recommendation-client";
import type { GetRelatedItemRecommendationsInput } from "@crossingminds/recommendation-client";
// client.ts
import { RecommendationClient } from "@crossingminds/recommendation-client";
/** This recommendation client instance is authenticated. It can be used throughout your app */
const client = new RecommendationClient({
allowedAccountRoles: "backend",
initialCredentials: {
serviceLoginId: "service-login-for-my-account",
password: env.SERVICE_LOGIN_PASSWORD,
currentDatabaseId: "my-database-id-in-my-account",
},
});
import { RecommendationClient } from "@crossingminds/recommendation-client";
import { client } from "./client";
import { randomUUID } from "node:crypto";
/** Here's an example of making a session id for an end-user that's compatible with the recommendation API */
function generateNewSessionId() {
const sessionId = randomUUID();
return sessionId;
}
/** get session based recommendations */
export async function getRecommendations(sessionId: string) {
try {
const { itemIds } = await client.send(
new GetSessionBasedItemRecommendationsCommand({ sessionId })
);
return itemIds;
} catch {
// handle possible network errors
}
}
You can authenticate an instance of the client when it's instantiated by passing in the initialCredentials
option as shown above.
Client's can also be authenticated after instantiation using LoginIndividualCommand
, LoginServiceCommand
, and RenewLoginWithRefreshTokenCommand
commands.
Access the internally saved credentials using the .getCredentials()
method on an instance of RecommendationClient
. The internal auth token will be attached as a header to all network requests made by the client. If the token expires, it will be automatically renewed if there is a refresh-token available.
import {
RecommendationClient,
LoginServiceCommand,
} from "@crossingminds/recommendation-client";
const client = new RecommendationClient({
allowedAccountRoles: ["frontend"],
});
client.getCredentials();
/* returns {} */
await client.send(
new LoginServiceCommand({
serviceLoginId: "my-frontend-service-login-id",
databaseId: "ZFhtzINgq2Uz0AAvRSw4TQ",
password: "frontend-passwords-are-not-secret",
})
);
client.getCredentials();
/* returns
{
token:
'eyJ0eXAiOiJKV1QiLCJhbGciOiJgUzI1NiJ9.eyJlbmNyeXB0ZWRfZGF0YSI6IkRDSTFCSTNFTxd4SlJBeXQxYldTUTJQc2hyOUcrZGpiYjVnSU5KYjhManpMdWprZ0hqaXpIcFo4K2RGbXBsNG9UWUU1OXVjWGxkR0l6YnFVRElFTi9hSURiOFErWG5mREpjNjQ4TWZnRGk1dE1WUExuN1FvNVRIeDFIZHFZN1F4cFQwcmcvQ0g0cHRTTmU1eFhML3hiUT09Iiwic2FsdCI6Ii9YbGl1TUxrcEtCazNUSm42Vmdjcnc9PSIsInN1YiI6MTM1MjR9.bKIzTGzG0HrhkDvalnWam-93iPrSCxBDlwpkAMcaKNU',
refreshToken:
'Rx3q+dmSYYt6mbadQ6yeyjgl5IyKS3nsIvya9agMd8fjNT5ejy8+gvKunR4ZimZDmE+dP4qa7ZVnmBrsIC31uw==',
tokenExpectedExpiration: '2023-03-19T22:01:13.056Z',
refreshTokenExpectedExpiration: '2023-04-17T21:32:13.056Z',
serviceLoginId: 'my-frontend-service-login-id',
currentDatabaseId: 'ZFhtzINgq2Uz0AAvRSw4TQ'
}
*/
RecommendationClient
persistCredentialsInLocalStorage
CreateOneAnonymousSessionInteractionCommand
GetHistoricalDataCommand
GetHistoricalDataByCountTypeCommand
GetRelatedItemRecommendationsCommand
GetSessionBasedItemRecommendationsCommand
GetUserBasedItemRecommendationsCommand
ListAllDatabasesCommand
ListRecentBackgroundTasksCommand
LoginIndividualCommand
LoginServiceCommand
RenewLoginWithRefreshTokenCommand
GetCurrentDatabase
CreateInteractionsForManyUsers
ListAllItemProperties
ListAllUserProperties
ListPropertiesOfAllItems
ResolveOneAnonymousSession
UpdateItemPropertiesInBulk
UpdateUserPropertiesInBulk