@agent-analytics/paperclip-live-analytics-plugin 0.1.0

package/dist/assets/index-dyBLLxDx.css

@@ -0,0 +1 @@
+:root{--aa-bg: #f0e8dc;--aa-bg-deep: #e4d6c0;--aa-ink: #1f2a2a;--aa-muted: #576665;--aa-panel: rgba(255, 250, 242, .78);--aa-panel-stroke: rgba(31, 42, 42, .11);--aa-accent: #0f8b8d;--aa-accent-warm: #dc6f36;--aa-accent-cool: #265f88;--aa-live: #1a9a63;--aa-error: #b24a2f;--aa-shadow: 0 18px 50px rgba(31, 42, 42, .08);--aa-serif: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;--aa-sans: "IBM Plex Sans", "Avenir Next", "Segoe UI", sans-serif;--aa-mono: "IBM Plex Mono", "SFMono-Regular", monospace}*{box-sizing:border-box}body{margin:0;font-family:var(--aa-sans);color:var(--aa-ink);background:radial-gradient(circle at top left,rgba(15,139,141,.16),transparent 28%),radial-gradient(circle at top right,rgba(220,111,54,.16),transparent 22%),linear-gradient(180deg,#f8f3eb 0%,var(--aa-bg) 45%,var(--aa-bg-deep) 100%)}a{color:inherit;text-decoration:none}button,input,select{font:inherit}.aa-app{min-height:100vh;padding:24px}.aa-page-shell,.aa-settings-shell{max-width:1400px;margin:0 auto}.aa-hero,.aa-panel,.aa-widget,.aa-metric-card,.aa-asset-card{background:var(--aa-panel);border:1px solid var(--aa-panel-stroke);box-shadow:var(--aa-shadow);-webkit-backdrop-filter:blur(18px);backdrop-filter:blur(18px)}.aa-hero{display:flex;justify-content:space-between;gap:24px;padding:28px;border-radius:28px}.aa-kicker{margin:0 0 8px;font-family:var(--aa-mono);font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:var(--aa-muted)}.aa-hero h1,.aa-panel h2,.aa-widget h2{margin:0;font-family:var(--aa-serif);line-height:1}.aa-hero h1{font-size:clamp(2.6rem,5vw,4.3rem);max-width:12ch}.aa-hero-copy{max-width:58ch;color:var(--aa-muted)}.aa-hero-status{min-width:220px;display:flex;flex-direction:column;align-items:flex-end;gap:12px}.aa-metric-grid,.aa-main-grid,.aa-evidence-grid,.aa-asset-grid,.aa-settings-grid,.aa-form-grid{display:grid;gap:18px}.aa-metric-grid{grid-template-columns:repeat(4,minmax(0,1fr));margin:18px 0}.aa-metric-card{border-radius:22px;padding:20px}.aa-metric-card span,.aa-label{display:block;font-size:.82rem;color:var(--aa-muted)}.aa-metric-card strong{display:block;margin-top:10px;font-size:2.3rem;font-family:var(--aa-serif)}.aa-main-grid{grid-template-columns:1.25fr 1fr;align-items:start}.aa-panel,.aa-widget,.aa-asset-card{border-radius:26px;padding:22px}.aa-panel-header,.aa-widget-header,.aa-asset-topline,.aa-widget-footer,.aa-inline-actions,.aa-settings-row{display:flex;justify-content:space-between;gap:14px;align-items:flex-start}.aa-world-grid{display:grid;grid-template-columns:minmax(260px,.9fr) 1.1fr;gap:20px;align-items:center}.aa-globe{position:relative;aspect-ratio:1;border-radius:999px;background:radial-gradient(circle at 30% 30%,rgba(15,139,141,.45),transparent 44%),radial-gradient(circle at 70% 65%,rgba(220,111,54,.24),transparent 32%),linear-gradient(180deg,#173838,#0f6465);overflow:hidden;box-shadow:inset 0 0 80px #ffffff26}.aa-globe-ring{position:absolute;inset:18%;border:1px solid rgba(255,255,255,.22);border-radius:999px}.aa-globe-ring-two{inset:8%}.aa-globe-ring-three{inset:32%}.aa-globe-core{position:absolute;inset:38%;display:grid;place-items:center;border-radius:999px;background:#fffaf2eb;color:var(--aa-ink);font-family:var(--aa-mono);letter-spacing:.12em;text-transform:uppercase;font-size:.75rem}.aa-country-list,.aa-feed,.aa-settings-stack{display:grid;gap:12px}.aa-country-row,.aa-feed-row,.aa-mini-row,.aa-settings-row{padding:12px 0;border-top:1px solid rgba(31,42,42,.08)}.aa-country-row:first-child,.aa-feed-row:first-child,.aa-mini-row:first-child,.aa-settings-row:first-child{border-top:0;padding-top:0}.aa-country-row strong,.aa-mini-row strong,.aa-feed-row strong,.aa-settings-row strong{display:block}.aa-country-row span,.aa-feed-row span,.aa-settings-row span{color:var(--aa-muted);font-size:.92rem}.aa-country-bar{width:100%;height:8px;margin-top:8px;border-radius:999px;background:#265f881f;overflow:hidden}.aa-country-bar-fill{height:100%;border-radius:999px;background:linear-gradient(90deg,var(--aa-accent) 0%,var(--aa-accent-warm) 100%)}.aa-world-hot,.aa-status-pill{padding:7px 12px;border-radius:999px;font-size:.78rem;font-family:var(--aa-mono);letter-spacing:.08em;text-transform:uppercase}.aa-world-hot,.aa-status-live,.aa-status-connected,.aa-status-streaming{background:#1a9a6324;color:var(--aa-live)}.aa-status-error,.aa-status-attention{background:#b24a2f24;color:var(--aa-error)}.aa-status-idle,.aa-status-pending,.aa-status-disconnected{background:#265f881f;color:var(--aa-accent-cool)}.aa-mini-panel{background:#ffffff6b;border-radius:20px;padding:18px;border:1px solid rgba(31,42,42,.08)}.aa-mini-panel h3,.aa-assets-section h2{margin:0 0 12px;font-family:var(--aa-serif)}.aa-feed-row{display:flex;justify-content:space-between;gap:12px}.aa-feed-row time{white-space:nowrap;font-size:.85rem;color:var(--aa-muted)}.aa-assets-section{margin-top:18px}.aa-asset-grid{grid-template-columns:repeat(auto-fit,minmax(280px,1fr));margin-top:18px}.aa-asset-card{display:grid;gap:16px}.aa-asset-metrics,.aa-asset-details,.aa-asset-evidence,.aa-widget-metrics{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px}.aa-asset-metrics strong,.aa-widget-metrics strong{display:block;margin-top:8px;font-family:var(--aa-serif);font-size:1.6rem}.aa-button{border:0;border-radius:999px;padding:10px 14px;cursor:pointer;transition:transform .12s ease,opacity .12s ease}.aa-button:hover{transform:translateY(-1px)}.aa-button-primary{background:var(--aa-ink);color:#fff}.aa-button-secondary{background:#0f8b8d1f;color:var(--aa-accent)}.aa-button-ghost{background:transparent;color:var(--aa-muted);border:1px solid rgba(31,42,42,.12)}.aa-widget{max-width:520px;margin:0 auto}.aa-widget-metrics{margin:18px 0}.aa-settings-grid{grid-template-columns:1.15fr .85fr}.aa-form-grid{grid-template-columns:repeat(2,minmax(0,1fr));margin-top:14px}.aa-form-grid label,.aa-auth-box label{display:grid;gap:8px;font-size:.92rem;color:var(--aa-muted)}.aa-form-grid input,.aa-form-grid select,.aa-auth-box input{border-radius:14px;border:1px solid rgba(31,42,42,.12);padding:12px 14px;background:#ffffffb8}.aa-auth-box{display:grid;gap:12px;margin-top:16px;padding:16px;border-radius:18px;background:#ffffff7a}.aa-checkbox{display:flex!important;align-items:center;gap:10px}.aa-muted-note{color:var(--aa-muted);font-size:.92rem;display:inline-flex;align-items:center}.aa-panel-warning{border-color:#dc6f3647}@media(max-width:1100px){.aa-metric-grid,.aa-main-grid,.aa-settings-grid,.aa-world-grid{grid-template-columns:1fr}.aa-hero{flex-direction:column}.aa-hero-status{align-items:flex-start}}@media(max-width:720px){.aa-app{padding:14px}.aa-metric-grid,.aa-form-grid,.aa-asset-metrics,.aa-asset-details,.aa-asset-evidence,.aa-widget-metrics{grid-template-columns:1fr 1fr}.aa-feed-row,.aa-panel-header,.aa-widget-header,.aa-widget-footer,.aa-settings-row,.aa-inline-actions{flex-direction:column}}

package/dist/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Agent Analytics Live</title>
+    <script type="module" crossorigin src="/assets/index-DCET-swI.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-dyBLLxDx.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+  </html>
+

package/docs/MAINTAINER.md

@@ -0,0 +1,30 @@
+# Maintainer Notes
+
+## Host contract
+
+- Manifest entrypoints:
+  - `entrypoints.worker` → `./src/worker/index.js`
+  - `entrypoints.ui` → `./dist`
+- Declared surfaces:
+  - `page`
+  - `dashboardWidget`
+  - `settingsPage`
+
+## Worker/UI boundary
+
+- Worker owns auth, refresh, `/stream`, `/live`, per-company cache, and stream emission
+- UI consumes worker data/actions/streams only
+- No third-party credentials leave the worker boundary
+
+## State ownership
+
+- Company-scoped config: base URL, live window, poll cadence, enabled mappings
+- Company-scoped auth: access token, refresh token, tier, pending detached login state
+- Company-scoped UI state: snoozed assets
+
+## Stream delivery
+
+- Worker opens one company-scoped host stream channel
+- Worker emits normalized full-state payloads
+- UI replaces local live state wholesale on each event
+

package/docs/asset-mapping.md

@@ -0,0 +1,22 @@
+# Asset Mapping Guide
+
+Mappings are explicit and company-scoped.
+
+## Required fields
+
+- `assetKey`
+- `label`
+- `kind`
+- `agentAnalyticsProject`
+
+## Optional fields
+
+- `paperclipProjectId`
+- `primaryHostname`
+- `allowedOrigins`
+- `enabled`
+
+## Important v1 rule
+
+`/live` snapshots are project-scoped. If multiple mappings reuse the same Agent Analytics project, the plugin may mirror the same live totals across more than one asset card. The settings page warns when this happens.
+

package/docs/limits-and-troubleshooting.md

@@ -0,0 +1,16 @@
+# Limits And Troubleshooting
+
+## Hard limits
+
+- `/stream` and `/live` are metered read routes
+- `/live` is paid-only
+- Upstream live streams are capped at 10 concurrent streams per account
+- `/live` keeps only the most recent 5 minutes of backing event history
+
+## Common failure modes
+
+- `unauthorized` or `invalid refresh token`: reconnect from settings
+- duplicate project mappings: reduce repeated project use or accept mirrored project totals
+- no live data with a free tier: upgrade the connected account
+- stale UI while connection is healthy: check whether the asset is snoozed or disabled
+

package/docs/live-behavior.md

@@ -0,0 +1,20 @@
+# Live Behavior
+
+## Data sources
+
+- `/stream`: incremental live event feed over Server-Sent Events
+- `/live`: authoritative rollup snapshot for the short live window
+
+## What the metrics mean
+
+- `Active visitors`: unique users inside the current `/live` window
+- `Active sessions`: unique sessions inside the current `/live` window
+- `Events / min`: current live-window event rate
+- `Recent events`: operator evidence feed, not a full audit log
+
+## What this plugin is not
+
+- Not a rebuild of the Agent Analytics reporting product
+- Not a historical dashboard
+- Not an automated issue router
+

package/docs/operator-overview.md

@@ -0,0 +1,18 @@
+# Operator Overview
+
+Agent Analytics Live is the Paperclip surface for answering one question quickly:
+
+Which company asset is moving right now, and is that movement worth operator attention?
+
+## Surfaces
+
+- `page`: company-level live monitor with asset cards, world/country emphasis, top pages, top events, and recent evidence
+- `dashboardWidget`: compact pulse for the main dashboard
+- `settingsPage`: connection, asset mapping, and rollout controls
+
+## Assumptions
+
+- One Paperclip company connects one Agent Analytics account
+- `/live` and `/stream` are paid live routes, so the account tier must permit live reads
+- The plugin is intentionally live-window-only; it is not historical reporting
+

package/docs/setup-auth.md

@@ -0,0 +1,23 @@
+# Setup And Auth
+
+## Default auth path
+
+The plugin is login-first.
+
+1. Open the plugin `settingsPage`
+2. Click `Start login`
+3. Open the returned approval URL
+4. Sign in with Google or GitHub
+5. Paste the finish code into the settings page
+6. The worker exchanges the code, stores the session, validates `GET /projects`, and starts live sync
+
+## Worker-owned boundary
+
+- Access token and refresh token are stored in worker-owned company state
+- The browser UI never receives a raw Agent Analytics API key
+- `/stream` and `/live` are called only from the worker
+
+## Compatibility fallback
+
+The worker code keeps an internal API-key auth adapter for legacy or self-hosted environments, but v1 does not expose API-key entry in the UI.
+

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Agent Analytics Live</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/ui/main.jsx"></script>
+  </body>
+  </html>
+

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@agent-analytics/paperclip-live-analytics-plugin",
+  "version": "0.1.0",
+  "description": "Thin Paperclip plugin that exposes live Agent Analytics signals inside a company workspace.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Agent-Analytics/paperclip-live-analytics-plugin.git"
+  },
+  "homepage": "https://github.com/Agent-Analytics/paperclip-live-analytics-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/Agent-Analytics/paperclip-live-analytics-plugin/issues"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "analytics",
+    "live",
+    "agent-analytics"
+  ],
+  "files": [
+    "dist",
+    "docs",
+    "src",
+    "index.html",
+    "paperclip-plugin.manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "npm test && npm run build",
+    "pack:local": "npm pack"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^5.1.3",
+    "vite": "^7.2.4"
+  }
+}

