first commit
This commit is contained in:
111
docs/commerce/contacts/audience-rules/README.md
Normal file
111
docs/commerce/contacts/audience-rules/README.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# @suaveplan/audience-rules - Universal audience segmentation: rule-based filtering with 14 comparison operators, AND/OR chaining, dot-notation field resolution including array indices, three refresh modes (realtime/scheduled/manual), seven predicate factories, pluggable SegmentStore with InMemorySegmentStore (Clock + IdGenerator injectable), SegmentRefresher with typed EventBus emission, Zod-validated boundaries, and AudienceRulesError with stable AUDIENCE_RULES.* code registry.
|
||||
|
||||
Universal audience segmentation: rule-based filtering on contact data
|
||||
with 14 comparison operators, AND/OR chaining, dot-notation field
|
||||
resolution including array indices, three refresh modes
|
||||
(realtime/scheduled/manual), seven predicate factory helpers, a pluggable
|
||||
`SegmentStore` with an `InMemorySegmentStore` (injectable `Clock` +
|
||||
`IdGenerator`), and a `SegmentRefresher` that emits `segment:refreshed`
|
||||
on a typed `EventBus<SegmentRefresherEventMap>`. Inputs are
|
||||
Zod-validated; failures raise `AudienceRulesError` with a stable
|
||||
`AUDIENCE_RULES.*` code registry.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` defines the stable, namespaced error-code registry for the `@suaveplan/audience-rules` package, alongs…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` defines the stable, namespaced error-code registry for the `@suaveplan/audience-rules` package, alongs…
|
||||
- [predicates](./src/predicates/predicates.md) — `predicates.ts` ships seven factory functions that produce `SegmentRule` values for the most common audience filters: t…
|
||||
- [predicates](./src/predicates/predicates.md) — `predicates.ts` ships seven factory functions that produce `SegmentRule` values for the most common audience filters: t…
|
||||
- [schemas](./src/schemas/schemas.md) — `schemas.ts` exposes the Zod validators that guard every public input boundary on the `@suaveplan/audience-rules` store…
|
||||
- [schemas](./src/schemas/schemas.md) — `schemas.ts` exposes the Zod validators that guard every public input boundary on the `@suaveplan/audience-rules` store…
|
||||
- [segment-evaluator](./src/segment-evaluator/segment-evaluator.md) — `segment-evaluator.ts` provides the pure-function rule engine that decides, for a given `Segment` and a tenant's `Conta…
|
||||
- [segment-evaluator](./src/segment-evaluator/segment-evaluator.md) — `segment-evaluator.ts` provides the pure-function rule engine that decides, for a given `Segment` and a tenant's `Conta…
|
||||
- [segment-refresher](./src/segment-refresher/segment-refresher.md) — `segment-refresher.ts` orchestrates re-evaluation of one or many segments and persists the resulting `contactIds` back…
|
||||
- [segment-refresher](./src/segment-refresher/segment-refresher.md) — `segment-refresher.ts` orchestrates re-evaluation of one or many segments and persists the resulting `contactIds` back…
|
||||
- [store](./src/store/store.md) — `store.ts` defines the `SegmentStore` interface that abstracts segment persistence behind a six-method contract (`creat…
|
||||
- [store](./src/store/store.md) — `store.ts` defines the `SegmentStore` interface that abstracts segment persistence behind a six-method contract (`creat…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/audience-rules
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import {
|
||||
InMemorySegmentStore,
|
||||
SegmentEvaluator,
|
||||
SegmentRefresher,
|
||||
hasTag,
|
||||
statusIs,
|
||||
} from "@suaveplan/audience-rules";
|
||||
|
||||
const provider = async () => [
|
||||
{ id: "c1", tags: ["vip"], status: "active" },
|
||||
{ id: "c2", tags: ["basic"], status: "active" },
|
||||
{ id: "c3", tags: ["vip"], status: "unsubscribed" },
|
||||
];
|
||||
|
||||
const store = new InMemorySegmentStore();
|
||||
const evaluator = new SegmentEvaluator(provider);
|
||||
const refresher = new SegmentRefresher(store, evaluator);
|
||||
|
||||
const segment = await store.create({
|
||||
tenantId: "tenant-1",
|
||||
name: "Active VIPs",
|
||||
rules: [hasTag("vip"), statusIs("active")],
|
||||
refreshMode: "manual",
|
||||
});
|
||||
|
||||
refresher.events.on("segment:refreshed", ({ segmentId, result }) => {
|
||||
console.log(`${segmentId}: ${result.total} matches`);
|
||||
});
|
||||
|
||||
await refresher.refresh(segment.id);
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [error-codes](src/error-codes/error-codes.md) — `AUDIENCE_RULES_CODES`
|
||||
registry + `AudienceRulesError`.
|
||||
- [schemas](src/schemas/schemas.md) — Zod validators + `parseOrThrow`.
|
||||
- [store](src/store/store.md) — `SegmentStore` interface +
|
||||
`InMemorySegmentStore` with `Clock` + `IdGenerator` injection.
|
||||
- [segment-evaluator](src/segment-evaluator/segment-evaluator.md) —
|
||||
14-operator rule engine with dot-notation field resolution and AND/OR
|
||||
chaining.
|
||||
- [segment-refresher](src/segment-refresher/segment-refresher.md) —
|
||||
re-evaluation orchestrator with typed `EventBus` emission.
|
||||
- [predicates](src/predicates/predicates.md) — seven `SegmentRule` factory
|
||||
helpers for tags, channels, status, activity dates, and metadata.
|
||||
|
||||
## Features
|
||||
|
||||
- 14 operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`,
|
||||
`not_contains`, `in`, `not_in`, `exists`, `not_exists`, `starts_with`,
|
||||
`ends_with`.
|
||||
- AND/OR logical chaining via `logicalOp` on each rule.
|
||||
- Dot-notation field paths with numeric array indices
|
||||
(`channels.0.type`).
|
||||
- Three refresh modes for cache policy: `realtime`, `scheduled`, `manual`.
|
||||
- Multi-tenant isolation via `tenantId` on `Segment` and `list`.
|
||||
- Predicate factories for the seven most common audience filters.
|
||||
- Pluggable storage — provide a `SegmentStore` implementation backed by
|
||||
the persistence layer of your choice. `InMemorySegmentStore` is the
|
||||
reference implementation.
|
||||
- Typed event emission via `EventBus<SegmentRefresherEventMap>` from
|
||||
`@suaveplan/events`.
|
||||
- Stable `AUDIENCE_RULES.*` code registry with `INVALID_INPUT`,
|
||||
`SEGMENT_NOT_FOUND`, `UNKNOWN_OPERATOR`, `PROVIDER_FAILED`.
|
||||
|
||||
## See also
|
||||
|
||||
- `@suaveplan/contacts` — contact and group management, provides the
|
||||
`ContactData` consumed by audience-rules.
|
||||
- `@suaveplan/events` — typed `EventBus<TMap>` substrate.
|
||||
- `@suaveplan/error` — `SuaveplanError` + `defineCodes`.
|
||||
|
||||
Reference in New Issue
Block a user