we0-analyze-sdk 0.1.0

package/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## Project Rules
+
+- Keep implementation code as small as possible.
+- Do not add fallback, retry, queue, polyfill, adapter, or compatibility code.
+- Only use the most basic `catch` block for surfacing errors.
+- Backend persistence is paused. Use colored `console.log` as the only reporter until the docs are confirmed.
+- Do not add new runtime dependencies without explicit approval.
+- Keep public SDK APIs explicit and narrow.
+
+## Current Scope
+
+- Browser SDK boilerplate.
+- Pageview event collection.
+- PV and UV fields in the reported payload.
+- Manual custom event capture.
+- Manual user identify.

package/README.md

@@ -0,0 +1,38 @@
+# we0-analyze-sdk
+
+Minimal browser analytics SDK boilerplate for pageview, pageleave, attribution, device, and conversion events.
+
+## Install
+
+```bash
+npm install we0-analyze-sdk
+```
+
+## Usage
+
+```ts
+import { init } from 'we0-analyze-sdk'
+
+const we0 = init({
+  projectId: process.env.PROJECT_ID!,
+  autoTrackPageview: true,
+  supabaseUrl: process.env.SUPABASE_URL!,
+  supabaseAnonKey: process.env.SUPABASE_ANON_KEY!,
+})
+
+we0.capture('signup_click', {
+  source: 'home',
+})
+
+we0.conversion('signup')
+we0.identify('user_id')
+
+console.log(we0.getMetrics())
+```
+
+Run `docs/supabase-schema.sql` in the Supabase project before enabling database writes. The SDK writes to:
+
+- `${PROJECT_ID}____we0_pageviews`
+- `${PROJECT_ID}____we0_events`
+
+Colored `console.log` output is still kept for local debugging.

package/dist/attribution.d.ts

@@ -0,0 +1,2 @@
+import type { We0Attribution } from './types.js';
+export declare function collectAttribution(): We0Attribution;

package/dist/attribution.js

