@yiyi_zhang/reactflow-ui 1.2.0 → 1.3.0

package/dist/telemetry/buffer.d.ts

@@ -0,0 +1,37 @@
+import type { IdeEvent, TelemetrySink } from './types';
+/** 定时器注入点（测试用）；默认使用全局 setTimeout / clearTimeout */
+export interface TelemetryTimers {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** 最小事件目标接口（document / window 或测试替身） */
+export interface TelemetryEventTarget {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface TelemetryBufferOptions {
+    /** 距第一条待发送事件多久后 flush。默认 5000 */
+    flushIntervalMs?: number;
+    /** 累计多少条立即 flush。默认 20 */
+    maxBatchSize?: number;
+    timers?: TelemetryTimers;
+    /** 监听 `visibilitychange`（读取 visibilityState）；默认取全局 document，非浏览器环境忽略 */
+    document?: (TelemetryEventTarget & {
+        visibilityState?: string;
+    }) | null;
+    /** 监听 `pagehide`；默认取全局 window，非浏览器环境忽略 */
+    window?: TelemetryEventTarget | null;
+}
+export interface TelemetryBuffer {
+    /** 入队；sink 缺失时丢弃。永不抛出 */
+    push(event: IdeEvent): void;
+    /** 立即发送队列中的事件。永不抛出 */
+    flush(): void;
+    /** flush 并移除定时器与页面监听；之后 push 无效 */
+    dispose(): void;
+}
+/**
+ * 创建埋点缓冲：批量发送、页面隐藏时 flush、吞掉 sink 的任何错误（只 warn 一次）。
+ * sink 为空时 push 直接丢弃，不产生定时器与监听。
+ */
+export declare function createTelemetryBuffer(sink: TelemetrySink | undefined | null, opts?: TelemetryBufferOptions): TelemetryBuffer;

package/dist/telemetry/once.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 「每个实例只执行一次」的守卫，用于 `ide_opened` 去重。
+ *
+ * React StrictMode（开发环境）会把 effect 执行 → 清理 → 再执行一次，但 `useRef` 的值在两次之间保留，
+ * 所以把守卫放在 ref 里即可保证同一个 IDE 实例只上报一次；真正重新挂载（新实例）会得到新的守卫。
+ */
+export interface OnceGuard {
+    /** 第一次调用返回 true，之后都返回 false */
+    take(): boolean;
+}
+export declare function createOnceGuard(): OnceGuard;

package/dist/telemetry/track.d.ts

@@ -0,0 +1,17 @@
+import type { IdeEvent, IdeEventName } from './types';
+export type IdeEventProps = Record<string, string | number | boolean>;
+/**
+ * 只保留 string / number（有限）/ boolean 的属性值，其余（对象、数组、函数、null、undefined、NaN）一律丢弃，
+ * 避免上层误把参数、表达式等载荷塞进埋点。全部被丢弃时返回 undefined。
+ */
+export declare function sanitizeProps(props: Record<string, unknown> | undefined | null): IdeEventProps | undefined;
+export interface TrackerOptions {
+    ide: 'workflow' | 'ai';
+    /** 返回当前流程名；每次 track 时调用 */
+    getWorkflowName: () => string | undefined;
+    /** 事件发往的缓冲；返回 undefined 表示没有 sink */
+    push: (event: IdeEvent) => void;
+    now?: () => number;
+}
+/** 构造事件并交给 push：补齐 at / ide / workflowName，清洗 props。永不抛出。 */
+export declare function createTracker(opts: TrackerOptions): (name: IdeEventName, props?: Record<string, unknown>) => void;

package/dist/telemetry/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 接入埋点：事件与 Sink 契约（设计见 docs/design/v1.3.0-自助接入设计.md 第 5 节）。
+ *
+ * 只采集「用了什么功能」，不采集参数值、表达式、提示词、对话内容、执行数据。
+ */
+/**
+ * 事件名清单（首批，与设计文档 5.2 节、接入指南「接入埋点」表一致；
+ * 单测会校验三处同步，新增事件时请一并更新文档）。
+ */
+export declare const IDE_EVENT_NAMES: readonly ["ide_opened", "trial_started", "workflow_created", "step_added", "api_imported", "sandbox_run", "workflow_saved", "promotion_requested", "promotion_state", "ai_event"];
+export type IdeEventName = typeof IDE_EVENT_NAMES[number];
+export interface IdeEvent {
+    name: IdeEventName;
+    /** epoch ms */
+    at: number;
+    ide: 'workflow' | 'ai';
+    /** 不含任何参数值 */
+    workflowName?: string;
+    props?: Record<string, string | number | boolean>;
+}
+export interface TelemetrySink {
+    /** SDK 侧批量调用（默认 5 秒或 20 条），页面隐藏时强制 flush */
+    track(events: IdeEvent[]): void | Promise<void>;
+}

package/dist/telemetry/useTelemetry.d.ts

@@ -0,0 +1,22 @@
+import type { IdeEventName, TelemetrySink } from './types';
+/**
+ * IDE 内部使用：按解析后的 sink 维护一个缓冲，返回稳定的 `track(name, props?)`。
+ * - `at` / `ide` / `workflowName`（取当前画布流程名）自动补齐；
+ * - `props` 只保留 string / number / boolean；
+ * - sink 变化时先把旧缓冲 flush 给旧 sink；卸载时 flush；
+ * - 没有 sink 时 track 为空操作。
+ */
+export declare function useTelemetry(ide: 'workflow' | 'ai', sink: TelemetrySink | undefined): (name: IdeEventName, props?: Record<string, unknown>) => void;
+type Track = (name: IdeEventName, props?: Record<string, unknown>) => void;
+/**
+ * 挂载时上报一次 `ide_opened`。守卫放在 ref 里：StrictMode 的「执行 → 清理 → 再执行」不会重复上报；
+ * 真正重新挂载（新实例）会得到新的守卫。
+ */
+export declare function useIdeOpenedOnce(track: Track): void;
+/**
+ * 专业模式经 store 的操作统一上报：
+ * - 本地试跑（`runLocalSandboxDryRun`）→ `sandbox_run`，`entry: 'pro'`
+ * - 画布新增步骤（`addNode`）→ `step_added`，`source: 'builtin'`
+ */
+export declare function useProStoreTelemetry(track: Track): void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yiyi_zhang/reactflow-ui",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Conductor Workflow IDE — Next-Gen AI-Native visual workflow designer with W-LSP data lineage, deterministic in-browser sandbox dry-run, time-travel waterfall debugger, and live split-view sync built with React 19, ReactFlow and Zustand.",
   "keywords": [
     "conductor",