@revturbine/sdk 0.2.36 → 0.2.37

package/dist/types/web-sdk/react/TelemetryScope.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+/**
+ * Advisory event purpose (plan 144 TASK-12 / REQ-28). A **server-side allowlist**
+ * — never this client-declared value — decides whether an event feeds engagement
+ * scoring. The listed values are suggestions; any string is accepted.
+ */
+export type TrackPurpose = 'engagement' | 'conversion' | 'operational' | 'diagnostic' | (string & {});
+/**
+ * Ambient telemetry context established by {@link TelemetryScope} and merged into
+ * every event emitted by {@link useTrack} beneath it.
+ */
+export interface TelemetryScopeValue {
+    /** Logical product area (e.g. `'billing'`, `'editor'`). */
+    area?: string;
+    /** Default action label for events in this scope. */
+    action?: string;
+    /** Advisory {@link TrackPurpose}. */
+    purpose?: TrackPurpose;
+}
+declare const TelemetryScopeContext: React.Context<TelemetryScopeValue>;
+/** Props for {@link TelemetryScope}. */
+export interface TelemetryScopeProps extends TelemetryScopeValue {
+    children?: React.ReactNode;
+}
+/**
+ * Establishes ambient telemetry context (`area` / `action` / `purpose`) for its
+ * descendants (plan 144 TASK-12 / REQ-21). Nested scopes merge
+ * **inner-over-outer**, and per-event {@link useTrack} options override the
+ * scope (the outer → inner → invocation precedence). It is renderless — renders
+ * its children unchanged, adds no DOM node (REQ-19), and works with or without a
+ * RevTurbine provider (AC-13).
+ */
+export declare function TelemetryScope({ children, ...scope }: TelemetryScopeProps): React.ReactElement;
+/** The current merged telemetry scope (plan 144 TASK-12). Empty when outside any {@link TelemetryScope}. */
+export declare function useTelemetryScope(): TelemetryScopeValue;
+export { TelemetryScopeContext };
+//# sourceMappingURL=TelemetryScope.d.ts.map

package/dist/types/web-sdk/react/TelemetryScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryScope.d.ts","sourceRoot":"","sources":["../../../../react/TelemetryScope.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEtG;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,QAAA,MAAM,qBAAqB,oCAAyC,CAAC;AAErE,wCAAwC;AACxC,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAW9F;AAED,4GAA4G;AAC5G,wBAAgB,iBAAiB,IAAI,mBAAmB,CAEvD;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/types/web-sdk/react/index.d.ts

@@ -6,6 +6,8 @@ export * from './SurfaceTypes';
 export * from './PlacementDecisionInspector';
 export * from './UserProfile';
 export * from './useEntitlement';
+export * from './TelemetryScope';
+export * from './useTrack';
 export * from './useCan';
 export * from './useUsageSnapshot';
 export { useRevTurbineTheme } from '../theme/ThemeContext';

package/dist/types/web-sdk/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../react/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../react/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/web-sdk/react/useTrack.d.ts

@@ -0,0 +1,36 @@
+import { type TrackPurpose } from './TelemetryScope';
+import type { SdkEventProperties } from '../customer-side';
+/**
+ * Per-event options for {@link useTrack} — the one shared shape scope defaults
+ * and later telemetry components also draw from (plan 144 TASK-12).
+ */
+export interface TrackOptions {
+    /** Overrides the scope `area` for this event. */
+    area?: string;
+    /** Overrides the scope `action` for this event. */
+    action?: string;
+    /** Advisory {@link TrackPurpose}; overrides the scope purpose. */
+    purpose?: TrackPurpose;
+    /** Emit at most once per distinct key, for this hook instance's lifetime. */
+    dedupeKey?: string;
+    /** Emit at most once (keyed on the event name), for this hook instance's lifetime. */
+    once?: boolean;
+    /** Send immediately instead of batching. */
+    immediate?: boolean;
+}
+/** The tracking function returned by {@link useTrack}. */
+export type TrackFn = (name: string, data?: SdkEventProperties, options?: TrackOptions) => void;
+/**
+ * Returns a `track(name, data?, options?)` function bound to the enclosing
+ * {@link TelemetryScope} (plan 144 TASK-12 / REQ-21).
+ *
+ * - Scope context (`area` / `action` / `purpose`) merges **outer → inner →
+ *   invocation** — the per-event option wins.
+ * - `once` and `dedupeKey` suppress repeats for this hook instance's lifetime.
+ * - Reserved property names are dropped so a caller can't overwrite canonical
+ *   fields.
+ * - Without a RevTurbine provider (absent or failed init) the function is a safe
+ *   no-op and never throws (AC-13).
+ */
+export declare function useTrack(): TrackFn;
+//# sourceMappingURL=useTrack.d.ts.map

package/dist/types/web-sdk/react/useTrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTrack.d.ts","sourceRoot":"","sources":["../../../../react/useTrack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAuB3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,0DAA0D;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;AAyBhG;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CA8BlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/sdk",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "RevTurbine customer-facing SDK — placement decisioning, entitlement checks, and usage tracking.",
   "type": "module",
   "packageManager": "pnpm@11.12.0",