@@ -0,0 +1,15 @@
+export function collectAttribution() {
+    const url = new URL(location.href);
+    const source = url.searchParams.get('utm_source');
+    const referrerHost = document.referrer ? new URL(document.referrer).host : '';
+    return {
+        type: source ? 'utm' : referrerHost ? 'referrer' : 'direct',
+        source: source ?? (referrerHost || 'direct'),
+        medium: url.searchParams.get('utm_medium') ?? '',
+        campaign: url.searchParams.get('utm_campaign') ?? '',
+        content: url.searchParams.get('utm_content') ?? '',
+        term: url.searchParams.get('utm_term') ?? '',
+        referrer: document.referrer,
+        referrerHost,
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { We0Config, We0MetricsSnapshot } from './types.js';
+export declare class We0Client {
+    private readonly config;
+    private readonly distinctId;
+    private readonly sessionId;
+    private readonly visitCount;
+    private readonly metrics;
+    private isNewVisitor;
+    private activePage?;
+    private sessionPageviewCount;
+    private sessionConversionCount;
+    private readonly reporter;
+    constructor(config: We0Config);
+    pageview(properties?: Record<string, unknown>): void;
+    pageleave(properties?: Record<string, unknown>): void;
+    private leavePage;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    conversion(event: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, properties?: Record<string, unknown>): void;
+    getMetrics(): We0MetricsSnapshot;
+    private report;
+}

package/dist/client.js

@@ -0,0 +1,158 @@
+import { collectAttribution } from './attribution.js';
+import { collectDevice } from './device.js';
+import { logEvent, logMetrics } from './logger.js';
+import { MetricsStore } from './metrics.js';
+import { SupabaseReporter } from './supabase-reporter.js';
+import { resolveSession, resolveVisitor } from './visitor.js';
+export class We0Client {
+    config;
+    distinctId;
+    sessionId;
+    visitCount;
+    metrics;
+    isNewVisitor;
+    activePage;
+    sessionPageviewCount = 0;
+    sessionConversionCount = 0;
+    reporter;
+    constructor(config) {
+        this.config = config;
+        const visitor = resolveVisitor();
+        const session = resolveSession();
+        this.distinctId = visitor.distinctId;
+        this.sessionId = session.sessionId;
+        this.visitCount = session.visitCount;
+        this.metrics = new MetricsStore(session.visitCount);
+        this.isNewVisitor = visitor.isNew;
+        this.reporter = new SupabaseReporter(config);
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden') {
+                this.pageleave();
+            }
+        });
+        window.addEventListener('pagehide', () => this.pageleave());
+        if (config.autoTrackPageview) {
+            this.pageview();
+        }
+    }
+    pageview(properties) {
+        this.leavePage(false);
+        const uv = this.isNewVisitor ? 1 : 0;
+        const attribution = collectAttribution();
+        const device = collectDevice();
+        this.sessionPageviewCount += 1;
+        // 关联离开事件
+        const pageviewId = crypto.randomUUID();
+        this.activePage = {
+            pageviewId,
+            path: location.pathname,
+            startedAt: performance.now(),
+        };
+        this.metrics.recordPageview(location.pathname, uv, attribution.source, device);
+        this.report({
+            kind: 'pageview',
+            event: '$pageview',
+            projectId: this.config.projectId,
+            distinctId: this.distinctId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            properties: {
+                ...properties,
+                pageviewId,
+                url: location.href,
+                path: location.pathname,
+                title: document.title,
+                referrer: document.referrer,
+                pv: 1,
+                uv,
+                visitCount: this.visitCount,
+                sessionPageviewCount: this.sessionPageviewCount,
+                attribution,
+                device,
+            },
+        }, true);
+        this.isNewVisitor = false;
+    }
+    pageleave(properties) {
+        this.leavePage(true, properties);
+    }
+    leavePage(sessionEnded, properties) {
+        if (!this.activePage) {
+            return;
+        }
+        const activePage = this.activePage;
+        const stayDurationMs = performance.now() - activePage.startedAt;
+        const bounced = sessionEnded && this.sessionPageviewCount === 1 && this.sessionConversionCount === 0;
+        this.activePage = undefined;
+        this.metrics.recordPageleave(activePage.path, stayDurationMs, bounced, sessionEnded);
+        this.report({
+            kind: 'pageleave',
+            event: '$pageleave',
+            projectId: this.config.projectId,
+            distinctId: this.distinctId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            properties: {
+                ...properties,
+                pageviewId: activePage.pageviewId,
+                path: activePage.path,
+                stayDurationMs,
+                bounced,
+                sessionEnded,
+                sessionPageviewCount: this.sessionPageviewCount,
+                sessionConversionCount: this.sessionConversionCount,
+            },
+        }, true);
+    }
+    capture(event, properties) {
+        this.report({
+            kind: 'capture',
+            event,
+            projectId: this.config.projectId,
+            distinctId: this.distinctId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            properties,
+        });
+    }
+    conversion(event, properties) {
+        this.sessionConversionCount += 1;
+        this.metrics.recordConversion();
+        this.report({
+            kind: 'conversion',
+            event,
+            projectId: this.config.projectId,
+            distinctId: this.distinctId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            properties,
+        }, true);
+    }
+    identify(userId, properties) {
+        this.report({
+            kind: 'identify',
+            event: '$identify',
+            projectId: this.config.projectId,
+            distinctId: this.distinctId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            properties: {
+                ...properties,
+                userId,
+            },
+        });
+    }
+    getMetrics() {
+        return this.metrics.snapshot();
+    }
+    report(event, includeMetrics = false) {
+        const metrics = includeMetrics ? this.metrics.snapshot() : undefined;
+        if (this.reporter.isEnabled()) {
+            void this.reporter.write(event);
+        }
+        logEvent(event);
+        if (metrics) {
+            logMetrics(metrics);
+        }
+    }
+}

package/dist/device.d.ts

@@ -0,0 +1,2 @@
+import type { We0Device } from './types.js';
+export declare function collectDevice(): We0Device;

package/dist/device.js

