@createcms/core 0.1.1

package/dist/plugins/ab-test/index.d.ts

@@ -0,0 +1,1131 @@
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { PgDatabase, AnyPgTable } from 'drizzle-orm/pg-core';
+import { AnyColumn, SQL } from 'drizzle-orm';
+import * as better_call from 'better-call';
+import { ConsentState, ConsentPurpose } from '../consent/index.js';
+export { ConsentPurpose, ConsentSignal, ConsentState } from '../consent/index.js';
+
+type DrizzleInstance = PgDatabase<any, Record<string, unknown>, any>;
+
+declare const notificationTypeEnum: drizzle_orm_pg_core.PgEnum<["mention", "comment", "threadResolved", "approvalRequested", "approvalApproved", "approvalRejected", "mergeRequestOpened", "mergeRequestMerged", "mergeRequestClosed", "mergeRequestReopened", "published", "custom"]>;
+
+type NotificationType = (typeof notificationTypeEnum.enumValues)[number];
+type NotificationPayload = {
+    id: string;
+    recipientId: string;
+    actorId: string | null;
+    type: NotificationType;
+    title: string;
+    body: string | null;
+    resourceType: string | null;
+    resourceId: string | null;
+    collection: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: Date;
+};
+type OnNotificationHandler = (notification: NotificationPayload) => void | Promise<void>;
+type NotificationInput = Omit<NotificationPayload, 'id' | 'createdAt'>;
+
+type NotificationService = ReturnType<typeof createNotificationService>;
+declare function createNotificationService(db: DrizzleInstance, handlers: OnNotificationHandler[]): {
+    notify(input: NotificationInput): Promise<NotificationPayload>;
+    notifyMany(inputs: NotificationInput[]): Promise<NotificationPayload[]>;
+};
+
+type ResolvedUserConfig = {
+    table: AnyPgTable;
+    tableName: string;
+    schemaName: string | null;
+    idColumn: AnyColumn;
+    /** The camelCase key used in the Drizzle table definition (e.g. "id"). */
+    idColumnKey: string;
+    /** The actual database column name (e.g. "id" or "user_id"). */
+    idColumnDbName: string;
+    allColumns: Record<string, AnyColumn>;
+    /** Allowlist (camelCase keys) of columns exposable via `withUser`. */
+    exposeColumns: string[];
+    sqlTableRef: string;
+};
+
+type SchemaNamespace = 'cms';
+type ColumnScalarType = 'text' | 'boolean' | 'integer' | 'timestamp' | 'jsonb' | 'tsvector';
+type ColumnType<EnumTarget extends string = string> = ColumnScalarType | {
+    enum: EnumTarget;
+};
+type DefaultValue = {
+    kind: 'literal';
+    value: boolean | number | string | string[] | Record<string, unknown>;
+} | {
+    kind: 'sql';
+    value: string;
+};
+type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+type IndexUsing = 'btree' | 'gin';
+type ColumnDefinition<ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    type: ColumnType<EnumTarget>;
+    columnName?: string;
+    notNull?: boolean;
+    primaryKey?: boolean;
+    unique?: boolean;
+    default?: DefaultValue;
+    defaultId?: boolean;
+    defaultIdPrefix?: string;
+    defaultNow?: boolean;
+    jsonType?: string;
+    references?: {
+        table: ReferenceTarget;
+        column: string;
+        onDelete?: ForeignKeyAction;
+        onUpdate?: ForeignKeyAction;
+    };
+};
+type TableColumns<ReferenceTarget extends string = string, EnumTarget extends string = string> = Record<string, ColumnDefinition<ReferenceTarget, EnumTarget>>;
+type IndexDefinition<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+    unique?: boolean;
+    using?: IndexUsing;
+    where?: string;
+};
+type CompositePrimaryKey<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+};
+type TableLevelForeignKey<ColumnName extends string = string> = {
+    columns: readonly ColumnName[];
+    foreignTable: string;
+    foreignColumns: readonly string[];
+    name?: string;
+    onDelete?: ForeignKeyAction;
+    onUpdate?: ForeignKeyAction;
+};
+type TableDefinition<Columns extends TableColumns = TableColumns, ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    tableName?: string;
+    indexPrefix?: string;
+    columns: Columns;
+    indexes?: Record<string, IndexDefinition<Extract<keyof Columns, string>>>;
+    compositePrimaryKey?: CompositePrimaryKey<Extract<keyof Columns, string>>;
+    foreignKeys?: TableLevelForeignKey<Extract<keyof Columns, string>>[];
+};
+type EnumDefinition = {
+    values: readonly string[];
+    enumName?: string;
+};
+type EnumMap = Record<string, EnumDefinition>;
+type TableMap = Record<string, TableDefinition>;
+type SchemaModule<_Namespace extends SchemaNamespace = SchemaNamespace, Tables extends TableMap = {}, Enums extends EnumMap = {}, Extensions = {}> = {
+    enums?: Enums;
+    tables?: Tables;
+    extend?: Extensions;
+};
+
+/**
+ * Endpoint key used as a hook action identifier.
+ * Accepts any string so internal plumbing doesn't need the full union,
+ * but the exported `CMSEndpointKey` (from `index.ts`) provides a narrowed
+ * union with autocomplete for hook authors.
+ */
+type CMSHookAction = string & {};
+type CMSBeforeHookContext = {
+    action: CMSHookAction;
+    collection: string;
+    db: DrizzleInstance;
+    input: Record<string, unknown>;
+    /**
+     * The resolved per-request scope (tenant/i18n), available to before-hooks so
+     * they can tenant-scope any cross-resource reads they perform. Set by the
+     * endpoint wrapper before hooks run; may be undefined for hooks invoked
+     * outside that path.
+     */
+    scope?: ResolvedScope;
+};
+type CMSPluginContext = CMSProcedureCtx & {
+    collections: Record<string, CollectionWithName>;
+};
+
+/**
+ * Per-request scope produced by a ScopeConditionFactory.
+ * `where` — appended to SELECT/UPDATE/DELETE queries.
+ * `insertColumns` — snake_case column name → value pairs merged directly
+ *   into the raw SQL INSERT via `scopedInsert` / `scopedInsertBatch`.
+ */
+type TableScope = {
+    where?: SQL;
+    insertColumns?: Record<string, unknown>;
+};
+/**
+ * `roots` scope additionally supports a per-NEW-ENTRY column contributor: a
+ * plugin can compute fresh insert columns once per newly-created logical entry
+ * (e.g. a freshly minted translation-group id), which the static `insertColumns`
+ * channel (same value on every row) can't express. Called once per
+ * createRoot / root-duplication. Generic — core names no column. (Seam D.)
+ */
+type RootTableScope = TableScope & {
+    newEntryColumns?: () => Record<string, unknown>;
+    /**
+     * Scope columns to EXCLUDE from cross-scope read filtering — columns the
+     * plugin varies INDEPENDENTLY of a query so that cross-scope reads (a
+     * reference/host/usage that legitimately spans them) must not filter on them.
+     * The i18n plugin declares `['language']` (a host/reference in any sibling
+     * language still counts; the read path already resolved a specific sibling).
+     * Generic — core names no column; passed to `rootScopeConditions` as its
+     * `exclude`. Empty/absent → every scope column filters. (Seam D6.)
+     */
+    crossScopeExclude?: readonly string[];
+};
+/**
+ * A plugin-provided resolver for reference values (rootId / group-key strings),
+ * carried on the resolved scope and consumed by the read path and the A/B
+ * co-render walk. Core ships an IDENTITY default (`coreReferenceResolver`)
+ * reproducing the single-language, no-plugin behaviour byte-for-byte; the i18n
+ * plugin supplies a real one that understands translation groups + the fallback
+ * chain. Core never names any i18n concept — it knows only this interface.
+ *
+ * `db` AND `scopeColumns` are passed PER CALL (not closed over): `db` so a
+ * caller inside a transaction (e.g. the A/B →running guard under FOR UPDATE)
+ * resolves against its own tx handle; `scopeColumns` because the MERGED root
+ * scope columns (tenant + language) exist only AFTER every scope factory has
+ * run — the i18n factory that builds the resolver sees only its OWN column at
+ * build time. The resolver therefore closes over just its resolution POLICY
+ * (e.g. the i18n active language + fallback chain). `scopeColumns` is the
+ * scope predicate; the resolver excludes its own cross-scope columns.
+ * (Seam B.)
+ */
+type ReferenceResolver = {
+    /**
+     * Read-time render pick: stored reference value → the ONE rootId it renders
+     * as (omit a key to leave it unresolved). Identity default: `value → value`.
+     */
+    resolveRenderTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, collection: string, storedValues: string[]): Promise<Map<string, string>>;
+    /**
+     * Conflict superset: stored reference keys → ALL rootIds they could render as
+     * (a group key expands to its whole group). Used by the A/B co-render walk;
+     * collection-agnostic (a reference may target any collection). Identity
+     * default: the existing, non-archived roots among `storedKeys` (by id).
+     */
+    resolveConflictTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, storedKeys: string[]): Promise<string[]>;
+    /** rootIds → all their group siblings. Identity default: the input rootIds. */
+    expandGroup(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+    /** rootIds → the group keys a host could embed them by. Default: `[]`. */
+    groupKeysFor(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+};
+/** One variant branch of a running A/B test on a referenced root. */
+type RunningAbTestVariant = {
+    branchId: string;
+    isControl: boolean;
+};
+/** A running A/B test on one root: the test plus its variant branches. */
+type RunningAbTest = {
+    testId: string;
+    trafficPercentage: number;
+    variants: RunningAbTestVariant[];
+};
+/**
+ * A plugin-provided resolver that reports which referenced roots currently have
+ * a RUNNING A/B test (with that test's variant branches). Carried on the
+ * resolved scope and consumed by the read path's reference loader to fan the one
+ * XOR-guaranteed varying block's branches out to the client (AB_FANOUT F2). Core
+ * ships NO default — when absent (no ab-test plugin) the read path assumes no
+ * running tests and every embed stays on its deterministic single pick (F0).
+ * Core never names any A/B concept beyond this interface. (Seam F.)
+ */
+type AbTestResolver = {
+    /**
+     * The subset of `rootIds` that have a running test, each mapped to its test +
+     * variant branches. `db` AND `scopeColumns` are passed PER CALL (same
+     * rationale as {@link ReferenceResolver}). The caller passes already
+     * render-resolved (active-language) rootIds, so this needs no group expansion.
+     */
+    runningTests(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<Map<string, RunningAbTest>>;
+};
+type ResolvedScope = {
+    roots?: RootTableScope;
+    assets?: TableScope;
+    assetFolders?: TableScope;
+    redirects?: TableScope;
+    /**
+     * Plugin-provided reference resolver (i18n translation-group resolution). When
+     * absent, callers use core's identity default. Generic — see `ReferenceResolver`.
+     */
+    referenceResolver?: ReferenceResolver;
+    /**
+     * Plugin-provided running-A/B-test resolver (AB_FANOUT F2 server fan-out).
+     * When absent, the read path assumes no running tests. Generic — see
+     * {@link AbTestResolver}.
+     */
+    abTestResolver?: AbTestResolver;
+    /**
+     * Opaque per-plugin context slots, keyed by plugin id. Core never reads it;
+     * each plugin stashes its own per-request context here from a scope factory
+     * and reads it back via its own exported accessor. Merged generically in
+     * computeScope (shallow, last-writer-wins per slot).
+     */
+    pluginContext?: Record<string, unknown>;
+};
+/**
+ * Factory registered by plugins during `init`.
+ * Called once per request with the middleware result to produce
+ * table-level WHERE conditions and extra INSERT values.
+ */
+type ScopeConditionFactory = (mwResult: MiddlewareResult) => ResolvedScope;
+type CMSOperation = 'read' | 'create' | 'update' | 'delete';
+type BlockTypes = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    richText: string;
+    image: string;
+    select: string;
+    reference: string;
+};
+type BlockPropertyType = keyof BlockTypes;
+type SelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+type BlockPropertySpec<T extends BlockPropertyType> = {
+    type: T;
+    required?: boolean;
+    defaultValue?: BlockTypes[T];
+    label: string;
+    description?: string;
+    placeholder?: string;
+} & (T extends 'select' ? {
+    options: readonly SelectOption[];
+} : {}) & (T extends 'reference' ? {
+    collection: string;
+} : {});
+/** Discriminated union over all concrete block-property specs. */
+type BlockProperty = {
+    [K in BlockPropertyType]: BlockPropertySpec<K>;
+}[BlockPropertyType];
+/** Scalar property subset usable as an event parameter (no references/media). */
+type ScalarBlockProperty = Extract<BlockProperty, {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'date';
+}>;
+/**
+ * Declares a meaningful event a functional block can emit (e.g. a form's
+ * `submitSuccess`). Living on the block DEFINITION makes it the single source of
+ * truth for the typed `fire(...)` union, the test-creation goal picker, and the
+ * analytics wire name. `name` overrides the GA4/dataLayer wire name (defaults to
+ * `cms_<blockType>_<eventKey>`, computed by the measurement layer). Whether an
+ * event counts as a conversion is decided per test in the UI, not here.
+ */
+type EventDeclaration = {
+    /** Analytics wire-name override (snake_case). Defaults to cms_<type>_<key>. */
+    name?: string;
+    /** Typed parameters carried with the event (scalar only). */
+    params?: Record<string, ScalarBlockProperty>;
+    /** Human label for the goal picker. */
+    label?: string;
+};
+type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TEvents extends Record<string, EventDeclaration> = Record<string, never>> = {
+    properties: TProps;
+    label: string;
+    description?: string;
+    previewImageUrl?: string;
+    /** Events this (functional) block can emit — see {@link EventDeclaration}. */
+    events?: TEvents;
+} & ({
+    allowChildren?: false;
+} | {
+    allowChildren: true;
+    allowedChildBlocks?: string[];
+});
+type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
+type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: TProps;
+};
+type SlugConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    root: string;
+    allowRoot?: boolean;
+    normalize?: boolean;
+    nested?: boolean;
+};
+type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition> = Record<string, AnyBlockDefinition>> = {
+    slug?: SlugConfig;
+    root: RootDefinition<TProps>;
+    blocks?: TBlocks;
+    label: string;
+    description?: string;
+    /**
+     * Marks this collection as one whose roots are meant to be EMBEDDED into other
+     * roots via a `reference` property (a "reusable block" library). Purely an
+     * ergonomic hint — it informs editor pickers and which endpoints to surface; it
+     * NEVER gates safety (the delete-in-use guard protects every referenced root
+     * regardless of this flag). Any collection can still be a reference target.
+     */
+    reusableBlock?: boolean;
+};
+type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
+type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {
+    name: string;
+    blocks: Record<string, AnyBlockDefinition>;
+};
+type DataRetentionConfig = {
+    keepDays: number;
+    keepMinCommits: number;
+    /**
+     * Grace period (days) before a soft-archived root (`archivedAt`) is physically
+     * hard-deleted by pruning. Defaults to `keepDays` when omitted — a trash
+     * window after which the page and its whole history are reclaimed.
+     */
+    archiveKeepDays?: number;
+};
+/** Result that user middleware can return to extend context */
+type MiddlewareResult = {
+    userId?: string;
+    [key: string]: unknown;
+};
+/** Base ctx injected by withCMSContext middleware. */
+type CMSProcedureCtx = {
+    db: DrizzleInstance;
+    collections: Record<string, CollectionWithName>;
+    dataRetention?: DataRetentionConfig;
+    scopeConditions?: ScopeConditionFactory[];
+    notificationService?: NotificationService;
+    resolvedUser?: ResolvedUserConfig;
+};
+
+type CMSEndpointMeta = {
+    permissionResource?: string;
+    operation: CMSOperation;
+    scope: 'collection' | 'system';
+    collection?: string;
+    /**
+     * When `true`, this endpoint is intentionally exempt from the auth /
+     * permission / scope / hook chain — it handles its own access control
+     * (e.g. a public asset redirect). Every other endpoint must carry full
+     * `cms` metadata; `toCMSEndpoints` throws on a missing one (fail-closed).
+     */
+    public?: boolean;
+};
+
+/** One variant branch of the resolved test (enough for edge bucketing). */
+type ResolvedAbVariant = {
+    /** ab_test_variants.id — the `variantId` resolveVariant buckets to. */
+    variantId: string;
+    /** The published branch this variant renders. */
+    branchId: string;
+    weight: number;
+    isControl: boolean;
+};
+type AbResolveResult = {
+    test: {
+        testId: string;
+        /** The root the test attaches to (page root or an embedded block root). */
+        rootId: string;
+        trafficPercentage: number;
+        variants: ResolvedAbVariant[];
+    } | null;
+};
+
+type ABTestContext = {
+    key: string;
+    anonymous?: boolean;
+};
+
+/** Where an event originated — a functional block instance. */
+type CMSEventSource = {
+    /** Stable, author-assigned instance handle (the block's `trackingId`). */
+    handle?: string;
+    /** Block type that emitted the event (e.g. `'signupForm'`). */
+    type?: string;
+};
+/**
+ * The decoupled, analytics-agnostic event core. A/B attribution is **optional**
+ * (`ab`), so non-A/B events (page views, form submits) are first-class and can
+ * flow to non-A/B sinks (GA4, GTM) without inventing a fake test/variant.
+ *
+ * `ABTestEvent` is the derived view where `ab` is mandatory.
+ */
+type CMSEvent = {
+    /**
+     * Optional id used as the storage row key. When absent, the sink mints one.
+     * Dedup behaviour is **sink-specific**: the postgres sink dedups on it via
+     * `ON CONFLICT (id) DO NOTHING`; the upstash sink does not. (A tenant-scoped,
+     * client-supplied idempotency key — distinct from this row key — arrives with
+     * the M3 client legs.)
+     */
+    id?: string;
+    /** Canonical event name, e.g. `'impression' | 'conversion' | 'form_submit'`. */
+    name: string;
+    /**
+     * Optional: the anonymous Pattern A path stores NO identifier (variant comes
+     * from the URL/variant-cookie). Only set for the consent-gated unique-visitor /
+     * GA4 path. Stored as NULL when absent → excluded from unique-visitor counts.
+     */
+    visitorId?: string;
+    anonymous: boolean;
+    /** A/B attribution. Absent for non-A/B analytics events. */
+    ab?: {
+        testId: string;
+        variantId: string;
+    };
+    /** Originating functional block instance, if any. */
+    source?: CMSEventSource;
+    /**
+     * Consent state under which the event was emitted (Consent Mode v2).
+     * Forwarded to consent-aware sinks (e.g. the M5 server-MP consent block). NOTE:
+     * M1 forwards but does NOT persist this — there is no consent column yet.
+     */
+    consent?: ConsentState;
+    /**
+     * Funnel grouping id (M4): a client-minted id shared by the attempt + success
+     * legs of ONE interaction (e.g. a <TrackedForm> submit). Lets completion_rate
+     * pair them. Distinct from any storage/dedup key — it groups, it doesn't dedup.
+     */
+    interactionId?: string;
+    /**
+     * GA4 stitching identifiers (M5 server-MP): the client reads them from the
+     * `_ga` / `_ga_<id>` cookies and sends them ONLY when analytics_storage is
+     * granted, so the server-side ga4ServerSink can attribute the Measurement
+     * Protocol hit to the same user/session (else GA4 shows `(not set)`). Absent on
+     * the anonymous consent-free path — its presence is what gates the GA4 forward.
+     */
+    transport?: {
+        clientId?: string;
+        sessionId?: string;
+        engagementTimeMsec?: number;
+    };
+    metadata?: Record<string, unknown>;
+    timestamp: Date;
+};
+/** A {@link CMSEvent} that carries mandatory A/B attribution (the A/B view). */
+type ABTestEvent = CMSEvent & {
+    ab: {
+        testId: string;
+        variantId: string;
+    };
+};
+type AggregatedVariantResult = {
+    variantId: string;
+    variantName: string;
+    impressions: number;
+    conversions: number;
+    uniqueVisitors: number;
+    conversionRate: number;
+    /**
+     * Funnel (M4): total distinct interaction ids (each <TrackedForm> submit mints
+     * one) = the attempts. completionRate = distinct interactions that reached the
+     * goal event / attempts (computed by getResults when a goal is set).
+     */
+    attempts: number;
+    completionRate: number;
+    eventBreakdown: Record<string, {
+        count: number;
+        uniqueVisitors: number;
+        distinctInteractions: number;
+    }>;
+};
+type AggregatedResults = {
+    testId: string;
+    variants: AggregatedVariantResult[];
+    totalImpressions: number;
+    totalConversions: number;
+};
+type ABTestAnalyticsAdapter = {
+    /** Adapter-specific Postgres tables to merge into the plugin schema. */
+    tables?: Record<string, TableDefinition>;
+    /** Called once during plugin init. Receives the Drizzle DB instance. */
+    init?(db: DrizzleInstance): Promise<void> | void;
+    /**
+     * Record a single event. Accepts any {@link CMSEvent}: A/B-attributed events
+     * (impression/conversion) carry `ab`, non-A/B analytics events (form_submit,
+     * page_view) omit it.
+     */
+    track(event: CMSEvent): Promise<void>;
+    /** Query aggregated results for a test. */
+    query(testId: string, options?: {
+        from?: Date;
+        to?: Date;
+    }): Promise<AggregatedResults>;
+    /** Optional batch flush (e.g. Upstash -> Postgres). */
+    flush?(testId?: string): Promise<{
+        flushed: number;
+    }>;
+};
+type LiveDelta = {
+    variantId: string;
+    eventType: string;
+    count: 1;
+    timestamp: number;
+};
+
+/**
+ * Where the server forwards events. Both variants are server-only (an api_secret
+ * must never reach the browser). `endpointUrl` is required — supply the GA4 MP
+ * URL (https://www.google-analytics.com/mp/collect) or your sGTM container URL,
+ * so a regional/proxy endpoint is a config change, not a code change.
+ */
+type GA4ServerConfig = {
+    type: 'measurementProtocol';
+    endpointUrl: string;
+    measurementId: string;
+    apiSecret: string;
+} | {
+    type: 'sgtm';
+    endpointUrl: string;
+};
+/** The GA4 Measurement Protocol request body (the shape MP/sGTM expects). */
+type GA4Payload = {
+    client_id: string;
+    events: Array<{
+        name: string;
+        params: Record<string, unknown>;
+    }>;
+    consent?: {
+        ad_user_data: string;
+        ad_personalization: string;
+    };
+};
+/**
+ * Builds the MP payload from a {@link CMSEvent}. Pure (no I/O) + exported so the
+ * mapping is unit-testable. Returns null when the event cannot be a valid MP hit
+ * — no consent (analytics_storage not granted) or no client_id — so the caller
+ * simply does not forward. The A/B attribution rides as GA4's
+ * `experiment_id`/`experiment_variant` convention (event-scoped custom dims).
+ */
+declare function buildGa4Payload(event: CMSEvent): GA4Payload | null;
+/**
+ * Forwards one event to GA4 server-side, IF it is a valid consenting MP hit.
+ * Best-effort + non-fatal: a network/endpoint error never breaks the ingest
+ * (the A/B store write already happened). No-ops on missing consent/client_id.
+ *
+ * The trackEvent handler awaits this, so it is hard-bounded by an
+ * {@link AbortSignal.timeout}: a slow/hung GA4/sGTM endpoint can never stall the
+ * public response — the abort surfaces as a caught error and the ingest returns.
+ */
+declare function forwardToGa4(event: CMSEvent, config: GA4ServerConfig, fetchImpl?: typeof fetch): Promise<void>;
+
+/** One pickable A/B goal: a declared event on a functional block INSTANCE. */
+type GoalCandidate = {
+    /** The block instance's authored trackingId (stable goal anchor); null if unset. */
+    handle: string | null;
+    blockType: string;
+    blockId: string;
+    /** The declared event KEY (what code fires). */
+    event: string;
+    /** The resolved GA4/dataLayer wire name + stored event_type (what to match on). */
+    name: string;
+    label?: string;
+    /** Declared scalar param keys. */
+    params: string[];
+    /**
+     * True when this candidate sits in the tested root's OWN tree (the varying
+     * render). False for a candidate in an EMBEDDED reusable block — shared,
+     * co-rendered content whose conversions won't reflect THIS page's variants
+     * cleanly (§6g attribution caution).
+     */
+    inVaryingRoot: boolean;
+    /** The root whose tree this candidate lives in. */
+    hostRootId: string;
+};
+
+declare function postgresAnalytics(): ABTestAnalyticsAdapter;
+
+type RateLimitStore = {
+    /**
+     * Records one hit for `key` and returns how many hits fall in the current
+     * `windowMs` window (this one included). The default store is in-memory
+     * (fixed window). Provide a distributed store (e.g. Redis/Upstash) when
+     * running multiple instances or serverless — an in-memory count is per
+     * instance and resets on cold start, so it only bounds a single instance.
+     */
+    hit(key: string, windowMs: number, now: number): number | Promise<number>;
+};
+type ABTestRateLimitOptions = {
+    /** Max `/abTest/trackEvent` requests allowed per `windowMs` per key. */
+    limit: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /**
+     * Derive the rate-limit key from the request. Default {@link defaultRateLimitKey}:
+     * the trusted client IP (rightmost `x-forwarded-for` hop, else `x-real-ip`).
+     * Two caveats worth knowing:
+     * - The default assumes ONE trusted appending proxy (Vercel/most CDNs). Behind
+     *   multiple proxies, or a proxy that does not append, override this.
+     * - Keying on IP means a shared egress (CGNAT / corporate NAT) shares one
+     *   budget; size `limit` for the busiest legitimate egress, not a single user.
+     * Return null to SKIP limiting a request (the default does so when no proxy
+     * header is present — see {@link defaultRateLimitKey}).
+     */
+    getKey?: (request: Request) => string | null;
+    /** Counter store. Default: in-memory fixed-window (per instance). */
+    store?: RateLimitStore;
+};
+/**
+ * In-memory fixed-window counter. Memory is HARD-bounded at `maxKeys`: when a
+ * new key would exceed the cap, the oldest-inserted entry is evicted in O(1)
+ * (Map preserves insertion order) — so even a within-window flood of DISTINCT
+ * keys (e.g. an IP-rotating attacker) cannot grow the map past `maxKeys`, and
+ * there is no O(maxKeys) scan on the hot path. A live key being hit again is
+ * O(1) and never triggers eviction. Eviction can reset an old key's window
+ * under a flood (the standard bounded-limiter tradeoff). Per-instance only (see
+ * the module header) — inject a distributed store for multi-instance/serverless.
+ */
+declare function createInMemoryRateLimitStore(maxKeys?: number): RateLimitStore;
+/**
+ * Default rate-limit key: the trusted client IP.
+ *
+ * `x-forwarded-for` is a client→proxy→…→server CHAIN. An appending proxy
+ * (Vercel, most CDNs) appends the real connecting IP as the LAST entry; the
+ * FIRST entry is whatever the client sent and is trivially spoofable. So we take
+ * the RIGHTMOST entry, never the first — using the leftmost would let an
+ * attacker rotate `x-forwarded-for` to mint a fresh bucket per request and evade
+ * the limit entirely. (This assumes ONE trusted appending proxy; behind multiple
+ * proxies or a non-appending one, override `getKey`.) Falls back to `x-real-ip`
+ * (set by nginx/Vercel to the connecting IP).
+ *
+ * Returns null when neither header is present — the caller then does NOT limit
+ * (fail-open). NOTE: a deployment NOT behind a proxy (a directly-exposed server
+ * with no `x-forwarded-for`/`x-real-ip`) therefore gets NO limiting from this
+ * default — provide a `getKey` that reads your real client IP.
+ */
+declare function defaultRateLimitKey(request: Request): string | null;
+/**
+ * Enforces the ingest rate-limit for one request. Returns a 429 Response to
+ * short-circuit when the limit is exceeded, or null to let the request proceed.
+ * No-ops (null) when the key cannot be resolved. The caller (plugin onRequest)
+ * binds this to POST `/abTest/trackEvent`. `store` is created ONCE per plugin
+ * instance (never per request) so the window survives across requests.
+ */
+declare function enforceTrackEventRateLimit(request: Request, options: ABTestRateLimitOptions, store: RateLimitStore, now?: number): Promise<Response | null>;
+
+type PrivacyNoticeItem = {
+    name: string;
+    type: 'cookie' | 'sessionStorage' | 'localStorage' | 'external-cookie-read';
+    purpose: string;
+    lifetime: string;
+    /** Whether the value can identify/re-identify a visitor. */
+    isIdentifier: boolean;
+    /** The consent purpose gating it, or null when strictly-necessary (no consent). */
+    consentRequired: ConsentPurpose | null;
+    recipient: string;
+};
+/**
+ * The A/B measurement privacy-notice items. The `_ga` read is ALWAYS listed: the
+ * client reads `_ga` whenever `analytics_storage` is granted (to obtain the GA4
+ * client_id), independent of server-MP. Pass `ga4: true` when the server-MP
+ * forward (M5) is configured — it only changes the `_ga` recipient/purpose to
+ * name Google Analytics 4 as the destination of the forwarded hit.
+ * `variantCookiePrefix` must match the middleware's `variantCookiePrefix`.
+ */
+declare function getPrivacyNoticeItems(options?: {
+    ga4?: boolean;
+    variantCookiePrefix?: string;
+}): PrivacyNoticeItem[];
+
+declare const $ERROR_CODES: {
+    readonly AB_TEST_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "A/B test not found";
+    };
+    readonly AB_TEST_INVALID_STATUS: {
+        readonly status: 400;
+        readonly message: "Invalid status transition for this A/B test";
+    };
+    readonly AB_TEST_WEIGHTS_INVALID: {
+        readonly status: 400;
+        readonly message: "Variant weights must sum to 100";
+    };
+    readonly AB_TEST_DUPLICATE_RUNNING: {
+        readonly status: 409;
+        readonly message: "Another test is already running for this root";
+    };
+    readonly AB_TEST_CROSS_EMBED_CONFLICT: {
+        readonly status: 409;
+        readonly message: "Cannot run: a co-rendering root (an embedded reusable block or its host page) already has a running test — at most one A/B axis may vary per render";
+    };
+    readonly AB_TEST_BRANCH_NOT_PUBLISHED: {
+        readonly status: 400;
+        readonly message: "All variant branches must be published";
+    };
+    readonly AB_TEST_NO_CONTEXT: {
+        readonly status: 400;
+        readonly message: "No visitor context set. Call identify() first.";
+    };
+    readonly AB_TEST_FLUSH_NOT_SUPPORTED: {
+        readonly status: 400;
+        readonly message: "Flush is not supported by the current analytics adapter";
+    };
+    readonly AB_TEST_VARIANT_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "A/B test variant not found";
+    };
+    readonly AB_TEST_TRACKING_ID_MISSING: {
+        readonly status: 400;
+        readonly message: "A functional block (one that declares events) is missing its trackingId — every such block must have a non-empty trackingId before the branch can be published";
+    };
+    readonly AB_TEST_TRACKING_ID_DUPLICATE: {
+        readonly status: 400;
+        readonly message: "Duplicate trackingId in this branch — each functional block must have a unique trackingId";
+    };
+    readonly AB_TEST_TRACKING_ID_DRIFT: {
+        readonly status: 409;
+        readonly message: "trackingId drift across A/B variant branches — the set of functional trackingIds must be identical across all variant branches of a root, so a chosen goal exists in every arm";
+    };
+};
+
+type ABTestPluginOptions = {
+    analytics?: ABTestAnalyticsAdapter;
+    /**
+     * Opt-in server-side GA4 forwarding (M5). When set, each consenting,
+     * client_id-bearing event is POSTed to your GA4 Measurement Protocol / sGTM
+     * endpoint server-side (ad-blocker-resistant). Omit to use only the
+     * client-side dataLayer path. See {@link GA4ServerConfig}.
+     */
+    ga4?: GA4ServerConfig;
+    /**
+     * Opt-in rate-limit for the anonymous `/abTest/trackEvent` ingest — the one
+     * unauthenticated write path. Strongly recommended before production: an open
+     * ingest can skew the A/B aggregate, bloat the events table, and (with `ga4`)
+     * amplify into outbound GA4 POSTs. Default key = client IP; default counter =
+     * in-memory (per instance — inject a distributed `store` for serverless /
+     * multi-instance). See {@link ABTestRateLimitOptions}.
+     */
+    rateLimit?: ABTestRateLimitOptions;
+};
+declare function abTest(options?: ABTestPluginOptions): {
+    id: "abTest";
+    schema: SchemaModule<"cms", {}, {}, {}>;
+    endpoints: {
+        createTest: better_call.Endpoint<"/abTest/createTest", "POST", {
+            rootId: string;
+            collection: string;
+            name: string;
+            trafficPercentage?: number;
+            goalHandle?: string;
+            goalEvent?: string;
+            variants: Array<{
+                branchId: string;
+                name: string;
+                weight: number;
+                isControl?: boolean;
+            }>;
+        }, Record<string, any> | undefined, [], {
+            testId: string;
+        }, {
+            $Infer: {
+                body: {
+                    rootId: string;
+                    collection: string;
+                    name: string;
+                    trafficPercentage?: number;
+                    goalHandle?: string;
+                    goalEvent?: string;
+                    variants: Array<{
+                        branchId: string;
+                        name: string;
+                        weight: number;
+                        isControl?: boolean;
+                    }>;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        updateTest: better_call.Endpoint<"/abTest/updateTest", "POST", {
+            testId: string;
+            name?: string;
+            status?: "draft" | "running" | "paused" | "completed";
+            trafficPercentage?: number;
+            goalHandle?: string | null;
+            goalEvent?: string | null;
+            variants?: Array<{
+                branchId: string;
+                name: string;
+                weight: number;
+                isControl?: boolean;
+            }>;
+        }, Record<string, any> | undefined, [], {
+            testId: string;
+        }, {
+            $Infer: {
+                body: {
+                    testId: string;
+                    name?: string;
+                    status?: "draft" | "running" | "paused" | "completed";
+                    trafficPercentage?: number;
+                    goalHandle?: string | null;
+                    goalEvent?: string | null;
+                    variants?: Array<{
+                        branchId: string;
+                        name: string;
+                        weight: number;
+                        isControl?: boolean;
+                    }>;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        deleteTest: better_call.Endpoint<"/abTest/deleteTest", "POST", {
+            testId: string;
+        }, Record<string, any> | undefined, [], {
+            testId: string;
+        }, {
+            $Infer: {
+                body: {
+                    testId: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        getTest: better_call.Endpoint<"/abTest/getTest", "GET", undefined, {
+            testId: string;
+        }, [], {
+            variants: {
+                id: string;
+                branchId: string;
+                name: string;
+                weight: number;
+                isControl: boolean;
+            }[];
+            id: string;
+            rootId: string;
+            collection: string;
+            name: string;
+            goalHandle: string | null;
+            goalEvent: string | null;
+            status: string;
+            trafficPercentage: number;
+            startedAt: string | null;
+            endedAt: string | null;
+            createdBy: string | null;
+            createdAt: string;
+            updatedAt: string;
+        }, {
+            $Infer: {
+                query: {
+                    testId: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        /**
+         * M4 goal-picker: the pickable A/B goals for a root. Reads each block type's
+         * declared `events` (off the collection definitions) for the blocks present
+         * in the root's published tree, returning one candidate per (functional block
+         * instance × event). Candidates in the tested root's own tree are
+         * `inVaryingRoot: true`; candidates in embedded reusable blocks are
+         * `inVaryingRoot: false` (§6g attribution caution). The `name` is the
+         * resolved wire name (the same string fire() stores as event_type), so the
+         * UI-pickable goals are exactly the code-fireable events.
+         */
+        listGoalEvents: better_call.Endpoint<"/abTest/listGoalEvents", "GET", undefined, {
+            rootId: string;
+        }, [], {
+            rootId: string;
+            goals: GoalCandidate[];
+        }, {
+            $Infer: {
+                query: {
+                    rootId: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        listTests: better_call.Endpoint<"/abTest/listTests", "GET", undefined, {
+            collection?: string;
+            status?: string;
+            limit?: number;
+            offset?: number;
+        }, [], {
+            tests: {
+                id: string;
+                rootId: string;
+                collection: string;
+                name: string;
+                goalHandle: string | null;
+                goalEvent: string | null;
+                status: string;
+                trafficPercentage: number;
+                startedAt: string | null;
+                endedAt: string | null;
+                createdBy: string | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+            total: number;
+            hasMore: boolean;
+        }, {
+            $Infer: {
+                query: {
+                    collection?: string;
+                    status?: string;
+                    limit?: number;
+                    offset?: number;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        assignVariant: better_call.Endpoint<"/abTest/assignVariant", "POST", {
+            testId: string;
+            context: ABTestContext;
+        }, Record<string, any> | undefined, [], {
+            variantId: string;
+            branchId: string;
+            inTest: boolean;
+        }, {
+            $Infer: {
+                body: {
+                    testId: string;
+                    context: ABTestContext;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        trackEvent: better_call.Endpoint<"/abTest/trackEvent", "POST", {
+            testId?: string;
+            variantId?: string;
+            branchId?: string;
+            visitorId?: string;
+            anonymous?: boolean;
+            eventType: string;
+            metadata?: Record<string, unknown>;
+            source?: {
+                handle?: string;
+                type?: string;
+            };
+            interactionId?: string;
+            transport?: {
+                clientId?: string;
+                sessionId?: string;
+                engagementTimeMsec?: number;
+            };
+            consent?: ConsentState;
+        }, Record<string, any> | undefined, [], {}, {
+            $Infer: {
+                body: {
+                    testId?: string;
+                    variantId?: string;
+                    branchId?: string;
+                    visitorId?: string;
+                    anonymous?: boolean;
+                    eventType: string;
+                    metadata?: Record<string, unknown>;
+                    source?: {
+                        handle?: string;
+                        type?: string;
+                    };
+                    interactionId?: string;
+                    transport?: {
+                        clientId?: string;
+                        sessionId?: string;
+                        engagementTimeMsec?: number;
+                    };
+                    consent?: ConsentState;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        getResults: better_call.Endpoint<"/abTest/getResults", "GET", undefined, {
+            testId: string;
+            from?: Date;
+            to?: Date;
+        }, [], AggregatedResults, {
+            $Infer: {
+                query: {
+                    testId: string;
+                    from?: Date;
+                    to?: Date;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        flushEvents: better_call.Endpoint<"/abTest/flushEvents", "POST", {
+            testId?: string;
+        }, Record<string, any> | undefined, [], {
+            flushed: number;
+        }, {
+            $Infer: {
+                body: {
+                    testId?: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+    };
+    collectionEndpoints: (def: CollectionWithName) => {
+        resolveAbVariant: better_call.Endpoint<`/${string}/resolveAbVariant`, "GET", undefined, {
+            path: string;
+        }, [], AbResolveResult, {
+            $Infer: {
+                query: {
+                    path: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+    };
+    $ERROR_CODES: {
+        readonly AB_TEST_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test not found";
+        };
+        readonly AB_TEST_INVALID_STATUS: {
+            readonly status: 400;
+            readonly message: "Invalid status transition for this A/B test";
+        };
+        readonly AB_TEST_WEIGHTS_INVALID: {
+            readonly status: 400;
+            readonly message: "Variant weights must sum to 100";
+        };
+        readonly AB_TEST_DUPLICATE_RUNNING: {
+            readonly status: 409;
+            readonly message: "Another test is already running for this root";
+        };
+        readonly AB_TEST_CROSS_EMBED_CONFLICT: {
+            readonly status: 409;
+            readonly message: "Cannot run: a co-rendering root (an embedded reusable block or its host page) already has a running test — at most one A/B axis may vary per render";
+        };
+        readonly AB_TEST_BRANCH_NOT_PUBLISHED: {
+            readonly status: 400;
+            readonly message: "All variant branches must be published";
+        };
+        readonly AB_TEST_NO_CONTEXT: {
+            readonly status: 400;
+            readonly message: "No visitor context set. Call identify() first.";
+        };
+        readonly AB_TEST_FLUSH_NOT_SUPPORTED: {
+            readonly status: 400;
+            readonly message: "Flush is not supported by the current analytics adapter";
+        };
+        readonly AB_TEST_VARIANT_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "A/B test variant not found";
+        };
+        readonly AB_TEST_TRACKING_ID_MISSING: {
+            readonly status: 400;
+            readonly message: "A functional block (one that declares events) is missing its trackingId — every such block must have a non-empty trackingId before the branch can be published";
+        };
+        readonly AB_TEST_TRACKING_ID_DUPLICATE: {
+            readonly status: 400;
+            readonly message: "Duplicate trackingId in this branch — each functional block must have a unique trackingId";
+        };
+        readonly AB_TEST_TRACKING_ID_DRIFT: {
+            readonly status: 409;
+            readonly message: "trackingId drift across A/B variant branches — the set of functional trackingIds must be identical across all variant branches of a root, so a chosen goal exists in every arm";
+        };
+    };
+    hooks: {
+        before: {
+            action: "publishBranch";
+            handler: (ctx: CMSBeforeHookContext) => Promise<void>;
+        }[];
+    };
+    init(ctx: CMSPluginContext): Promise<{
+        context: {
+            scopeConditions: (() => {
+                abTestResolver: AbTestResolver;
+            })[];
+        };
+    }>;
+    onRequest(request: Request, _ctx: CMSPluginContext): Promise<{
+        response: any;
+    } | undefined>;
+};
+
+export { $ERROR_CODES, abTest, buildGa4Payload, createInMemoryRateLimitStore, defaultRateLimitKey, enforceTrackEventRateLimit, forwardToGa4, getPrivacyNoticeItems, postgresAnalytics };
+export type { ABTestAnalyticsAdapter, ABTestContext, ABTestEvent, ABTestPluginOptions, ABTestRateLimitOptions, AggregatedResults, AggregatedVariantResult, CMSEvent, CMSEventSource, GA4Payload, GA4ServerConfig, LiveDelta, PrivacyNoticeItem, RateLimitStore };