we0-analyze-sdk 0.1.0

package/docs/supabase-persistence.md

@@ -0,0 +1,193 @@
+# Supabase 持久化方案
+
+## 目标
+
+SDK 在浏览器采集事件，并使用宿主应用显式传入的 Supabase anon key 直接写入用户自己的 Supabase 项目。SDK 不建表，不读取宿主 `.env`，建表 SQL 由后端或迁移流程在合适时机执行。
+
+建表 SQL 见 [`supabase-schema.sql`](./supabase-schema.sql)。
+
+## 初始化
+
+宿主应用把环境变量读出来，再显式传给 SDK：
+
+```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!,
+})
+```
+
+SDK 不使用 `SUPABASE_SERVICE_ROLE_KEY`。service role key 只应留在宿主后端或迁移流程里。
+
+## 表设计
+
+表名由 `projectId` 决定：
+
+```text
+{PROJECT_ID}____we0_pageviews
+{PROJECT_ID}____we0_events
+```
+
+推荐保留两张表：
+
+- `$pageview`：插入 `{PROJECT_ID}____we0_pageviews`，一条 PV 一行。
+- `$pageleave`：更新同一条 `{PROJECT_ID}____we0_pageviews`，不新增行。
+- `capture`、`conversion`、`$identify`：插入 `{PROJECT_ID}____we0_events`。
+- 页面统计从 pageviews 表聚合。
+- 业务事件统计从 events 表聚合。
+
+这个方案把基础场景的行数从 `daily_pv * 2` 降到约 `daily_pv * 1`。页面表不保存完整 `properties jsonb`、完整 `url`、完整 `referrer` 和完整 `userAgent`，避免重复存大字段。
+
+## 写入行为
+
+SDK 侧行为：
+
+- 未配置 Supabase 时，只输出彩色 console 日志。
+- 配置 Supabase 后，所有事件都会尝试写入对应项目表。
+- 每次 `$pageview` 会生成 `pageviewId`，对应 `$pageleave` 复用同一个 `pageviewId`。
+- 写库成功会输出绿色 console。
+- 缺少 `PROJECT_ID`、Supabase 配置不完整、表未创建或权限不足时会输出橘色 console。
+- `metrics` 只用于本地调试，不写入数据库。
+
+SDK 不做建表、队列、重试、fallback 或聚合。
+
+## SQL 变量说明
+
+普通 SQL 参数不能直接替代表名这类 identifier。`supabase-schema.sql` 使用 PL/pgSQL：
+
+```sql
+do $$
+declare
+  project_id text := 'YOUR_PROJECT_ID';
+  pageviews_table text := project_id || '____we0_pageviews';
+  events_table text := project_id || '____we0_events';
+begin
+  execute format('create table if not exists public.%I (...)', pageviews_table);
+end $$;
+```
+
+执行前只需要替换 `project_id` 的值。
+
+## 字段映射
+
+`$pageview` 插入 pageviews 表：
+
+| 表字段 | 来源 |
+| --- | --- |
+| `id` | `event.properties.pageviewId` |
+| `viewed_at` | `event.timestamp` |
+| `project_id` | `event.projectId` |
+| `distinct_id` | `event.distinctId` |
+| `session_id` | `event.sessionId` |
+| `path` | `event.properties.path` |
+| `title` | `event.properties.title` |
+| `uv` | `event.properties.uv` |
+| `visit_count` | `event.properties.visitCount` |
+| `session_pageview_count` | `event.properties.sessionPageviewCount` |
+| attribution 字段 | `event.properties.attribution` |
+| device 字段 | `event.properties.device` |
+
+`$pageleave` 更新 pageviews 表：
+
+| 表字段 | 来源 |
+| --- | --- |
+| `left_at` | `event.timestamp` |
+| `stay_duration_ms` | `round(event.properties.stayDurationMs)` |
+| `bounced` | `event.properties.bounced` |
+| `session_ended` | `event.properties.sessionEnded` |
+| `session_pageview_count` | `event.properties.sessionPageviewCount` |
+| `session_conversion_count` | `event.properties.sessionConversionCount` |
+
+`capture`、`conversion`、`$identify` 插入 events 表：
+
+| 表字段 | 来源 |
+| --- | --- |
+| `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` | `event.properties.userId`，仅 `$identify` 使用 |
+| `properties` | `event.properties` |
+
+## 表数据量估算
+
+基础场景里没有自定义事件、转化事件和 identify：
+
+```text
+daily_rows ~= daily_pv
+```
+
+如果平均每个 PV 还会触发 `n` 个自定义事件：
+
+```text
+daily_rows ~= daily_pv * (1 + n) + daily_conversion_events + daily_identify_events
+```
+
+页面表先按每行 `1 KB` 到 `2 KB` 估算；默认用 `1.5 KB` 每行做预算。
+
+| 日 PV | 页面表 30 天行数 | 页面表 30 天存储 |
+| --- | ---: | ---: |
+| `1,000` | `~30,000` | `~45 MB` |
+| `10,000` | `~300,000` | `~450 MB` |
+| `50,000` | `~1,500,000` | `~2.25 GB` |
+| `100,000` | `~3,000,000` | `~4.5 GB` |
+| `1,000,000` | `~30,000,000` | `~45 GB` |
+
+上线后用真实表校准平均行大小：
+
+```sql
+select
+  count(*) as rows,
+  pg_size_pretty(pg_total_relation_size('public.YOUR_PROJECT_ID____we0_pageviews')) as total_size,
+  pg_total_relation_size('public.YOUR_PROJECT_ID____we0_pageviews') / nullif(count(*), 0) as bytes_per_row
+from public.YOUR_PROJECT_ID____we0_pageviews;
+```
+
+`pg_total_relation_size` 包含表、索引和 toast 数据，更适合做 Supabase 容量预算。
+
+## 常用统计 SQL
+
+PV：
+
+```sql
+select count(*) as pv
+from public.YOUR_PROJECT_ID____we0_pageviews
+where viewed_at >= $1
+  and viewed_at < $2;
+```
+
+UV：
+
+```sql
+select count(distinct distinct_id) as uv
+from public.YOUR_PROJECT_ID____we0_pageviews
+where viewed_at >= $1
+  and viewed_at < $2;
+```
+
+平均停留时长：
+
+```sql
+select avg(stay_duration_ms) as average_stay_duration_ms
+from public.YOUR_PROJECT_ID____we0_pageviews
+where viewed_at >= $1
+  and viewed_at < $2
+  and stay_duration_ms is not null;
+```
+
+事件数：
+
+```sql
+select event_name, count(*) as count
+from public.YOUR_PROJECT_ID____we0_events
+where event_at >= $1
+  and event_at < $2
+group by event_name
+order by count desc;
+```

