# @suaveplan/ab-testing - Enterprise A/B testing and experimentation: deterministic FNV-1a bucketing, targeting rules, variant assignment, conversion tracking, and OTel instrumentation

## Summary

Enterprise A/B testing and experimentation engine with deterministic FNV-1a bucketing, targeting rules, variant assignment, conversion tracking, result aggregation, and OpenTelemetry instrumentation.

<!-- begin:auto-docs -->
## Documentation tree

- [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [providers](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [provider](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [common](./src/types/common.md) — Defines the shared TypeScript interfaces and type aliases that form the public contract of `@suaveplan/ab-testing`. Eve…
- [schemas](./src/types/schemas.md) — Provides Zod validation schemas for all public input types in `@suaveplan/ab-testing`. These schemas serve as the singl…
<!-- end:auto-docs -->  - [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [providers](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [common](./src/types/common.md) — Defines the shared TypeScript interfaces and type aliases that form the public contract of `@suaveplan/ab-testing`. Eve…
- [schemas](./src/types/schemas.md) — Provides Zod validation schemas for all public input types in `@suaveplan/ab-testing`. These schemas serve as the singl…
- [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [providers](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [common](./src/types/common.md) — Defines the shared TypeScript interfaces and type aliases that form the public contract of `@suaveplan/ab-testing`. Eve…
- [schemas](./src/types/schemas.md) — Provides Zod validation schemas for all public input types in `@suaveplan/ab-testing`. These schemas serve as the singl…
- [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [providers](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [common](./src/types/common.md) — Defines the shared TypeScript interfaces and type aliases that form the public contract of `@suaveplan/ab-testing`. Eve…
- [schemas](./src/types/schemas.md) — Provides Zod validation schemas for all public input types in `@suaveplan/ab-testing`. These schemas serve as the singl…
- [bucketing](./src/bucketing/bucketing.md) — <!-- begin:auto-docs --> _(no submodules)_- [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_  - [experiment-manager](./src/core/experiment-manager/experiment-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [providers](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_  - [provider](./src/providers/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_  - [results](./src/results/results.md) — <!-- begin:auto-docs --> _(no submodules)_- [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_  - [targeting](./src/targeting/targeting.md) — <!-- begin:auto-docs --> _(no submodules)_- [common](./src/types/common.md) — Defines the shared TypeScript interfaces and type aliases that form the public contract of `@suaveplan/ab-testing`. Eve…
- [schemas](./src/types/schemas.md) — Provides Zod validation schemas for all public input types in `@suaveplan/ab-testing`. These schemas serve as the singl…

## Features

- **Deterministic bucketing** — FNV-1a 32-bit hash maps `(userId, experimentId)` to a stable variant with configurable seed
- **Targeting rules** — eight operators (`eq`, `neq`, `in`, `notIn`, `gt`, `lt`, `gte`, `lte`) evaluated with AND logic
- **Sample rate** — fraction-based inclusion gate via injectable RNG for deterministic testing
- **Assignment caching** — repeat `assign()` calls for the same user always return the same variant
- **Conversion tracking** — named metric events with numeric values, aggregated per variant
- **Provider API** — plug in external platforms via `ExperimentProvider` for forced assignments and event forwarding
- **OTel instrumentation** — `ab.assign` span, `ab.assignments_total` counter, `ab.conversions_total` counter
- **Event bus** — emits `ab:assigned` and `ab:conversion` events on an injectable `EventBusLike`
- **Zod validation** — all experiment definitions and metric events are validated at the boundary
- **Injectable dependencies** — `clock`, `rng`, `logger`, `eventBus`, `hashSeed` for deterministic testing

## Installation

```bash
bun add @suaveplan/ab-testing
```

## Quick Start

```ts
import { createExperimentManager } from '@suaveplan/ab-testing';

const manager = createExperimentManager();

manager.defineExperiment({
  id: 'checkout-cta',
  name: 'Checkout CTA Colour',
  status: 'running',
  variants: [
    { id: 'ctrl',  name: 'Blue',  weight: 1, isControl: true },
    { id: 'treat', name: 'Green', weight: 1 },
  ],
  primaryMetric: 'checkout_started',
});

const assignment = manager.assign('checkout-cta', 'user-123');

if (assignment.inExperiment) {
  console.log(`Variant: ${assignment.variantId}`);
}

// Track a conversion
manager.track('checkout-cta', 'user-123', { name: 'checkout_started' });

// Read results
const results = manager.getResults('checkout-cta');
console.log(`Conversion rate: ${results.variants[0]?.conversionRate}`);
```

## Module Documentation

| Module | Description |
|---|---|
| [`src/types/common.md`](src/types/common.md) | Core domain type interfaces |
| [`src/types/schemas.md`](src/types/schemas.md) | Zod validation schemas |
| [`src/core/experiment-manager/experiment-manager.md`](src/core/experiment-manager/experiment-manager.md) | Main manager implementation |
| [`src/bucketing/bucketing.md`](src/bucketing/bucketing.md) | FNV-1a bucketing primitives |
| [`src/targeting/targeting.md`](src/targeting/targeting.md) | Targeting rule evaluation |
| [`src/results/results.md`](src/results/results.md) | Results aggregation |
| [`src/providers/provider.md`](src/providers/provider.md) | Built-in provider implementations |

## Subpath Exports

```ts
import { createExperimentManager } from '@suaveplan/ab-testing';
import { bucketUser } from '@suaveplan/ab-testing/bucketing';
import { evaluateTargeting } from '@suaveplan/ab-testing/targeting';
import { computeResults } from '@suaveplan/ab-testing/results';
import { ForceVariantProvider, LoggingProvider } from '@suaveplan/ab-testing/providers';
import { AbTestingError, AB_CODES } from '@suaveplan/ab-testing/errors';
```