<!--
AUTO-GENERATED — DO NOT EDIT THIS FILE.
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
To change this document, edit the module-level JSDoc in src/index.ts.
Generated: 2026-10-16T23:28:50.774Z
-->

# @molecule/api-analytics-http

Generic HTTP analytics provider.

POSTs each `track()` / `identify()` / `page()` call as a small JSON document
to a configured first-party endpoint (the `url` option or the
`MOLECULE_ANALYTICS_URL` env var). No endpoint is assumed — when none is
configured the provider no-ops, so an unconfigured consumer never silently
phones home. Every POST is best-effort: network failures are swallowed
(logged only via the optional `onError` hook), so telemetry can never break
the CLI or service emitting it.

Built for first-party ingestion — molecule.dev's own tooling (the `mlcl`
CLI, the `molecule-mcp` server) uses this bond to emit usage telemetry into
the platform's existing analytics pipeline, dogfooding the same
`@molecule/api-analytics` interface scaffolded apps consume.

> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
> It is written to be read by coding agents as much as by people, and is generated from this
> package's source — edit `src/index.ts` JSDoc, not this file.

## Quick Start

```typescript
import { setProvider } from '@molecule/api-analytics'
import { createHttpAnalyticsProvider } from '@molecule/api-analytics-http'

setProvider(
  createHttpAnalyticsProvider({
    url: 'https://api.molecule.dev/v1/telemetry/cli',
    // Optional request tagging — defaults to 'unknown'.
    source: 'mlcl',
  }),
)
// track() now POSTs; failures are swallowed.
```

## Type

`provider`

## Installation

```bash
npm install @molecule/api-analytics-http @molecule/api-analytics
```

## API

### Interfaces

#### `HttpAnalyticsProviderOptions`

Options for {@link createHttpAnalyticsProvider}.

```typescript
interface HttpAnalyticsProviderOptions {
  /** Endpoint that receives the POSTs. Defaults to $MOLECULE_ANALYTICS_URL; no-op when neither is set. */
  url?: string
  /** Tag identifying the emitting tool ('mlcl', 'molecule-mcp', …). Defaults to 'unknown'. */
  source?: string
  /** Best-effort error observer (e.g. debug logging). Never throws. */
  onError?: (error: unknown) => void
  /** Abort emit after this many ms (default 5000). */
  timeoutMs?: number
}
```

### Functions

#### `createHttpAnalyticsProvider(options?)`

Build an HTTP analytics provider bound to the configured endpoint.

```typescript
function createHttpAnalyticsProvider(options?: HttpAnalyticsProviderOptions): AnalyticsProvider
```

## Core Interface

Implements `@molecule/api-analytics` interface.

## Injection Notes

### Runtime Dependencies

- `@molecule/api-analytics`

Wire format — one JSON object per call:

```json
{
  "kind": "track",              // "track" | "identify" | "page" | "group"
  "source": "mlcl",             // the `source` option
  "sentAt": "2026-09-19T…",     // ISO timestamp
  "event": { /* the AnalyticsEvent / user / pageView as given *\/ }
}
```

The receiving endpoint is expected to validate and allowlist (never trust a
remote client's event names) — see molecule-dev's `/v1/telemetry/cli` route
for the reference implementation. POSTs carry a 5-second timeout; a slow or
dead endpoint costs at most one aborted request, never a hang.

## E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt
each item to this app's actual screens/flows, and check every box off one
by one. A box you can't check is an integration bug to fix — not a skip:

- [ ] Each user action the app cares about (signup/login, a page or screen
      view, a purchase/conversion or other domain event) EMITS a `track()` /
      `page()` with the RIGHT event name + properties when performed in the UI —
      and the event is actually RECORDED, proven by reading it back, not by
      finding a `track(...)` call in source. Analytics is fire-and-forget to a
      third-party (Mixpanel/PostHog/Segment) that is NOT reachable in the sandbox
      and NOT captured by `read_activity` (that captures email/sms/push/webhook/
      channel, never analytics). So prove the wiring locally: read the event back
      from the app's own events store/dashboard/funnel if it has one, or bond a
      local recording/console provider for dev and confirm the call fired via
      `read_logs`.
- [ ] Events are ATTRIBUTED to the right identity: `identify({ userId, ... })`
      runs at signup/login so events carry that `userId`. Server-side has no
      ambient session — a `track()` / `page()` with neither `userId` nor
      `anonymousId` collapses every user into one shared "anonymous" identity.
      If the app tracks activity before login, confirm those `anonymousId` events
      associate/merge to the user on identify.
- [ ] Tracking is NON-BLOCKING. Unlike the app-side bond, these SERVER
      functions PROPAGATE provider failures (they reject when the provider does,
      and throw when none is bonded), so fire-and-forget is the CALLER's job:
      every call site wraps the call in `.catch()` / log-and-continue. Verify by
      forcing a failure (unbonded or erroring provider) — the user action
      (signup, checkout) still completes with no visible error and no added
      latency; the analytics await never blocks the response.
- [ ] PRIVACY — no secret or sensitive PII in event `properties` or identify
      `traits`: never a password, full card/PAN, CVV, auth token, or session
      cookie. Read the recorded event back and confirm only non-sensitive
      attributes (plan name, amount, item id) are present.
- [ ] If the app exposes analytics reports/dashboards/funnels, the numbers
      reflect REAL recorded events (perform an action, the matching count/funnel
      step increments) and are SCOPED — a user/org reads only its OWN analytics;
      no endpoint lets one org read another org's numbers (`group()` associates a
      user under the bond's group type, 'company' by default).
