tracwell
v0.6.2
Published
Privacy-aware browser analytics, optional server-side AI crawler tracking, and the tracwell CLI for coding agents
Maintainers
Readme
SDK
Browser analytics SDK for page views, custom events, identity, batching, and delivery retries that outlast short Collector outages.
Script installation
The production browser artifact is served from the existing Collector domain:
<script
defer
src="https://collect.tracwell.app/script.js"
data-project-key="tw_live_..."
data-collection-mode="private"
></script>Optional script attributes
| Attribute | Values | Default |
| --- | --- | --- |
| data-project-key | Your public project key (never a server key) | Required |
| data-collection-mode | private, product | private |
| data-consent | granted, required, denied | granted |
| data-respect-do-not-track | true, false | true |
Keep collection mode explicit and aligned with website settings. The generated
snippet omits default consent and Do Not Track attributes. Add
data-consent="required" to wait for consent before identity creation or event
collection. After the script loads, forward the visitor's saved choice and
subsequent changes using window.tracwell?.setConsent("granted") or
window.tracwell?.setConsent("denied"). An early call before the script loads
has no effect; initialize the consent integration after SDK load.
Only these four data attributes are supported. Use the npm SDK for other initialization options, including batching, persistence overrides, and a custom collector URL. The script reads attributes at load time and does not fetch configuration from the dashboard; update the installed snippet when changing website settings.
When consent and Do Not Track permit collection, loading the script captures the initial page view and exposes the same client
as window.tracwell for custom events:
window.tracwell?.track("signup_completed", { plan: "starter" });The script derives /v1/events from its own origin, so the same artifact works
against the loopback Collector during local development. The production bundle
reports SDK version 0.2.0, targets ES2022-capable browsers, and has the
accepted 5 KB (5,120-byte) gzip budget enforced by build:cdn.
Public API
Install the npm package:
pnpm add tracwellimport { createTracwell } from "tracwell";
const tracwell = createTracwell({
collectionMode: "private",
projectKey: "tw_live_...",
});
tracwell.track("signup_completed", { plan: "starter" });
tracwell.identify("customer_123");
const session = tracwell.getSession();createTracwell() starts collection immediately in the browser and captures
the initial page view by default. It must be called after the document is
available, not during server rendering.
Framework compatibility
The npm SDK is a framework-neutral ESM browser library. It has no React, Vue,
Svelte, Angular, router, or rendering-framework dependency. Importing it during
SSR is safe; call createTracwell() from that framework's browser mount or
hydration lifecycle after document is available.
Multi-page applications capture a page view each time the browser loads the
application. Single-page applications using the standard History API receive
automatic page views for pushState, replaceState, and back/forward
navigation. This covers the default path-based routers in modern web
frameworks. Hash fragments remain intentionally excluded from analytics URLs;
hash-only navigation does not create a page view.
Framework adapters should own only lifecycle integration and dependency injection. Event validation, identity, attribution, navigation observation, batching, retries, consent, and delivery remain in this core package.
Responsibilities
- Generate stable event and batch IDs before delivery.
- Capture initial page views, SPA navigation, referrer, UTM, and tagged-link context.
- Expose typed custom-event and identity APIs.
- Batch only against the limits exported by
@tracwell/contracts. - Retry transient failures with backoff without changing event IDs.
- Respect configured consent and Do Not Track behavior before collection.
The default SDK entry must remain browser-only, small, non-blocking, and unable to set trusted collector fields. It must not contain secrets or connect to ClickHouse. The separate server entry accepts a server-side key as documented below.
Identity and attribution
Collection mode is explicit:
privateis the default. It never reads or writes cookies,localStorage, orsessionStorage;identify()reportsIDENTIFY_UNAVAILABLE. Anonymous and session values exist only in memory until the collector replaces them.productpersists first-party anonymous, session, and optional user identity inlocalStorage. Configure consent before collection where required.Private mode rejects an explicit
persistence: "localStorage"instead of silently weakening the project's privacy behavior.anonymous_idis first-party and persists per project unless persistence is disabled or identity is reset.session_idrotates after 30 minutes without a captured event.A different non-empty UTM campaign starts a new session immediately.
The first external referrer and UTM values are preserved for the session.
The SDK preserves the absolute referrer. Trusted ClickHouse row mapping uses registered-domain/public-suffix parsing so sibling subdomains are not reported as external acquisition.
identify()validates the supplied opaque user ID before associating it with future events.Identifying a different user on the same installation rotates both anonymous identity and session before recording the new identity. Call
reset()on logout so an anonymous post-logout visit also starts cleanly.getSession()returns the active Product-modeanonymousId,sessionId, and optionaluserIdso a server-created checkout can carry the same identifiers into an authenticated revenue event. It returnsundefinedin Private mode, without consent, when Do Not Track blocks collection, or after shutdown.Treat the returned IDs as attribution context, not authorization. Revenue
user_idmust come from the authenticated account or verified payment webhook rather than a client-supplied value.Hash-only URL changes do not create duplicate SPA page views.
URL fragments are excluded from captured URLs and
pathcontains only the pathname.
Product identity uses localStorage, never fingerprinting. If storage is
disabled or unavailable, the SDK explicitly reports STORAGE_UNAVAILABLE
through onError and uses in-memory identity for the page lifetime.
Delivery semantics
- Events receive lightweight client preflight validation before entering memory. The Collector remains the canonical Zod validation boundary for all untrusted browser input.
- Normal cross-origin delivery uses a safelisted
text/plainJSON body so it does not add a CORS preflight request; the collector still parses and validates the body as JSON. - Batches default to 25 events and are reduced when necessary to remain within the shared 48 KiB limit.
- Normal delivery reports
acceptedonly after a matching202receipt confirms the batch ID and event count. - Network errors,
408,429, and5xxresponses are retried with backoff (2 s doubling, at most 5 minutes per wait) without changing event or batch IDs, until the oldest event nears the Collector's 24-hour age limit. An explicitmaxRetries(0-5) caps attempts; by default there is no fixed cap. Periodic flushes wait for a scheduled retry;flush()andshutdown()send immediately. - While delivery is failing at most 100 events are held; the oldest waiting
events are dropped and reported through
onError. - Product mode with
persistence: "localStorage"also stores held events undertracwell:<projectKey>:pendingand resumes them on the next page load. Private mode never writes them to browser storage. Denying consent clears them. Resending an event a beacon already delivered is safe: event IDs are stable and deduplicated. - Other
4xxresponses reportDELIVERY_REJECTEDand are not retried. - Page-hide and hidden-document delivery prefers
sendBeacon; a successful browser handoff reportshanded_off, neveraccepted. - Exhausted delivery is surfaced through
onErrorwith the affected event IDs.
The default collector endpoint is
https://collect.tracwell.app/v1/events. Production overrides must use HTTPS;
loopback HTTP is allowed only for local development.
Privacy controls
consent: "required"prevents identity creation and collection untilsetConsent("granted").- Revoking consent stops listeners, removes queued events, and resets identity.
- Do Not Track is respected by default and can be disabled explicitly per customer configuration.
persistence: "none"keeps all identifiers in memory.- Private collection forces
persistence: "none"and blocksidentify().
Structure
src/
index.ts Stable public exports and browser-only factory
script.ts Lean self-starting CDN entry and `window.tracwell` exposure
script-config.ts Strict script-dataset parsing and normalized CDN defaults
client.ts Consent-aware API and lifecycle orchestration
config.ts Defaults and configuration validation
identity.ts Anonymous, session, and user identity state
attribution.ts First-touch-per-session UTM and referrer capture
events.ts Context creation and contract-validated events
transport.ts Size-aware batching, receipts, beacon, and retries
preflight.ts Small client-side event and receipt checks
runtime.ts Browser API adapter
types.ts Public configuration, client, delivery, and error types
client.test.ts Deterministic SDK behavior and failure tests
index.test.ts SSR import and browser-initialization boundary
cli/ The `tracwell` command (Node only, own tsconfig.cli.json)
main.ts Commands, help and output
args.ts Flag parsing
config.ts Saved login and default website (0600 file)
oauth.ts Browser login, refresh and revoke
mcp.ts JSON-RPC client for `/mcp`
tool-arguments.ts Flags to tool arguments, --site/--days/requestId
install.ts Skill and AGENTS.md install into the current repo
definitions.ts `goals add` / `funnels add` step parsing
skills/tracwell/
SKILL.md Agent skill, shipped in the package and served at /skill.md
scripts/
build-cdn.mjs Minified browser build and gzip-size enforcement
build-npm.mjs Self-contained ESM package build, including dist/npm/cli.js
smoke-npm.mjs Packed runtime, TypeScript, CLI and skill consumer smoke test
static/
_headers Cross-origin browser asset headersKeep browser globals isolated in runtime.ts, keep index.ts as the stable
public API, and test behavior through an injected deterministic runtime.
Dependencies
@tracwell/contractsfor inferred types and shared limits- Browser platform APIs for navigation, lifecycle, and delivery
esbuildat build time for the minified browser artifact
The published npm artifact bundles its runtime contract constants and ships generated declarations, so consumers do not need the private contracts workspace. Compile-time compatibility checks keep the duplicated public property and issue types aligned with the canonical contracts package.
The npm package is distributed under the MIT License. Publishing the package does not make the private application repository public.
Verify
pnpm --filter {packages/sdk} typecheck
pnpm --filter {packages/sdk} test
pnpm --filter {packages/sdk} build:cdn
pnpm --filter {packages/sdk} check:packageServer-only AI crawler entry
tracwell/server exports trackAiCrawler(request, { serverKey, statusCode?,
collectorUrl? }). Import only on your backend; never expose tw_sk_
keys in browser code. This separate bundle adds nothing to the default browser
entry or CDN script. Available starting with npm package version 0.3.0. The unchanged browser
transport continues reporting browser SDK version 0.2.0.
Call from Next.js proxy/middleware or another server/edge handler. Pass the
promise to the hosting runtime's waitUntil (and inspect its result), or await
on a persistent server. Keep existing request handling intact. The helper ignores
ordinary traffic, API paths and common static assets. Robots, sitemap and Markdown
requests remain trackable. Handler/cache placement determines coverage.
Results are ignored, accepted (matching Queue receipt), or failed with a
non-sensitive error code. Three total attempts use the same event ID, timestamp
and sanitized URL. Retries are in memory only. Do not treat acceptance as confirmed
database persistence. Queries/fragments are stripped; no IP, cookies or other
request headers are sent. Raw UA is sent solely for collector classification and
is not stored. Current provider matches are user-agent based, not IP verified.
See the public /docs/ai-crawlers guide for setup and direct POST integration.
Use 0.3.1 or newer on Cloudflare Workers: crawler delivery uses manual redirect handling because Workers does not support the fetch redirect error mode. Redirect responses are rejected without forwarding the server key.
Version 0.4.0 expands server crawler recognition to 23 tokens across 12 providers. Existing server integrations must upgrade and redeploy to send newly supported crawlers; keys and browser installation are unchanged. The collector determines the purpose, including other for mixed/general crawling.
CLI
The package also installs a tracwell command for terminals and coding agents:
npx tracwell init --url https://acme.com # sign in, find or add the site, snippet, skill
npx tracwell login # browser sign-in; pick websites on the consent screen
npx tracwell sites add Acme https://acme.com
npx tracwell use <website-id>
npx tracwell snippet # install snippet for the website
npx tracwell verify # waiting / receiving
npx tracwell overview --days 30
npx tracwell goals add "Signed up" --event signup_completed --category signup
npx tracwell funnels add Checkout --steps /pricing,event:checkout_started
npx tracwell search funnel # find tools by keyword
npx tracwell call funnel_create --name Checkout --dry-run
npx tracwell help overview # arguments, read live from Tracwell
npx tracwell skill install # .agents/skills/tracwell (and .claude/skills if present)
npx tracwell agents-md installinit signs in if there is no saved login, then picks the website: --site,
else the one whose origin matches --url (it reads each website's install
record, since the list has no URLs), else creates it with website_create
(OAuth with "Add websites" only), else the saved or only website. It saves the
website as the default, prints the snippet, and runs skill install and
agents-md install. skill install leaves a copy that differs alone unless
--force; agents-md install replaces only the marked tracwell:start/end
block. --dry-run prints the tool, its arguments and whether it writes, without
calling it; it still reads the tool list, so it needs a login.
It is a thin client for the existing /mcp endpoint: each command is one
stateless tools/call, so the CLI has the same tools, permissions and plan
checks as MCP and needs no API of its own. Short commands cover the common
tools; tracwell call <tool> --arg value runs any other, and tracwell tools
lists what the current login can use. Output is JSON (--compact for one
line). Exit codes: 0 ok, 1 request failed, 2 bad input, 3 sign-in needed.
login registers a public OAuth client for a http://127.0.0.1:<port>/callback
redirect, opens the consent page with S256 PKCE and the /mcp resource, and
stores the access and refresh tokens. login --key, --key on any command, or
TRACWELL_API_KEY use an API key instead; keys cannot add websites. Credentials
live in $TRACWELL_CONFIG_DIR, else $XDG_CONFIG_HOME/tracwell or
~/.config/tracwell (%APPDATA%\tracwell on Windows), mode 0600. TRACWELL_URL
points the CLI at another Tracwell origin. login goes to TRACWELL_URL or
https://tracwell.app, never the saved login's address, so an old local login
cannot trap it; other commands use the address of the saved login. logout
revokes the OAuth grant and deletes the file.
The CLI is built as a separate Node 20 entry (dist/npm/cli.js); the browser
and tracwell/server entries never import it. skills/tracwell/SKILL.md is the
agent skill: sign in, add the site, install the snippet, verify, read reports.
The web build serves the same file at https://tracwell.app/skill.md.
