bluestone-commercetools API

Everything the package exports, by the path you import it from. Open an export for its signature and options.

@evolve-framework/bluestone-commercetools

Everything below except ./testing, plus SyncContext and createSyncContext

Classes

BluestoneCommercetoolsConfigThe environment configuration of the sync: the CTP_* settings of CommercetoolsConfig, plus Bluestone and the commercetools keys the sync writes with.

import { BluestoneCommercetoolsConfig } from "@evolve-framework/bluestone-commercetools";

Extends CommercetoolsConfig

new BluestoneCommercetoolsConfig()

BluestoneCommercetoolsModuleThe HTTP module that receives Bluestone's webhook.

import { BluestoneCommercetoolsModule } from "@evolve-framework/bluestone-commercetools";

• POST /product-sync-done verifies the signature and the payload, passes the payload to publishMessage and answers 201. It answers 401 for a bad signature or payload, and 500 when publishMessage throws.
• GET /healthcheck answers 200 with the component name.

It does not run the sync: a queue consumer does that with handleProductSyncDone, so Bluestone gets its answer at once.

Extends AbstractModule<unknown>

new BluestoneCommercetoolsModule(options: BluestoneCommercetoolsModuleOptions)

Option	Type	Description
config	BluestoneCommercetoolsModuleConfig	How the webhook checks its calls, and what the healthcheck reports.
publishMessage	(payload: { timestamp: number; events: { changes: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: …	Called with the payload once its signature and shape are valid. It usually publishes to a queue, with a MessagePublisher from a cloud adapter. A test or a single-process deployment can call handleProductSyncDone directly instead, but then Bluestone waits for the whole sync.

BluestonePimClientThe Bluestone PIM APIs the sync reads from: products, categories, the differences of a sync, and the publication contexts.

import { BluestonePimClient } from "@evolve-framework/bluestone-commercetools";

new BluestonePimClient(configuration: Configuration)

Method	Description
products(): ProductsApi	The Products API, to read products and their variants.
categories(): CategoriesApi	The Categories API, to read the category tree.
differences(): DifferencesApi	The Differences API, to read what changed in a Bluestone sync.
contexts(): ContextsApi	The Contexts API, to read the publication contexts.

Functions

createBluestonePimClientCreate a Bluestone PIM client from BLUESTONE_API_KEY and BLUESTONE_API_URL.

import { createBluestonePimClient } from "@evolve-framework/bluestone-commercetools";

function createBluestonePimClient(
  config: BluestoneCommercetoolsConfig,
): BluestonePimClient

Returns BluestonePimClient

createCtClientCreate the commercetools request builder the sync writes with, from the CTP_* settings of the configuration.

import { createCtClient } from "@evolve-framework/bluestone-commercetools";

function createCtClient(
  config: BluestoneCommercetoolsConfig,
): Promise<RequestBuilder>

Returns Promise<RequestBuilder>

createSyncContextBuild a SyncContext from a loaded configuration, with both clients created by createBluestonePimClient and createCtClient.

import { createSyncContext } from "@evolve-framework/bluestone-commercetools";

function createSyncContext(
  config: BluestoneCommercetoolsConfig,
): Promise<SyncContext>

Returns Promise<SyncContext>

fullSyncCopy the complete webshop from Bluestone to commercetools, for every publication context: the category tree under BLUESTONE_CATEGORY_WEBSHOP_ID, then all products in it, then their related products.

import { fullSync } from "@evolve-framework/bluestone-commercetools";

A context without locales in BLUESTONE_CONTEXT_MAPPING is skipped. The sync id it writes is manual.

function fullSync(ctx: SyncContext): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

handleProductSyncDoneThe queue consumer for a webhook payload: runs sync for its event, dated with the payload's timestamp.

import { handleProductSyncDone } from "@evolve-framework/bluestone-commercetools";

function handleProductSyncDone(
  ctx: SyncContext,
  message: { timestamp: number; events: { changes: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: string; }; }; }[]; },
): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

syncApply one Bluestone sync to commercetools: first the categories, then the products, then the related products of every product that was created or updated.

import { sync } from "@evolve-framework/bluestone-commercetools";

function sync(
  ctx: SyncContext,
  payload: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: string; }; },
  syncDate: Date,
): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