package/paperclip-plugin.manifest.json

@@ -0,0 +1,36 @@
+{
+  "id": "@agent-analytics/paperclip-live-analytics-plugin",
+  "name": "Agent Analytics Live",
+  "displayName": "Agent Analytics Live",
+  "version": "0.1.0",
+  "categories": ["connector", "ui"],
+  "entrypoints": {
+    "worker": "./src/worker/index.js",
+    "ui": "./dist"
+  },
+  "surfaces": [
+    {
+      "type": "page",
+      "key": "agentAnalyticsLivePage",
+      "title": "Agent Analytics Live"
+    },
+    {
+      "type": "dashboardWidget",
+      "key": "agentAnalyticsLiveWidget",
+      "title": "Agent Analytics Live"
+    },
+    {
+      "type": "settingsPage",
+      "key": "agentAnalyticsLiveSettings",
+      "title": "Agent Analytics Live Settings"
+    }
+  ],
+  "capabilities": [
+    "http.outbound",
+    "plugin.state.read",
+    "plugin.state.write",
+    "companies.read",
+    "projects.read"
+  ]
+}
+

package/src/shared/agent-analytics-client.js

@@ -0,0 +1,204 @@
+import {
+  AGENT_SESSION_SCOPES,
+  DEFAULT_BASE_URL,
+  PLUGIN_DISPLAY_NAME,
+  PLUGIN_ID,
+} from './constants.js';
+
+function createJsonHeaders(auth) {
+  const headers = {
+    'Content-Type': 'application/json',
+  };
+  if (auth?.access_token) headers.Authorization = `Bearer ${auth.access_token}`;
+  else if (auth?.api_key) headers['X-API-Key'] = auth.api_key;
+  return headers;
+}
+
+function buildQuery(params) {
+  return Object.entries(params)
+    .filter(([, value]) => value !== null && value !== undefined && value !== '')
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join('&');
+}
+
+function parseSseEvent(rawEvent) {
+  const event = {
+    event: 'message',
+    data: '',
+    comment: null,
+  };
+
+  const lines = rawEvent.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line) continue;
+    if (line.startsWith(':')) {
+      event.comment = line.slice(1).trim();
+      continue;
+    }
+    const separatorIndex = line.indexOf(':');
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    const value = separatorIndex === -1 ? '' : line.slice(separatorIndex + 1).trimStart();
+    if (field === 'event') event.event = value;
+    if (field === 'data') event.data = event.data ? `${event.data}\n${value}` : value;
+  }
+  return event;
+}
+
+export class AgentAnalyticsClient {
+  constructor({
+    auth = null,
+    baseUrl = DEFAULT_BASE_URL,
+    fetchImpl = globalThis.fetch,
+    onAuthUpdate = null,
+  } = {}) {
+    this.auth = auth ? { ...auth } : null;
+    this.baseUrl = baseUrl;
+    this.fetchImpl = fetchImpl;
+    this.onAuthUpdate = onAuthUpdate;
+  }
+
+  setAuth(auth) {
+    this.auth = auth ? { ...auth } : null;
+  }
+
+  async request(method, path, body, { retryOnRefresh = true } = {}) {
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: createJsonHeaders(this.auth),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const data = await response.json().catch(() => ({}));
+
+    if (response.status === 401 && retryOnRefresh && this.auth?.refresh_token) {
+      const refreshed = await this.refreshAgentSession().catch(() => null);
+      if (refreshed?.access_token) {
+        return this.request(method, path, body, { retryOnRefresh: false });
+      }
+    }
+
+    if (!response.ok) {
+      throw new Error(data.message || data.error || `HTTP ${response.status}`);
+    }
+
+    return data;
+  }
+
+  async startPaperclipAuth({ companyId, label } = {}) {
+    return this.request(
+      'POST',
+      '/agent-sessions/start',
+      {
+        mode: 'detached',
+        client_type: 'paperclip',
+        client_name: PLUGIN_DISPLAY_NAME,
+        client_instance_id: companyId || null,
+        label: label || `Paperclip Company ${companyId || ''}`.trim(),
+        scopes: AGENT_SESSION_SCOPES,
+        metadata: {
+          platform: 'paperclip',
+          plugin_id: PLUGIN_ID,
+          company_id: companyId || null,
+        },
+      },
+      { retryOnRefresh: false }
+    );
+  }
+
+  async exchangeAgentSession(authRequestId, exchangeCode) {
+    return this.request(
+      'POST',
+      '/agent-sessions/exchange',
+      {
+        auth_request_id: authRequestId,
+        exchange_code: exchangeCode,
+      },
+      { retryOnRefresh: false }
+    );
+  }
+
+  async refreshAgentSession() {
+    if (!this.auth?.refresh_token) {
+      throw new Error('No refresh token available');
+    }
+
+    const refreshed = await this.request(
+      'POST',
+      '/agent-sessions/refresh',
+      {
+        refresh_token: this.auth.refresh_token,
+      },
+      { retryOnRefresh: false }
+    );
+
+    this.auth = {
+      ...this.auth,
+      ...refreshed.agent_session,
+    };
+    this.onAuthUpdate?.(this.auth);
+    return this.auth;
+  }
+
+  async listProjects() {
+    return this.request('GET', '/projects');
+  }
+
+  async getLive(project, { window } = {}) {
+    const query = buildQuery({ project, window });
+    return this.request('GET', `/live?${query}`);
+  }
+
+  async subscribeToStream({ project, filter, signal, onConnected, onTrack, onComment }) {
+    const query = buildQuery({
+      project,
+      filter,
+    });
+
+    const response = await this.fetchImpl(`${this.baseUrl}/stream?${query}`, {
+      method: 'GET',
+      headers: createJsonHeaders(this.auth),
+      signal,
+    });
+
+    if (!response.ok || !response.body) {
+      const payload = await response.text().catch(() => '');
+      throw new Error(payload || `Stream failed with HTTP ${response.status}`);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.indexOf('\n\n');
+      while (boundary !== -1) {
+        const rawEvent = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const event = parseSseEvent(rawEvent);
+
+        if (event.comment) {
+          onComment?.(event.comment);
+        }
+
+        if (event.data) {
+          let parsed = {};
+          try {
+            parsed = JSON.parse(event.data);
+          } catch {
+            parsed = { raw: event.data };
+          }
+
+          if (event.event === 'connected') onConnected?.(parsed);
+          if (event.event === 'track') onTrack?.(parsed);
+        }
+
+        boundary = buffer.indexOf('\n\n');
+      }
+    }
+  }
+}
+

