@shopbb/helium 0.7.7 → 0.8.0

package/dist/analytics/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @shopbb/helium/analytics — 埋点 SDK 公开 API
+ *
+ * 浏览器侧用法：
+ *   - <TrackingProvider>：包在 root，初始化 session、起 flush 定时器、自动 page_view
+ *   - useTracking()：在组件内拿到 track() 函数
+ *
+ * 服务端不要用本模块——服务端事件（checkout_paid）由 platform-api 直接 INSERT。
+ *
+ * 注意：本模块与 components/AnalyticsProvider 是两个独立产品：
+ *   - AnalyticsProvider（components）：客户端事件总线，挂 GA / 自定义 reporter
+ *   - TrackingProvider（本模块）：把 5 个核心事件批量发到 /api/events，给 agent 用
+ */
+export { TrackingProvider, useTracking } from './react';
+export type { TrackingProviderProps } from './react';
+export { AnalyticsQueue } from './queue';
+export type { AnalyticsEvent, AnalyticsConfig, EventType, PageViewProps, ProductViewProps, AddToCartProps, CheckoutStartProps, TrackFn, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,YAAY,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,OAAO,GACR,MAAM,SAAS,CAAC"}

package/dist/analytics/index.js

@@ -0,0 +1,16 @@
+/**
+ * @shopbb/helium/analytics — 埋点 SDK 公开 API
+ *
+ * 浏览器侧用法：
+ *   - <TrackingProvider>：包在 root，初始化 session、起 flush 定时器、自动 page_view
+ *   - useTracking()：在组件内拿到 track() 函数
+ *
+ * 服务端不要用本模块——服务端事件（checkout_paid）由 platform-api 直接 INSERT。
+ *
+ * 注意：本模块与 components/AnalyticsProvider 是两个独立产品：
+ *   - AnalyticsProvider（components）：客户端事件总线，挂 GA / 自定义 reporter
+ *   - TrackingProvider（本模块）：把 5 个核心事件批量发到 /api/events，给 agent 用
+ */
+export { TrackingProvider, useTracking } from './react';
+export { AnalyticsQueue } from './queue';
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/analytics/queue.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AnalyticsQueue — 浏览器侧事件缓冲队列
+ *
+ * 职责：
+ *   1. 把 track() 调用收集到内存队列
+ *   2. 定时（3s）或满批（20）触发 flush
+ *   3. flush 调 POST /api/events，失败重试 1 次
+ *   4. beforeunload 时用 navigator.sendBeacon 兜底刷出
+ *
+ * 注意：这是浏览器侧逻辑。SSR 阶段调 track() 会被丢弃（typeof window === 'undefined' 检查）。
+ */
+import type { AnalyticsConfig, AnalyticsEvent } from './types';
+export declare class AnalyticsQueue {
+    private readonly config;
+    private queue;
+    private timer;
+    private sessionId;
+    private flushing;
+    constructor(config: AnalyticsConfig);
+    start(): void;
+    stop(): void;
+    setBuyerId(id: string | null): void;
+    track(event: AnalyticsEvent): void;
+    /** 主动 flush。返回是否实际发送了请求 */
+    flush(): Promise<boolean>;
+    /** 用 sendBeacon 兜底，页面卸载场景 */
+    private flushBeacon;
+    private headers;
+    private log;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/analytics/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/analytics/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAe,MAAM,SAAS,CAAC;AAgC5E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IACF,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,eAAe;IAWnC,KAAK,IAAI,IAAI;IAqBb,IAAI,IAAI,IAAI;IAOZ,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAInC,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAoClC,2BAA2B;IACrB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IA0C/B,6BAA6B;IAC7B,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,GAAG;CAMZ"}

package/dist/analytics/queue.js

@@ -0,0 +1,203 @@
+/**
+ * AnalyticsQueue — 浏览器侧事件缓冲队列
+ *
+ * 职责：
+ *   1. 把 track() 调用收集到内存队列
+ *   2. 定时（3s）或满批（20）触发 flush
+ *   3. flush 调 POST /api/events，失败重试 1 次
+ *   4. beforeunload 时用 navigator.sendBeacon 兜底刷出
+ *
+ * 注意：这是浏览器侧逻辑。SSR 阶段调 track() 会被丢弃（typeof window === 'undefined' 检查）。
+ */
+const SESSION_COOKIE = 'sbb_sid';
+const SESSION_TTL_DAYS = 365;
+/**
+ * 读 sbb_sid cookie，没有则生成一个新的并 set。
+ * 仅浏览器环境调用。
+ */
+function getOrCreateSessionId() {
+    if (typeof document === 'undefined')
+        return '';
+    const match = document.cookie.match(/(?:^|;\s*)sbb_sid=([^;]+)/);
+    if (match)
+        return match[1];
+    // 生成 UUID（不依赖 crypto.randomUUID 以兼容老浏览器）
+    const sid = crypto?.randomUUID?.() ?? generateFallbackUuid();
+    const maxAge = SESSION_TTL_DAYS * 24 * 60 * 60;
+    document.cookie = `${SESSION_COOKIE}=${sid}; max-age=${maxAge}; path=/; samesite=lax`;
+    return sid;
+}
+function generateFallbackUuid() {
+    // RFC4122 v4 简化版
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export class AnalyticsQueue {
+    config;
+    queue = [];
+    timer = null;
+    sessionId = '';
+    flushing = false;
+    constructor(config) {
+        this.config = {
+            apiBase: config.apiBase.replace(/\/+$/, ''),
+            publicAccessToken: config.publicAccessToken,
+            buyerId: config.buyerId ?? null,
+            debug: !!config.debug,
+            flushIntervalMs: config.flushIntervalMs ?? 3000,
+            flushBatchSize: config.flushBatchSize ?? 20,
+        };
+    }
+    start() {
+        if (typeof window === 'undefined')
+            return;
+        this.sessionId = getOrCreateSessionId();
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.config.flushIntervalMs);
+        // 页面卸载兜底
+        window.addEventListener('pagehide', () => this.flushBeacon());
+        window.addEventListener('beforeunload', () => this.flushBeacon());
+        if (typeof document !== 'undefined') {
+            document.addEventListener('visibilitychange', () => {
+                if (document.visibilityState === 'hidden') {
+                    this.flushBeacon();
+                }
+            });
+        }
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    setBuyerId(id) {
+        this.config.buyerId = id;
+    }
+    track(event) {
+        if (typeof window === 'undefined') {
+            this.log('skip-ssr', event.type);
+            return;
+        }
+        if (!this.sessionId) {
+            this.sessionId = getOrCreateSessionId();
+        }
+        const queued = {
+            type: event.type,
+            occurredAt: event.occurredAt ?? Math.floor(Date.now() / 1000),
+            path: event.path !== undefined
+                ? event.path
+                : typeof location !== 'undefined'
+                    ? location.pathname + location.search
+                    : null,
+            referrer: event.referrer !== undefined
+                ? event.referrer
+                : typeof document !== 'undefined'
+                    ? document.referrer || null
+                    : null,
+            props: event.props ?? {},
+        };
+        this.queue.push(queued);
+        this.log('queued', queued.type, this.queue.length);
+        if (this.queue.length >= this.config.flushBatchSize) {
+            void this.flush();
+        }
+    }
+    /** 主动 flush。返回是否实际发送了请求 */
+    async flush() {
+        if (this.flushing)
+            return false;
+        if (this.queue.length === 0)
+            return false;
+        if (!this.config.publicAccessToken) {
+            this.log('skip-no-token');
+            return false;
+        }
+        this.flushing = true;
+        const batch = this.queue.splice(0, this.config.flushBatchSize);
+        const body = JSON.stringify({
+            events: batch.map((e) => ({
+                type: e.type,
+                occurredAt: e.occurredAt,
+                path: e.path ?? undefined,
+                referrer: e.referrer ?? undefined,
+                props: e.props,
+            })),
+        });
+        try {
+            const res = await fetch(`${this.config.apiBase}/api/events`, {
+                method: 'POST',
+                headers: this.headers(),
+                body,
+                keepalive: true,
+            });
+            if (!res.ok) {
+                this.log('flush-failed-status', res.status);
+                // 失败不重试入队（避免堆积），demo 阶段简化
+                return false;
+            }
+            this.log('flushed', batch.length);
+            return true;
+        }
+        catch (err) {
+            this.log('flush-error', err);
+            return false;
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /** 用 sendBeacon 兜底，页面卸载场景 */
+    flushBeacon() {
+        if (this.queue.length === 0)
+            return;
+        if (typeof navigator === 'undefined' || !navigator.sendBeacon)
+            return;
+        if (!this.config.publicAccessToken)
+            return;
+        const batch = this.queue.splice(0, this.config.flushBatchSize);
+        const body = JSON.stringify({
+            events: batch.map((e) => ({
+                type: e.type,
+                occurredAt: e.occurredAt,
+                path: e.path ?? undefined,
+                referrer: e.referrer ?? undefined,
+                props: e.props,
+            })),
+            // sendBeacon 无法设 header，所以把 token / session 塞进 body 作为兜底
+            // platform-api handler 优先认 header；body 字段用于 beacon 场景
+            _auth: {
+                token: this.config.publicAccessToken,
+                sessionId: this.sessionId,
+                buyerId: this.config.buyerId,
+            },
+        });
+        const blob = new Blob([body], { type: 'application/json' });
+        const ok = navigator.sendBeacon(`${this.config.apiBase}/api/events?beacon=1`, blob);
+        this.log('beacon', ok, batch.length);
+    }
+    headers() {
+        const h = {
+            'Content-Type': 'application/json',
+            'X-Storefront-Access-Token': this.config.publicAccessToken,
+            'X-Session-Id': this.sessionId,
+        };
+        if (this.config.buyerId) {
+            h['X-Buyer-Id'] = this.config.buyerId;
+        }
+        return h;
+    }
+    log(...args) {
+        if (this.config.debug) {
+            // eslint-disable-next-line no-console
+            console.log('[helium-analytics]', ...args);
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/analytics/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/analytics/queue.ts"],"names":[],"mappings":"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"}

package/dist/analytics/react.d.ts

@@ -0,0 +1,44 @@
+/**
+ * TrackingProvider + useTracking — React 绑定（后端事件埋点）
+ *
+ * 与 components/AnalyticsProvider 不同：
+ *   - AnalyticsProvider（旧）：客户端事件总线，商家挂 GA / Plausible 等 reporter
+ *   - TrackingProvider（新）：把 5 个核心事件发到 platform-api /api/events
+ *
+ * 用法：
+ *   <TrackingProvider
+ *     apiBase={store.apiBase}
+ *     publicAccessToken={store.publicAccessToken}
+ *     buyerId={buyer?.id}
+ *     debug
+ *   >
+ *     <App />
+ *   </TrackingProvider>
+ *
+ *   const { track } = useTracking();
+ *   track({ type: 'add_to_cart', props: { productId, quantity: 1 } });
+ *
+ * 自动事件：
+ *   - 首次挂载发一次 page_view
+ *   - 监听 history pushState/replaceState/popstate，每次 URL 变化补发 page_view
+ */
+import * as React from 'react';
+import type { AnalyticsConfig, TrackFn } from './types';
+interface ContextValue {
+    track: TrackFn;
+    setBuyerId: (id: string | null) => void;
+}
+export interface TrackingProviderProps extends AnalyticsConfig {
+    children: React.ReactNode;
+    /** 是否自动发 page_view（默认 true） */
+    autoPageview?: boolean;
+}
+export declare function TrackingProvider(props: TrackingProviderProps): React.ReactElement;
+/**
+ * 在组件里拿到 track 函数。
+ *
+ * 在 TrackingProvider 之外调用会得到一个 no-op，不报错（方便在测试/SSR 中使用）。
+ */
+export declare function useTracking(): ContextValue;
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/analytics/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/analytics/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAkB,eAAe,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAExE,UAAU,YAAY;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACzC;AAID,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,+BAA+B;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAuFjF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,YAAY,CAI1C"}

package/dist/analytics/react.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * TrackingProvider + useTracking — React 绑定（后端事件埋点）
+ *
+ * 与 components/AnalyticsProvider 不同：
+ *   - AnalyticsProvider（旧）：客户端事件总线，商家挂 GA / Plausible 等 reporter
+ *   - TrackingProvider（新）：把 5 个核心事件发到 platform-api /api/events
+ *
+ * 用法：
+ *   <TrackingProvider
+ *     apiBase={store.apiBase}
+ *     publicAccessToken={store.publicAccessToken}
+ *     buyerId={buyer?.id}
+ *     debug
+ *   >
+ *     <App />
+ *   </TrackingProvider>
+ *
+ *   const { track } = useTracking();
+ *   track({ type: 'add_to_cart', props: { productId, quantity: 1 } });
+ *
+ * 自动事件：
+ *   - 首次挂载发一次 page_view
+ *   - 监听 history pushState/replaceState/popstate，每次 URL 变化补发 page_view
+ */
+import * as React from 'react';
+import { AnalyticsQueue } from './queue';
+const TrackingCtx = React.createContext(null);
+export function TrackingProvider(props) {
+    const { children, autoPageview = true, apiBase, publicAccessToken, buyerId, debug, flushIntervalMs, flushBatchSize, } = props;
+    // 用 ref 持有 queue，避免每次 re-render 重建
+    const queueRef = React.useRef(null);
+    if (queueRef.current === null) {
+        queueRef.current = new AnalyticsQueue({
+            apiBase,
+            publicAccessToken,
+            buyerId,
+            debug,
+            flushIntervalMs,
+            flushBatchSize,
+        });
+    }
+    // buyerId 变化时同步到 queue
+    React.useEffect(() => {
+        queueRef.current?.setBuyerId(buyerId ?? null);
+    }, [buyerId]);
+    // 启动 queue（只在浏览器侧）
+    React.useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const q = queueRef.current;
+        if (!q)
+            return;
+        q.start();
+        return () => q.stop();
+    }, []);
+    // 自动 page_view
+    React.useEffect(() => {
+        if (!autoPageview)
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const q = queueRef.current;
+        if (!q)
+            return;
+        const send = () => {
+            q.track({
+                type: 'page_view',
+                props: { title: typeof document !== 'undefined' ? document.title : undefined },
+            });
+        };
+        // 首次
+        send();
+        // patch history methods 以捕获 SPA 导航
+        const origPush = history.pushState;
+        const origReplace = history.replaceState;
+        history.pushState = function (...args) {
+            origPush.apply(this, args);
+            send();
+        };
+        history.replaceState = function (...args) {
+            origReplace.apply(this, args);
+            send();
+        };
+        const onPop = () => send();
+        window.addEventListener('popstate', onPop);
+        return () => {
+            history.pushState = origPush;
+            history.replaceState = origReplace;
+            window.removeEventListener('popstate', onPop);
+        };
+    }, [autoPageview]);
+    const value = React.useMemo(() => ({
+        track: (e) => queueRef.current?.track(e),
+        setBuyerId: (id) => queueRef.current?.setBuyerId(id),
+    }), []);
+    return _jsx(TrackingCtx.Provider, { value: value, children: children });
+}
+/**
+ * 在组件里拿到 track 函数。
+ *
+ * 在 TrackingProvider 之外调用会得到一个 no-op，不报错（方便在测试/SSR 中使用）。
+ */
+export function useTracking() {
+    const ctx = React.useContext(TrackingCtx);
+    if (ctx)
+        return ctx;
+    return NOOP;
+}
+const NOOP = {
+    track: () => { },
+    setBuyerId: () => { },
+};
+//# sourceMappingURL=react.js.map

package/dist/analytics/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../../src/analytics/react.tsx"],"names":[],"mappings":"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"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Analytics SDK 类型
+ *
+ * Helium 的埋点接口。与 platform-api 的事件 schema 保持一致。
+ */
+export type EventType = 'page_view' | 'product_view' | 'add_to_cart' | 'checkout_start' | 'checkout_paid';
+/** 单条事件输入 */
+export interface AnalyticsEvent {
+    /** 事件类型 */
+    type: EventType;
+    /** 客户端发生时间（秒，Unix）。默认 Date.now()/1000 */
+    occurredAt?: number;
+    /** 页面 path（默认 window.location.pathname） */
+    path?: string;
+    /** referrer（默认 document.referrer） */
+    referrer?: string;
+    /** 事件附加数据 */
+    props?: Record<string, unknown>;
+}
+/** 各事件的 props 形状 */
+export interface PageViewProps {
+    title?: string;
+}
+export interface ProductViewProps {
+    productId: string;
+    variantId?: string;
+    priceCents?: number;
+    currency?: string;
+}
+export interface AddToCartProps {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    priceCents?: number;
+    currency?: string;
+}
+export interface CheckoutStartProps {
+    cartId?: string;
+    itemCount: number;
+    subtotalCents: number;
+    currency: string;
+}
+/** AnalyticsProvider 初始化配置 */
+export interface AnalyticsConfig {
+    /** 平台 API base URL，例如 https://api.oxygen-demo.cloudc.top */
+    apiBase: string;
+    /** Storefront public access token */
+    publicAccessToken: string;
+    /** 当前买家 ID（已登录时传入） */
+    buyerId?: string | null;
+    /** 是否开启 debug 日志 */
+    debug?: boolean;
+    /** flush 间隔（毫秒），默认 3000 */
+    flushIntervalMs?: number;
+    /** 批量上限（条），默认 20 */
+    flushBatchSize?: number;
+}
+/** track 函数签名 */
+export type TrackFn = (event: AnalyticsEvent) => void;
+/** 内部队列条目 */
+export interface QueuedEvent {
+    type: EventType;
+    occurredAt: number;
+    path: string | null;
+    referrer: string | null;
+    props: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,eAAe,CAAC;AAEpB,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2BAA2B;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iBAAiB;AACjB,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAEtD,aAAa;AACb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC"}

package/dist/analytics/types.js

@@ -0,0 +1,7 @@
+/**
+ * Analytics SDK 类型
+ *
+ * Helium 的埋点接口。与 platform-api 的事件 schema 保持一致。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/components/AddToCartButton.d.ts

@@ -17,6 +17,7 @@
  * 监听全局 fetcher 状态。Hydrogen demo store 用 `useAside().open()` 模式。
  */
 import * as React from 'react';
+import { type CartLineInput } from './CartForm';
 export interface AddToCartButtonProps {
     /** variant GID */
     variantId: string;
@@ -39,6 +40,12 @@ export interface AddToCartButtonProps {
     route?: string;
     /** 按钮 children */
     children?: React.ReactNode;
+    /**
+     * 按钮被点击时触发（form 提交之前）。
+     * 用于埋点 / dataLayer / 自定义分析回调。
+     * 不影响表单提交流程。
+     */
+    onAdd?: (line: CartLineInput) => void;
 }
 export declare function AddToCartButton(props: AddToCartButtonProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=AddToCartButton.d.ts.map

package/dist/components/AddToCartButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AddToCartButton.d.ts","sourceRoot":"","sources":["../../src/components/AddToCartButton.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,oBAAoB;IACnC,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,kDAAkD;IAClD,eAAe,CAAC,EAAE,GAAG,CAAC;IACtB,kBAAkB;IAClB,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAClC,sBAAsB;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAwC1D"}
+{"version":3,"file":"AddToCartButton.d.ts","sourceRoot":"","sources":["../../src/components/AddToCartButton.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,kDAAkD;IAClD,eAAe,CAAC,EAAE,GAAG,CAAC;IACtB,kBAAkB;IAClB,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAClC,sBAAsB;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACvC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CAoD1D"}

package/dist/components/AddToCartButton.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { CartForm } from './CartForm';
 export function AddToCartButton(props) {
-    const { variantId, quantity = 1, attributes, selectedVariant, unavailableText = '缺货', loadingText = '加入中...', disabled = false, className, route = '/cart', children = '加入购物车', } = props;
+    const { variantId, quantity = 1, attributes, selectedVariant, unavailableText = '缺货', loadingText = '加入中...', disabled = false, className, route = '/cart', children = '加入购物车', onAdd, } = props;
     const line = { merchandiseId: variantId, quantity };
     if (attributes && attributes.length > 0)
         line.attributes = attributes;
@@ -9,7 +9,18 @@ export function AddToCartButton(props) {
         line.selectedVariant = selectedVariant;
     return (_jsx(CartForm, { route: route, action: CartForm.ACTIONS.LinesAdd, inputs: { lines: [line] }, children: (fetcher) => {
             const submitting = fetcher.state !== 'idle';
-            return (_jsx("button", { type: "submit", className: className, disabled: disabled || submitting, "data-add-to-cart": true, "data-loading": submitting ? '' : undefined, children: submitting ? loadingText : disabled ? unavailableText : children }));
+            return (_jsx("button", { type: "submit", className: className, disabled: disabled || submitting, "data-add-to-cart": true, "data-loading": submitting ? '' : undefined, onClick: () => {
+                    if (onAdd && !submitting && !disabled) {
+                        try {
+                            onAdd(line);
+                        }
+                        catch (err) {
+                            if (typeof console !== 'undefined') {
+                                console.warn('[AddToCartButton] onAdd threw', err);
+                            }
+                        }
+                    }
+                }, children: submitting ? loadingText : disabled ? unavailableText : children }));
         } }));
 }
 //# sourceMappingURL=AddToCartButton.js.map

package/dist/components/AddToCartButton.js.map

@@ -1 +1 @@
-{"version":3,"file":"AddToCartButton.js","sourceRoot":"","sources":["../../src/components/AddToCartButton.tsx"],"names":[],"mappings":";AAoBA,OAAO,EAAE,QAAQ,EAAsB,MAAM,YAAY,CAAC;AAuB1D,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,EACJ,SAAS,EACT,QAAQ,GAAG,CAAC,EACZ,UAAU,EACV,eAAe,EACf,eAAe,GAAG,IAAI,EACtB,WAAW,GAAG,QAAQ,EACtB,QAAQ,GAAG,KAAK,EAChB,SAAS,EACT,KAAK,GAAG,OAAO,EACf,QAAQ,GAAG,OAAO,GACnB,GAAG,KAAK,CAAC;IAEV,MAAM,IAAI,GAAkB,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IACnE,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACtE,IAAI,eAAe;QAAE,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IAE5D,OAAO,CACL,KAAC,QAAQ,IACP,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EACjC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,YAExB,CAAC,OAAO,EAAE,EAAE;YACX,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC;YAC5C,OAAO,CACL,iBACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,QAAQ,IAAI,UAAU,4CAElB,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,YAExC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,GAC1D,CACV,CAAC;QACJ,CAAC,GACQ,CACZ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"AddToCartButton.js","sourceRoot":"","sources":["../../src/components/AddToCartButton.tsx"],"names":[],"mappings":";AAoBA,OAAO,EAAE,QAAQ,EAAsB,MAAM,YAAY,CAAC;AA6B1D,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,EACJ,SAAS,EACT,QAAQ,GAAG,CAAC,EACZ,UAAU,EACV,eAAe,EACf,eAAe,GAAG,IAAI,EACtB,WAAW,GAAG,QAAQ,EACtB,QAAQ,GAAG,KAAK,EAChB,SAAS,EACT,KAAK,GAAG,OAAO,EACf,QAAQ,GAAG,OAAO,EAClB,KAAK,GACN,GAAG,KAAK,CAAC;IAEV,MAAM,IAAI,GAAkB,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IACnE,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACtE,IAAI,eAAe;QAAE,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IAE5D,OAAO,CACL,KAAC,QAAQ,IACP,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EACjC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,YAExB,CAAC,OAAO,EAAE,EAAE;YACX,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC;YAC5C,OAAO,CACL,iBACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,QAAQ,IAAI,UAAU,4CAElB,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EACzC,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAI,KAAK,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;wBACtC,IAAI,CAAC;4BACH,KAAK,CAAC,IAAI,CAAC,CAAC;wBACd,CAAC;wBAAC,OAAO,GAAG,EAAE,CAAC;4BACb,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;gCACnC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,GAAG,CAAC,CAAC;4BACrD,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC,YAEA,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,GAC1D,CACV,CAAC;QACJ,CAAC,GACQ,CACZ,CAAC;AACJ,CAAC"}

package/dist/react.d.ts

@@ -95,4 +95,9 @@ export interface ReactRendererOptions {
     onError?: (err: unknown, request: Request) => Response | Promise<Response>;
 }
 export declare function createReactRenderer(opts: ReactRendererOptions): (request: Request, env: any, executionContext: ExecutionContext) => Promise<Response>;
+/**
+ * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
+ */
+export { TrackingProvider, useTracking, AnalyticsQueue, } from './analytics';
+export type { TrackingProviderProps, AnalyticsEvent, AnalyticsConfig, EventType as AnalyticsEventType, TrackFn, PageViewProps, ProductViewProps, AddToCartProps, CheckoutStartProps, } from './analytics';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,6EAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE;QACX,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,IAE1D,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,kBAAkB,gBAAgB,KACjC,OAAO,CAAC,QAAQ,CAAC,CAkHrB"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,6EAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE;QACX,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,IAE1D,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,kBAAkB,gBAAgB,KACjC,OAAO,CAAC,QAAQ,CAAC,CAkHrB;AAYD;;GAEG;AAUH,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,IAAI,kBAAkB,EAC/B,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACnB,MAAM,aAAa,CAAC"}

package/dist/react.js

@@ -148,6 +148,16 @@ function escapeHtml(s) {
 /**
  * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
  */
+// ============================================================
+// Tracking SDK re-export
+// ============================================================
+// 把 5 个核心事件（page_view / product_view / add_to_cart / checkout_start / checkout_paid）
+// 批量发到 platform-api 的 /api/events。
+//
+// 与 components/AnalyticsProvider 解耦：
+//   - AnalyticsProvider 是商家用的事件总线（自定义 reporter）
+//   - TrackingProvider 是平台的标准埋点（发到 platform-api）
+export { TrackingProvider, useTracking, AnalyticsQueue, } from './analytics';
 function composeStream(head, body, tail) {
     const encoder = new TextEncoder();
     return new ReadableStream({

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",

package/src/analytics/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @shopbb/helium/analytics — 埋点 SDK 公开 API
+ *
+ * 浏览器侧用法：
+ *   - <TrackingProvider>：包在 root，初始化 session、起 flush 定时器、自动 page_view
+ *   - useTracking()：在组件内拿到 track() 函数
+ *
+ * 服务端不要用本模块——服务端事件（checkout_paid）由 platform-api 直接 INSERT。
+ *
+ * 注意：本模块与 components/AnalyticsProvider 是两个独立产品：
+ *   - AnalyticsProvider（components）：客户端事件总线，挂 GA / 自定义 reporter
+ *   - TrackingProvider（本模块）：把 5 个核心事件批量发到 /api/events，给 agent 用
+ */
+
+export { TrackingProvider, useTracking } from './react';
+export type { TrackingProviderProps } from './react';
+export { AnalyticsQueue } from './queue';
+export type {
+  AnalyticsEvent,
+  AnalyticsConfig,
+  EventType,
+  PageViewProps,
+  ProductViewProps,
+  AddToCartProps,
+  CheckoutStartProps,
+  TrackFn,
+} from './types';

package/src/analytics/queue.ts

@@ -0,0 +1,224 @@
+/**
+ * AnalyticsQueue — 浏览器侧事件缓冲队列
+ *
+ * 职责：
+ *   1. 把 track() 调用收集到内存队列
+ *   2. 定时（3s）或满批（20）触发 flush
+ *   3. flush 调 POST /api/events，失败重试 1 次
+ *   4. beforeunload 时用 navigator.sendBeacon 兜底刷出
+ *
+ * 注意：这是浏览器侧逻辑。SSR 阶段调 track() 会被丢弃（typeof window === 'undefined' 检查）。
+ */
+
+import type { AnalyticsConfig, AnalyticsEvent, QueuedEvent } from './types';
+
+const SESSION_COOKIE = 'sbb_sid';
+const SESSION_TTL_DAYS = 365;
+
+/**
+ * 读 sbb_sid cookie，没有则生成一个新的并 set。
+ * 仅浏览器环境调用。
+ */
+function getOrCreateSessionId(): string {
+  if (typeof document === 'undefined') return '';
+
+  const match = document.cookie.match(/(?:^|;\s*)sbb_sid=([^;]+)/);
+  if (match) return match[1];
+
+  // 生成 UUID（不依赖 crypto.randomUUID 以兼容老浏览器）
+  const sid = crypto?.randomUUID?.() ?? generateFallbackUuid();
+
+  const maxAge = SESSION_TTL_DAYS * 24 * 60 * 60;
+  document.cookie = `${SESSION_COOKIE}=${sid}; max-age=${maxAge}; path=/; samesite=lax`;
+  return sid;
+}
+
+function generateFallbackUuid(): string {
+  // RFC4122 v4 简化版
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export class AnalyticsQueue {
+  private readonly config: Required<Omit<AnalyticsConfig, 'buyerId' | 'debug'>> & {
+    buyerId: string | null;
+    debug: boolean;
+  };
+  private queue: QueuedEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private sessionId = '';
+  private flushing = false;
+
+  constructor(config: AnalyticsConfig) {
+    this.config = {
+      apiBase: config.apiBase.replace(/\/+$/, ''),
+      publicAccessToken: config.publicAccessToken,
+      buyerId: config.buyerId ?? null,
+      debug: !!config.debug,
+      flushIntervalMs: config.flushIntervalMs ?? 3000,
+      flushBatchSize: config.flushBatchSize ?? 20,
+    };
+  }
+
+  start(): void {
+    if (typeof window === 'undefined') return;
+    this.sessionId = getOrCreateSessionId();
+
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.config.flushIntervalMs);
+
+    // 页面卸载兜底
+    window.addEventListener('pagehide', () => this.flushBeacon());
+    window.addEventListener('beforeunload', () => this.flushBeacon());
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          this.flushBeacon();
+        }
+      });
+    }
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  setBuyerId(id: string | null): void {
+    this.config.buyerId = id;
+  }
+
+  track(event: AnalyticsEvent): void {
+    if (typeof window === 'undefined') {
+      this.log('skip-ssr', event.type);
+      return;
+    }
+
+    if (!this.sessionId) {
+      this.sessionId = getOrCreateSessionId();
+    }
+
+    const queued: QueuedEvent = {
+      type: event.type,
+      occurredAt: event.occurredAt ?? Math.floor(Date.now() / 1000),
+      path:
+        event.path !== undefined
+          ? event.path
+          : typeof location !== 'undefined'
+            ? location.pathname + location.search
+            : null,
+      referrer:
+        event.referrer !== undefined
+          ? event.referrer
+          : typeof document !== 'undefined'
+            ? document.referrer || null
+            : null,
+      props: event.props ?? {},
+    };
+
+    this.queue.push(queued);
+    this.log('queued', queued.type, this.queue.length);
+
+    if (this.queue.length >= this.config.flushBatchSize) {
+      void this.flush();
+    }
+  }
+
+  /** 主动 flush。返回是否实际发送了请求 */
+  async flush(): Promise<boolean> {
+    if (this.flushing) return false;
+    if (this.queue.length === 0) return false;
+    if (!this.config.publicAccessToken) {
+      this.log('skip-no-token');
+      return false;
+    }
+
+    this.flushing = true;
+    const batch = this.queue.splice(0, this.config.flushBatchSize);
+    const body = JSON.stringify({
+      events: batch.map((e) => ({
+        type: e.type,
+        occurredAt: e.occurredAt,
+        path: e.path ?? undefined,
+        referrer: e.referrer ?? undefined,
+        props: e.props,
+      })),
+    });
+
+    try {
+      const res = await fetch(`${this.config.apiBase}/api/events`, {
+        method: 'POST',
+        headers: this.headers(),
+        body,
+        keepalive: true,
+      });
+      if (!res.ok) {
+        this.log('flush-failed-status', res.status);
+        // 失败不重试入队（避免堆积），demo 阶段简化
+        return false;
+      }
+      this.log('flushed', batch.length);
+      return true;
+    } catch (err) {
+      this.log('flush-error', err);
+      return false;
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /** 用 sendBeacon 兜底，页面卸载场景 */
+  private flushBeacon(): void {
+    if (this.queue.length === 0) return;
+    if (typeof navigator === 'undefined' || !navigator.sendBeacon) return;
+    if (!this.config.publicAccessToken) return;
+
+    const batch = this.queue.splice(0, this.config.flushBatchSize);
+    const body = JSON.stringify({
+      events: batch.map((e) => ({
+        type: e.type,
+        occurredAt: e.occurredAt,
+        path: e.path ?? undefined,
+        referrer: e.referrer ?? undefined,
+        props: e.props,
+      })),
+      // sendBeacon 无法设 header，所以把 token / session 塞进 body 作为兜底
+      // platform-api handler 优先认 header；body 字段用于 beacon 场景
+      _auth: {
+        token: this.config.publicAccessToken,
+        sessionId: this.sessionId,
+        buyerId: this.config.buyerId,
+      },
+    });
+
+    const blob = new Blob([body], { type: 'application/json' });
+    const ok = navigator.sendBeacon(`${this.config.apiBase}/api/events?beacon=1`, blob);
+    this.log('beacon', ok, batch.length);
+  }
+
+  private headers(): HeadersInit {
+    const h: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-Storefront-Access-Token': this.config.publicAccessToken,
+      'X-Session-Id': this.sessionId,
+    };
+    if (this.config.buyerId) {
+      h['X-Buyer-Id'] = this.config.buyerId;
+    }
+    return h;
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.config.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[helium-analytics]', ...args);
+    }
+  }
+}

package/src/analytics/react.tsx

@@ -0,0 +1,146 @@
+/**
+ * TrackingProvider + useTracking — React 绑定（后端事件埋点）
+ *
+ * 与 components/AnalyticsProvider 不同：
+ *   - AnalyticsProvider（旧）：客户端事件总线，商家挂 GA / Plausible 等 reporter
+ *   - TrackingProvider（新）：把 5 个核心事件发到 platform-api /api/events
+ *
+ * 用法：
+ *   <TrackingProvider
+ *     apiBase={store.apiBase}
+ *     publicAccessToken={store.publicAccessToken}
+ *     buyerId={buyer?.id}
+ *     debug
+ *   >
+ *     <App />
+ *   </TrackingProvider>
+ *
+ *   const { track } = useTracking();
+ *   track({ type: 'add_to_cart', props: { productId, quantity: 1 } });
+ *
+ * 自动事件：
+ *   - 首次挂载发一次 page_view
+ *   - 监听 history pushState/replaceState/popstate，每次 URL 变化补发 page_view
+ */
+
+import * as React from 'react';
+import { AnalyticsQueue } from './queue';
+import type { AnalyticsEvent, AnalyticsConfig, TrackFn } from './types';
+
+interface ContextValue {
+  track: TrackFn;
+  setBuyerId: (id: string | null) => void;
+}
+
+const TrackingCtx = React.createContext<ContextValue | null>(null);
+
+export interface TrackingProviderProps extends AnalyticsConfig {
+  children: React.ReactNode;
+  /** 是否自动发 page_view（默认 true） */
+  autoPageview?: boolean;
+}
+
+export function TrackingProvider(props: TrackingProviderProps): React.ReactElement {
+  const {
+    children,
+    autoPageview = true,
+    apiBase,
+    publicAccessToken,
+    buyerId,
+    debug,
+    flushIntervalMs,
+    flushBatchSize,
+  } = props;
+
+  // 用 ref 持有 queue，避免每次 re-render 重建
+  const queueRef = React.useRef<AnalyticsQueue | null>(null);
+
+  if (queueRef.current === null) {
+    queueRef.current = new AnalyticsQueue({
+      apiBase,
+      publicAccessToken,
+      buyerId,
+      debug,
+      flushIntervalMs,
+      flushBatchSize,
+    });
+  }
+
+  // buyerId 变化时同步到 queue
+  React.useEffect(() => {
+    queueRef.current?.setBuyerId(buyerId ?? null);
+  }, [buyerId]);
+
+  // 启动 queue（只在浏览器侧）
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const q = queueRef.current;
+    if (!q) return;
+    q.start();
+    return () => q.stop();
+  }, []);
+
+  // 自动 page_view
+  React.useEffect(() => {
+    if (!autoPageview) return;
+    if (typeof window === 'undefined') return;
+    const q = queueRef.current;
+    if (!q) return;
+
+    const send = () => {
+      q.track({
+        type: 'page_view',
+        props: { title: typeof document !== 'undefined' ? document.title : undefined },
+      });
+    };
+
+    // 首次
+    send();
+
+    // patch history methods 以捕获 SPA 导航
+    const origPush = history.pushState;
+    const origReplace = history.replaceState;
+    history.pushState = function (...args) {
+      origPush.apply(this, args as any);
+      send();
+    };
+    history.replaceState = function (...args) {
+      origReplace.apply(this, args as any);
+      send();
+    };
+    const onPop = () => send();
+    window.addEventListener('popstate', onPop);
+
+    return () => {
+      history.pushState = origPush;
+      history.replaceState = origReplace;
+      window.removeEventListener('popstate', onPop);
+    };
+  }, [autoPageview]);
+
+  const value = React.useMemo<ContextValue>(
+    () => ({
+      track: (e: AnalyticsEvent) => queueRef.current?.track(e),
+      setBuyerId: (id) => queueRef.current?.setBuyerId(id),
+    }),
+    [],
+  );
+
+  return <TrackingCtx.Provider value={value}>{children}</TrackingCtx.Provider>;
+}
+
+/**
+ * 在组件里拿到 track 函数。
+ *
+ * 在 TrackingProvider 之外调用会得到一个 no-op，不报错（方便在测试/SSR 中使用）。
+ */
+export function useTracking(): ContextValue {
+  const ctx = React.useContext(TrackingCtx);
+  if (ctx) return ctx;
+  return NOOP;
+}
+
+const NOOP: ContextValue = {
+  track: () => {},
+  setBuyerId: () => {},
+};

package/src/analytics/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Analytics SDK 类型
+ *
+ * Helium 的埋点接口。与 platform-api 的事件 schema 保持一致。
+ */
+
+export type EventType =
+  | 'page_view'
+  | 'product_view'
+  | 'add_to_cart'
+  | 'checkout_start'
+  | 'checkout_paid';
+
+/** 单条事件输入 */
+export interface AnalyticsEvent {
+  /** 事件类型 */
+  type: EventType;
+  /** 客户端发生时间（秒，Unix）。默认 Date.now()/1000 */
+  occurredAt?: number;
+  /** 页面 path（默认 window.location.pathname） */
+  path?: string;
+  /** referrer（默认 document.referrer） */
+  referrer?: string;
+  /** 事件附加数据 */
+  props?: Record<string, unknown>;
+}
+
+/** 各事件的 props 形状 */
+export interface PageViewProps {
+  title?: string;
+}
+
+export interface ProductViewProps {
+  productId: string;
+  variantId?: string;
+  priceCents?: number;
+  currency?: string;
+}
+
+export interface AddToCartProps {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  priceCents?: number;
+  currency?: string;
+}
+
+export interface CheckoutStartProps {
+  cartId?: string;
+  itemCount: number;
+  subtotalCents: number;
+  currency: string;
+}
+
+/** AnalyticsProvider 初始化配置 */
+export interface AnalyticsConfig {
+  /** 平台 API base URL，例如 https://api.oxygen-demo.cloudc.top */
+  apiBase: string;
+  /** Storefront public access token */
+  publicAccessToken: string;
+  /** 当前买家 ID（已登录时传入） */
+  buyerId?: string | null;
+  /** 是否开启 debug 日志 */
+  debug?: boolean;
+  /** flush 间隔（毫秒），默认 3000 */
+  flushIntervalMs?: number;
+  /** 批量上限（条），默认 20 */
+  flushBatchSize?: number;
+}
+
+/** track 函数签名 */
+export type TrackFn = (event: AnalyticsEvent) => void;
+
+/** 内部队列条目 */
+export interface QueuedEvent {
+  type: EventType;
+  occurredAt: number;
+  path: string | null;
+  referrer: string | null;
+  props: Record<string, unknown>;
+}

package/src/components/AddToCartButton.tsx

@@ -39,6 +39,12 @@ export interface AddToCartButtonProps {
   route?: string;
   /** 按钮 children */
   children?: React.ReactNode;
+  /**
+   * 按钮被点击时触发（form 提交之前）。
+   * 用于埋点 / dataLayer / 自定义分析回调。
+   * 不影响表单提交流程。
+   */
+  onAdd?: (line: CartLineInput) => void;
 }
 
 export function AddToCartButton(props: AddToCartButtonProps) {
@@ -53,6 +59,7 @@ export function AddToCartButton(props: AddToCartButtonProps) {
     className,
     route = '/cart',
     children = '加入购物车',
+    onAdd,
   } = props;
 
   const line: CartLineInput = { merchandiseId: variantId, quantity };
@@ -74,6 +81,17 @@ export function AddToCartButton(props: AddToCartButtonProps) {
             disabled={disabled || submitting}
             data-add-to-cart
             data-loading={submitting ? '' : undefined}
+            onClick={() => {
+              if (onAdd && !submitting && !disabled) {
+                try {
+                  onAdd(line);
+                } catch (err) {
+                  if (typeof console !== 'undefined') {
+                    console.warn('[AddToCartButton] onAdd threw', err);
+                  }
+                }
+              }
+            }}
           >
             {submitting ? loadingText : disabled ? unavailableText : children}
           </button>

package/src/react.tsx

@@ -274,6 +274,32 @@ function escapeHtml(s: string): string {
 /**
  * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
  */
+// ============================================================
+// Tracking SDK re-export
+// ============================================================
+// 把 5 个核心事件（page_view / product_view / add_to_cart / checkout_start / checkout_paid）
+// 批量发到 platform-api 的 /api/events。
+//
+// 与 components/AnalyticsProvider 解耦：
+//   - AnalyticsProvider 是商家用的事件总线（自定义 reporter）
+//   - TrackingProvider 是平台的标准埋点（发到 platform-api）
+export {
+  TrackingProvider,
+  useTracking,
+  AnalyticsQueue,
+} from './analytics';
+export type {
+  TrackingProviderProps,
+  AnalyticsEvent,
+  AnalyticsConfig,
+  EventType as AnalyticsEventType,
+  TrackFn,
+  PageViewProps,
+  ProductViewProps,
+  AddToCartProps,
+  CheckoutStartProps,
+} from './analytics';
+
 function composeStream(
   head: string,
   body: ReadableStream<Uint8Array>,