@createcms/core 0.1.1

package/dist/plugins/ab-test/analytics/upstash.d.cts

@@ -0,0 +1,193 @@
+import { PgDatabase } from 'drizzle-orm/pg-core';
+import { ConsentState } from '../../consent/index.cjs';
+
+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 DrizzleInstance = PgDatabase<any, Record<string, unknown>, any>;
+
+/** 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;
+};
+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 UpstashAnalyticsOptions = {
+    url: string;
+    token: string;
+};
+
+/**
+ * Upstash Redis Stream adapter with batch flush and realtime delta publishing.
+ *
+ * Requires `@upstash/redis` and `@upstash/realtime` as peer dependencies.
+ * Events are stored in Redis Streams and flushed to Postgres on demand.
+ * Live deltas are published to `ab:live:{testId}` channels for realtime dashboards.
+ */
+declare function upstashAnalytics(options: UpstashAnalyticsOptions): ABTestAnalyticsAdapter & {
+    realtimeInstance: unknown;
+};
+
+export { upstashAnalytics };

package/dist/plugins/ab-test/analytics/upstash.d.ts

@@ -0,0 +1,193 @@
+import { PgDatabase } from 'drizzle-orm/pg-core';
+import { ConsentState } from '../../consent/index.js';
+
+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 DrizzleInstance = PgDatabase<any, Record<string, unknown>, any>;
+
+/** 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;
+};
+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 UpstashAnalyticsOptions = {
+    url: string;
+    token: string;
+};
+
+/**
+ * Upstash Redis Stream adapter with batch flush and realtime delta publishing.
+ *
+ * Requires `@upstash/redis` and `@upstash/realtime` as peer dependencies.
+ * Events are stored in Redis Streams and flushed to Postgres on demand.
+ * Live deltas are published to `ab:live:{testId}` channels for realtime dashboards.
+ */
+declare function upstashAnalytics(options: UpstashAnalyticsOptions): ABTestAnalyticsAdapter & {
+    realtimeInstance: unknown;
+};
+
+export { upstashAnalytics };