@@ -0,0 +1,21 @@
+export function collectDevice() {
+    const userAgent = navigator.userAgent;
+    return {
+        type: getDeviceType(userAgent),
+        userAgent,
+        language: navigator.language,
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight,
+        screenWidth: screen.width,
+        screenHeight: screen.height,
+    };
+}
+function getDeviceType(userAgent) {
+    if (/iPad|Tablet/.test(userAgent)) {
+        return 'tablet';
+    }
+    if (/Mobi|Android|iPhone/.test(userAgent)) {
+        return 'mobile';
+    }
+    return 'desktop';
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { We0Client } from './client.js';
+import type { We0Config } from './types.js';
+export type { We0Attribution, We0Config, We0Device, We0Event, We0EventKind, We0MetricsSnapshot, We0PageMetrics, } from './types.js';
+export { We0Client } from './client.js';
+export declare function init(config: We0Config): We0Client;

package/dist/index.js

@@ -0,0 +1,5 @@
+import { We0Client } from './client.js';
+export { We0Client } from './client.js';
+export function init(config) {
+    return new We0Client(config);
+}

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+import type { We0Event, We0MetricsSnapshot } from './types.js';
+export declare function logEvent(event: We0Event): void;
+export declare function logMetrics(metrics: We0MetricsSnapshot): void;
+export declare function logPersistenceSuccess(tableName: string, event: We0Event): void;
+export declare function logPersistenceWarning(message: string, details?: unknown): void;
+export declare function logError(error: unknown): void;

package/dist/logger.js

@@ -0,0 +1,26 @@
+const styles = {
+    pageview: 'color:#2563eb;font-weight:700',
+    pageleave: 'color:#0f766e;font-weight:700',
+    capture: 'color:#16a34a;font-weight:700',
+    identify: 'color:#9333ea;font-weight:700',
+    conversion: 'color:#c2410c;font-weight:700',
+};
+export function logEvent(event) {
+    console.log(`%c[we0:${event.kind}]`, styles[event.kind], event);
+}
+export function logMetrics(metrics) {
+    console.log('%c[we0:metrics]', 'color:#ea580c;font-weight:700', metrics);
+}
+export function logPersistenceSuccess(tableName, event) {
+    console.log('%c[we0:database:success]', 'color:#16a34a;font-weight:700', {
+        tableName,
+        kind: event.kind,
+        event: event.event,
+    });
+}
+export function logPersistenceWarning(message, details) {
+    console.warn('%c[we0:database:warning]', 'color:#f59e0b;font-weight:700', message, details);
+}
+export function logError(error) {
+    console.error('%c[we0:error]', 'color:#dc2626;font-weight:700', error);
+}

package/dist/metrics.d.ts

@@ -0,0 +1,21 @@
+import type { We0Device, We0MetricsSnapshot } from './types.js';
+export declare class MetricsStore {
+    private readonly visitCount;
+    private totalPv;
+    private totalUv;
+    private totalStayDurationMs;
+    private staySamples;
+    private bouncedSessions;
+    private endedSessions;
+    private conversionCount;
+    private readonly pages;
+    private readonly trafficSources;
+    private readonly devices;
+    private readonly seenPages;
+    constructor(visitCount: number);
+    recordPageview(path: string, uv: number, trafficSource: string, device: We0Device): void;
+    recordPageleave(path: string, stayDurationMs: number, bounced: boolean, sessionEnded: boolean): void;
+    recordConversion(): void;
+    snapshot(): We0MetricsSnapshot;
+    private getPage;
+}

package/dist/metrics.js

@@ -0,0 +1,81 @@
+export class MetricsStore {
+    visitCount;
+    totalPv = 0;
+    totalUv = 0;
+    totalStayDurationMs = 0;
+    staySamples = 0;
+    bouncedSessions = 0;
+    endedSessions = 0;
+    conversionCount = 0;
+    pages = {};
+    trafficSources = {};
+    devices = {};
+    seenPages = new Set();
+    constructor(visitCount) {
+        this.visitCount = visitCount;
+    }
+    recordPageview(path, uv, trafficSource, device) {
+        this.totalPv += 1;
+        this.totalUv += uv;
+        const page = this.getPage(path);
+        const pageUv = this.seenPages.has(path) ? 0 : 1;
+        this.seenPages.add(path);
+        page.pv += 1;
+        page.uv += pageUv;
+        this.trafficSources[trafficSource] = (this.trafficSources[trafficSource] ?? 0) + 1;
+        this.devices[device.type] = (this.devices[device.type] ?? 0) + 1;
+    }
+    recordPageleave(path, stayDurationMs, bounced, sessionEnded) {
+        this.totalStayDurationMs += stayDurationMs;
+        this.staySamples += 1;
+        const page = this.getPage(path);
+        page.stayDurationMs += stayDurationMs;
+        page.staySamples += 1;
+        if (sessionEnded) {
+            this.endedSessions += 1;
+            page.exits += 1;
+            if (bounced) {
+                this.bouncedSessions += 1;
+                page.bounces += 1;
+            }
+        }
+    }
+    recordConversion() {
+        this.conversionCount += 1;
+    }
+    snapshot() {
+        const pages = {};
+        for (const path of Object.keys(this.pages)) {
+            const page = this.pages[path];
+            pages[path] = {
+                pv: page.pv,
+                uv: page.uv,
+                stayDurationMs: page.stayDurationMs,
+                averageStayDurationMs: page.staySamples ? page.stayDurationMs / page.staySamples : 0,
+                bounceRate: page.exits ? page.bounces / page.exits : 0,
+            };
+        }
+        return {
+            totalPv: this.totalPv,
+            totalUv: this.totalUv,
+            visitCount: this.visitCount,
+            averageStayDurationMs: this.staySamples ? this.totalStayDurationMs / this.staySamples : 0,
+            bounceRate: this.endedSessions ? this.bouncedSessions / this.endedSessions : 0,
+            conversionCount: this.conversionCount,
+            pages,
+            trafficSources: this.trafficSources,
+            devices: this.devices,
+        };
+    }
+    getPage(path) {
+        this.pages[path] ??= {
+            pv: 0,
+            uv: 0,
+            stayDurationMs: 0,
+            staySamples: 0,
+            bounces: 0,
+            exits: 0,
+        };
+        return this.pages[path];
+    }
+}

package/dist/supabase-reporter.d.ts

@@ -0,0 +1,9 @@
+import type { We0Config, We0Event } from './types.js';
+export declare class SupabaseReporter {
+    private readonly config?;
+    constructor(config: We0Config);
+    isEnabled(): boolean;
+    write(event: We0Event): Promise<void>;
+    private insert;
+    private updatePageview;
+}

package/dist/supabase-reporter.js

@@ -0,0 +1,164 @@
+import { logPersistenceSuccess, logPersistenceWarning } from './logger.js';
+function readRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+// 拼接表名
+function tableName(projectId, name) {
+    return `${projectId}____${name}`;
+}
+function endpoint(config, table) {
+    return `${config.url.replace(/\/$/, '')}/rest/v1/${encodeURIComponent(table)}`;
+}
+function headers(config) {
+    return {
+        apikey: config.anonKey,
+        Authorization: `Bearer ${config.anonKey}`,
+        'Content-Type': 'application/json',
+        Prefer: 'return=minimal',
+    };
+}
+// 解析配置
+function createConfig(config) {
+    if (!config.supabaseUrl && !config.supabaseAnonKey) {
+        return undefined;
+    }
+    if (!config.projectId) {
+        logPersistenceWarning('PROJECT_ID 未配置');
+        return undefined;
+    }
+    if (!config.supabaseUrl || !config.supabaseAnonKey) {
+        logPersistenceWarning('Supabase 配置未完整');
+        return undefined;
+    }
+    return {
+        projectId: config.projectId,
+        url: config.supabaseUrl,
+        anonKey: config.supabaseAnonKey,
+    };
+}
+// 检查写入
+async function checkResponse(response, table) {
+    if (response.ok) {
+        return true;
+    }
+    const body = await response.text();
+    const message = body || response.statusText;
+    if (response.status === 404 || message.includes('Could not find the table')) {
+        logPersistenceWarning('Supabase 表未建表', { tableName: table, status: response.status, body });
+        return false;
+    }
+    else if (response.status === 401 || response.status === 403) {
+        logPersistenceWarning('Supabase 写入权限不足', { tableName: table, status: response.status, body });
+        return false;
+    }
+    throw new Error(`Failed to write ${table}: ${message}`);
+}
+// 页面行
+function pageviewRow(event) {
+    const properties = readRecord(event.properties);
+    const attribution = readRecord(properties.attribution);
+    const device = readRecord(properties.device);
+    return {
+        id: properties.pageviewId,
+        viewed_at: event.timestamp,
+        project_id: event.projectId,
+        distinct_id: event.distinctId,
+        session_id: event.sessionId,
+        path: properties.path,
+        title: properties.title,
+        uv: properties.uv,
+        visit_count: properties.visitCount,
+        session_pageview_count: properties.sessionPageviewCount,
+        attribution_type: attribution.type,
+        traffic_source: attribution.source,
+        traffic_medium: attribution.medium,
+        traffic_campaign: attribution.campaign,
+        traffic_content: attribution.content,
+        traffic_term: attribution.term,
+        referrer_host: attribution.referrerHost,
+        device_type: device.type,
+        browser_language: device.language,
+        viewport_width: device.viewportWidth,
+        viewport_height: device.viewportHeight,
+        screen_width: device.screenWidth,
+        screen_height: device.screenHeight,
+    };
+}
+// 离开行
+function pageleaveRow(event) {
+    const properties = readRecord(event.properties);
+    return {
+        left_at: event.timestamp,
+        stay_duration_ms: Math.round(Number(properties.stayDurationMs)),
+        bounced: properties.bounced,
+        session_ended: properties.sessionEnded,
+        session_pageview_count: properties.sessionPageviewCount,
+        session_conversion_count: properties.sessionConversionCount,
+    };
+}
+// 事件行
+function eventRow(event) {
+    const properties = readRecord(event.properties);
+    return {
+        id: crypto.randomUUID(),
+        event_at: event.timestamp,
+        project_id: event.projectId,
+        kind: event.kind,
+        event_name: event.event,
+        distinct_id: event.distinctId,
+        session_id: event.sessionId,
+        user_id: properties.userId,
+        properties,
+    };
+}
+export class SupabaseReporter {
+    config;
+    constructor(config) {
+        this.config = createConfig(config);
+    }
+    isEnabled() {
+        return Boolean(this.config);
+    }
+    async write(event) {
+        if (!this.config) {
+            return;
+        }
+        if (event.kind === 'pageview') {
+            await this.insert(this.config, tableName(this.config.projectId, 'we0_pageviews'), pageviewRow(event), event);
+            return;
+        }
+        if (event.kind === 'pageleave') {
+            await this.updatePageview(this.config, event);
+            return;
+        }
+        await this.insert(this.config, tableName(this.config.projectId, 'we0_events'), eventRow(event), event);
+    }
+    async insert(config, table, row, event) {
+        const response = await fetch(endpoint(config, table), {
+            method: 'POST',
+            headers: headers(config),
+            keepalive: true,
+            body: JSON.stringify(row),
+        });
+        if (await checkResponse(response, table)) {
+            logPersistenceSuccess(table, event);
+        }
+    }
+    async updatePageview(config, event) {
+        const properties = readRecord(event.properties);
+        const table = tableName(config.projectId, 'we0_pageviews');
+        const pageviewId = String(properties.pageviewId);
+        const response = await fetch(`${endpoint(config, table)}?id=eq.${encodeURIComponent(pageviewId)}`, {
+            method: 'PATCH',
+            headers: headers(config),
+            keepalive: true,
+            body: JSON.stringify(pageleaveRow(event)),
+        });
+        if (await checkResponse(response, table)) {
+            logPersistenceSuccess(table, event);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type We0Config = {
+    projectId: string;
+    autoTrackPageview: boolean;
+    supabaseUrl?: string;
+    supabaseAnonKey?: string;
+};
+export type We0EventKind = 'pageview' | 'pageleave' | 'capture' | 'identify' | 'conversion';
+export type We0Attribution = {
+    type: 'utm' | 'referrer' | 'direct';
+    source: string;
+    medium: string;
+    campaign: string;
+    content: string;
+    term: string;
+    referrer: string;
+    referrerHost: string;
+};
+export type We0Device = {
+    type: 'desktop' | 'tablet' | 'mobile';
+    userAgent: string;
+    language: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+};
+export type We0Event = {
+    kind: We0EventKind;
+    event: string;
+    projectId: string;
+    distinctId: string;
+    sessionId: string;
+    timestamp: string;
+    properties?: Record<string, unknown>;
+};
+export type We0PageMetrics = {
+    pv: number;
+    uv: number;
+    stayDurationMs: number;
+    averageStayDurationMs: number;
+    bounceRate: number;
+};
+export type We0MetricsSnapshot = {
+    totalPv: number;
+    totalUv: number;
+    visitCount: number;
+    averageStayDurationMs: number;
+    bounceRate: number;
+    conversionCount: number;
+    pages: Record<string, We0PageMetrics>;
+    trafficSources: Record<string, number>;
+    devices: Record<string, number>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/visitor.d.ts

@@ -0,0 +1,11 @@
+export type Visitor = {
+    distinctId: string;
+    isNew: boolean;
+};
+export type VisitSession = {
+    sessionId: string;
+    isNew: boolean;
+    visitCount: number;
+};
+export declare function resolveVisitor(): Visitor;
+export declare function resolveSession(): VisitSession;