@crossingminds/recommendation-client

Crossing Minds - Recommendation Client

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.

Type Documentation

For the most up-to-date information on exports and interfaces, please visit TS Docs.

Note: This documentation is currently in beta and works most of the time.

Installation

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";

Usage

Basic

// 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
  }
}

Auth

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'
}
*/

Exports

RecommendationClient

persistCredentialsInLocalStorage

CreateOneAnonymousSessionInteractionCommand

GetHistoricalDataCommand

GetHistoricalDataByCountTypeCommand

GetRelatedItemRecommendationsCommand

GetSessionBasedItemRecommendationsCommand

GetUserBasedItemRecommendationsCommand

ListAllDatabasesCommand

ListRecentBackgroundTasksCommand

LoginIndividualCommand

LoginServiceCommand

RenewLoginWithRefreshTokenCommand

GetCurrentDatabase

CreateInteractionsForManyUsers

ListAllItemProperties

ListAllUserProperties

ListPropertiesOfAllItems

ResolveOneAnonymousSession

UpdateItemPropertiesInBulk

UpdateUserPropertiesInBulk