package/docs/supabase-schema.sql

@@ -0,0 +1,115 @@
+-- Replace this value before running the SQL.
+do $$
+declare
+  project_id text := '619063b3-5f46-4bbc-9c28-1c6ad5852b4e';
+  placeholder_project_id text := 'YOUR_' || 'PROJECT_ID';
+  pageviews_table text := project_id || '____we0_pageviews';
+  events_table text := project_id || '____we0_events';
+begin
+  if project_id = placeholder_project_id or length(trim(project_id)) = 0 then
+    raise exception 'Set project_id before running we0 schema SQL';
+  end if;
+
+  execute format(
+    'create table if not exists public.%I (
+      id uuid primary key,
+      received_at timestamptz not null default now(),
+      viewed_at timestamptz not null,
+      left_at timestamptz,
+
+      project_id text not null,
+      distinct_id text not null,
+      session_id text not null,
+
+      path text not null,
+      title text,
+
+      pv smallint not null default 1 check (pv = 1),
+      uv smallint not null default 0 check (uv in (0, 1)),
+      visit_count integer check (visit_count is null or visit_count >= 0),
+      session_pageview_count integer check (
+        session_pageview_count is null or session_pageview_count >= 0
+      ),
+      session_conversion_count integer check (
+        session_conversion_count is null or session_conversion_count >= 0
+      ),
+
+      stay_duration_ms integer check (
+        stay_duration_ms is null or stay_duration_ms >= 0
+      ),
+      bounced boolean,
+      session_ended boolean,
+
+      attribution_type text check (
+        attribution_type is null or attribution_type in (''utm'', ''referrer'', ''direct'')
+      ),
+      traffic_source text,
+      traffic_medium text,
+      traffic_campaign text,
+      traffic_content text,
+      traffic_term text,
+      referrer_host text,
+
+      device_type text check (
+        device_type is null or device_type in (''desktop'', ''tablet'', ''mobile'')
+      ),
+      browser_language text,
+      viewport_width integer check (viewport_width is null or viewport_width >= 0),
+      viewport_height integer check (viewport_height is null or viewport_height >= 0),
+      screen_width integer check (screen_width is null or screen_width >= 0),
+      screen_height integer check (screen_height is null or screen_height >= 0)
+    )',
+    pageviews_table
+  );
+
+  execute format(
+    'create table if not exists public.%I (
+      id uuid primary key,
+      received_at timestamptz not null default now(),
+      event_at timestamptz not null,
+
+      project_id text not null,
+      kind text not null check (
+        kind in (''capture'', ''identify'', ''conversion'')
+      ),
+      event_name text not null,
+      distinct_id text not null,
+      session_id text not null,
+      user_id text,
+
+      properties jsonb not null default ''{}''::jsonb
+    )',
+    events_table
+  );
+
+  execute format('alter table public.%I enable row level security', pageviews_table);
+  execute format('alter table public.%I enable row level security', events_table);
+
+  execute format('grant insert, update on table public.%I to anon', pageviews_table);
+  execute format('grant insert on table public.%I to anon', events_table);
+
+  execute format('drop policy if exists we0_pageviews_anon_insert on public.%I', pageviews_table);
+  execute format(
+    'create policy we0_pageviews_anon_insert on public.%I
+     for insert to anon
+     with check (true)',
+    pageviews_table
+  );
+
+  execute format('drop policy if exists we0_pageviews_anon_update on public.%I', pageviews_table);
+  execute format(
+    'create policy we0_pageviews_anon_update on public.%I
+     for update to anon
+     using (true)
+     with check (true)',
+    pageviews_table
+  );
+
+  execute format('drop policy if exists we0_events_anon_insert on public.%I', events_table);
+  execute format(
+    'create policy we0_events_anon_insert on public.%I
+     for insert to anon
+     with check (true)',
+    events_table
+  );
+end $$;

package/docs/supabase-test.sql

@@ -0,0 +1,15 @@
+-- SQL Editor smoke test.
+select now() as sql_editor_ok;
+
+-- 临时测试
+create temp table we0_sql_editor_test (
+  id integer primary key,
+  note text not null,
+  created_at timestamptz not null default now()
+);
+
+insert into we0_sql_editor_test (id, note)
+values (1, 'ok');
+
+select *
+from we0_sql_editor_test;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "we0-analyze-sdk",
+  "version": "0.1.0",
+  "description": "Minimal browser analytics SDK for pageview, PV, and UV tracking.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Minf97/we0-analyze-sdk.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
+}