@alphatrait/sdk

Browser SDK for TesterKit: wraps console and fetch, listens for global errors, records SPA URL changes and capture-phase clicks (outside [data-testerkit-exclude]), batches telemetry, and posts to your ingestion API (default POST /api/bug-report).

Install

Public package — no npm token required:

npm install @alphatrait/sdk
# or
pnpm add @alphatrait/sdk

Quick start

BugKit.init() enables background capture only — it does not render a bug icon. For the floating reporter UI, install @alphatrait/react and mount <TesterKitReporter /> (see that package’s README).

import { BugKit, shutdown } from "@alphatrait/sdk";

BugKit.init({
  projectId: "your-project-key",
  apiKey: "tk_publishable_key_from_testerkit", // required when ingest keys are enabled
  apiBaseUrl: "https://your-testerkit-dashboard.example", // TesterKit deployment origin
});

// later
BugKit.report({ metadata: { userComment: "…" } });

// on teardown (e.g. SPA route unmount)
shutdown();

Point apiBaseUrl at the host that serves your TesterKit /api/bug-report route (e.g. https://stk.alphatrait.com).

For the floating bug icon (stk demo UX), install @alphatrait/react@^0.1.2 — see docs/CUSTOMER-INTEGRATION.md or packages/react/README.md.

Security & privacy

This package is client-side only. It does not ship Supabase keys or service roles.

Ingest API keys (apiKey) are publishable credentials (like a Sentry DSN): they only allow posting telemetry to your TesterKit ingest routes, and the server binds each key to a single projectId. They will be visible in the browser network tab — rotate per site, never use Supabase service keys here.

Enable keys on the dashboard deployment with TESTERKIT_INGEST_KEYS and TESTERKIT_REQUIRE_INGEST_KEY=true (see repo .env.example).

Environment metadata (automatic):

• On init, captures metadata.device: browser, OS, device type, timezone, screen, connection, hardware hints, and capabilities.
• On each flush, captures metadata.page: URL, title, referrer, and viewport at send time.
• Disable with captureDeviceContext: false if needed for privacy.

What the SDK captures (by design):

• Console log lines (serialized arguments)
• fetch URLs, methods, status, timing (ingest URL is excluded)
• Global errors and unhandled rejections
• Page URLs (including SPA navigation)
• Click targets (tag, id, class, truncated visible text) — not password fields

Risks to plan for in production:

| Risk | Mitigation | |------|------------| | Tokens in URLs or console output | Use shouldIgnoreFetch to skip noisy/sensitive requests; avoid logging secrets | | Sensitive UI in screenshots / clicks | Mark containers with data-testerkit-exclude | | Open ingest API spam | Secure your server (/api/bug-report): rate limits, auth, or allowlists — not in this SDK | | Cross-origin posts | Ingest host must send appropriate CORS headers (TesterKit dashboard uses permissive CORS for ingestion) |

Ingest requests use credentials: "omit" (no cookies sent to the ingest URL).

Publish (maintainers)

cd packages/sdk
npm publish --access public

Development (monorepo)

Apps depend on "@alphatrait/sdk": "workspace:*". prepublishOnly compiles src/ → dist/ before upload. Only dist/ and this README are published.