Vue Storefront is now Alokai! Learn More
@vsf-enterprise/bloomreach-discovery-api

@vsf-enterprise/bloomreach-discovery-api

7.0.0

Minor Changes

  • ADDED Error adapter for Bloomreach Discovery API client with standardized error normalization.

What changed:

All Bloomreach Discovery API client methods now automatically normalize errors to HttpError instances:

  • HTTP errors from the API preserve their original status codes
  • Network errors return 502 Bad Gateway
  • All errors include standardized format for debugging

New exports:

  • errorAdapter - Provides createNormalizer() and withErrorNormalizer() methods
  • BloomreachDiscoveryAdapter - Type interface for the error adapter

Migration notes:

The error adapter is automatically applied to clients created via buildClient(). If you have custom error handling logic that depends on catching native Axios errors directly, you should now catch HttpError instead. The original error is available via error.cause property.

Minor Changes

  • ADDED New dedicated @vsf-enterprise/bloomreach-discovery-api package that implements the official Bloomreach Discovery REST API. This package provides fully typed API methods generated from OpenAPI specifications, offering better performance, type safety, and access to all modern Bloomreach Discovery features.

The package includes the following API clients:

  • Product & Category Search API: Search and filter products with faceting support
  • Autosuggest API: Real-time search suggestions for query and products
  • Content Search API: Search through content items
  • Bestseller API: Retrieve bestselling products
  • Recommendations and Pathways API: Item-based and personalized recommendations
  • Email Widget API: Email campaign widget support
  • Facet Version 3.0: Enhanced faceting and filtering capabilities

Middleware Configuration:

// apps/storefront-middleware/integrations/bloomreach-discovery/config.ts
import type {
  ApiClientExtension,
  Integration,
} from "@alokai/connect/middleware";
import type { MiddlewareConfig } from "@vsf-enterprise/bloomreach-discovery-api";

export const config = {
  configuration: {
    discoveryApi: {
      accountId: Number(process.env.BLOOMREACH_DISCOVERY_ACCOUNT_ID),
      authKey: process.env.BLOOMREACH_DISCOVERY_AUTH_KEY,
      domainKey: process.env.BLOOMREACH_DISCOVERY_DOMAIN_KEY,
      facetVersion: "3.0",
    },
  },
  extensions: (existing: ApiClientExtension[]) => [...existing],
  location: "@vsf-enterprise/bloomreach-discovery-api/server",
} satisfies Integration<Config>;

SDK Usage:

// storefront-unified-nextjs/sdk/modules/bloomreach-discovery.ts
import { defineSdkModule } from "@vue-storefront/next";
import type { BrDiscoveryEndpoints } from "storefront-middleware/types";

export const bloomreachDiscovery = defineSdkModule(
  ({ buildModule, config, middlewareModule }) =>
    buildModule(middlewareModule<BrDiscoveryEndpoints>, {
      apiUrl: `${config.apiUrl}/bloomreach-discovery`,
      ssrApiUrl: `${config.ssrApiUrl}/bloomreach-discovery`,
    }),
);

// Usage in components
const sdk = getSdk();
const searchResults = await sdk.bloomreachDiscovery.productSearchApi({
  q: "running shoes",
  rows: 20,
  start: 0,
});
  • ADDED Legacy extension support for backward compatibility with the existing GraphQL-based Bloomreach Discovery API. Customers can optionally configure the legacy extension to maintain existing integrations while gradually migrating to the new REST API.

Legacy Configuration:

export const config = {
  configuration: {
    discoveryApi: {
      accountId: Number(process.env.BLOOMREACH_DISCOVERY_ACCOUNT_ID),
      authKey: process.env.BLOOMREACH_DISCOVERY_AUTH_KEY,
      domainKey: process.env.BLOOMREACH_DISCOVERY_DOMAIN_KEY,
      facetVersion: "3.0",
    },
    legacy: process.env.BLOOMREACH_LEGACY_ENDPOINT
      ? {
          endpoint: process.env.BLOOMREACH_LEGACY_ENDPOINT,
          envId: process.env.BLOOMREACH_LEGACY_ENV_ID,
        }
      : undefined,
  },
  extensions: (existing: ApiClientExtension[]) => [...existing],
  location: "@vsf-enterprise/bloomreach-discovery-api/server",
} satisfies Integration<Config>;

Migration guide

Migrating from GraphQL to REST API

If you're currently using the legacy GraphQL-based Bloomreach Discovery integration, follow these steps to migrate to the new REST API:

Step 1: Update middleware configuration

