Crossing Minds - Beam Core

A high-level library for integrating Crossing Minds recommendation services into your application. Beam Core provides easy access to personalized recommendation APIs in a library with minimal dependencies that can run in browsers and servers.

Installation

Install the package using your preferred package manager:

npm install @crossingminds/beam-core
# or
pnpm add @crossingminds/beam-core

Prerequisites

Account Details

You'll need the following Crossing Minds account details:

• A service account serviceLoginId with a frontend role
• A serviceLoginKey for the service account
• A databaseId in the same organization as your service account

If you don't have a service account, you can add one in Beam Studio (the Crossing Minds admin console), or contact Crossing Minds directly.

Note: Only service accounts can be used with this library, not individual or team accounts.

By default, only accounts with a frontend role can be used with this library. This is because this library assumes lenient permissions where the serviceLoginKey of frontend accounts is not secret, allowing for easier auth implementation.

Session Management

sessionIds are required to use most parts of this library. A sessionId is a unique identifier assigned to an end-user of your product. Every end-user must be assigned a unique sessionId, which should be a UUID and remain consistent for that end-user across server and client environments for as long as your product defines a session.

Note that userIds are different from sessionIds:

• userIds are only assigned to known (logged-in) end-users and remain permanent
• sessionIds are assigned to all end-users, including anonymous ones

Core Functions

Get Recommendations

Beam Core provides several methods to retrieve recommendations:

// Get personalized recommendations for a user or session
const { itemIds } = await getPersonalizedRecommendations({
  databaseId: "your-database-id",
  serviceLoginId: "your-service-login-id",
  serviceLoginKey: "your-service-login-key",
  sessionId: "user-session-id",
});

// Get item-based recommendations
const { itemIds } = await getRelatedItemRecommendations({
  databaseId: "your-database-id",
  serviceLoginId: "your-service-login-id",
  serviceLoginKey: "your-service-login-key",
  itemId: "product-12345",
  sessionId: "user-session-id",
  scenario: "similar_products",
});

// Get precomputed item-based recommendations
const { itemIds } = await getPrecomputedItemBasedRecommendations({
  databaseId: "your-database-id",
  serviceLoginId: "your-service-login-id",
  serviceLoginKey: "your-service-login-key",
  itemId: "product-12345",
  sessionId: "user-session-id",
  scenario: "frequently_bought_together",
});

Track User Events

Record interactions to improve recommendation quality:

// Record when a user views an item
await emitEvent({
  databaseId: "your-database-id",
  serviceLoginId: "your-service-login-id",
  serviceLoginKey: "your-service-login-key",
  sessionId: "user-session-id",
  event: {
    event_type: "view",
    item_id: "product-12345",
    timestamp: new Date().toISOString(),
  },
});

Resolve Sessions

Associate anonymous sessions with known users:

// Link a session ID to a user ID when a user logs in
const success = await resolveSessionId({
  databaseId: "your-database-id",
  serviceLoginId: "your-service-login-id",
  serviceLoginKey: "your-service-login-key",
  sessionId: "anonymous-session-id",
  userId: "authenticated-user-id",
});

Server and Client Usage

Beam Core works in both browser and server environments. For server environments (like Node.js), simply use the library as shown above.

For browser environments, you can integrate with frameworks like React Query:

import { useQuery } from "@tanstack/react-query";
import { getRelatedItemRecommendations } from "@crossingminds/beam-core";

function ProductRecommendations({ itemId, sessionId }) {
  const { data, isLoading } = useQuery({
    queryKey: ["recommendations", itemId, sessionId],
    queryFn: async () => {
      const { itemIds } = await getRelatedItemRecommendations({
        databaseId: "your-database-id",
        serviceLoginId: "your-service-login-id",
        serviceLoginKey: "your-service-login-key",
        itemId,
        sessionId,
        scenario: "similar_products"
      });
      return itemIds;
    }
  });

  if (isLoading) return <div>Loading recommendations...</div>;

  return (
    <div>
      {data.map(id => (
        <ProductCard key={id} id={id} />
      ))}
    </div>
  );
}

API Reference

Core Functions

| Function | Description | | ---------------------------------------- | --------------------------------------------------- | | getItemRecommendations | Flexible "generic" recommendation endpoint | | getPersonalizedRecommendations | Get user or session-based recommendations | | getRelatedItemRecommendations | Get item-to-item recommendations | | getPrecomputedItemBasedRecommendations | Get precomputed item-to-item recommendations | | getPropertyRecommendations | Get recommended properties based on user or session | | emitEvent | Record user interactions (views, purchases, etc.) | | resolveSessionId | Associate a session ID with a user ID |

Utility Exports

| Export | Description | | -------------------------- | ------------------------------------------------- | | AccessSessionId | Helper class for managing session IDs in browsers | | SCENARIO_OMITTED | Symbol to explicitly omit scenario parameter | | OptimizedInputProperties | Type for common input parameters | | MEMORY_CACHE_ONLY | Symbol to prevent localStorage usage |

TypeScript Support

This library includes comprehensive TypeScript definitions for all exports.

Framework-specific Libraries

If you're using React, check out @crossingminds/beam-react for React-specific hooks and components.

Documentation

For more detailed API documentation, visit Crossing Minds API Documentation.