wip

Author: toddbaert

packages/server/src/client/client.ts

@@ -8,12 +8,14 @@ import type {
 import type { Features } from '../evaluation';
 import type { ProviderStatus } from '../provider';
 import type { ProviderEvents } from '../events';
+import type { Tracking } from '../tracking';
 
 export interface Client
   extends EvaluationLifeCycle<Client>,
     Features,
     ManageContext<Client>,
     ManageLogger<Client>,
+    Tracking,
     Eventing<ProviderEvents> {
   readonly metadata: ClientMetadata;
   /**

packages/server/src/client/internal/open-feature-client.ts

@@ -8,6 +8,7 @@ import type {
   HookContext,
   JsonValue,
   Logger,
+  TrackingEventDetails,
   OpenFeatureError,
   ResolutionDetails} from '@openfeature/core';
 import {
@@ -223,6 +224,19 @@ export class OpenFeatureClient implements Client {
     return this.evaluate<T>(flagKey, this._provider.resolveObjectEvaluation, defaultValue, 'object', context, options);
   }
 
+  track(occurrenceKey: string, context: EvaluationContext, occurrenceDetails: TrackingEventDetails): void {
+
+    this.shortCircuitIfNotReady();
+
+    const mergedContext = this.mergeContexts(context);
+
+    if (typeof this._provider.track === 'function') {
+      return this._provider.track?.(occurrenceKey, mergedContext, occurrenceDetails);
+    } else {
+      this._logger.debug('Provider does not implement track function: will no-op.');
+    }
+  }
+
   private async evaluate<T extends FlagValue>(
     flagKey: string,
     resolver: (
@@ -246,13 +260,7 @@ export class OpenFeatureClient implements Client {
     ];
     const allHooksReversed = [...allHooks].reverse();
 
-    // merge global and client contexts
-    const mergedContext = {
-      ...OpenFeature.getContext(),
-      ...OpenFeature.getTransactionContext(),
-      ...this._context,
-      ...invocationContext,
-    };
+    const mergedContext = this.mergeContexts(invocationContext);
 
     // this reference cannot change during the course of evaluation
     // it may be used as a key in WeakMaps
@@ -269,12 +277,7 @@ export class OpenFeatureClient implements Client {
     try {
       const frozenContext = await this.beforeHooks(allHooks, hookContext, options);
 
-      // short circuit evaluation entirely if provider is in a bad state
-      if (this.providerStatus === ProviderStatus.NOT_READY) {
-        throw new ProviderNotReadyError('provider has not yet initialized');
-      } else if (this.providerStatus === ProviderStatus.FATAL) {
-        throw new ProviderFatalError('provider is in an irrecoverable error state');
-      }
+      this.shortCircuitIfNotReady();
 
       // run the referenced resolver, binding the provider.
       const resolution = await resolver.call(this._provider, flagKey, defaultValue, frozenContext, this._logger);
@@ -380,4 +383,23 @@ export class OpenFeatureClient implements Client {
   private get _logger() {
     return this._clientLogger || this.globalLogger();
   }
+
+  private mergeContexts(invocationContext: EvaluationContext) {
+    // merge global and client contexts
+    return {
+      ...OpenFeature.getContext(),
+      ...OpenFeature.getTransactionContext(),
+      ...this._context,
+      ...invocationContext,
+    };
+  }
+
+  private shortCircuitIfNotReady() {
+    // short circuit evaluation entirely if provider is in a bad state
+    if (this.providerStatus === ProviderStatus.NOT_READY) {
+      throw new ProviderNotReadyError('provider has not yet initialized');
+    } else if (this.providerStatus === ProviderStatus.FATAL) {
+      throw new ProviderFatalError('provider is in an irrecoverable error state');
+    }
+  }
 }

packages/server/src/index.ts

@@ -5,4 +5,5 @@ export * from './open-feature';
 export * from './transaction-context';
 export * from './events';
 export * from './hooks';
+export * from './tracking';
 export * from '@openfeature/core';

packages/server/src/provider/provider.ts

@@ -1,5 +1,13 @@
-import type { CommonProvider, EvaluationContext, JsonValue, Logger, ResolutionDetails} from '@openfeature/core';
-import { ServerProviderStatus } from '@openfeature/core';
+import type {
+  CommonProvider,
+  EvaluationContext,
+  JsonValue,
+  Logger,
+  TrackingEventDetails,
+  ResolutionDetails} from '@openfeature/core';
+import {
+  ServerProviderStatus,
+} from '@openfeature/core';
 import type { Hook } from '../hooks';
 
 export { ServerProviderStatus as ProviderStatus };
@@ -58,4 +66,12 @@ export interface Provider extends CommonProvider<ServerProviderStatus> {
     context: EvaluationContext,
     logger: Logger,
   ): Promise<ResolutionDetails<T>>;
+
+  /**
+   * Track a user action or application state, usually representing a business objective or outcome.
+   * @param trackingEventName
+   * @param context
+   * @param trackingEventDetails
+   */
+  track?(trackingEventName: string, context?: EvaluationContext, trackingEventDetails?: TrackingEventDetails): void;
 }

packages/server/src/tracking/index.ts

@@ -0,0 +1 @@
+export * from './tracking';

packages/server/src/tracking/tracking.ts

@@ -0,0 +1,12 @@
+import type { EvaluationContext, TrackingEventDetails } from '@openfeature/core';
+
+export interface Tracking {
+
+  /**
+   * Track a user action or application state, usually representing a business objective or outcome.
+   * @param trackingEventName an identifier for the event
+   * @param context the evaluation context
+   * @param trackingEventDetails the details of the tracking event
+   */
+  track(trackingEventName: string, context?: EvaluationContext, trackingEventDetails?: TrackingEventDetails): void;
+}

packages/shared/src/evaluation/context.ts

@@ -1,4 +1,4 @@
-import type { PrimitiveValue } from './evaluation';
+import type { PrimitiveValue } from '../types';
 
 export type EvaluationContextValue =
   | PrimitiveValue

packages/shared/src/evaluation/evaluation.ts

@@ -1,13 +1,6 @@
-export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
-
-export type PrimitiveValue = null | boolean | string | number;
-export type JsonObject = { [key: string]: JsonValue };
-export type JsonArray = JsonValue[];
+import type { JsonValue } from '../types/structure';
 
-/**
- * Represents a JSON node value.
- */
-export type JsonValue = PrimitiveValue | JsonObject | JsonArray;
+export type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
 
 /**
  * Represents a JSON node value, or Date.

packages/shared/src/index.ts

@@ -7,4 +7,5 @@ export * from './logger';
 export * from './provider';
 export * from './evaluation';
 export * from './type-guards';
+export * from './tracking';
 export * from './open-feature';

packages/shared/src/tracking/index.ts

@@ -0,0 +1 @@
+export * from './tracking-event';