Constants

webhookPayloadSchemaZod schema of the body Bluestone posts to POST /product-sync-done.

import { webhookPayloadSchema } from "@evolve-framework/bluestone-commercetools";

const webhookPayloadSchema: ZodObject<{ timestamp: ZodNumber; events: ZodArray<ZodObject<{ changes: ZodObject<{ eventType: ZodLiteral<"PRODUCT_SYNC_DONE">; entityIds: ZodArray<ZodString>; …

Types

BluestoneCommercetoolsModuleConfigHow the webhook checks its calls, and what the healthcheck reports.

import { type BluestoneCommercetoolsModuleConfig } from "@evolve-framework/bluestone-commercetools";

export type BluestoneCommercetoolsModuleConfig = {
  webhookSecret: string;
  validateSignature?: boolean;
  componentName?: string;
};

ProductSyncDoneEventThe event Bluestone sends when it finished publishing a sync.

import { type ProductSyncDoneEvent } from "@evolve-framework/bluestone-commercetools";

export type ProductSyncDoneEvent = z.infer<typeof productSyncDoneEventSchema>;

SyncContextWhat a sync needs at runtime: the configuration and both clients.

import { type SyncContext } from "@evolve-framework/bluestone-commercetools";

type SyncContext = {
  config: BluestoneCommercetoolsConfig;
  bluestone: BluestonePimClient;
  ct: RequestBuilder;
};

WebhookPayloadThe body of a Bluestone webhook, as webhookPayloadSchema validates it.

import { type WebhookPayload } from "@evolve-framework/bluestone-commercetools";

export type WebhookPayload = z.infer<typeof webhookPayloadSchema>;

@evolve-framework/bluestone-commercetools/client

BluestonePimClient and createBluestonePimClient, the Bluestone PIM API client, which retries when it is rate limited

Classes

BluestonePimClientThe Bluestone PIM APIs the sync reads from: products, categories, the differences of a sync, and the publication contexts.

import { BluestonePimClient } from "@evolve-framework/bluestone-commercetools/client";

new BluestonePimClient(configuration: Configuration)

Method	Description
products(): ProductsApi	The Products API, to read products and their variants.
categories(): CategoriesApi	The Categories API, to read the category tree.
differences(): DifferencesApi	The Differences API, to read what changed in a Bluestone sync.
contexts(): ContextsApi	The Contexts API, to read the publication contexts.

Functions

createBluestonePimClientCreate a Bluestone PIM client from BLUESTONE_API_KEY and BLUESTONE_API_URL.

import { createBluestonePimClient } from "@evolve-framework/bluestone-commercetools/client";

function createBluestonePimClient(
  config: BluestoneCommercetoolsConfig,
): BluestonePimClient

Returns BluestonePimClient

@evolve-framework/bluestone-commercetools/commercetools

createCtClient, the commercetools request builder for the sync

Functions

createCtClientCreate the commercetools request builder the sync writes with, from the CTP_* settings of the configuration.

import { createCtClient } from "@evolve-framework/bluestone-commercetools/commercetools";

function createCtClient(
  config: BluestoneCommercetoolsConfig,
): Promise<RequestBuilder>

Returns Promise<RequestBuilder>

@evolve-framework/bluestone-commercetools/config

BluestoneCommercetoolsConfig, the environment configuration that a service loads or extends

Classes

BluestoneCommercetoolsConfigThe environment configuration of the sync: the CTP_* settings of CommercetoolsConfig, plus Bluestone and the commercetools keys the sync writes with.

import { BluestoneCommercetoolsConfig } from "@evolve-framework/bluestone-commercetools/config";

Extends CommercetoolsConfig

new BluestoneCommercetoolsConfig()

@evolve-framework/bluestone-commercetools/core/sync

sync, which applies one Bluestone sync to commercetools

Functions

syncApply one Bluestone sync to commercetools: first the categories, then the products, then the related products of every product that was created or updated.

import { sync } from "@evolve-framework/bluestone-commercetools/core/sync";

function sync(
  ctx: SyncContext,
  payload: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: string; }; },
  syncDate: Date,
): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

@evolve-framework/bluestone-commercetools/events/product-sync-done

handleProductSyncDone, the queue consumer for a webhook payload

Functions

handleProductSyncDoneThe queue consumer for a webhook payload: runs sync for its event, dated with the payload's timestamp.

import { handleProductSyncDone } from "@evolve-framework/bluestone-commercetools/events/product-sync-done";

function handleProductSyncDone(
  ctx: SyncContext,
  message: { timestamp: number; events: { changes: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: string; }; }; }[]; },
): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