package/src/shared/constants.js

@@ -0,0 +1,41 @@
+export const PLUGIN_ID = '@agent-analytics/paperclip-live-analytics-plugin';
+export const PLUGIN_DISPLAY_NAME = 'Agent Analytics Live';
+export const DEFAULT_BASE_URL = 'https://api.agentanalytics.sh';
+export const DEFAULT_LIVE_WINDOW_SECONDS = 60;
+export const DEFAULT_POLL_INTERVAL_SECONDS = 15;
+export const MIN_LIVE_WINDOW_SECONDS = 10;
+export const MAX_LIVE_WINDOW_SECONDS = 300;
+export const MIN_POLL_INTERVAL_SECONDS = 5;
+export const MAX_POLL_INTERVAL_SECONDS = 60;
+export const DEFAULT_SNOOZE_MINUTES = 30;
+export const MAX_ENABLED_ASSET_STREAMS = 10;
+export const LIVE_STREAM_CHANNEL = 'agent-analytics-live';
+export const STATE_NAMESPACE = 'agent-analytics-live';
+
+export const DATA_KEYS = {
+  livePageLoad: 'live.page.load',
+  liveWidgetLoad: 'live.widget.load',
+  settingsLoad: 'settings.load',
+};
+
+export const ACTION_KEYS = {
+  authStart: 'auth.start',
+  authComplete: 'auth.complete',
+  authDisconnect: 'auth.disconnect',
+  authReconnect: 'auth.reconnect',
+  settingsSave: 'settings.save',
+  mappingUpsert: 'mapping.upsert',
+  mappingRemove: 'mapping.remove',
+  assetSnooze: 'asset.snooze',
+  assetUnsnooze: 'asset.unsnooze',
+};
+
+export const AGENT_SESSION_SCOPES = [
+  'account:read',
+  'projects:write',
+  'analytics:read',
+  'live:read',
+];
+
+export const ASSET_KINDS = ['website', 'docs', 'app', 'api', 'other'];
+

