Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

fix(sdk): automatic click events carry their page again (#584)

Carl-Gerhard Lindesvärdd45de45af0c0
diff --git a/.claude/skills/sdk-testbed/SKILL.md b/.claude/skills/sdk-testbed/SKILL.md
new file mode 100644
index 000000000..b3776e65a
--- /dev/null
+++ b/.claude/skills/sdk-testbed/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: sdk-testbed
+description: Verify a change to the JavaScript SDKs (packages/sdks/sdk, packages/sdks/web and the wrappers built on them) the way a customer site would hit it - drive apps/testbed in a real browser against your local API and check the rows that land in ClickHouse. Use after any SDK change, when the user says "test the sdk", "run the testbed", or asks whether an event is tracked and stored correctly.
+allowed-tools: Bash, Read, Edit, Write, Grep, Glob
+---
+
+# SDK testbed
+
+`apps/testbed` is a small React shop (`TESTSTORE`) that uses `@openpanel/web`
+exactly like a customer site: screen views, custom `track()` calls, identify,
+groups, revenue, plus a footer with a `data-track` button and an outgoing link
+for the automatic trackers. Vite resolves `@openpanel/web` from the package
+*source*, so an SDK edit is live on the next reload; nothing has to be built.
+
+Unit tests (`bun run --filter @openpanel/web test`) prove what the SDK *sends*.
+This skill proves what gets *stored*: browser → `POST /track` → Kafka → worker →
+ClickHouse `events`, with `path`, `origin`, properties and session as the
+dashboard will show them.
+
+## 1. Preflight
+
+- **The API must be running with the worker role** (`ROLE=all`). In a
+ worktree it is supervised (`WORKTREE.md`); if the supervisor is gone, start it
+ yourself and keep the log:
+ `bun run --filter @openpanel/api dev > /tmp/api.log 2>&1 &` then wait for
+ `"Boot complete"` in the log. Confirm with `curl -s -o /dev/null -w '%{http_code}' $API_URL_SSR/track`
+ (any HTTP answer means it is up).
+- **A seeded client.** `.seed.json` (repo root) lists the projects; the config
+ picks the `website` one (Acme Web, CORS `*`), which accepts the testbed's
+ `http://localhost:<port>` origin. No `.seed.json` → `bun run seed`.
+- **A port.** The testbed listens on `TESTBED_PORT`, defaulting to `WEB_PORT + 9`
+ in a worktree and `3100` otherwise. Override it if that port is taken.
+- Do not reseed, migrate or restart processes from a sub-agent; only the main
+ agent does that, before anything else runs.
+
+Everything is read from the shell env (`API_URL_SSR`/`API_URL`, `CLICKHOUSE_URL`,
+`WEB_PORT`) and `.seed.json`; the config in `apps/testbed/playwright.config.ts`
+is the single place that turns them into `VITE_OPENPANEL_API_URL`,
+`VITE_OPENPANEL_CLIENT_ID` and the port.
+
+## 2. Run the journey
+
+```bash
+bun run --filter @openpanel/testbed e2e
+```
+
+`apps/testbed/e2e/sdk.spec.ts` starts the testbed (or reuses one already up),
+clicks through shop → product → data-track button → outgoing link, then polls
+ClickHouse until the rows exist and asserts their `path` and properties. A
+missing row fails with the list of what *was* stored, which is usually the
+whole diagnosis. The trace for a failed run is under
+`apps/testbed/test-results/`.
+
+When your change adds behaviour the journey does not cover (a new option, a
+new automatic tracker, a payload shape), extend the spec: add the fixture to
+`apps/testbed/src` (the footer in `App.tsx` is for the automatic trackers), the
+click to the spec, and the assertion on the stored row. The spec is the
+regression test for the next person.
+
+## 3. Look yourself
+
+For anything the spec does not say, start the testbed and read ClickHouse
+directly. Filter on `origin`, which is the testbed URL, so seeded and other
+traffic stay out of the way:
+
+```bash
+# Same default as playwright.config.ts: WEB_PORT + 9 in a worktree, 3100 elsewhere.
+port=${TESTBED_PORT:-$(( ${WEB_PORT:-3091} + 9 ))}
+TESTBED_PORT=$port VITE_OPENPANEL_API_URL=${API_URL_SSR:-http://localhost:3333} \
+VITE_OPENPANEL_CLIENT_ID=<website clientId from .seed.json> \
+bun run --filter @openpanel/testbed dev > /tmp/testbed.log 2>&1 &
+
+curl -s "${CLICKHOUSE_URL%/*}/?database=${CLICKHOUSE_URL##*/}" --data-binary "
+ SELECT name, path, properties, session_id, toString(created_at) AS at
+ FROM events
+ WHERE origin = 'http://localhost:$port'
+ ORDER BY created_at DESC LIMIT 20
+ FORMAT PrettyCompactMonoBlock"
+```
+
+Use the browser with the Playwright MCP (`browser_*` tools) if you have one,
+otherwise a throwaway spec next to `sdk.spec.ts`. Watch `/tmp/api.log` while
+clicking: a refused request (`Ingestion: ...`) or a bot verdict is logged there,
+not in the browser. `sessions` and `profiles` are the other tables to read
+when the change touches identify, groups or session handling.
+
+## What trips people up
+
+- **Events before `ready()` are queued, not lost.** The testbed constructs the
+ SDK with `disabled: true` and calls `op.ready()` after restoring the login,
+ so the first screen view arrives slightly after page load.
+- **`path`/`origin` come from `__path`.** An event without `__path` is stored
+ with empty `path` *and* empty `origin`, so it will not match the origin
+ filter above. "No rows at all" for an event that reached the API usually
+ means the page was missing, not the event.
+- **Revenue needs a verified client secret** or the project's
+ `allowUnsafeRevenueTracking`; the whole request is refused otherwise. The
+ seeded web client has no secret in the browser, so `op.revenue()` from the
+ testbed is refused by design.
+- **Identical requests within 100 ms are dropped** as the web SDK's known
+ double-fire. Two different clicks are fine; a loop firing the same payload is
+ not.
+- **Latency.** Rows take a few seconds to show up (Kafka, the worker, the
+ buffer). Poll with a deadline; never assert right after the click.
+- **`op1.js` (the script tag build) is not what the testbed runs.** It uses the
+ npm entry. To check the IIFE, `bun run --filter @openpanel/web build` and load
+ `packages/sdks/web/dist/src/tracker.global.js` in a page yourself.
+
+## Report
+
+Say what the spec covered, paste the stored rows (names, paths, the properties
+that matter) and name anything you could not drive through the testbed.
diff --git a/.github/workflows/sdks.yml b/.github/workflows/sdks.yml
new file mode 100644
index 000000000..0188d5978
--- /dev/null
+++ b/.github/workflows/sdks.yml
@@ -0,0 +1,181 @@
+name: SDKs
+
+# The SDKs ship to npm, not in the Docker images, so docker-build.yml ignores
+# packages/sdks entirely. This workflow is their pipeline:
+# verify every push that touches an SDK typechecks, tests and builds all
+# of them through the real release script (dry run, nothing
+# published), so a broken build is caught before release day.
+# publish a manual run on main releases one SDK and its dependents to npm
+# with tooling/publish, then commits the bumped `-local` versions
+# and the new op1.js back to main. npm trusts this workflow file
+# (trusted publishing, no token). `mode: stage` instead parks the
+# versions for a maintainer's `npm stage approve <stage-id>` + 2FA.
+on:
+ push:
+ branches:
+ - "**"
+ paths:
+ - "packages/sdks/**"
+ - "tooling/publish/**"
+ - ".github/workflows/sdks.yml"
+ workflow_dispatch:
+ inputs:
+ package:
+ description: SDK to release (its dependents are released with it)
+ type: choice
+ required: true
+ options:
+ - "@openpanel/sdk"
+ - "@openpanel/web"
+ - "@openpanel/nextjs"
+ - "@openpanel/astro"
+ - "@openpanel/nuxt"
+ - "@openpanel/express"
+ - "@openpanel/react-native"
+ type:
+ description: Version bump
+ type: choice
+ required: true
+ default: patch
+ options:
+ - patch
+ - minor
+ - major
+ - prerelease
+ mode:
+ description: Publish directly, or stage for a maintainer's 2FA approval
+ type: choice
+ required: true
+ default: publish
+ options:
+ - publish
+ - stage
+
+permissions:
+ contents: read
+
+# Pushes to one ref supersede each other; releases never get cancelled and
+# run one at a time, in their own group, so a push to main during a release
+# cannot stop it between the npm publish and the version commit.
+concurrency:
+ group: ${{ github.event_name == 'workflow_dispatch' && 'sdks-release' || format('sdks-{0}', github.ref) }}
+ cancel-in-progress: ${{ github.event_name == 'push' }}
+
+jobs:
+ verify:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: ./.github/actions/setup
+
+ - name: Typecheck the SDKs
+ run: bun run --filter './packages/sdks/*' typecheck
+
+ - name: Test the SDKs
+ run: bun run --filter @openpanel/web test
+
+ # Releasing @openpanel/sdk takes every other SDK with it, so this one
+ # dry run builds all of them exactly as a release would. The version
+ # edits it makes are thrown away with the runner.
+ - name: Build every SDK through the release script
+ run: bun tooling/publish/publish.ts --name @openpanel/sdk --type patch --skip-git
+
+ - name: Check what each package would publish
+ run: |
+ set -euo pipefail
+ for dir in packages/sdks/*/; do
+ if [ "$(jq -r '.private // false' "$dir/package.json")" = "true" ]; then
+ continue
+ fi
+ echo "::group::$dir"
+ (cd "$dir" && npm pack --dry-run)
+ echo "::endgroup::"
+ done
+
+ publish:
+ if: github.event_name == 'workflow_dispatch'
+ needs: verify
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ permissions:
+ contents: write
+ # GitHub mints the OIDC token npm exchanges for publish rights.
+ id-token: write
+ steps:
+ - name: Releases come from main only
+ if: github.ref != 'refs/heads/main'
+ env:
+ BRANCH: ${{ github.ref_name }}
+ run: |
+ echo "::error::Run this workflow on main; $BRANCH is not released."
+ exit 1
+
+ # Full history: the release commit is rebased onto main before the push.
+ - uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
+
+ - uses: ./.github/actions/setup
+
+ # Trusted publishing needs npm 11.5; staging needs 11.15. Node's bundled
+ # npm lags both.
+ - name: Update npm
+ run: npm install -g npm@latest && npm --version
+
+ - name: ${{ inputs.mode == 'stage' && 'Stage' || 'Publish' }} ${{ inputs.package }} (${{ inputs.type }})
+ env:
+ PACKAGE: ${{ inputs.package }}
+ BUMP: ${{ inputs.type }}
+ STAGE_FLAG: ${{ inputs.mode == 'stage' && '--stage' || '' }}
+ run: bun tooling/publish/publish.ts --name "$PACKAGE" --type "$BUMP" --publish --npm --skip-git $STAGE_FLAG
+
+ - name: How to approve
+ if: inputs.mode == 'stage'
+ run: |
+ echo "::notice::The versions are staged, not public. A maintainer approves each with 2FA: npm stage list <package>, then npm stage approve <stage-id> (npm 11.15+)."
+
+ # The script leaves the released packages at `<version>-local` and, for
+ # @openpanel/web, the new tracker in apps/public/public. That is the
+ # state main has to carry so the next release bumps from here. A staged
+ # version that is later rejected simply leaves a gap in the numbering.
+ - name: Commit the released versions
+ env:
+ PACKAGE: ${{ inputs.package }}
+ BUMP: ${{ inputs.type }}
+ run: |
+ set -euo pipefail
+ dir="$(bun -e 'const fs = require("fs"); for (const d of fs.readdirSync("packages/sdks")) { const p = `packages/sdks/${d}/package.json`; if (fs.existsSync(p) && require(`./${p}`).name === process.argv[1]) console.log(d) }' "$PACKAGE")"
+ version="$(jq -r '.version | sub("-local$"; "")' "packages/sdks/$dir/package.json")"
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git add packages/sdks apps/public/public/op1.js apps/public/public/op1-replay.js
+ git commit -m "chore(sdk): release $PACKAGE $version" \
+ -m "Released from the SDKs workflow ($BUMP bump). Dependent SDKs were released with it; see the package versions in this commit."
+ git format-patch -1 --stdout > /tmp/sdk-release.patch
+ echo "RELEASE_TAG=$PACKAGE@$version" >> "$GITHUB_ENV"
+ echo "Released $PACKAGE $version"
+
+ # The packages are on npm by now, so this commit must land whatever
+ # happened on main meanwhile: rebase onto the current tip, never force.
+ - name: Push the release commit to main
+ run: |
+ set -euo pipefail
+ git fetch origin main
+ if ! git rebase origin/main; then
+ echo "::error::main moved during the release and the version commit conflicts with it. The packages are published; apply the sdk-release-commit artifact to main by hand."
+ exit 1
+ fi
+ git tag "$RELEASE_TAG"
+ git push --atomic origin HEAD:main "refs/tags/$RELEASE_TAG"
+
+ - name: Keep the release commit if it could not be pushed
+ if: failure()
+ uses: actions/upload-artifact@v7
+ with:
+ name: sdk-release-commit
+ path: /tmp/sdk-release.patch
+ if-no-files-found: ignore
diff --git a/AGENTS.md b/AGENTS.md
index f02ca1354..f0eb05f97 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,6 +80,7 @@ a one-line fix does not need the full suite, a query or ingest change always doe
| tRPC procedure / REST route (`packages/core`) | Call it (recipes below) with seeded ids and check the JSON; for auth changes, try the wrong role too | `bun test --isolate` in `packages/core` for that module |
| ClickHouse query / chart / overview | Run old and new against the seeded data and diff results; check the numbers on the dashboard match a manual query | `packages/core` tests for the module; `bun run --filter @openpanel/db test` if you touched `packages/db` |
| Ingest / worker / buffers / sessions | `bun run send journey --project acme-shop` (live events through Kafka → worker → ClickHouse), then query `events`/`sessions`/`profiles` for that session id | `packages/core` ingest + buffer tests, `apps/api/e2e/` for session lifecycle |
+| SDK (`packages/sdks/*`) | `/sdk-testbed`: drive `apps/testbed` in a real browser against *your* API and read the rows in ClickHouse (`bun run --filter @openpanel/testbed e2e`); extend the spec for new behaviour | `bun run --filter @openpanel/web test`, `bun run --filter "./packages/sdks/*" typecheck`; a release goes through the SDKs workflow (`.github/workflows/sdks.yml`) |
| MCP tools (`packages/core/src/modules/mcp`) | Call the product's MCP against *your* API and data: as the `openpanel` MCP server if one is configured for you, else over HTTP (`.seed.json` → `mcp.url`, recipe below); compare its answer with a direct query | `packages/core` mcp tests |
| Schema / migration | `bun run --filter @openpanel/db migrate:deploy` on your isolated database, then `bun run seed --reset` and the seed tests (`bun run --filter @openpanel/seed test`) | `bun run typecheck` |
| Anything shared (`packages/shared`, `packages/db`, config, deps) | — | `bun run typecheck` and `bun run test` in full |
diff --git a/apps/testbed/.gitignore b/apps/testbed/.gitignore
index f2770ead3..1a263f84b 100644
--- a/apps/testbed/.gitignore
+++ b/apps/testbed/.gitignore
@@ -2,3 +2,5 @@ node_modules
dist
public/op1.js
.env
+test-results
+playwright-report
diff --git a/apps/testbed/e2e/clickhouse.ts b/apps/testbed/e2e/clickhouse.ts
new file mode 100644
index 000000000..f01fbfa65
--- /dev/null
+++ b/apps/testbed/e2e/clickhouse.ts
@@ -0,0 +1,87 @@
+// Reads the events the testbed produced straight from ClickHouse over HTTP,
+// so the spec asserts what was stored, not what the browser sent.
+
+const DEFAULT_CLICKHOUSE_URL = 'http://localhost:8123/openpanel';
+const POLL_INTERVAL_MS = 1000;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export type StoredEvent = {
+ name: string;
+ path: string;
+ origin: string;
+ properties: Record<string, string>;
+ stored_at: string;
+};
+
+function clickhouseEndpoint() {
+ const url = new URL(process.env.CLICKHOUSE_URL ?? DEFAULT_CLICKHOUSE_URL);
+ const database = url.pathname.replace(/^\//, '');
+ const headers: Record<string, string> = {};
+ if (url.username) {
+ const credentials = Buffer.from(
+ `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`
+ ).toString('base64');
+ headers.authorization = `Basic ${credentials}`;
+ }
+ url.username = '';
+ url.password = '';
+ url.pathname = '/';
+ if (database) {
+ url.searchParams.set('database', database);
+ }
+ return { url, headers };
+}
+
+export async function query<Row>(sql: string): Promise<Row[]> {
+ const { url, headers } = clickhouseEndpoint();
+ const response = await fetch(url, {
+ method: 'POST',
+ headers,
+ body: `${sql} FORMAT JSONEachRow`,
+ });
+ const text = await response.text();
+ if (!response.ok) {
+ throw new Error(`ClickHouse ${response.status}: ${text}`);
+ }
+ return text
+ .split('\n')
+ .filter((line) => line.length > 0)
+ .map((line) => JSON.parse(line) as Row);
+}
+
+function toClickhouseDateTime(date: Date) {
+ return date.toISOString().replace('T', ' ').replace('Z', '');
+}
+
+export function eventsSince(origin: string, since: Date) {
+ return query<StoredEvent>(`
+ SELECT name, path, origin, properties, toString(created_at) AS stored_at
+ FROM events
+ WHERE origin = '${origin}'
+ AND created_at >= toDateTime64('${toClickhouseDateTime(since)}', 3, 'UTC')
+ ORDER BY created_at
+ `);
+}
+
+// Ingest goes through Kafka, the worker and a buffer before the insert, so
+// the rows arrive a few seconds after the click.
+export async function waitForEvents(
+ origin: string,
+ since: Date,
+ isComplete: (events: StoredEvent[]) => boolean,
+ timeoutMs = DEFAULT_TIMEOUT_MS
+) {
+ const deadline = Date.now() + timeoutMs;
+ let events: StoredEvent[] = [];
+ while (Date.now() < deadline) {
+ events = await eventsSince(origin, since);
+ if (isComplete(events)) {
+ return events;
+ }
+ await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+ }
+ const seen = events.map((event) => `${event.name} ${event.path}`);
+ throw new Error(
+ `Timed out after ${timeoutMs}ms waiting for events in ClickHouse. Stored so far: ${JSON.stringify(seen)}`
+ );
+}
diff --git a/apps/testbed/e2e/sdk.spec.ts b/apps/testbed/e2e/sdk.spec.ts
new file mode 100644
index 000000000..687c39cec
--- /dev/null
+++ b/apps/testbed/e2e/sdk.spec.ts
@@ -0,0 +1,54 @@
+import { expect, test } from '@playwright/test';
+import { TESTBED_URL } from '../playwright.config';
+import { type StoredEvent, waitForEvents } from './clickhouse';
+
+const OUTGOING_LINK = 'https://openpanel.dev/';
+
+function byName(events: StoredEvent[], name: string) {
+ return events.filter((event) => event.name === name);
+}
+
+test('the web SDK stores screen views, custom and automatic events with their page', async ({
+ page,
+}) => {
+ const since = new Date();
+ // The click would leave the testbed; the stub keeps the browser here.
+ await page.route(`${OUTGOING_LINK}**`, (route) =>
+ route.fulfill({ body: 'stub', contentType: 'text/plain' })
+ );
+
+ await page.goto('/');
+ await page.getByRole('button', { name: 'Add to cart' }).first().click();
+ await page.getByRole('link', { name: 'Classic T-Shirt' }).click();
+ await expect(page).toHaveURL(/\/product\/p1$/);
+
+ await page.getByTestId('sdk-fixture-data-track').click();
+ await page.getByTestId('sdk-fixture-outgoing-link').click();
+
+ const events = await waitForEvents(
+ TESTBED_URL,
+ since,
+ (stored) =>
+ byName(stored, 'screen_view').length >= 2 &&
+ byName(stored, 'add_to_cart').length >= 1 &&
+ byName(stored, 'testbed_cta').length >= 1 &&
+ byName(stored, 'link_out').length >= 1
+ );
+
+ expect(byName(events, 'screen_view').map((event) => event.path)).toEqual([
+ '/',
+ '/product/p1',
+ ]);
+
+ const [addToCart] = byName(events, 'add_to_cart');
+ expect(addToCart?.path).toBe('/');
+ expect(addToCart?.properties).toMatchObject({ product_id: 'p1' });
+
+ const [cta] = byName(events, 'testbed_cta');
+ expect(cta?.path).toBe('/product/p1');
+ expect(cta?.properties).toMatchObject({ ctaTarget: 'docs' });
+
+ const [linkOut] = byName(events, 'link_out');
+ expect(linkOut?.path).toBe('/product/p1');
+ expect(linkOut?.properties).toMatchObject({ href: OUTGOING_LINK });
+});
diff --git a/apps/testbed/package.json b/apps/testbed/package.json
index 41552f37c..1442ecfe2 100644
--- a/apps/testbed/package.json
+++ b/apps/testbed/package.json
@@ -4,9 +4,11 @@
"version": "0.0.0",
"type": "module",
"scripts": {
- "dev": "node scripts/copy-op1.mjs && vite --port 3100",
+ "dev": "node scripts/copy-op1.mjs && vite --port ${TESTBED_PORT:-3100} --strictPort",
"build": "node scripts/copy-op1.mjs && tsc && vite build",
- "postinstall": "node scripts/copy-op1.mjs"
+ "e2e": "playwright test",
+ "postinstall": "node scripts/copy-op1.mjs",
+ "typecheck": "tsc --noEmit"
},
"dependencies": {
"@openpanel/web": "workspace:*",
@@ -15,6 +17,8 @@
"react-router-dom": "7.13.1"
},
"devDependencies": {
+ "@playwright/test": "1.63.0",
+ "@types/node": "catalog:",
"@types/react": "19.2.7",
"@types/react-dom": "19.2.3",
"@vitejs/plugin-react": "5.2.0",
diff --git a/apps/testbed/playwright.config.ts b/apps/testbed/playwright.config.ts
new file mode 100644
index 000000000..8e5a2d454
--- /dev/null
+++ b/apps/testbed/playwright.config.ts
@@ -0,0 +1,79 @@
+// Drives the testbed in a real browser against an already-running API, the
+// way a customer site would use the SDK. The API is never started from here:
+// in a worktree it is supervised, in a plain checkout `bun run dev` runs it.
+// The testbed itself is started on demand (or reused if already up).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { defineConfig, devices } from '@playwright/test';
+
+const DEFAULT_PORT = 3100;
+// Worktrees get a block of ports starting at WEB_PORT; this offset stays
+// clear of the web, api and studio ports the hub hands out.
+const WORKTREE_PORT_OFFSET = 9;
+const DEFAULT_API_URL = 'http://localhost:3333';
+const SEED_FILE = new URL('../../.seed.json', import.meta.url);
+
+type SeedFile = {
+ projects: { id: string; archetype: string; clientId: string }[];
+};
+
+function readSeededWebsiteClient() {
+ if (!existsSync(SEED_FILE)) {
+ return;
+ }
+ const seed = JSON.parse(readFileSync(SEED_FILE, 'utf-8')) as SeedFile;
+ const website =
+ seed.projects.find((project) => project.archetype === 'website') ??
+ seed.projects[0];
+ return website?.clientId;
+}
+
+const webPort = process.env.WEB_PORT ? Number(process.env.WEB_PORT) : undefined;
+export const TESTBED_PORT = Number(
+ process.env.TESTBED_PORT ??
+ (webPort ? webPort + WORKTREE_PORT_OFFSET : DEFAULT_PORT)
+);
+export const TESTBED_URL = `http://localhost:${TESTBED_PORT}`;
+
+// Plain http to the API process beats the worktree's self-signed https proxy.
+const apiUrl =
+ process.env.VITE_OPENPANEL_API_URL ??
+ process.env.API_URL_SSR ??
+ process.env.API_URL ??
+ DEFAULT_API_URL;
+const clientId =
+ process.env.VITE_OPENPANEL_CLIENT_ID ?? readSeededWebsiteClient();
+
+if (!clientId) {
+ throw new Error(
+ 'No client id: set VITE_OPENPANEL_CLIENT_ID or seed the database (bun run seed) so .seed.json exists'
+ );
+}
+
+export default defineConfig({
+ testDir: 'e2e',
+ // Longer than the ClickHouse poll, so a missing row fails with the list of
+ // what was stored instead of a bare test timeout.
+ timeout: 90_000,
+ fullyParallel: false,
+ workers: 1,
+ retries: 0,
+ reporter: process.env.CI ? 'github' : 'list',
+ use: {
+ baseURL: TESTBED_URL,
+ ignoreHTTPSErrors: true,
+ trace: 'retain-on-failure',
+ },
+ webServer: {
+ command: 'bun run dev',
+ url: TESTBED_URL,
+ reuseExistingServer: true,
+ env: {
+ ...process.env,
+ TESTBED_PORT: String(TESTBED_PORT),
+ VITE_OPENPANEL_API_URL: apiUrl,
+ VITE_OPENPANEL_CLIENT_ID: clientId,
+ },
+ },
+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+});
diff --git a/apps/testbed/src/App.tsx b/apps/testbed/src/App.tsx
index bf3056316..df2e1cbbc 100644
--- a/apps/testbed/src/App.tsx
+++ b/apps/testbed/src/App.tsx
@@ -42,7 +42,7 @@ export default function App() {
for (const id of u.groupIds) {
const meta = PRESET_GROUPS.find((g) => g.id === id);
if (meta) {
- op.upsertGroup({ id, ...meta });
+ op.upsertGroup(meta);
}
}
}
@@ -212,6 +212,24 @@ export default function App() {
/>
</Routes>
</main>
+
+ {/* Exercises the SDK's automatic trackers (trackAttributes, trackOutgoingLinks). */}
+ <footer className="sdk-fixtures">
+ <button
+ data-cta-target="docs"
+ data-testid="sdk-fixture-data-track"
+ data-track="testbed_cta"
+ type="button"
+ >
+ data-track button
+ </button>
+ <a
+ data-testid="sdk-fixture-outgoing-link"
+ href="https://openpanel.dev/"
+ >
+ Outgoing link
+ </a>
+ </footer>
</div>
);
}
diff --git a/apps/testbed/src/pages/Login.tsx b/apps/testbed/src/pages/Login.tsx
index f7a145c4d..4b3009f3c 100644
--- a/apps/testbed/src/pages/Login.tsx
+++ b/apps/testbed/src/pages/Login.tsx
@@ -192,7 +192,7 @@ export function LoginPage({ onLogin }: Props) {
type="button"
>
{group.name}
- <span className="group-plan">{group.plan}</span>
+ <span className="group-plan">{group.properties.plan}</span>
</button>
);
})}
diff --git a/apps/testbed/src/styles.css b/apps/testbed/src/styles.css
index 2442124b7..bfe8043fe 100644
--- a/apps/testbed/src/styles.css
+++ b/apps/testbed/src/styles.css
@@ -360,3 +360,12 @@ input:focus {
gap: 8px;
margin-top: 8px;
}
+
+.sdk-fixtures {
+ display: flex;
+ gap: 12px;
+ align-items: center;
+ padding: 16px 24px;
+ border-top: 1px solid #ddd;
+ font-size: 13px;
+}
diff --git a/apps/testbed/tsconfig.json b/apps/testbed/tsconfig.json
index 4c77361f3..4ba16608d 100644
--- a/apps/testbed/tsconfig.json
+++ b/apps/testbed/tsconfig.json
@@ -11,7 +11,8 @@
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
- "strict": true
+ "strict": true,
+ "types": ["vite/client", "node"]
},
- "include": ["src"]
+ "include": ["src", "e2e", "playwright.config.ts"]
}
diff --git a/bun.lock b/bun.lock
index b27efa7f0..8f0bc49e8 100644
--- a/bun.lock
+++ b/bun.lock
@@ -292,6 +292,8 @@
"react-router-dom": "7.13.1",
},
"devDependencies": {
+ "@playwright/test": "1.63.0",
+ "@types/node": "catalog:",
"@types/react": "19.2.7",
"@types/react-dom": "19.2.3",
"@vitejs/plugin-react": "5.2.0",
@@ -571,7 +573,10 @@
},
"devDependencies": {
"@openpanel/tsconfig": "workspace:*",
+ "@types/jsdom": "30.0.0",
"@types/node": "catalog:",
+ "bun-types": "1.4.0",
+ "jsdom": "26.1.0",
"tsup": "7.3.0",
"typescript": "catalog:",
},
@@ -2765,6 +2770,8 @@
"@types/js-yaml": ["@types/[email protected]", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
+ "@types/jsdom": ["@types/[email protected]", "", { "dependencies": { "@types/node": "*", "@types/tough-cookie": "*", "parse5": "^8.0.0", "undici-types": "^8.9.0" } }, "sha512-uAHGxujGE0cDaKGdK28zgDotFtNA7MKq5DXl8LrfdxdCI8VHcg15oJz+amHTChPNI5JpgEPQWc2xFdrw3em/nQ=="],
+
"@types/json-schema": ["@types/[email protected]", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
"@types/jsonwebtoken": ["@types/[email protected]", "", { "dependencies": { "@types/ms": "*", "@types/node": "*" } }, "sha512-asx5hIG9Qmf/1oStypjanR7iKTv0gXQ1Ov/jfrX6kS/EO0OFni8orbmGCn0672NHR3kXHwpAwR+B368ZGN/2rA=="],
@@ -6655,6 +6662,10 @@
"@types/estree-jsx/@types/estree": ["@types/[email protected]", "", {}, "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg=="],
+ "@types/jsdom/parse5": ["[email protected]", "", { "dependencies": { "entities": "^8.0.0" } }, "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw=="],
+
+ "@types/jsdom/undici-types": ["[email protected]", "", {}, "sha512-EXE4ydL3S76dFb27UFjNVZHTyv/TLdATj/KUe29ptdcg6qXL48J2tZ3126E5kICj5jn781OR+XlVH1N6Mz8jbA=="],
+
"@types/memcached/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~7.12.0" } }, "sha512-FYxk1I7wPv3K2XBaoyH2cTnocQEu8AOZ60hPbsyukMPLv5/5qr7V1i8PLHdl6Zf87I+xZXFvPCXYjiTFq+YSDQ=="],
"@types/mysql/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~7.12.0" } }, "sha512-FYxk1I7wPv3K2XBaoyH2cTnocQEu8AOZ60hPbsyukMPLv5/5qr7V1i8PLHdl6Zf87I+xZXFvPCXYjiTFq+YSDQ=="],
@@ -8121,6 +8132,8 @@
"@types/d3-sankey/@types/d3-shape/@types/d3-path": ["@types/[email protected]", "", {}, "sha512-4pQMp8ldf7UaB/gR8Fvvy69psNHkTpD/pVw3vmEi8iZAB9EPMBruB1JvHO4BIq9QkUUd2lV1F5YXpMNj7JPBpw=="],
+ "@types/jsdom/parse5/entities": ["[email protected]", "", {}, "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA=="],
+
"@types/memcached/@types/node/undici-types": ["[email protected]", "", {}, "sha512-goOacqME2GYyOZZfb5Lgtu+1IDmAlAEu5xnD3+xTzS10hT0vzpf0SPjkXwAw9Jm+4n/mQGDP3LO8CPbYROeBfQ=="],
"@types/mysql/@types/node/undici-types": ["[email protected]", "", {}, "sha512-goOacqME2GYyOZZfb5Lgtu+1IDmAlAEu5xnD3+xTzS10hT0vzpf0SPjkXwAw9Jm+4n/mQGDP3LO8CPbYROeBfQ=="],
diff --git a/package.json b/package.json
index 7363691b3..c04a59068 100644
--- a/package.json
+++ b/package.json
@@ -58,7 +58,7 @@
"scripts": {
"test": "bun run test:core && bun run test:rest",
"test:core": "bun run --filter @openpanel/core test",
- "test:rest": "bun run --filter @openpanel/db test && bun run --filter @openpanel/api test && bun run --filter @openpanel/seed test && bun run --filter start test && bun run --filter @openpanel/release test && vitest run && bun test tooling/gates/conformance",
+ "test:rest": "bun run --filter @openpanel/db test && bun run --filter @openpanel/api test && bun run --filter @openpanel/seed test && bun run --filter @openpanel/web test && bun run --filter start test && bun run --filter @openpanel/release test && vitest run && bun test tooling/gates/conformance",
"gen:bots": "bun run --filter @openpanel/core gen:bots",
"gen:referrers": "bun run --filter @openpanel/core gen:referrers",
"dock:up": "docker compose up -d",
diff --git a/packages/sdks/astro/package.json b/packages/sdks/astro/package.json
index 916a2069e..055cdb69d 100644
--- a/packages/sdks/astro/package.json
+++ b/packages/sdks/astro/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/astro",
"version": "1.4.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/astro"
+ },
"config": {
"transformPackageJson": false,
"transformEnvs": true,
diff --git a/packages/sdks/express/package.json b/packages/sdks/express/package.json
index 61aa4b380..7a47f7e73 100644
--- a/packages/sdks/express/package.json
+++ b/packages/sdks/express/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/express",
"version": "1.3.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/express"
+ },
"module": "index.ts",
"config": {
"docPath": "apps/public/content/docs/(tracking)/sdks/express.mdx"
diff --git a/packages/sdks/nextjs/package.json b/packages/sdks/nextjs/package.json
index f6d6b1262..e01fa72e4 100644
--- a/packages/sdks/nextjs/package.json
+++ b/packages/sdks/nextjs/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/nextjs",
"version": "1.5.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/nextjs"
+ },
"module": "index.ts",
"config": {
"docPath": "apps/public/content/docs/(tracking)/sdks/nextjs.mdx"
diff --git a/packages/sdks/nuxt/package.json b/packages/sdks/nuxt/package.json
index dadb7f026..fdf611962 100644
--- a/packages/sdks/nuxt/package.json
+++ b/packages/sdks/nuxt/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/nuxt",
"version": "0.4.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/nuxt"
+ },
"type": "module",
"main": "./dist/module.mjs",
"exports": {
@@ -19,9 +24,9 @@
"docPath": "apps/public/content/docs/(tracking)/sdks/nuxt.mdx"
},
"scripts": {
- "build": "npx nuxt-module-build build",
- "dev:prepare": "npx nuxt-module-build build --stub",
- "prepack": "npx nuxt-module-build build",
+ "build": "nuxt-module-build build",
+ "dev:prepare": "nuxt-module-build build --stub",
+ "prepack": "nuxt-module-build build",
"typecheck": "tsc --noEmit"
},
"dependencies": {
diff --git a/packages/sdks/react-native/package.json b/packages/sdks/react-native/package.json
index 585c1ffc2..e6f840655 100644
--- a/packages/sdks/react-native/package.json
+++ b/packages/sdks/react-native/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/react-native",
"version": "1.4.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/react-native"
+ },
"module": "index.ts",
"config": {
"docPath": "apps/public/content/docs/(tracking)/sdks/react-native.mdx"
diff --git a/packages/sdks/sdk/package.json b/packages/sdks/sdk/package.json
index 75aed2cac..e05c000bf 100644
--- a/packages/sdks/sdk/package.json
+++ b/packages/sdks/sdk/package.json
@@ -2,6 +2,11 @@
"name": "@openpanel/sdk",
"version": "1.3.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/sdk"
+ },
"module": "index.ts",
"config": {
"docPath": "apps/public/content/docs/(tracking)/sdks/javascript.mdx"
diff --git a/packages/sdks/web/package.json b/packages/sdks/web/package.json
index cbb1977eb..270a7a035 100644
--- a/packages/sdks/web/package.json
+++ b/packages/sdks/web/package.json
@@ -2,12 +2,18 @@
"name": "@openpanel/web",
"version": "1.4.1-local",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/Openpanel-dev/openpanel.git",
+ "directory": "packages/sdks/web"
+ },
"module": "index.ts",
"config": {
"docPath": "apps/public/content/docs/(tracking)/sdks/web.mdx"
},
"scripts": {
"build": "rm -rf dist && tsup",
+ "test": "bun test",
"typecheck": "tsc --noEmit"
},
"dependencies": {
@@ -17,7 +23,10 @@
},
"devDependencies": {
"@openpanel/tsconfig": "workspace:*",
+ "@types/jsdom": "30.0.0",
"@types/node": "catalog:",
+ "bun-types": "1.4.0",
+ "jsdom": "26.1.0",
"tsup": "7.3.0",
"typescript": "catalog:"
}
diff --git a/packages/sdks/web/src/index.test.ts b/packages/sdks/web/src/index.test.ts
new file mode 100644
index 000000000..3983cf2bc
--- /dev/null
+++ b/packages/sdks/web/src/index.test.ts
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { TrackHandlerPayload } from '@openpanel/sdk';
+import { JSDOM } from 'jsdom';
+import { OpenPanel, type OpenPanelOptions } from './index';
+
+const PAGE_URL = 'https://example.com/pricing';
+const OUTGOING_URL = 'https://other.example/docs';
+
+const DOM_GLOBALS = [
+ 'window',
+ 'document',
+ 'history',
+ 'sessionStorage',
+ 'HTMLElement',
+ 'MouseEvent',
+ 'Event',
+] as const;
+
+let dom: JSDOM;
+let sent: TrackHandlerPayload[];
+
+function createSdk(options: Omit<OpenPanelOptions, 'clientId'>) {
+ return new OpenPanel({
+ clientId: 'test-client',
+ // Captures every payload before it reaches the network.
+ filter: (payload) => {
+ sent.push(payload);
+ return false;
+ },
+ ...options,
+ });
+}
+
+function click(element: Element) {
+ element.dispatchEvent(new dom.window.MouseEvent('click', { bubbles: true }));
+}
+
+function sentTrackEvents() {
+ return sent.flatMap((item) => (item.type === 'track' ? [item.payload] : []));
+}
+
+beforeEach(() => {
+ dom = new JSDOM('<!doctype html><html><body></body></html>', {
+ url: PAGE_URL,
+ });
+ for (const name of DOM_GLOBALS) {
+ (globalThis as Record<string, unknown>)[name] = dom.window[name];
+ }
+ sent = [];
+});
+
+afterEach(() => {
+ for (const name of DOM_GLOBALS) {
+ delete (globalThis as Record<string, unknown>)[name];
+ }
+ dom.window.close();
+});
+
+describe('automatic click events', () => {
+ test('fall back to the browser location when no screen view was tracked', () => {
+ createSdk({ trackAttributes: true });
+
+ const button = dom.window.document.createElement('button');
+ button.setAttribute('data-track', 'cta');
+ dom.window.document.body.appendChild(button);
+ click(button);
+
+ const [cta] = sentTrackEvents();
+ expect(cta?.name).toBe('cta');
+ expect(cta?.properties).toMatchObject({ __path: PAGE_URL });
+ });
+
+ test('outgoing link clicks carry the current page', () => {
+ const sdk = createSdk({ trackOutgoingLinks: true });
+ sdk.screenView(PAGE_URL);
+
+ const link = dom.window.document.createElement('a');
+ link.setAttribute('href', OUTGOING_URL);
+ link.setAttribute('title', 'Docs');
+ dom.window.document.body.appendChild(link);
+ click(link);
+
+ const [, linkOut] = sentTrackEvents();
+ expect(linkOut?.name).toBe('link_out');
+ expect(linkOut?.properties).toMatchObject({
+ href: OUTGOING_URL,
+ text: 'Docs',
+ __path: PAGE_URL,
+ });
+ });
+
+ test('data-track clicks carry the current page', () => {
+ const sdk = createSdk({ trackAttributes: true });
+ sdk.screenView(PAGE_URL);
+
+ const button = dom.window.document.createElement('button');
+ button.setAttribute('data-track', 'cta');
+ button.setAttribute('data-cta-target', 'signup');
+ dom.window.document.body.appendChild(button);
+ click(button);
+
+ const [, cta] = sentTrackEvents();
+ expect(cta?.name).toBe('cta');
+ expect(cta?.properties).toMatchObject({
+ ctaTarget: 'signup',
+ __path: PAGE_URL,
+ });
+ });
+});
diff --git a/packages/sdks/web/src/index.ts b/packages/sdks/web/src/index.ts
index 3493717f1..4d4ecbdb4 100644
--- a/packages/sdks/web/src/index.ts
+++ b/packages/sdks/web/src/index.ts
@@ -212,7 +212,7 @@ export class OpenPanel extends OpenPanelBase {
const linkUrl = new URL(href);
const currentHostname = window.location.hostname;
if (linkUrl.hostname !== currentHostname) {
- super.track('link_out', {
+ this.track('link_out', {
href,
text:
link.innerText ||
@@ -287,14 +287,25 @@ export class OpenPanel extends OpenPanelBase {
}
const name = element.getAttribute('data-track');
if (name) {
- super.track(name, properties);
+ this.track(name, properties);
}
}
});
}
+ // The automatic click trackers must call this, not super.track(), or their
+ // events lose the page they happened on.
track(name: string, properties?: TrackProperties) {
- return super.track(name, { ...properties, __path: this.lastPath });
+ return super.track(name, { ...properties, __path: this.currentPath() });
+ }
+
+ // Without screen view tracking nothing sets lastPath, so fall back to the
+ // page the browser is on.
+ private currentPath() {
+ if (this.lastPath) {
+ return this.lastPath;
+ }
+ return this.isServer() ? '' : window.location.href;
}
screenView(properties?: TrackProperties): void;
diff --git a/packages/sdks/web/tsconfig.json b/packages/sdks/web/tsconfig.json
index 95a0d8537..0016afe24 100644
--- a/packages/sdks/web/tsconfig.json
+++ b/packages/sdks/web/tsconfig.json
@@ -3,7 +3,11 @@
"compilerOptions": {
"incremental": false,
"outDir": "dist",
- "strictNullChecks": true
+ "strictNullChecks": true,
+ // `bun test` is the runner: the test file imports `bun:test`, which only
+ // `bun-types` declares. Listing it opts out of the automatic @types/* sweep,
+ // so `node` is named back in.
+ "types": ["bun-types", "node"]
},
"exclude": ["dist"]
}
diff --git a/tooling/publish/publish.ts b/tooling/publish/publish.ts
index 92ebb3754..8a9347e0a 100644
--- a/tooling/publish/publish.ts
+++ b/tooling/publish/publish.ts
@@ -32,8 +32,16 @@ export interface PackageInfo extends PackageJson {
interface PublishConfig {
registry: string;
clear: boolean;
+ // Stage for a maintainer's 2FA approval (`npm stage approve`) instead of
+ // publishing outright; what CI does under a stage-only trusted publisher.
+ stage: boolean;
+ // Prereleases go under their own dist-tag so `latest` keeps pointing at a
+ // stable version.
+ distTag?: string;
}
+const PRERELEASE_DIST_TAG = 'rc';
+
const workspacePath = (relativePath: string) =>
resolve(__dirname, '../../', relativePath);
@@ -239,7 +247,7 @@ const buildPackages = (
continue;
}
console.log(`🔨 Building ${dep}`);
- const cmd = `pnpm build ${versionEnvs.join(' ')}`;
+ const cmd = `bun run build ${versionEnvs.join(' ')}`;
console.log(` Running: ${cmd}`);
execSync(cmd, {
cwd: workspacePath(packages[dep]!.localPath),
@@ -256,14 +264,17 @@ const publishPackages = (
execSync('rm -rf ~/.local/share/verdaccio/storage/@openpanel');
}
+ const publishCommand = config.stage ? 'npm stage publish' : 'npm publish';
for (const dep of dependents) {
- console.log(`🚀 Publishing ${dep} to ${config.registry}`);
console.log(
- `📦 Install: pnpm install ${dep} --registry ${config.registry}`
+ `🚀 ${config.stage ? 'Staging' : 'Publishing'} ${dep} to ${config.registry}`
+ );
+ execSync(
+ `${publishCommand} --access=public --registry ${config.registry}`,
+ {
+ cwd: workspacePath(packages[dep]!.localPath),
+ }
);
- execSync(`npm publish --access=public --registry ${config.registry}`, {
- cwd: workspacePath(packages[dep]!.localPath),
- });
if (dep === '@openpanel/web') {
execSync(
@@ -340,6 +351,7 @@ function main() {
'--skip-git': Boolean,
'--type': String,
'--clear': Boolean,
+ '--stage': Boolean,
});
if (!args['--skip-git']) {
@@ -385,6 +397,10 @@ function main() {
? 'https://registry.npmjs.org'
: 'http://localhost:4873',
clear: args['--clear'] ?? false,
+ stage: args['--stage'] ?? false,
+ distTag: args['--type']!.startsWith('pre')
+ ? PRERELEASE_DIST_TAG
+ : undefined,
};
publishPackages(packages, dependents, config);