blocfeed 0.17.3 → 0.19.0

package/dist/main.d.cts

@@ -1,5 +1,5 @@
-import { B as BlocFeedConfig, a as BlocFeedHandle, b as BlocFeedState, c as BlocFeedController, C as CaptureConfig, F as FeedbackCategory, S as SubmitResult, d as BehavioralEvent, e as BehavioralConfig } from './controller-09cYt2qm.cjs';
-export { f as BehavioralEventType, g as BlocFeedError, h as BlocFeedStrings, i as BlocFeedUser, j as CaptureDiagnostics, k as CaptureResult, l as ConsoleEntry, D as DiagnosticsConfig, E as ElementDescriptor, m as FeedbackApiResponse, n as FeedbackPayload, I as ImageAsset, M as MaybePromise, o as MetadataConfig, p as MetadataContext, N as NetworkEntry, P as PickerConfig, R as RecordingConfig, q as Rect, r as ScreenshotAdapter, s as ScreenshotAdapterOptions, t as ScreenshotIntent, u as ScreenshotMime, v as SecurityConfig, w as SecurityFinding, x as SecuritySnapshot, y as SessionPhase, T as ThemeConfig, z as TransportConfig, A as TransportResult, G as TriggerStyle, V as VideoAsset, H as VideoIntent, J as VideoMime, K as VoiceConfig, W as WidgetPosition } from './controller-09cYt2qm.cjs';
+import { B as BlocFeedConfig, a as BlocFeedHandle, b as BlocFeedState, c as BlocFeedController, C as CaptureConfig, F as FeedbackCategory, S as SubmitResult, d as BehavioralEvent, e as BehavioralConfig } from './controller-C5mxpGk4.cjs';
+export { f as BehavioralEventType, g as BlocFeedError, h as BlocFeedStrings, i as BlocFeedUser, j as CaptureDiagnostics, k as CaptureResult, l as ConsoleEntry, D as DiagnosticsConfig, E as ElementDescriptor, m as FeedbackApiResponse, n as FeedbackPayload, I as ImageAsset, M as MaybePromise, o as MetadataConfig, p as MetadataContext, N as NetworkEntry, P as PickerConfig, R as RecordingConfig, q as Rect, r as ScreenshotAdapter, s as ScreenshotAdapterOptions, t as ScreenshotIntent, u as ScreenshotMime, v as SecurityConfig, w as SecurityFinding, x as SecuritySnapshot, y as SessionPhase, T as ThemeConfig, z as TransportConfig, A as TransportResult, G as TriggerStyle, V as VideoAsset, H as VideoIntent, J as VideoMime, K as VoiceConfig, W as WidgetPosition } from './controller-C5mxpGk4.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -17,6 +17,24 @@ type BlocFeedWidgetProps = {
 };
 declare const BlocFeedWidget: react.ForwardRefExoticComponent<BlocFeedWidgetProps & react.RefAttributes<BlocFeedHandle>>;
 