package/src/shared/defaults.js

@@ -0,0 +1,73 @@
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_LIVE_WINDOW_SECONDS,
+  DEFAULT_POLL_INTERVAL_SECONDS,
+} from './constants.js';
+
+export function createDefaultSettings() {
+  return {
+    agentAnalyticsBaseUrl: DEFAULT_BASE_URL,
+    liveWindowSeconds: DEFAULT_LIVE_WINDOW_SECONDS,
+    pollIntervalSeconds: DEFAULT_POLL_INTERVAL_SECONDS,
+    monitoredAssets: [],
+    pluginEnabled: true,
+  };
+}
+
+export function createDefaultAuthState() {
+  return {
+    mode: 'agent_session',
+    accessToken: null,
+    refreshToken: null,
+    accessExpiresAt: null,
+    refreshExpiresAt: null,
+    accountSummary: null,
+    tier: null,
+    status: 'disconnected',
+    pendingAuthRequest: null,
+    lastValidatedAt: null,
+    lastError: null,
+  };
+}
+
+export function createDefaultSnoozeState() {
+  return {};
+}
+
+export function createEmptyCompanyLiveState() {
+  return {
+    type: 'live_state',
+    generatedAt: Date.now(),
+    pluginEnabled: true,
+    authStatus: 'disconnected',
+    tier: null,
+    account: null,
+    connection: {
+      status: 'idle',
+      label: 'Not connected',
+      detail: 'Connect Agent Analytics from settings to start the live feed.',
+    },
+    metrics: {
+      activeVisitors: 0,
+      activeSessions: 0,
+      eventsPerMinute: 0,
+      assetsConfigured: 0,
+      assetsVisible: 0,
+      countriesTracked: 0,
+    },
+    world: {
+      hotCountry: null,
+      countries: [],
+    },
+    evidence: {
+      topPages: [],
+      topEvents: [],
+      recentEvents: [],
+      countries: [],
+    },
+    assets: [],
+    snoozedAssets: [],
+    warnings: [],
+  };
+}
+