@evolve-framework/bluestone-commercetools/messages

webhookPayloadSchema and the webhook payload types

Constants

webhookPayloadSchemaZod schema of the body Bluestone posts to POST /product-sync-done.

import { webhookPayloadSchema } from "@evolve-framework/bluestone-commercetools/messages";

const webhookPayloadSchema: ZodObject<{ timestamp: ZodNumber; events: ZodArray<ZodObject<{ changes: ZodObject<{ eventType: ZodLiteral<"PRODUCT_SYNC_DONE">; entityIds: ZodArray<ZodString>; …

Types

ProductSyncDoneEventThe event Bluestone sends when it finished publishing a sync.

import { type ProductSyncDoneEvent } from "@evolve-framework/bluestone-commercetools/messages";

export type ProductSyncDoneEvent = z.infer<typeof productSyncDoneEventSchema>;

WebhookPayloadThe body of a Bluestone webhook, as webhookPayloadSchema validates it.

import { type WebhookPayload } from "@evolve-framework/bluestone-commercetools/messages";

export type WebhookPayload = z.infer<typeof webhookPayloadSchema>;

@evolve-framework/bluestone-commercetools/module

BluestoneCommercetoolsModule, the HTTP module with POST /product-sync-done and GET /healthcheck, and its option types

Classes

BluestoneCommercetoolsModuleThe HTTP module that receives Bluestone's webhook.

import { BluestoneCommercetoolsModule } from "@evolve-framework/bluestone-commercetools/module";

• POST /product-sync-done verifies the signature and the payload, passes the payload to publishMessage and answers 201. It answers 401 for a bad signature or payload, and 500 when publishMessage throws.
• GET /healthcheck answers 200 with the component name.

It does not run the sync: a queue consumer does that with handleProductSyncDone, so Bluestone gets its answer at once.

Extends AbstractModule<unknown>

new BluestoneCommercetoolsModule(options: BluestoneCommercetoolsModuleOptions)

Option	Type	Description
config	BluestoneCommercetoolsModuleConfig	How the webhook checks its calls, and what the healthcheck reports.
publishMessage	(payload: { timestamp: number; events: { changes: { eventType: "PRODUCT_SYNC_DONE"; entityIds: string[]; syncDoneData: { field: string; value: string; context: …	Called with the payload once its signature and shape are valid. It usually publishes to a queue, with a MessagePublisher from a cloud adapter. A test or a single-process deployment can call handleProductSyncDone directly instead, but then Bluestone waits for the whole sync.

Types

BluestoneCommercetoolsModuleConfigHow the webhook checks its calls, and what the healthcheck reports.

import { type BluestoneCommercetoolsModuleConfig } from "@evolve-framework/bluestone-commercetools/module";

export type BluestoneCommercetoolsModuleConfig = {
  webhookSecret: string;
  validateSignature?: boolean;
  componentName?: string;
};

@evolve-framework/bluestone-commercetools/processes/full

fullSync, which copies the complete webshop tree

Functions

fullSyncCopy the complete webshop from Bluestone to commercetools, for every publication context: the category tree under BLUESTONE_CATEGORY_WEBSHOP_ID, then all products in it, then their related products.

import { fullSync } from "@evolve-framework/bluestone-commercetools/processes/full";

A context without locales in BLUESTONE_CONTEXT_MAPPING is skipped. The sync id it writes is manual.

function fullSync(ctx: SyncContext): Promise<void>

Option	Type	Description
config	BluestoneCommercetoolsConfig	The loaded configuration.
bluestone	BluestonePimClient	The client the sync reads Bluestone PIM with.
ct	ByProjectKeyRequestBuilder	The commercetools request builder the sync writes with.

Returns Promise<void>

Not listed: 4 options types. They appear as the tables under the constructors and functions they type.