@revturbine/sdk 0.2.35 → 0.2.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/headless.js +10 -10
- package/dist/headless.js.map +1 -1
- package/dist/index.js +60 -60
- package/dist/index.js.map +1 -1
- package/dist/types/web-sdk/controllers.d.ts +52 -7
- package/dist/types/web-sdk/controllers.d.ts.map +1 -1
- package/dist/types/web-sdk/react/TelemetryScope.d.ts +37 -0
- package/dist/types/web-sdk/react/TelemetryScope.d.ts.map +1 -0
- package/dist/types/web-sdk/react/index.d.ts +2 -0
- package/dist/types/web-sdk/react/index.d.ts.map +1 -1
- package/dist/types/web-sdk/react/usePlacement.d.ts +11 -1
- package/dist/types/web-sdk/react/usePlacement.d.ts.map +1 -1
- package/dist/types/web-sdk/react/useTrack.d.ts +36 -0
- package/dist/types/web-sdk/react/useTrack.d.ts.map +1 -0
- package/package.json +1 -1
|
@@ -51,7 +51,33 @@ export interface PlacementControllerOptions {
|
|
|
51
51
|
ttlMs?: number;
|
|
52
52
|
/** Whether to track an impression automatically when the decision is visible. Default `true`. */
|
|
53
53
|
autoTrackImpression?: boolean;
|
|
54
|
+
/**
|
|
55
|
+
* When the presentation-writing `impression` fires (plan 144 TASK-11 / REQ-17).
|
|
56
|
+
* - `legacy_resolution` (default) — at decision resolution, exactly as today.
|
|
57
|
+
* - `render` — when the placement's visual root renders.
|
|
58
|
+
* - `viewport` — when the root scrolls into the viewport; if
|
|
59
|
+
* `IntersectionObserver` is unavailable it falls back to resolution
|
|
60
|
+
* (Q-8 ruling), tagged `render_fallback`.
|
|
61
|
+
*
|
|
62
|
+
* Only `viewport` (with `IntersectionObserver` present) moves the
|
|
63
|
+
* `placement_presentations` denominator — a deliberate metric-definition
|
|
64
|
+
* change (see the plan's Q-8 / REQ-17b). The default keeps the denominator and
|
|
65
|
+
* its history unchanged.
|
|
66
|
+
*/
|
|
67
|
+
placementExposure?: PlacementExposureMode;
|
|
54
68
|
}
|
|
69
|
+
/**
|
|
70
|
+
* When the presentation-writing `impression` fires relative to a placement's
|
|
71
|
+
* lifecycle (plan 144 TASK-11). See {@link PlacementControllerOptions.placementExposure}.
|
|
72
|
+
*/
|
|
73
|
+
export type PlacementExposureMode = 'legacy_resolution' | 'render' | 'viewport';
|
|
74
|
+
/**
|
|
75
|
+
* The lifecycle point an `impression` was credited to, recorded on the
|
|
76
|
+
* presentation row's `exposure_basis` (plan 144 TASK-11). `render_fallback` marks
|
|
77
|
+
* a `viewport`-mode impression that fell back to resolution because
|
|
78
|
+
* `IntersectionObserver` was unavailable (AC-10).
|
|
79
|
+
*/
|
|
80
|
+
export type PresentationBasis = 'legacy_resolution' | 'render' | 'viewport' | 'render_fallback';
|
|
55
81
|
/**
|
|
56
82
|
* Read-only snapshot of a {@link PlacementController}'s state.
|
|
57
83
|
*/
|
|
@@ -95,24 +121,43 @@ export declare class PlacementController {
|
|
|
95
121
|
private _error;
|
|
96
122
|
private _impressionTracked;
|
|
97
123
|
private _loadSeq;
|
|
124
|
+
private _rendered;
|
|
98
125
|
private _exposed;
|
|
99
126
|
private _exposureBasis;
|
|
100
127
|
constructor(sdk: RevTurbineCustomerSdk, options: PlacementControllerOptions);
|
|
101
128
|
/** Current state snapshot. */
|
|
102
129
|
get state(): PlacementControllerState;
|
|
130
|
+
/** The configured exposure mode (plan 144 TASK-11). Defaults to `legacy_resolution`. */
|
|
131
|
+
private get exposureMode();
|
|
132
|
+
/**
|
|
133
|
+
* Called when the placement's visual root renders (plan 144 TASK-11). Emits
|
|
134
|
+
* `placement_rendered` once, and under `placementExposure: 'render'` credits
|
|
135
|
+
* the presentation now. Idempotent.
|
|
136
|
+
*/
|
|
137
|
+
markRendered(): void;
|
|
103
138
|
/**
|
|
104
139
|
* Called by the viewport-exposure substrate when the placement's visual root
|
|
105
140
|
* first enters the viewport — or immediately with `'render_fallback'` when
|
|
106
|
-
* `IntersectionObserver` is unavailable (plan 144 TASK-9 / AC-10).
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
* `placementExposure: 'viewport'` (TASK-11) the resolution-time impression
|
|
111
|
-
* moves here. In TASK-9 it records state without emitting an event.
|
|
141
|
+
* `IntersectionObserver` is unavailable (plan 144 TASK-9/11 / AC-9, AC-10).
|
|
142
|
+
* Emits `placement_exposed` once with the basis, and under
|
|
143
|
+
* `placementExposure: 'viewport'` a viewport exposure credits the presentation
|
|
144
|
+
* here (Q-8). Idempotent.
|
|
112
145
|
*
|
|
113
146
|
* @param basis - how exposure was established; defaults to `'viewport'`
|
|
114
147
|
*/
|
|
115
148
|
markVisible(basis?: ExposureBasis): void;
|
|
149
|
+
/**
|
|
150
|
+
* Fire the presentation-writing `impression` (→ `placement_presentations`)
|
|
151
|
+
* once, tagged with the lifecycle basis it was credited at (plan 144 TASK-11).
|
|
152
|
+
* Honors `autoTrackImpression: false` and only fires for a visible decision.
|
|
153
|
+
* Best-effort — telemetry never breaks a placement.
|
|
154
|
+
*/
|
|
155
|
+
private fireImpression;
|
|
156
|
+
/**
|
|
157
|
+
* Emit a placement lifecycle signal (`placement_rendered` / `placement_exposed`)
|
|
158
|
+
* with decision provenance (plan 144 TASK-11). Best-effort.
|
|
159
|
+
*/
|
|
160
|
+
private emitPlacementLifecycle;
|
|
116
161
|
/** Convenience: `true` when the current decision says the placement is visible. */
|
|
117
162
|
get visible(): boolean;
|
|
118
163
|
/** Current resolved content, or `null` if no decision has been loaded. */
|
|
@@ -128,7 +173,7 @@ export declare class PlacementController {
|
|
|
128
173
|
* automatically records an impression event.
|
|
129
174
|
*/
|
|
130
175
|
load(): Promise<RevTurbinePlacementDecision | null>;
|
|
131
|
-
/** Re-fetch the placement decision (clears impression + exposure tracking). */
|
|
176
|
+
/** Re-fetch the placement decision (clears impression + render + exposure tracking). */
|
|
132
177
|
refresh(): Promise<RevTurbinePlacementDecision | null>;
|
|
133
178
|
/** Record a dismiss interaction and hide the placement. */
|
|
134
179
|
dismiss(cooldownMs?: number): Promise<void>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"controllers.d.ts","sourceRoot":"","sources":["../../../controllers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,oCAAoC,EACpC,gCAAgC,EAChC,qBAAqB,EACrB,4BAA4B,EAC5B,qBAAqB,EAGrB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,EACb,UAAU,EACX,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"controllers.d.ts","sourceRoot":"","sources":["../../../controllers.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import React from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Advisory event purpose (plan 144 TASK-12 / REQ-28). A **server-side allowlist**
|
|
4
|
+
* — never this client-declared value — decides whether an event feeds engagement
|
|
5
|
+
* scoring. The listed values are suggestions; any string is accepted.
|
|
6
|
+
*/
|
|
7
|
+
export type TrackPurpose = 'engagement' | 'conversion' | 'operational' | 'diagnostic' | (string & {});
|
|
8
|
+
/**
|
|
9
|
+
* Ambient telemetry context established by {@link TelemetryScope} and merged into
|
|
10
|
+
* every event emitted by {@link useTrack} beneath it.
|
|
11
|
+
*/
|
|
12
|
+
export interface TelemetryScopeValue {
|
|
13
|
+
/** Logical product area (e.g. `'billing'`, `'editor'`). */
|
|
14
|
+
area?: string;
|
|
15
|
+
/** Default action label for events in this scope. */
|
|
16
|
+
action?: string;
|
|
17
|
+
/** Advisory {@link TrackPurpose}. */
|
|
18
|
+
purpose?: TrackPurpose;
|
|
19
|
+
}
|
|
20
|
+
declare const TelemetryScopeContext: React.Context<TelemetryScopeValue>;
|
|
21
|
+
/** Props for {@link TelemetryScope}. */
|
|
22
|
+
export interface TelemetryScopeProps extends TelemetryScopeValue {
|
|
23
|
+
children?: React.ReactNode;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Establishes ambient telemetry context (`area` / `action` / `purpose`) for its
|
|
27
|
+
* descendants (plan 144 TASK-12 / REQ-21). Nested scopes merge
|
|
28
|
+
* **inner-over-outer**, and per-event {@link useTrack} options override the
|
|
29
|
+
* scope (the outer → inner → invocation precedence). It is renderless — renders
|
|
30
|
+
* its children unchanged, adds no DOM node (REQ-19), and works with or without a
|
|
31
|
+
* RevTurbine provider (AC-13).
|
|
32
|
+
*/
|
|
33
|
+
export declare function TelemetryScope({ children, ...scope }: TelemetryScopeProps): React.ReactElement;
|
|
34
|
+
/** The current merged telemetry scope (plan 144 TASK-12). Empty when outside any {@link TelemetryScope}. */
|
|
35
|
+
export declare function useTelemetryScope(): TelemetryScopeValue;
|
|
36
|
+
export { TelemetryScopeContext };
|
|
37
|
+
//# sourceMappingURL=TelemetryScope.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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"}
|
|
@@ -6,6 +6,8 @@ export * from './SurfaceTypes';
|
|
|
6
6
|
export * from './PlacementDecisionInspector';
|
|
7
7
|
export * from './UserProfile';
|
|
8
8
|
export * from './useEntitlement';
|
|
9
|
+
export * from './TelemetryScope';
|
|
10
|
+
export * from './useTrack';
|
|
9
11
|
export * from './useCan';
|
|
10
12
|
export * from './useUsageSnapshot';
|
|
11
13
|
export { useRevTurbineTheme } from '../theme/ThemeContext';
|
|
@@ -1 +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"}
|
|
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,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type RevTurbinePlacementConfig, type RevTurbineSurfaceSlotConfig, type RevTurbinePlacementContent, type RevTurbinePlacementDecision, type RevTurbinePlacementDecisionOverrides, type RevTurbineContextMode } from '../customer-side';
|
|
2
|
+
import type { PlacementExposureMode } from '../controllers';
|
|
2
3
|
import { type ExposureBasis } from '../telemetry';
|
|
3
4
|
/**
|
|
4
5
|
* Options for the {@link usePlacement} hook.
|
|
@@ -27,6 +28,15 @@ export type UsePlacementOptions = {
|
|
|
27
28
|
* exposure instead (plan 144 TASK-9 / REQ-15). Read at mount.
|
|
28
29
|
*/
|
|
29
30
|
autoTrackImpression?: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* When the presentation-writing `impression` fires (plan 144 TASK-11 / REQ-17).
|
|
33
|
+
* `legacy_resolution` (default) fires at resolution as today; `render` at
|
|
34
|
+
* render; `viewport` on viewport exposure (falling back to resolution when
|
|
35
|
+
* `IntersectionObserver` is unavailable). Only `viewport` moves the dashboard
|
|
36
|
+
* denominator — attach {@link UsePlacementResult.exposureRef} to the visual
|
|
37
|
+
* root to use it. Read at mount.
|
|
38
|
+
*/
|
|
39
|
+
placementExposure?: PlacementExposureMode;
|
|
30
40
|
};
|
|
31
41
|
/**
|
|
32
42
|
* Result returned by the {@link usePlacement} hook.
|
|
@@ -82,5 +92,5 @@ export type UsePlacementResult = {
|
|
|
82
92
|
* );
|
|
83
93
|
* ```
|
|
84
94
|
*/
|
|
85
|
-
export declare function usePlacement({ placement, surfaceSlot, userId, contextMode, overrides, traits, ttlMs, autoLoad, autoTrackImpression, }: UsePlacementOptions): UsePlacementResult;
|
|
95
|
+
export declare function usePlacement({ placement, surfaceSlot, userId, contextMode, overrides, traits, ttlMs, autoLoad, autoTrackImpression, placementExposure, }: UsePlacementOptions): UsePlacementResult;
|
|
86
96
|
//# sourceMappingURL=usePlacement.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"usePlacement.d.ts","sourceRoot":"","sources":["../../../../react/usePlacement.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGnE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,yEAAyE;IACzE,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oDAAoD;IACpD,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"usePlacement.d.ts","sourceRoot":"","sources":["../../../../react/usePlacement.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGnE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,yEAAyE;IACzE,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,oDAAoD;IACpD,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC7C,OAAO,EAAE,0BAA0B,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACtD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,WAAW,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,SAAS,EACT,WAAW,EACX,MAAM,EACN,WAAoB,EACpB,SAAS,EACT,MAAM,EACN,KAAK,EACL,QAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,EAAE,mBAAmB,GAAG,kBAAkB,CA4G1C"}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { type TrackPurpose } from './TelemetryScope';
|
|
2
|
+
import type { SdkEventProperties } from '../customer-side';
|
|
3
|
+
/**
|
|
4
|
+
* Per-event options for {@link useTrack} — the one shared shape scope defaults
|
|
5
|
+
* and later telemetry components also draw from (plan 144 TASK-12).
|
|
6
|
+
*/
|
|
7
|
+
export interface TrackOptions {
|
|
8
|
+
/** Overrides the scope `area` for this event. */
|
|
9
|
+
area?: string;
|
|
10
|
+
/** Overrides the scope `action` for this event. */
|
|
11
|
+
action?: string;
|
|
12
|
+
/** Advisory {@link TrackPurpose}; overrides the scope purpose. */
|
|
13
|
+
purpose?: TrackPurpose;
|
|
14
|
+
/** Emit at most once per distinct key, for this hook instance's lifetime. */
|
|
15
|
+
dedupeKey?: string;
|
|
16
|
+
/** Emit at most once (keyed on the event name), for this hook instance's lifetime. */
|
|
17
|
+
once?: boolean;
|
|
18
|
+
/** Send immediately instead of batching. */
|
|
19
|
+
immediate?: boolean;
|
|
20
|
+
}
|
|
21
|
+
/** The tracking function returned by {@link useTrack}. */
|
|
22
|
+
export type TrackFn = (name: string, data?: SdkEventProperties, options?: TrackOptions) => void;
|
|
23
|
+
/**
|
|
24
|
+
* Returns a `track(name, data?, options?)` function bound to the enclosing
|
|
25
|
+
* {@link TelemetryScope} (plan 144 TASK-12 / REQ-21).
|
|
26
|
+
*
|
|
27
|
+
* - Scope context (`area` / `action` / `purpose`) merges **outer → inner →
|
|
28
|
+
* invocation** — the per-event option wins.
|
|
29
|
+
* - `once` and `dedupeKey` suppress repeats for this hook instance's lifetime.
|
|
30
|
+
* - Reserved property names are dropped so a caller can't overwrite canonical
|
|
31
|
+
* fields.
|
|
32
|
+
* - Without a RevTurbine provider (absent or failed init) the function is a safe
|
|
33
|
+
* no-op and never throws (AC-13).
|
|
34
|
+
*/
|
|
35
|
+
export declare function useTrack(): TrackFn;
|
|
36
|
+
//# sourceMappingURL=useTrack.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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
CHANGED