# `@geenius/analytics`

Privacy-first analytics primitives, UI components, and backend provider helpers for Geenius applications across shared runtime, React, React CSS, SolidJS, SolidJS CSS, Convex, Neon, Cloudflare KV, and Memory entrypoints.

## Install

```bash
pnpm add @geenius/analytics
```

Install the framework peers you use in your application:

```bash
pnpm add react react-dom
pnpm add solid-js
pnpm add convex
pnpm add @neondatabase/serverless drizzle-orm
```

## Current Run Scope

The current package gauntlet is driven by [`variants.json`](./variants.json) and
the Omega scope file. These UI variants are active: `react`, `react-css`,
`solidjs`, `solidjs-css`, and `react-native`. The DB providers `convex`, `neon`,
`cloudflareKV`, and `memory` are active.

Deferred UI-library adapters remain declared in the canonical manifest with
`inScope: false` and are excluded from local build, type-check, Storybook,
Playwright, size, and coverage sweeps until the run scope changes.

The deferred adapters are `react-ant`, `react-chakra`, `react-daisyui`,
`react-heroui`, `react-mantine`, `react-mui`, `react-shadcn`, `solidjs-ark`,
`solidjs-kobalte`, and `solidjs-solidui`.

## Public Imports

Shared utilities from the root export:

```ts
import {
  createTracker,
  defaultAnalyticsConfig,
  analyzeFunnel,
} from '@geenius/analytics'
```

Shared validators and privacy helpers are also exported from the root. Do not
import a `shared` subpath; implementation packages stay private.
UI providers/components/hooks are exported from UI variant subpaths, DB stores
from DB provider subpaths, and Convex functions from `@geenius/analytics/convex`.
Use `cloudflareKV` for provider ids and public imports; lowercase driver labels
such as `cloudflare-kv` are implementation metadata.

```ts
import {
  AnalyticsEventSchema,
  sanitizeAnalyticsEvent,
} from '@geenius/analytics'
```

React hooks, providers, and Tailwind-based UI:

```tsx
import {
  AnalyticsProvider,
  StatsCard,
  useAnalytics,
} from '@geenius/analytics/react'
```

React vanilla-CSS components:

```tsx
import '@geenius/analytics/react-css/styles.css'
import {
  AnalyticsProvider,
  StatsCard,
} from '@geenius/analytics/react-css'
```

The `react-css` entrypoint ships a standalone stylesheet for host-app theming.

SolidJS primitives, providers, and Tailwind-based UI:

```tsx
import {
  AnalyticsProvider,
  StatsCard,
  createAnalytics,
} from '@geenius/analytics/solidjs'
```

SolidJS vanilla-CSS components:

```tsx
import '@geenius/analytics/solidjs-css/styles.css'
import {
  AnalyticsProvider,
  StatsCard,
} from '@geenius/analytics/solidjs-css'
```

The `solidjs-css` entrypoint ships a standalone stylesheet for host-app theming.

Convex schema, queries, and mutations:

```ts
import {
  analyticsSchema,
  trackEvent,
  getRealtimeStats,
} from '@geenius/analytics/convex'
```

Neon, Cloudflare KV, and Memory stores:

```ts
import { createCloudflareKVAnalyticsStore } from '@geenius/analytics/cloudflareKV'
import { createMemoryAnalyticsStore } from '@geenius/analytics/memory'
import { createNeonAnalyticsStore } from '@geenius/analytics/neon'
```

React Native components and primitives:

```tsx
import {
  AnalyticsProvider,
  MetricCard,
  useAnalytics,
} from '@geenius/analytics/react-native'
```

## Basic Usage

```tsx
import {
  AnalyticsProvider,
  StatsCard,
  useAnalytics,
} from '@geenius/analytics/react'
import { defaultAnalyticsConfig } from '@geenius/analytics'

function OverviewCard() {
  const analytics = useAnalytics()

  async function handleOpen(): Promise<void> {
    await analytics.track('dashboard_opened', {
      surface: 'overview',
    })
  }

  return (
    <button onClick={() => void handleOpen()}>
      <StatsCard
        label="Unique visitors"
        value="12,480"
        change="+6.4%"
        trend="up"
      />
    </button>
  )
}

export function AnalyticsExample() {
  return (
    <AnalyticsProvider
      config={{
        ...defaultAnalyticsConfig,
        trackPageViews: true,
        debug: false,
      }}
    >
      <OverviewCard />
    </AnalyticsProvider>
  )
}
```

## Storybook Review Apps

This package includes V2 Storybook v10 review apps for the active UI variants in
`variants.json`. Deferred Storybook shells may remain on disk, but the package
build and test scripts filter them out by default.

```bash
pnpm storybook:react
pnpm storybook:react-css
pnpm storybook:solidjs
pnpm storybook:solidjs-css
```

Production verification uses:

```bash
pnpm storybook:react:build
pnpm test:storybook:build
pnpm test:storybook
```

## Contributing tests

The test matrix is driven by [`variants.json`](./variants.json). Re-include a
deferred launch variant there first, then update the matching package under
`packages/`, public export in `package.json`, harness registration, and
Storybook app. Do not add one-off variant arrays to scripts or Playwright
config.

Every package subdirectory must keep the TypeScript config trio:
`tsconfig.json`, `tsconfig.typecheck.json`, and `tsconfig.build.json`. The
convention suites under `__tests__/conventions/` enforce workspace deps,
tsconfig shape, public surface, Storybook V2 app shape, and ecosystem
consumption.

Common gates:

```bash
pnpm lint
pnpm type-check
pnpm test:unit
pnpm test:packed-smoke
pnpm test:coverage
pnpm test:coverage:diff
pnpm size
pnpm audit:supply-chain
pnpm test:gauntlet
pnpm test:all
```

Visual regression is default-on in Playwright. For fast local loops only, set `PW_VISUAL=0`; update committed baselines with `pnpm test:visual --update-snapshots`.

## License

Functional Source License 1.1 with Apache-2.0 future license. See [LICENSE](./LICENSE).