@decocms/apps-sfmc-personalization 0.0.0-stage → 8.1.0-next.0

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@decocms/apps-sfmc-personalization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.1.0-next.0",
+  "type": "module",
+  "description": "Thin client for Salesforce Marketing Cloud Personalization (formerly Evergage)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-sfmc-personalization"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-sfmc-personalization/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "8.1.0-next.0"
+  },
+  "devDependencies": {
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/__tests__/client.test.ts

@@ -0,0 +1,48 @@
+/**
+ * The Marketing Cloud Personalization client (/next/upstream-clients): the
+ * Event API through the instrumented fetch, errors without bodies.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { createSfmcPersonalizationClient, SfmcPersonalizationError } from "../index";
+
+function fakeFetch(status: number, body: unknown) {
+  return vi.fn(
+    async (_input: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+}
+
+const config = { baseUrl: "https://acme.us-1.evergage.com", dataset: "engage" };
+const event = {
+  source: { channel: "WebServer", url: "https://shop.example.com/" },
+  interaction: { name: "Personalization Campaigns" },
+  user: { anonymousId: "anon-1" },
+  flags: { nonInteractive: true, doNotTrack: false },
+  pageView: false,
+};
+
+describe("createSfmcPersonalizationClient", () => {
+  it("sendEvent posts the event to the dataset and returns the campaigns", async () => {
+    const campaigns = { campaignResponses: [{ campaignId: "c1", payload: { products: [] } }] };
+    const fetch = fakeFetch(200, campaigns);
+    const sfmc = createSfmcPersonalizationClient(config, { fetch });
+
+    await expect(sfmc.sendEvent(event)).resolves.toEqual(campaigns);
+
+    const [url, init] = fetch.mock.calls[0];
+    expect(String(url)).toBe("https://acme.us-1.evergage.com/api2/event/engage");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual(event);
+  });
+
+  it("throws the operation and status, never the body", async () => {
+    const fetch = fakeFetch(500, { error: "anon-1 not found" });
+    const sfmc = createSfmcPersonalizationClient(config, { fetch });
+
+    const error = await sfmc.sendEvent(event).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(SfmcPersonalizationError);
+    expect(error).toMatchObject({ operation: "sendEvent", status: 500 });
+    expect((error as Error).message).not.toContain("anon-1");
+  });
+});

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `@decocms/apps-sfmc-personalization`: a thin client for Salesforce
+ * Marketing Cloud Personalization (formerly Evergage). See /next/upstream-clients.
+ *
+ * Every request goes through `createInstrumentedFetch` with provider
+ * `sfmc-personalization`. No retries or circuit breaker. Reading the
+ * shopper's cookie, converting products to commerce types and caching belong
+ * to the site (platform templates and the framework binding).
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+import type { PersonalizationEvent, PersonalizationResponse } from "./types";
+
+export type {
+  CampaignResponse,
+  PersonalizationEvent,
+  PersonalizationLineItem,
+  PersonalizationProduct,
+  PersonalizationResponse,
+} from "./types";
+
+export interface SfmcPersonalizationConfig {
+  /** The account's API origin, e.g. `https://<account>.<instance>.evergage.com`. */
+  baseUrl: string;
+  /** The dataset events are sent to. */
+  dataset: string;
+}
+
+export class SfmcPersonalizationError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly status: number,
+  ) {
+    super(`sfmc-personalization ${operation} failed with HTTP ${status}`);
+  }
+}
+
+export function createSfmcPersonalizationClient(
+  config: SfmcPersonalizationConfig,
+  options: { fetch?: typeof fetch } = {},
+) {
+  const request = createInstrumentedFetch({
+    provider: "sfmc-personalization",
+    fetch: options.fetch,
+  });
+
+  return {
+    /** Sends an interaction and returns the campaigns it triggered. */
+    async sendEvent(event: PersonalizationEvent): Promise<PersonalizationResponse> {
+      const url = new URL(`/api2/event/${encodeURIComponent(config.dataset)}`, config.baseUrl);
+      const response = await request(url, {
+        operation: "sendEvent",
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(event),
+      });
+      if (!response.ok) throw new SfmcPersonalizationError("sendEvent", response.status);
+      return (await response.json()) as PersonalizationResponse;
+    },
+  };
+}
+
+export type SfmcPersonalizationClient = ReturnType<typeof createSfmcPersonalizationClient>;

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Salesforce Marketing Cloud Personalization (formerly Evergage): request and
+ * response shapes of the Event API (`POST /api2/event/{dataset}`).
+ *
+ * Product fields are configured per dataset, so `PersonalizationProduct`
+ * keeps the common fields and accepts whatever else the dataset exposes.
+ */
+
+export interface PersonalizationProduct {
+  id: string;
+  name: string;
+  /** List price. */
+  price: number;
+  /** Promotional price, when one is active. */
+  salePrice?: number;
+  inventoryCount: number;
+  imageUrls: string[];
+  /** Absolute product URL. */
+  url: string;
+  /** ISO 4217 currency code. */
+  currency: string;
+  description?: string;
+  itemType?: string;
+  categories?: string[];
+  /** Whatever else the dataset's catalog schema defines. */
+  [customField: string]: unknown;
+}
+
+/** A cart line, sent with cart-aware interactions. */
+export interface PersonalizationLineItem {
+  catalogObjectType: string;
+  catalogObjectId: string;
+  quantity: number;
+  price: number;
+}
+
+/** The interaction a shopper had; the response holds the campaigns it triggered. */
+export interface PersonalizationEvent {
+  source: {
+    channel: string;
+    url: string;
+  };
+  interaction: {
+    name: string;
+    lineItems?: PersonalizationLineItem[];
+  };
+  user: {
+    anonymousId?: string;
+    encryptedId?: string;
+    attributes?: Record<string, unknown>;
+  };
+  flags?: {
+    nonInteractive?: boolean;
+    doNotTrack?: boolean;
+  };
+  pageView?: boolean;
+}
+
+export interface CampaignResponse {
+  campaignId: string;
+  payload: {
+    experience?: string;
+    headerText?: string;
+    products?: PersonalizationProduct[];
+    userGroup?: string;
+    [field: string]: unknown;
+  };
+}
+
+export interface PersonalizationResponse {
+  campaignResponses?: CampaignResponse[];
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.