Add context workflow identifier support

src/behavioural-events/event.ts

@@ -7,6 +7,7 @@ export type EventData = {
   appUserId: string;
   properties: EventProperties;
   context: EventContext;
+  workflowIdentifier?: string;
 };
 
 type EventContextSingleValue = string | number | boolean;
@@ -67,6 +68,9 @@ export class Event {
       properties: {
         ...this.data.properties,
         traceId: this.data.traceId,
+        ...(this.data.workflowIdentifier !== undefined
+          ? { workflowIdentifier: this.data.workflowIdentifier }
+          : {}),
       },
     }) as EventPayload;
   }

src/behavioural-events/events-tracker.ts

@@ -10,6 +10,7 @@ import {
   buildEventContext,
   type SDKEventContextSource,
 } from "./sdk-event-context";
+import type { WorkflowContext } from "../entities/purchases-config";
 
 const MIN_INTERVAL_RETRY = 2_000;
 const MAX_INTERVAL_RETRY = 5 * 60_000;
@@ -26,6 +27,7 @@ export interface EventsTrackerProps {
   appUserId: string;
   rcSource: string | null;
   silent?: boolean;
+  workflowContext?: WorkflowContext;
 }
 
 export interface IEventsTracker {
@@ -49,13 +51,15 @@ export default class EventsTracker implements IEventsTracker {
   private appUserId: string;
   private readonly isSilent: boolean;
   private rcSource: string | null;
+  private readonly workflowContext?: WorkflowContext;
 
   constructor(props: EventsTrackerProps) {
     this.apiKey = props.apiKey;
     this.eventsUrl = `${RC_ANALYTICS_ENDPOINT}/v1/events`;
     this.appUserId = props.appUserId;
     this.isSilent = props.silent || false;
     this.rcSource = props.rcSource;
+    this.workflowContext = props.workflowContext;
     this.flushManager = new FlushManager(
       MIN_INTERVAL_RETRY,
       MAX_INTERVAL_RETRY,
@@ -91,6 +95,7 @@ export default class EventsTracker implements IEventsTracker {
         traceId: this.traceId,
         appUserId: this.appUserId,
         context: buildEventContext(props.source, this.rcSource),
+        workflowIdentifier: this.workflowContext?.workflowIdentifier,
         properties: props.properties || {},
       });
       this.eventsQueue.push(event);

src/entities/purchases-config.ts

@@ -1,6 +1,28 @@
 import type { FlagsConfig } from "./flags-config";
 import type { HttpConfig } from "./http-config";
 
+/**
+ * Contextual information specific to workflows.
+ * @internal
+ */
+export interface WorkflowContext {
+  /**
+   * Optional identifier to group events emitted by the SDK.
+   */
+  workflowIdentifier?: string;
+}
+
+/**
+ * Additional context to be associated with the configured Purchases instance.
+ * @internal
+ */
+export interface PurchasesContext {
+  /**
+   * Optional workflow-specific context shared across SDK components.
+   */
+  workflowContext?: WorkflowContext;
+}
+
 /**
  * Configuration object for initializing the Purchases SDK.
  *
@@ -42,4 +64,9 @@ export interface PurchasesConfig {
    * Advanced functionality configuration {@link FlagsConfig}.
    */
   flags?: FlagsConfig;
+  /**
+   * Additional contextual information for the Purchases instance.
+   * @internal
+   */
+  context?: PurchasesContext;
 }

src/main.ts

@@ -75,7 +75,10 @@ import {
   type FlagsConfig,
   supportedRCSources,
 } from "./entities/flags-config";
-import { type PurchasesConfig } from "./entities/purchases-config";
+import {
+  type PurchasesConfig,
+  type PurchasesContext,
+} from "./entities/purchases-config";
 import { generateUUID } from "./helpers/uuid-helper";
 import type { PlatformInfo } from "./entities/platform-info";
 import type { ReservedCustomerAttribute } from "./entities/attributes";
@@ -164,6 +167,9 @@ export class Purchases {
   /** @internal */
   private readonly _flags: FlagsConfig;
 
+  /** @internal */
+  private readonly _context?: PurchasesContext;
+
   /** @internal */
   private readonly backend: Backend;
 
@@ -304,7 +310,7 @@ export class Purchases {
   }
 
   private static configureInternal(config: PurchasesConfig): void {
-    const { apiKey, appUserId, httpConfig, flags } = config;
+    const { apiKey, appUserId, httpConfig, flags, context } = config;
     const finalHttpConfig = httpConfig ?? defaultHttpConfig;
     const finalFlags = flags ?? defaultFlagsConfig;
 
@@ -314,6 +320,7 @@ export class Purchases {
       appUserId,
       finalHttpConfig,
       finalFlags,
+      context,
     );
   }
 
@@ -376,10 +383,12 @@ export class Purchases {
     appUserId: string,
     httpConfig: HttpConfig = defaultHttpConfig,
     flags: FlagsConfig = defaultFlagsConfig,
+    context?: PurchasesContext,
   ) {
     this._API_KEY = apiKey;
     this._appUserId = appUserId;
     this._flags = { ...defaultFlagsConfig, ...flags };
+    this._context = context;
     if (RC_ENDPOINT === undefined) {
       Logger.errorLog(
         "Project was build without some of the environment variables set",
@@ -397,6 +406,7 @@ export class Purchases {
       appUserId: this._appUserId,
       silent: !this._flags.collectAnalyticsEvents,
       rcSource: this._flags.rcSource ?? null,
+      workflowContext: this._context?.workflowContext,
     });
     this.backend = new Backend(this._API_KEY, httpConfig);
     this.inMemoryCache = new InMemoryCache();

src/tests/behavioral-events/events-tracker.test.ts

@@ -161,6 +161,39 @@ describe("EventsTracker", (test) => {
     );
   });
 
+  test("passes the workflow identifier to the event", async () => {
+    const eventsTracker = new EventsTracker({
+      apiKey: testApiKey,
+      appUserId: "someAppUserId",
+      rcSource: "rcSource",
+      workflowContext: { workflowIdentifier: "workflow-id" },
+    });
+
+    eventsTracker.trackExternalEvent({
+      eventName: "external",
+      source: "sdk",
+      properties: { a: "b" },
+    });
+
+    await vi.advanceTimersToNextTimerAsync();
+
+    expect(APIPostRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        json: expect.objectContaining({
+          events: expect.arrayContaining([
+            expect.objectContaining({
+              properties: expect.objectContaining({
+                workflow_identifier: "workflow-id",
+              }),
+            }),
+          ]),
+        }),
+      }),
+    );
+
+    eventsTracker.dispose();
+  });
+
   test<EventsTrackerFixtures>("retries tracking events exponentially", async ({
     eventsTracker,
   }) => {

src/tests/main.test.ts

@@ -118,6 +118,7 @@ describe("Purchases.configure()", () => {
       appUserId: testUserId,
       httpConfig: {},
       flags: { autoCollectUTMAsMetadata: false },
+      context: { workflowContext: { workflowIdentifier: "workflow-id" } },
     });
     expect(purchases).toBeDefined();
   });