Playground improvements

.github/workflows/ci.yml

@@ -103,6 +103,47 @@ jobs:
           path: packages/trackkit/deadcode-report.md
           if-no-files-found: ignore
 
+  trackkit-e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    needs: trackkit-core # Run after build/unit tests pass (save resources)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.13.1
+          run_install: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Trackkit SDK
+        run: pnpm --filter trackkit run build
+
+      - name: Install Playwright Browsers
+        working-directory: packages/trackkit
+        run: pnpm exec playwright install --with-deps
+
+      - name: Run Playwright tests
+        run: pnpm --filter trackkit run test:e2e
+
+      - name: Upload Playwright Report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: packages/trackkit/playwright-report/
+          retention-days: 30
+
   docs:
     name: Build & Publish Docs
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Trackkit follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from **1.0.0** onwards.
+During the **0.x beta**, breaking changes may occur between minor versions and will be noted here.
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Export `ConsentStoredState` from the main `trackkit` entry point (`src/index.ts`). Previously accessible only as an internal type; now importable as `import type { ConsentStoredState } from 'trackkit'`.
+- Export `DiagnosticsSnapshot` from the main `trackkit` entry point. Previously required a direct import from `facade/diagnostics`; now importable as `import type { DiagnosticsSnapshot } from 'trackkit'`.
+
+### Changed
+
+- **Breaking (docs):** Provider configuration now uses a nested `provider` object rather than a top-level string plus loose fields.
+
+  Before (was documented incorrectly, never actually worked):
+  ```ts
+  createAnalytics({ provider: 'umami', site: 'abc', host: 'https://...' });
+  ```
+
+  After (correct, matches the actual `ProviderOptions` discriminated-union type):
+  ```ts
+  createAnalytics({ provider: { name: 'umami', site: 'abc', host: 'https://...' } });
+  ```
+
+  Provider-specific fields (`site`, `host`, `website`, `domain`, `measurementId`, `apiSecret`, etc.) belong inside the `provider` object. Facade-level fields (`autoTrack`, `debug`, `doNotTrack`, `queueSize`, `consent`, etc.) remain at the top level.
+
+- **Docs:** The correct configuration type name is `AnalyticsOptions` (not `InitOptions`, which does not exist). All documentation references updated.
+
+### Fixed
+
+- **API reference corrections** (`docs/reference/api.md`):
+  - `track()` third parameter is `category?: ConsentCategory`, not `url?`.
+  - `identify()` signature is `identify(userId: string | null)` — no `traits` parameter.
+  - `pageview()` signature is `pageview(url?: string)` — no structured object form.
+  - `waitForReady()` accepts `opts?: { timeoutMs?: number; mode?: string }`, not a bare `timeoutMs` number.
+  - `getConsent()` returns `ConsentStoredState | null`, not `ConsentStoredState | undefined`.
+  - `onConsentChange()` handler receives `(status: ConsentStatus, prev: ConsentStatus)`, not `(state: ConsentStoredState)`.
+  - Removed `setConsent()` from the public API docs. Use `grantConsent()`, `denyConsent()`, or `resetConsent()` instead.
+
+- **SSR example** (`packages/trackkit/README.md`): Corrected a misleading example that called `ssrTrack('pageview', { url: '/home' })` — this would create a custom event named `"pageview"`, not a proper SSR pageview. The correct call is `ssrPageview('/home')`.
+
+- All documentation code examples updated to use the correct nested provider config syntax (see above).
+
+---
+
+## [0.0.1] — Initial pre-release
+
+First tracked revision. Internal beta only.

README.md

@@ -56,9 +56,11 @@ npm i trackkit     # or: pnpm add trackkit  /  yarn add trackkit
 import { createAnalytics } from 'trackkit';
 
 const analytics = createAnalytics({
-  provider: 'umami',                      // 'umami' | 'plausible' | 'ga4' | 'noop'
-  site: '94db1cb1-74f4-4a40-ad6c-962362670409',
-  host: 'https://analytics.example.com',  // required if self-hosting/custom domain
+  provider: {
+    name: 'umami',                   // 'umami' | 'plausible' | 'ga4' | 'noop'
+    site: '94db1cb1-74f4-4a40-ad6c-962362670409',
+    host: 'https://analytics.example.com',  // required if self-hosting/custom domain
+  },
   debug: true,
 });
 
@@ -86,7 +88,7 @@ However, if you prefer a global approach, you can use the included singleton hel
 
 import { init, pageview, track } from 'trackkit';
 
-init({ provider: 'umami', site: '...' });
+init({ provider: { name: 'umami', site: '...' } });
 pageview();
 track('signup_submitted', { plan: 'starter' });
 ```
@@ -107,8 +109,7 @@ Every mechanism (SSR, offline, resilience, performance) is downstream of these g
 import { createAnalytics /* or init, grantConsent */ } from 'trackkit';
 
 const analytics = createAnalytics({
-  provider: 'ga4',
-  site: 'G-XXXXXXXXXX',
+  provider: { name: 'ga4', site: 'G-XXXXXXXXXX' },
   consent: {
     initialStatus: 'pending',      // 'pending' | 'granted' | 'denied'
     requireExplicit: true,         // default: true

docdefaults.config.mjs

@@ -28,10 +28,5 @@ export default {
       interface: 'PerformanceOptions',
       member: 'PERFORMANCE_DEFAULTS',
     },
-    {
-      types: 'src/dispatcher/types.ts',
-      interface: 'ResilienceOptions',
-      member: 'RESILIENCE_DEFAULTS',
-    },
   ],
 };