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

package/src/ui/surfaces/PageSurface.jsx

@@ -0,0 +1,218 @@
+function formatRelativeTime(timestamp) {
+  if (!timestamp) return 'No updates yet';
+  const seconds = Math.max(0, Math.round((Date.now() - timestamp) / 1000));
+  if (seconds < 5) return 'Updated just now';
+  if (seconds < 60) return `Updated ${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  return `Updated ${minutes}m ago`;
+}
+
+function CountryPulse({ liveState }) {
+  const hotCountry = liveState.world.hotCountry || 'World';
+  return (
+    <section className="aa-panel aa-world-panel">
+      <div className="aa-panel-header">
+        <div>
+          <p className="aa-kicker">World / Country View</p>
+          <h2>Supporting geography, not dashboard wallpaper.</h2>
+        </div>
+        <div className="aa-world-hot">{hotCountry}</div>
+      </div>
+      <div className="aa-world-grid">
+        <div className="aa-globe">
+          <div className="aa-globe-ring aa-globe-ring-one" />
+          <div className="aa-globe-ring aa-globe-ring-two" />
+          <div className="aa-globe-ring aa-globe-ring-three" />
+          <div className="aa-globe-core">
+            <span>Live</span>
+          </div>
+        </div>
+        <div className="aa-country-list">
+          {liveState.world.countries.map((country) => (
+            <div className="aa-country-row" key={country.country}>
+              <div>
+                <strong>{country.country}</strong>
+                <span>{country.visitors} visitors</span>
+              </div>
+              <div className="aa-country-bar">
+                <div
+                  className="aa-country-bar-fill"
+                  style={{ width: `${Math.min(100, (country.events / Math.max(1, liveState.metrics.eventsPerMinute)) * 100)}%` }}
+                />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function EvidenceColumn({ liveState }) {
+  return (
+    <section className="aa-panel">
+      <div className="aa-panel-header">
+        <div>
+          <p className="aa-kicker">Operator Evidence</p>
+          <h2>Fast feed, top pages, and why the pulse changed.</h2>
+        </div>
+      </div>
+      <div className="aa-evidence-grid">
+        <div className="aa-mini-panel">
+          <h3>Top Pages</h3>
+          {liveState.evidence.topPages.map((page) => (
+            <div className="aa-mini-row" key={page.path}>
+              <span>{page.path}</span>
+              <strong>{page.visitors}</strong>
+            </div>
+          ))}
+        </div>
+        <div className="aa-mini-panel">
+          <h3>Top Events</h3>
+          {liveState.evidence.topEvents.map((event) => (
+            <div className="aa-mini-row" key={event.event}>
+              <span>{event.event}</span>
+              <strong>{event.count}</strong>
+            </div>
+          ))}
+        </div>
+      </div>
+      <div className="aa-feed">
+        {liveState.evidence.recentEvents.map((event) => (
+          <div className="aa-feed-row" key={event.id}>
+            <div>
+              <strong>{event.event}</strong>
+              <span>{event.assetLabel || 'Unmapped asset'} · {event.path || 'no path'} · {event.country || '??'}</span>
+            </div>
+            <time>{formatRelativeTime(event.timestamp)}</time>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function AssetCard({ asset, onSnooze, basePath }) {
+  return (
+    <article className={`aa-asset-card aa-asset-card-${asset.kind}`}>
+      <div className="aa-asset-topline">
+        <div>
+          <p className="aa-kicker">{asset.kind}</p>
+          <h3>{asset.label}</h3>
+        </div>
+        <span className={`aa-status-pill aa-status-${asset.status}`}>{asset.status}</span>
+      </div>
+
+      <div className="aa-asset-metrics">
+        <div>
+          <span>Visitors</span>
+          <strong>{asset.activeVisitors}</strong>
+        </div>
+        <div>
+          <span>Sessions</span>
+          <strong>{asset.activeSessions}</strong>
+        </div>
+        <div>
+          <span>Events / min</span>
+          <strong>{asset.eventsPerMinute}</strong>
+        </div>
+      </div>
+
+      <div className="aa-asset-details">
+        <div>
+          <span className="aa-label">Project</span>
+          <strong>{asset.agentAnalyticsProject}</strong>
+        </div>
+        <div>
+          <span className="aa-label">Hot country</span>
+          <strong>{asset.lastHotCountry || 'Waiting for stream'}</strong>
+        </div>
+        <div>
+          <span className="aa-label">Updated</span>
+          <strong>{formatRelativeTime(asset.lastUpdatedAt)}</strong>
+        </div>
+      </div>
+
+      <div className="aa-asset-evidence">
+        <div>
+          <span className="aa-label">Top page</span>
+          <strong>{asset.topPages[0]?.path || 'No pages yet'}</strong>
+        </div>
+        <div>
+          <span className="aa-label">Top event</span>
+          <strong>{asset.topEvents[0]?.event || 'No events yet'}</strong>
+        </div>
+      </div>
+
+      <div className="aa-asset-actions">
+        {asset.paperclipProjectId ? (
+          <a className="aa-button aa-button-secondary" href={`${basePath || ''}/projects/${asset.paperclipProjectId}`}>
+            Open mapped project
+          </a>
+        ) : (
+          <span className="aa-muted-note">No Paperclip project linked yet</span>
+        )}
+        <button className="aa-button aa-button-ghost" onClick={() => onSnooze(asset.assetKey)}>
+          Snooze 30m
+        </button>
+      </div>
+    </article>
+  );
+}
+
+export function PageSurface({ liveState, onSnooze, basePath = '' }) {
+  return (
+    <div className="aa-page-shell">
+      <header className="aa-hero">
+        <div>
+          <p className="aa-kicker">Agent Analytics Live</p>
+          <h1>Ambient pulse for the company, backed by raw evidence.</h1>
+          <p className="aa-hero-copy">{liveState.connection.detail}</p>
+        </div>
+        <div className="aa-hero-status">
+          <span className={`aa-status-pill aa-status-${liveState.connection.status}`}>{liveState.connection.label}</span>
+          <p>{liveState.account?.email || 'No connected account'}</p>
+        </div>
+      </header>
+
+      <section className="aa-metric-grid">
+        <div className="aa-metric-card">
+          <span>Active visitors</span>
+          <strong>{liveState.metrics.activeVisitors}</strong>
+        </div>
+        <div className="aa-metric-card">
+          <span>Active sessions</span>
+          <strong>{liveState.metrics.activeSessions}</strong>
+        </div>
+        <div className="aa-metric-card">
+          <span>Events / min</span>
+          <strong>{liveState.metrics.eventsPerMinute}</strong>
+        </div>
+        <div className="aa-metric-card">
+          <span>Visible assets</span>
+          <strong>{liveState.metrics.assetsVisible}</strong>
+        </div>
+      </section>
+
+      <div className="aa-main-grid">
+        <CountryPulse liveState={liveState} />
+        <EvidenceColumn liveState={liveState} />
+      </div>
+
+      <section className="aa-assets-section">
+        <div className="aa-panel-header">
+          <div>
+            <p className="aa-kicker">Mapped Assets</p>
+            <h2>Each card ties live movement back to an owned company asset.</h2>
+          </div>
+        </div>
+        <div className="aa-asset-grid">
+          {liveState.assets.map((asset) => (
+            <AssetCard key={asset.assetKey} asset={asset} onSnooze={onSnooze} basePath={basePath} />
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}
+

package/src/ui/surfaces/SettingsSurface.jsx

@@ -0,0 +1,236 @@
+import { useState } from 'react';
+
+const EMPTY_MAPPING = {
+  assetKey: '',
+  label: '',
+  kind: 'website',
+  paperclipProjectId: '',
+  agentAnalyticsProject: '',
+  primaryHostname: '',
+  enabled: true,
+};
+
+function MappingRow({ mapping, onRemove }) {
+  return (
+    <div className="aa-settings-row">
+      <div>
+        <strong>{mapping.label}</strong>
+        <span>{mapping.kind} · {mapping.agentAnalyticsProject}</span>
+      </div>
+      <button className="aa-button aa-button-ghost" onClick={() => onRemove(mapping.assetKey)}>
+        Remove
+      </button>
+    </div>
+  );
+}
+
+export function SettingsSurface({
+  settingsData,
+  onStartAuth,
+  onCompleteAuth,
+  onReconnect,
+  onDisconnect,
+  onSaveSettings,
+  onUpsertMapping,
+  onRemoveMapping,
+}) {
+  const [formState, setFormState] = useState(() => ({
+    agentAnalyticsBaseUrl: settingsData.settings.agentAnalyticsBaseUrl,
+    liveWindowSeconds: settingsData.settings.liveWindowSeconds,
+    pollIntervalSeconds: settingsData.settings.pollIntervalSeconds,
+    pluginEnabled: settingsData.settings.pluginEnabled,
+  }));
+  const [mappingForm, setMappingForm] = useState(EMPTY_MAPPING);
+  const [exchangeCode, setExchangeCode] = useState('');
+
+  return (
+    <div className="aa-settings-shell">
+      <section className="aa-panel">
+        <div className="aa-panel-header">
+          <div>
+            <p className="aa-kicker">Connection</p>
+            <h2>Login-first auth, worker-held tokens.</h2>
+          </div>
+          <span className={`aa-status-pill aa-status-${settingsData.auth.status}`}>{settingsData.auth.status}</span>
+        </div>
+
+        <div className="aa-settings-grid">
+          <div className="aa-settings-stack">
+            <div className="aa-settings-row">
+              <div>
+                <strong>Connected account</strong>
+                <span>{settingsData.auth.accountSummary?.email || 'Not connected'}</span>
+              </div>
+              {settingsData.auth.connected ? (
+                <button className="aa-button aa-button-secondary" onClick={onDisconnect}>Disconnect</button>
+              ) : (
+                <button className="aa-button aa-button-primary" onClick={onStartAuth}>Start login</button>
+              )}
+            </div>
+
+            {settingsData.auth.pendingAuthRequest ? (
+              <div className="aa-auth-box">
+                <label>
+                  Approval URL
+                  <a href={settingsData.auth.pendingAuthRequest.authorizeUrl} target="_blank" rel="noreferrer">
+                    {settingsData.auth.pendingAuthRequest.authorizeUrl}
+                  </a>
+                </label>
+                <label>
+                  Finish code
+                  <input value={exchangeCode} onChange={(event) => setExchangeCode(event.target.value)} placeholder="Paste finish code" />
+                </label>
+                <div className="aa-inline-actions">
+                  <button className="aa-button aa-button-primary" onClick={() => onCompleteAuth(settingsData.auth.pendingAuthRequest.authRequestId, exchangeCode)}>
+                    Complete login
+                  </button>
+                  <button className="aa-button aa-button-ghost" onClick={onReconnect}>Refresh session</button>
+                </div>
+              </div>
+            ) : null}
+          </div>
+
+          <div className="aa-mini-panel">
+            <h3>Discovered projects</h3>
+            {(settingsData.discoveredProjects || []).map((project) => (
+              <div className="aa-mini-row" key={project.id || project.name}>
+                <span>{project.name}</span>
+                <strong>{project.allowed_origins || '*'}</strong>
+              </div>
+            ))}
+          </div>
+        </div>
+      </section>
+
+      <section className="aa-panel">
+        <div className="aa-panel-header">
+          <div>
+            <p className="aa-kicker">Rollout Controls</p>
+            <h2>Keep the live window short and the poll cadence explicit.</h2>
+          </div>
+        </div>
+
+        <div className="aa-form-grid">
+          <label>
+            Agent Analytics base URL
+            <input
+              value={formState.agentAnalyticsBaseUrl}
+              onChange={(event) => setFormState((current) => ({ ...current, agentAnalyticsBaseUrl: event.target.value }))}
+            />
+          </label>
+          <label>
+            Live window seconds
+            <input
+              type="number"
+              value={formState.liveWindowSeconds}
+              onChange={(event) => setFormState((current) => ({ ...current, liveWindowSeconds: Number(event.target.value) }))}
+            />
+          </label>
+          <label>
+            Poll interval seconds
+            <input
+              type="number"
+              value={formState.pollIntervalSeconds}
+              onChange={(event) => setFormState((current) => ({ ...current, pollIntervalSeconds: Number(event.target.value) }))}
+            />
+          </label>
+          <label className="aa-checkbox">
+            <input
+              type="checkbox"
+              checked={formState.pluginEnabled}
+              onChange={(event) => setFormState((current) => ({ ...current, pluginEnabled: event.target.checked }))}
+            />
+            Plugin enabled
+          </label>
+        </div>
+
+        <div className="aa-inline-actions">
+          <button className="aa-button aa-button-primary" onClick={() => onSaveSettings(formState)}>
+            Save controls
+          </button>
+          <button className="aa-button aa-button-ghost" onClick={onReconnect}>
+            Revalidate connection
+          </button>
+        </div>
+      </section>
+
+      <section className="aa-panel">
+        <div className="aa-panel-header">
+          <div>
+            <p className="aa-kicker">Asset Mapping</p>
+            <h2>Explicit Paperclip asset to Agent Analytics project links.</h2>
+          </div>
+        </div>
+
+        <div className="aa-form-grid">
+          <label>
+            Asset key
+            <input value={mappingForm.assetKey} onChange={(event) => setMappingForm((current) => ({ ...current, assetKey: event.target.value }))} />
+          </label>
+          <label>
+            Label
+            <input value={mappingForm.label} onChange={(event) => setMappingForm((current) => ({ ...current, label: event.target.value }))} />
+          </label>
+          <label>
+            Kind
+            <select value={mappingForm.kind} onChange={(event) => setMappingForm((current) => ({ ...current, kind: event.target.value }))}>
+              <option value="website">website</option>
+              <option value="docs">docs</option>
+              <option value="app">app</option>
+              <option value="api">api</option>
+              <option value="other">other</option>
+            </select>
+          </label>
+          <label>
+            Paperclip project ID
+            <input value={mappingForm.paperclipProjectId} onChange={(event) => setMappingForm((current) => ({ ...current, paperclipProjectId: event.target.value }))} />
+          </label>
+          <label>
+            Agent Analytics project
+            <input value={mappingForm.agentAnalyticsProject} onChange={(event) => setMappingForm((current) => ({ ...current, agentAnalyticsProject: event.target.value }))} />
+          </label>
+          <label>
+            Primary hostname
+            <input value={mappingForm.primaryHostname} onChange={(event) => setMappingForm((current) => ({ ...current, primaryHostname: event.target.value }))} />
+          </label>
+          <label className="aa-checkbox">
+            <input
+              type="checkbox"
+              checked={mappingForm.enabled}
+              onChange={(event) => setMappingForm((current) => ({ ...current, enabled: event.target.checked }))}
+            />
+            Enabled
+          </label>
+        </div>
+
+        <div className="aa-inline-actions">
+          <button
+            className="aa-button aa-button-primary"
+            onClick={() => {
+              onUpsertMapping(mappingForm);
+              setMappingForm(EMPTY_MAPPING);
+            }}
+          >
+            Save mapping
+          </button>
+        </div>
+
+        <div className="aa-settings-stack">
+          {settingsData.settings.monitoredAssets.map((mapping) => (
+            <MappingRow key={mapping.assetKey} mapping={mapping} onRemove={onRemoveMapping} />
+          ))}
+        </div>
+      </section>
+
+      {settingsData.validation.warnings.length > 0 ? (
+        <section className="aa-panel aa-panel-warning">
+          <h3>Warnings</h3>
+          {settingsData.validation.warnings.map((warning) => (
+            <p key={warning}>{warning}</p>
+          ))}
+        </section>
+      ) : null}
+    </div>
+  );
+}
+

package/src/ui/surfaces/WidgetSurface.jsx

@@ -0,0 +1,37 @@
+export function WidgetSurface({ widget, fullPageHref = '?surface=page' }) {
+  return (
+    <section className="aa-widget">
+      <div className="aa-widget-header">
+        <div>
+          <p className="aa-kicker">Live Status</p>
+          <h2>{widget.connection.label}</h2>
+        </div>
+        <span className={`aa-status-pill aa-status-${widget.connection.status}`}>{widget.tier || 'tier unknown'}</span>
+      </div>
+
+      <div className="aa-widget-metrics">
+        <div>
+          <span>Visitors</span>
+          <strong>{widget.metrics.activeVisitors}</strong>
+        </div>
+        <div>
+          <span>Sessions</span>
+          <strong>{widget.metrics.activeSessions}</strong>
+        </div>
+        <div>
+          <span>EPM</span>
+          <strong>{widget.metrics.eventsPerMinute}</strong>
+        </div>
+      </div>
+
+      <div className="aa-widget-footer">
+        <div>
+          <span className="aa-label">Top asset</span>
+          <strong>{widget.topAsset?.label || 'No live assets yet'}</strong>
+        </div>
+        <a className="aa-button aa-button-secondary" href={fullPageHref}>Open full live page</a>
+      </div>
+    </section>
+  );
+}
+

package/src/worker/index.js

@@ -0,0 +1,36 @@
+import { ACTION_KEYS, DATA_KEYS, PLUGIN_DISPLAY_NAME, PLUGIN_ID } from '../shared/constants.js';
+import { PaperclipLiveAnalyticsService } from './service.js';
+
+export const manifest = {
+  id: PLUGIN_ID,
+  displayName: PLUGIN_DISPLAY_NAME,
+  entrypoints: {
+    worker: './src/worker/index.js',
+    ui: './dist',
+  },
+  data: DATA_KEYS,
+  actions: ACTION_KEYS,
+  surfaces: ['page', 'dashboardWidget', 'settingsPage'],
+};
+
+export async function setup(ctx) {
+  const service = new PaperclipLiveAnalyticsService(ctx);
+  await service.register();
+
+  return {
+    async shutdown() {
+      await service.shutdown();
+    },
+    async health() {
+      return {
+        ok: true,
+        plugin: PLUGIN_ID,
+      };
+    },
+    async onConfigChange({ companyId }) {
+      await service.ensureLiveState(companyId, { forceSync: true });
+    },
+  };
+}
+
+export default manifest;

package/src/worker/paperclip.js

@@ -0,0 +1,37 @@
+import { LIVE_STREAM_CHANNEL } from '../shared/constants.js';
+
+export async function registerDataHandler(ctx, key, handler) {
+  if (ctx?.data?.register) {
+    return ctx.data.register(key, handler);
+  }
+  if (ctx?.registerData) {
+    return ctx.registerData(key, handler);
+  }
+  throw new Error(`Paperclip data registration is unavailable for key "${key}"`);
+}
+
+export async function registerActionHandler(ctx, key, handler) {
+  if (ctx?.actions?.register) {
+    return ctx.actions.register(key, handler);
+  }
+  if (ctx?.registerAction) {
+    return ctx.registerAction(key, handler);
+  }
+  throw new Error(`Paperclip action registration is unavailable for key "${key}"`);
+}
+
+export async function openLiveChannel(ctx, companyId) {
+  if (!ctx?.streams?.open) return;
+  await ctx.streams.open(LIVE_STREAM_CHANNEL, companyId);
+}
+
+export async function emitLiveState(ctx, companyId, payload) {
+  if (!ctx?.streams?.emit) return;
+  await ctx.streams.emit(LIVE_STREAM_CHANNEL, payload);
+}
+
+export async function closeLiveChannel(ctx, companyId) {
+  if (!ctx?.streams?.close) return;
+  await ctx.streams.close(LIVE_STREAM_CHANNEL, companyId);
+}
+