+/**
+ * Public-API types for the `track()` custom-event surface.
+ *
+ * `track(name, properties?, options?)` enqueues an event into a process-wide
+ * buffer that flushes to `POST /api/events/track`. See ./customEvents.ts.
+ */
+interface TrackOptions {
+    /** Override the auto-attached session_id (defaults to current rrweb session). */
+    sessionId?: string;
+    /** Override the auto-attached user_id (defaults to last `identify()` call). */
+    userId?: string;
+    /** Override the auto-attached page_url (defaults to window.location.href). */
+    pageUrl?: string;
+    /** Override the auto-attached occurred_at (defaults to now()). */
+    occurredAt?: Date | string;
+}
+type TrackProperties = Record<string, string | number | boolean | null>;
+
 type BlocFeedApi = {
     state: BlocFeedState;
     controller: BlocFeedController;
@@ -30,6 +48,14 @@ type BlocFeedApi = {
     startRecording: () => Promise<void>;
     stopRecording: () => void;
     removeVideo: () => void;
+    /**
+     * Send a custom event to BlocFeed for funnels, conversion tracking, and
+     * segment filters. Buffered + flushed periodically — non-blocking.
+     *
+     * `name` must match `/^[a-z][a-z0-9_]{0,127}$/`.
+     * `properties` is a flat object of string|number|boolean|null values.
+     */
+    track: (name: string, properties?: TrackProperties, options?: TrackOptions) => void;
 };
 declare function useBlocFeed(): BlocFeedApi;
 
@@ -60,4 +86,43 @@ declare class BehavioralTracker {
     uninstall(): void;
 }
 
-export { BehavioralConfig, BehavioralEvent, BehavioralTracker, type BlocFeedApi, BlocFeedConfig, BlocFeedHandle, BlocFeedProvider, BlocFeedState, BlocFeedWidget, CaptureConfig, FeedbackCategory, SubmitResult, useBlocFeed };
+/**
+ * Buffered custom-event tracker.
+ *
+ * Public API: `track(name, properties?, options?)`. Mirrors the offline-queue
+ * + flush patterns used by `runtime/replay/capture.ts` and the behavioral
+ * submitter — keepalive only on the pagehide beacon path, in-session flushes
+ * use plain fetch (lesson from v0.17.1).
+ *
+ * Singleton: one buffer per page load, lazily created on first track() call.
+ */
+
+declare function track(name: string, properties?: TrackProperties, options?: TrackOptions): void;
+
+/**
+ * Pinned at publish time. Sent with the heartbeat so the dashboard can
+ * surface SDK version drift to customers.
+ */
+declare const SDK_VERSION = "0.19.0";
+
+/**
+ * Non-React entry point. Mirrors the shape of the rest of the SDK exports;
+ * use this from Vue, Svelte, or vanilla apps where there is no
+ * `useBlocFeed()` hook available.
+ *
+ * ```ts
+ * import { BlocFeed } from "blocfeed";
+ * BlocFeed.identify("user_42");
+ * BlocFeed.track("checkout_completed", { plan: "team" });
+ * ```
+ */
+declare const BlocFeed: {
+    /** Register the blocfeed_id (only needed on Vue / vanilla; React provider does this for you). */
+    init(blocfeedId: string): void;
+    /** Attach a user_id to subsequent track() calls. Pass `undefined` to clear. */
+    identify(userId: string | undefined): void;
+    /** Send a custom event. See `track()` for validation rules. */
+    track: typeof track;
+};
+
+export { BehavioralConfig, BehavioralEvent, BehavioralTracker, BlocFeed, type BlocFeedApi, BlocFeedConfig, BlocFeedHandle, BlocFeedProvider, BlocFeedState, BlocFeedWidget, CaptureConfig, FeedbackCategory, SDK_VERSION, SubmitResult, type TrackOptions, type TrackProperties, track, useBlocFeed };

package/dist/main.d.ts

@@ -1,5 +1,5 @@
-import { B as BlocFeedConfig, a as BlocFeedHandle, b as BlocFeedState, c as BlocFeedController, C as CaptureConfig, F as FeedbackCategory, S as SubmitResult, d as BehavioralEvent, e as BehavioralConfig } from './controller-09cYt2qm.js';
-export { f as BehavioralEventType, g as BlocFeedError, h as BlocFeedStrings, i as BlocFeedUser, j as CaptureDiagnostics, k as CaptureResult, l as ConsoleEntry, D as DiagnosticsConfig, E as ElementDescriptor, m as FeedbackApiResponse, n as FeedbackPayload, I as ImageAsset, M as MaybePromise, o as MetadataConfig, p as MetadataContext, N as NetworkEntry, P as PickerConfig, R as RecordingConfig, q as Rect, r as ScreenshotAdapter, s as ScreenshotAdapterOptions, t as ScreenshotIntent, u as ScreenshotMime, v as SecurityConfig, w as SecurityFinding, x as SecuritySnapshot, y as SessionPhase, T as ThemeConfig, z as TransportConfig, A as TransportResult, G as TriggerStyle, V as VideoAsset, H as VideoIntent, J as VideoMime, K as VoiceConfig, W as WidgetPosition } from './controller-09cYt2qm.js';
+import { B as BlocFeedConfig, a as BlocFeedHandle, b as BlocFeedState, c as BlocFeedController, C as CaptureConfig, F as FeedbackCategory, S as SubmitResult, d as BehavioralEvent, e as BehavioralConfig } from './controller-C5mxpGk4.js';
+export { f as BehavioralEventType, g as BlocFeedError, h as BlocFeedStrings, i as BlocFeedUser, j as CaptureDiagnostics, k as CaptureResult, l as ConsoleEntry, D as DiagnosticsConfig, E as ElementDescriptor, m as FeedbackApiResponse, n as FeedbackPayload, I as ImageAsset, M as MaybePromise, o as MetadataConfig, p as MetadataContext, N as NetworkEntry, P as PickerConfig, R as RecordingConfig, q as Rect, r as ScreenshotAdapter, s as ScreenshotAdapterOptions, t as ScreenshotIntent, u as ScreenshotMime, v as SecurityConfig, w as SecurityFinding, x as SecuritySnapshot, y as SessionPhase, T as ThemeConfig, z as TransportConfig, A as TransportResult, G as TriggerStyle, V as VideoAsset, H as VideoIntent, J as VideoMime, K as VoiceConfig, W as WidgetPosition } from './controller-C5mxpGk4.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -17,6 +17,24 @@ type BlocFeedWidgetProps = {
 };
 declare const BlocFeedWidget: react.ForwardRefExoticComponent<BlocFeedWidgetProps & react.RefAttributes<BlocFeedHandle>>;
 