// apps/storefront-middleware/integrations/bloomreach-discovery/config.ts
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
-import type { ApiConfig } from './types/config';
+import type { MiddlewareConfig } from '@vsf-enterprise/bloomreach-discovery-api';

-export const config = {
-  configuration: {
-    endpoint: process.env.BLOOMREACH_ENDPOINT,
-    envId: process.env.BLOOMREACH_ENV_ID,
-  },
-  extensions: (existing: ApiClientExtension[]) => [...existing],
-  location: '@/integrations/bloomreach-discovery',
-} satisfies Integration<ApiConfig>;
+export const config = {
+  configuration: {
+    discoveryApi: {
+      accountId: Number(process.env.BLOOMREACH_DISCOVERY_ACCOUNT_ID),
+      authKey: process.env.BLOOMREACH_DISCOVERY_AUTH_KEY,
+      domainKey: process.env.BLOOMREACH_DISCOVERY_DOMAIN_KEY,
+      facetVersion: '3.0',
+    },
+  },
+  extensions: (existing: ApiClientExtension[]) => [...existing],
+  location: '@vsf-enterprise/bloomreach-discovery-api/server',
+} satisfies Integration<Config>;

Step 2: Update environment variables

-.env
-BLOOMREACH_ENDPOINT=https://your-graphql-endpoint.bloomreach.io/graphql
-BLOOMREACH_ENV_ID=your_environment_id
+BLOOMREACH_DISCOVERY_ACCOUNT_ID=your_account_id
+BLOOMREACH_DISCOVERY_DOMAIN_KEY=your_domain_key
+BLOOMREACH_DISCOVERY_AUTH_KEY=your_auth_key

Step 3: Update SDK configuration

// storefront-unified-nextjs/sdk/modules/bloomreach-discovery.ts
import { defineSdkModule } from '@vue-storefront/next';
-import { bloomreachDiscoveryModule } from '@vsf-enterprise/bloomreach-discovery-sdk';
+import type { BrDiscoveryEndpoints } from 'storefront-middleware/types';

