@revturbine/sdk 0.2.36 → 0.2.38

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

@@ -0,0 +1,35 @@
+import React from 'react';
+import { type TrackPurpose } from './TelemetryScope';
+/** Props for {@link EngagementArea}. */
+export interface EngagementAreaProps {
+    /** Logical area name — set as the telemetry scope for descendants and stamped on emitted events. */
+    area: string;
+    /** Event emitted once when the area is first qualified-viewed. Default `engagement_view`. */
+    viewEvent?: string;
+    /** Event emitted with accrued dwell (`dwell_ms`) when the area unmounts. Default `engagement_dwell`. */
+    dwellEvent?: string;
+    /** Event emitted when a descendant is clicked. Default `engagement_interaction`. */
+    interactionEvent?: string;
+    /** Advisory purpose applied to the scope and emitted events. */
+    purpose?: TrackPurpose;
+    /** Visible fraction required to count as viewed / dwelling (0–1). Default 0.5. */
+    threshold?: number;
+    /** Host element tag. Default `'div'`. */
+    as?: keyof React.JSX.IntrinsicElements;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * A qualified engagement region (plan 144 TASK-13 / REQ-21). It:
+ * - establishes a {@link TelemetryScope} (`area` / `purpose`) for its descendants;
+ * - emits `viewEvent` **once** when first viewport-qualified — one-shot across
+ *   React Strict Mode's double-mount (AC-12);
+ * - accrues dwell only while the region is **onscreen and the tab is visible**,
+ *   emitting `dwellEvent` with `dwell_ms` when it unmounts;
+ * - bubbles descendant clicks as `interactionEvent`.
+ *
+ * Renders its children and never throws without a provider (AC-13).
+ */
+export declare function EngagementArea({ area, viewEvent, dwellEvent, interactionEvent, purpose, threshold, as, className, style, children, }: EngagementAreaProps): React.ReactElement;
+//# sourceMappingURL=EngagementArea.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EngagementArea.d.ts","sourceRoot":"","sources":["../../../../react/EngagementArea.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAyC,MAAM,OAAO,CAAC;AAC9D,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrE,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,SAA6B,EAC7B,UAA+B,EAC/B,gBAA2C,EAC3C,OAAO,EACP,SAAe,EACf,EAAU,EACV,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAuG1C"}

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/TrackOnView.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import { type TrackOptions } from './useTrack';
+import type { SdkEventProperties } from '../customer-side';
+/** Props for {@link TrackOnView}. */
+export interface TrackOnViewProps {
+    /** Event name emitted once when the element is qualified-viewed. */
+    event: string;
+    /** Event data (reserved names are dropped by {@link useTrack}). */
+    data?: SdkEventProperties;
+    /** Track options (area / action / purpose / immediate). */
+    options?: TrackOptions;
+    /** Visible fraction required (0–1). Default 0.5. */
+    threshold?: number;
+    /** Minimum visible dwell before it counts, in ms. Default 0. */
+    minVisibleMs?: number;
+    /** Host element tag. Default `'div'`. */
+    as?: keyof React.JSX.IntrinsicElements;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * Emits `event` exactly once, the first time its host element is
+ * viewport-qualified (plan 144 TASK-13 / REQ-21). Falls back to firing on render
+ * when `IntersectionObserver` is unavailable (AC-10 degradation). The one-shot
+ * guard is a ref that survives React Strict Mode's development double-mount, so
+ * the event fires once, not twice (AC-12). Renders its children in the host
+ * element and never throws without a provider (AC-13).
+ */
+export declare function TrackOnView({ event, data, options, threshold, minVisibleMs, as, className, style, children, }: TrackOnViewProps): React.ReactElement;
+//# sourceMappingURL=TrackOnView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TrackOnView.d.ts","sourceRoot":"","sources":["../../../../react/TrackOnView.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAyC,MAAM,OAAO,CAAC;AAE9D,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,IAAI,EACJ,OAAO,EACP,SAAS,EACT,YAAY,EACZ,EAAU,EACV,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CAiCvC"}

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

@@ -6,6 +6,10 @@ export * from './SurfaceTypes';
 export * from './PlacementDecisionInspector';
 export * from './UserProfile';
 export * from './useEntitlement';
+export * from './TelemetryScope';
+export * from './useTrack';
+export * from './TrackOnView';
+export * from './EngagementArea';
 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,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,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.38",
   "description": "RevTurbine customer-facing SDK — placement decisioning, entitlement checks, and usage tracking.",
   "type": "module",
   "packageManager": "pnpm@11.12.0",