+/**
+ * Public-API types for the `track()` custom-event surface.
+ *
+ * `track(name, properties?, options?)` enqueues an event into a process-wide
+ * buffer that flushes to `POST /api/events/track`. See ./customEvents.ts.
+ */
+interface TrackOptions {
+    /** Override the auto-attached session_id (defaults to current rrweb session). */
+    sessionId?: string;
+    /** Override the auto-attached user_id (defaults to last `identify()` call). */
+    userId?: string;
+    /** Override the auto-attached page_url (defaults to window.location.href). */
+    pageUrl?: string;
+    /** Override the auto-attached occurred_at (defaults to now()). */
+    occurredAt?: Date | string;
+}
+type TrackProperties = Record<string, string | number | boolean | null>;
+
 type BlocFeedApi = {
     state: BlocFeedState;
     controller: BlocFeedController;
@@ -30,6 +48,14 @@ type BlocFeedApi = {
     startRecording: () => Promise<void>;
     stopRecording: () => void;
     removeVideo: () => void;
+    /**
+     * Send a custom event to BlocFeed for funnels, conversion tracking, and
+     * segment filters. Buffered + flushed periodically — non-blocking.
+     *
+     * `name` must match `/^[a-z][a-z0-9_]{0,127}$/`.
+     * `properties` is a flat object of string|number|boolean|null values.
+     */
+    track: (name: string, properties?: TrackProperties, options?: TrackOptions) => void;
 };
 declare function useBlocFeed(): BlocFeedApi;
 
@@ -60,4 +86,43 @@ declare class BehavioralTracker {
     uninstall(): void;
 }
 
-export { BehavioralConfig, BehavioralEvent, BehavioralTracker, type BlocFeedApi, BlocFeedConfig, BlocFeedHandle, BlocFeedProvider, BlocFeedState, BlocFeedWidget, CaptureConfig, FeedbackCategory, SubmitResult, useBlocFeed };
+/**
+ * Buffered custom-event tracker.
+ *
+ * Public API: `track(name, properties?, options?)`. Mirrors the offline-queue
+ * + flush patterns used by `runtime/replay/capture.ts` and the behavioral
+ * submitter — keepalive only on the pagehide beacon path, in-session flushes
+ * use plain fetch (lesson from v0.17.1).
+ *
+ * Singleton: one buffer per page load, lazily created on first track() call.
+ */
+
+declare function track(name: string, properties?: TrackProperties, options?: TrackOptions): void;
+
+/**
+ * Pinned at publish time. Sent with the heartbeat so the dashboard can
+ * surface SDK version drift to customers.
+ */
+declare const SDK_VERSION = "0.19.0";
+
+/**
+ * Non-React entry point. Mirrors the shape of the rest of the SDK exports;
+ * use this from Vue, Svelte, or vanilla apps where there is no
+ * `useBlocFeed()` hook available.
+ *
+ * ```ts
+ * import { BlocFeed } from "blocfeed";
+ * BlocFeed.identify("user_42");
+ * BlocFeed.track("checkout_completed", { plan: "team" });
+ * ```
+ */
+declare const BlocFeed: {
+    /** Register the blocfeed_id (only needed on Vue / vanilla; React provider does this for you). */
+    init(blocfeedId: string): void;
+    /** Attach a user_id to subsequent track() calls. Pass `undefined` to clear. */
+    identify(userId: string | undefined): void;
+    /** Send a custom event. See `track()` for validation rules. */
+    track: typeof track;
+};
+
+export { BehavioralConfig, BehavioralEvent, BehavioralTracker, BlocFeed, type BlocFeedApi, BlocFeedConfig, BlocFeedHandle, BlocFeedProvider, BlocFeedState, BlocFeedWidget, CaptureConfig, FeedbackCategory, SDK_VERSION, SubmitResult, type TrackOptions, type TrackProperties, track, useBlocFeed };