-export const brd = defineSdkModule(({ buildModule, config }) =>
-  buildModule(bloomreachDiscoveryModule, {
+export const bloomreachDiscovery = defineSdkModule(({ buildModule, config, middlewareModule }) =>
+  buildModule(middlewareModule<BrDiscoveryEndpoints>, {
    apiUrl: `${config.apiUrl}/bloomreach-discovery`,
    ssrApiUrl: `${config.ssrApiUrl}/bloomreach-discovery`,
  }),
);

Step 4: Update API calls

// Before: Using GraphQL SDK with predefined queries
-const data = await sdk.brd.findItemsByKeyword({
-  text: 'running shoes',
-  expect: `items { displayName, price }`,
-});

// After: Using new typed REST API methods
+const results = await sdk.bloomreachDiscovery.productSearchApi({
+  q: 'running shoes',
+  rows: 20,
+  start: 0,
+  fl: 'pid,title,price,thumb_image',
+});
+
+const products = results.data.response.docs;

Maintaining legacy support during migration

If you need to maintain the legacy GraphQL API during migration, you can configure both APIs simultaneously:

Step 1: Add legacy configuration

// apps/storefront-middleware/integrations/bloomreach-discovery/config.ts
export const config = {
  configuration: {
    discoveryApi: {
      accountId: Number(process.env.BLOOMREACH_DISCOVERY_ACCOUNT_ID),
      authKey: process.env.BLOOMREACH_DISCOVERY_AUTH_KEY,
      domainKey: process.env.BLOOMREACH_DISCOVERY_DOMAIN_KEY,
      facetVersion: "3.0",
    },
    legacy: {
      endpoint: process.env.BLOOMREACH_LEGACY_ENDPOINT,
      envId: process.env.BLOOMREACH_LEGACY_ENV_ID,
    },
  },
  extensions: (existing: ApiClientExtension[]) => [...existing],
  location: "@vsf-enterprise/bloomreach-discovery-api/server",
} satisfies Integration<Config>;

Step 2: Use legacy SDK alongside new API

// storefront-unified-nextjs/sdk/modules/bloomreach-discovery-legacy.ts
import { defineSdkModule } from "@vue-storefront/next";
import { bloomreachDiscoveryModule } from "@vsf-enterprise/bloomreach-discovery-sdk";

export const bloomreachDiscoveryLegacy = defineSdkModule(
  ({ buildModule, config }) =>
    buildModule(bloomreachDiscoveryModule, {
      apiUrl: `${config.apiUrl}/bloomreach-discovery/legacy`,
      ssrApiUrl: `${config.ssrApiUrl}/bloomreach-discovery/legacy`,
    }),
);

// Usage: Both APIs available
const newApiResults = await sdk.bloomreachDiscovery.productSearchApi({
  q: "shoes",
  rows: 20,
});
const legacyResults = await sdk.bloomreachDiscoveryLegacy.findItemsByKeyword({
  text: "shoes",
});

For detailed migration instructions and usage examples, see the Bloomreach Discovery documentation.

  • ADDED Unified API extension for Bloomreach Discovery.

Adds createUnifiedExtension for @vsf-enterprise/bloomreach-discovery-api that implements searchProducts and getProductDetails endpoints via the Bloomreach Discovery productCategorySearch API. Includes normalizers for product catalog items, facets (v3 and legacy), pagination, pricing, images, and ratings. Supports multi-currency price fields, configurable facet filtering, range facets, category navigation, and custom basePath for environment switching.

Patch Changes

  • CHANGED Updated internal dependencies for Yarn 4 compatibility.
  • CHANGED Replaced Rollup with tsdown for @vsf-enterprise and @alokai package builds.
  • Updated dependencies:
    • @alokai/connect@2.0.0
    • @alokai/middleware-axios-error-adapter@1.0.0

6.0.0

Major Changes

  • CHANGED Guarantee compatibility with @alokai/connect package.
  • CHANGED Updated the package for compatibility with Node.js 22.

Key Updates:

  • Upgraded to the latest version of Node.js 22
  • Updated CI pipelines to use Node.js 22 for consistency.
  • Updated .nvmrc or .node-version files to specify Node.js version 22.14.
  • Upgraded @types/node to version ^22.13.17 for compatibility with the latest Node.js features.

Recommendations:

  • Use Node.js version 22.14.0 or higher for optimal performance, security, and compatibility.
  • While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested. CHANGED Replaced core dependencies with a new @alokai/connect package. @vue-storefront/middleware, @vue-storefront/sdk, vue-storefront/logger, vue-storefront/unified-data-model, @vue-storefront/multistore were replaced with @alokai/connect. The replacement preserves the same functionality and interface as the original packages. To read more about the @alokai/connect package, please refer to the documentation.

Minor Changes

  • CHANGED Update axios version to "^1.7.9"

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0

6.0.0-rc.5

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.4

6.0.0-rc.4

Major Changes

  • CHANGED Updated the package for compatibility with Node.js 22.

Key Updates:

  • Upgraded to the latest version of Node.js 22
  • Updated CI pipelines to use Node.js 22 for consistency.
  • Updated .nvmrc or .node-version files to specify Node.js version 22.14.
  • Upgraded @types/node to version ^22.13.17 for compatibility with the latest Node.js features.

Recommendations:

  • Use Node.js version 22.14.0 or higher for optimal performance, security, and compatibility.
  • While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested.

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.3

6.0.0-rc.3

Minor Changes

  • CHANGED Update axios version to "^1.7.9"

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.2

6.0.0-rc.2

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.1

6.0.0-rc.1

Major Changes

Update packages to work with connect rc version

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.0

6.0.0-rc.0

Major Changes

CHANGED Replaced core dependencies with a new @alokai/connect package. @vue-storefront/middleware, @vue-storefront/sdk, vue-storefront/logger, vue-storefront/unified-data-model were replaced with @alokai/connect. The replacement preserves the same functionality and interface as the original packages. To read more about the @alokai/connect package, please refer to the documentation. You will also find a migration guide in the documentation.

5.1.0

Minor Changes

  • CHANGED Replace console with Alokai Logger. To learn more about logger, visit Alokai Logger.

5.0.0

Major Changes

CHANGE - Update middleware in packages to 5.1.0

4.0.0

Major Changes

  • BREAKING Updated @vue-storefront/middleware version to 4.1.0. Make sure this version is used in your project.
{
  ...
  "dependencies": {
-   "@vue-storefront/middleware": "3.x.x",
+   "@vue-storefront/middleware": "4.1.0"
  }
}

3.0.1

Patch Changes

Update axios to ^0.28.0 to mitigate security vulnerability CVE-2023-45857

3.0.0

Major Changes

  • CHANGED Changed minimum Node version from 16 to 18. The condition that was forcing the Node version to be lower than 19 is also removed.

2.1.0

Minor Changes

  • #35 f5c88f7 Thanks @lsliwaradioluz! - Bumped axios version to ^0.27.2 and @vue-storefront/middleware version to ^3.5.0 which introduces support for HTTP GET requests.

2.0.0

Major Changes

  • Added support for Node 18, and dropped support for Node 14