@active-reach/web-sdk 1.43.0 → 1.43.2

package/dist/ecommerce/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * E-Commerce event types following the Active Reach Intelligence spec.
+ * Compatible with Segment/GA4 e-commerce event schemas.
+ */
+export interface EcommerceProduct {
+    product_id: string;
+    sku?: string;
+    name: string;
+    price: number;
+    quantity?: number;
+    currency?: string;
+    category?: string;
+    brand?: string;
+    variant_id?: string;
+    variant_label?: string;
+    image_url?: string;
+    url?: string;
+    position?: number;
+}
+export interface EcommerceCart {
+    cart_id?: string;
+    value: number;
+    currency?: string;
+    products: EcommerceProduct[];
+}
+export interface EcommerceCheckout {
+    checkout_id?: string;
+    value: number;
+    currency?: string;
+    products: EcommerceProduct[];
+    coupon?: string;
+    shipping?: number;
+    tax?: number;
+}
+export interface EcommerceOrder {
+    order_id: string;
+    value: number;
+    revenue?: number;
+    currency?: string;
+    products: EcommerceProduct[];
+    coupon?: string;
+    shipping?: number;
+    tax?: number;
+    discount?: number;
+    payment_method?: string;
+}
+export interface EcommerceCoupon {
+    coupon_id?: string;
+    coupon_code: string;
+    discount_value?: number;
+    discount_type?: 'percentage' | 'fixed';
+    order_id?: string;
+    cart_id?: string;
+}
+export interface EcommerceSearch {
+    query: string;
+    results_count?: number;
+    filters?: Record<string, string | string[]>;
+}
+export interface EcommerceProductList {
+    list_id?: string;
+    list_name?: string;
+    products: EcommerceProduct[];
+    category?: string;
+}
+export interface EcommerceWishlist {
+    wishlist_id?: string;
+    wishlist_name?: string;
+    product: EcommerceProduct;
+}
+export interface EcommerceWaitlist {
+    product: EcommerceProduct;
+    channels?: Array<'whatsapp' | 'sms' | 'email' | 'push'>;
+}
+export interface EcommercePromotion {
+    promotion_id?: string;
+    name: string;
+    creative?: string;
+    position?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ecommerce/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ecommerce/types.ts"],"names":[],"mappings":"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"}

package/dist/governance/bloom-filter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bloom filter — wire-compatible with the Python builder in
+ * apps/control-plane/app/services/event_governance_bloom.py
+ *
+ * This SDK-side variant is QUERY-ONLY. The filter is built server-side
+ * from the org's registered event-name set, base64-encoded, and shipped
+ * to the browser on `/v1/sdk/bootstrap`. The SDK reads it once, uses it
+ * to gate `track()` calls, and discards it on the next bootstrap.
+ *
+ * Wire format:
+ *   • `m` bits of storage, represented as m/8 bytes, base64-encoded.
+ *   • Bit `i` is at byte `i >> 3`, bitmask `1 << (i & 7)` — LSB-first.
+ *   • `m` MUST be a power of two — allows `idx & (m-1)` modulo.
+ *   • `k` hash functions synthesized via Kirsch-Mitzenmacher from two
+ *     MurmurHash3 x86-32 hashes with seeds (seedA, seedB):
+ *         h_i(x) = (h1(x) + i * h2(x)) mod m
+ *   • Input strings are UTF-8 encoded (handled inside murmurhash3_x86_32).
+ */
+export interface BloomFilterParams {
+    /** Bits in the filter (must be power of 2). */
+    m: number;
+    /** Number of hash functions (Kirsch-Mitzenmacher synthesized). */
+    k: number;
+    /** Seed for the first MurmurHash3 call. */
+    seedA: number;
+    /** Seed for the second MurmurHash3 call. */
+    seedB: number;
+}
+export declare class BloomFilter {
+    private readonly params;
+    private readonly buf;
+    private readonly mask;
+    constructor(buf: Uint8Array, params: BloomFilterParams);
+    /** Build from the wire format (base64 bytes + explicit params). */
+    static fromBase64(bloomB64: string, params: BloomFilterParams): BloomFilter;
+    /**
+     * Returns true if `name` is probably in the set — possibly with the
+     * filter's configured false-positive rate. FALSE is always authoritative.
+     *
+     * FP here means: SDK thinks a name is already registered when it isn't.
+     * That costs one wasted server round-trip (gateway does the exact check
+     * and catches it) — strictly safer than a false-negative, which could
+     * leak a novel name past the SDK.
+     */
+    has(name: string): boolean;
+}
+//# sourceMappingURL=bloom-filter.d.ts.map

package/dist/governance/bloom-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bloom-filter.d.ts","sourceRoot":"","sources":["../../src/governance/bloom-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAuBH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,CAAC,EAAE,MAAM,CAAC;IACV,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAC;IACV,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,WAAW;IAIO,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHpD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,GAAG,EAAE,UAAU,EAAmB,MAAM,EAAE,iBAAiB;IAavE,mEAAmE;IACnE,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,WAAW;IAK3E;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAe3B"}

package/dist/governance/index.d.ts

@@ -0,0 +1,8 @@
+export { murmurhash3_x86_32, murmurhash3_bytes } from './murmur3';
+export { BloomFilter } from './bloom-filter';
+export type { BloomFilterParams } from './bloom-filter';
+export { NameGovernor } from './name-governor';
+export type { EventGovernanceHint, DropReport } from './name-governor';
+export { TraitGovernor } from './trait-governor';
+export type { TraitVerdict, TraitDrop, TraitResult } from './trait-governor';
+//# sourceMappingURL=index.d.ts.map

package/dist/governance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/governance/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/governance/murmur3.d.ts

@@ -0,0 +1,43 @@
+/**
+ * MurmurHash3 x86-32 — deterministic, byte-identical with Python `mmh3.hash`.
+ *
+ * We hand-roll rather than pull a dep because (a) our bundle-budget is
+ * aggressive for storefront first-paint, and (b) this is the authoritative
+ * cross-language hash for the event-governance bloom filter — any behavior
+ * drift between Python and JS produces silent FP-rate spikes in prod.
+ *
+ * Contract:
+ *   • Input is a JS string. It is UTF-8 encoded via TextEncoder before hashing.
+ *   • Output is an unsigned 32-bit integer (0 .. 2^32-1).
+ *   • Matches `mmh3.hash(s.encode('utf-8'), seed=seed, signed=False)` in
+ *     Python exactly — verified by libs/shared-types/bloom-test-vectors.json
+ *     in CI.
+ *
+ * Reference: Austin Appleby, MurmurHash3 (public domain).
+ *   https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp
+ *
+ * Implementation notes:
+ *   • All arithmetic on 32-bit ints. JS does bitwise ops on 32-bit ints natively;
+ *     `Math.imul` gives us correct 32-bit multiplication without overflow.
+ *   • We use `>>> 0` to coerce to unsigned after every step that could produce
+ *     a negative or >32-bit value.
+ *   • UTF-8 encoding matters — a naive `charCodeAt` loop would mis-hash any
+ *     string with non-ASCII characters (e.g. emoji, accented chars) and the
+ *     Python side would disagree. We always encode via TextEncoder first.
+ */
+/**
+ * Compute MurmurHash3 x86-32 of a UTF-8 encoded string.
+ *
+ * @param input  The string to hash.
+ * @param seed   32-bit unsigned seed.
+ * @returns      Unsigned 32-bit integer hash.
+ */
+export declare function murmurhash3_x86_32(input: string, seed?: number): number;
+/**
+ * Compute MurmurHash3 x86-32 over a byte buffer directly.
+ *
+ * Exposed for callers that already have UTF-8 bytes and want to skip the
+ * encode step (e.g., internal bloom-hash paths).
+ */
+export declare function murmurhash3_bytes(bytes: Uint8Array, seed?: number): number;
+//# sourceMappingURL=murmur3.d.ts.map

package/dist/governance/murmur3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"murmur3.d.ts","sourceRoot":"","sources":["../../src/governance/murmur3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,MAAM,CAI1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,MAAU,GAAG,MAAM,CA+C7E"}

package/dist/governance/name-governor.d.ts

@@ -0,0 +1,98 @@
+/**
+ * NameGovernor — client-side event-name cap enforcement.
+ *
+ * The governor consumes an `EventGovernanceHint` from the bootstrap response
+ * and decides whether to let a `track()` call proceed to the network or drop
+ * it locally.
+ *
+ * Why this exists:
+ *   Without it, a page that calls `track('new_btn_' + Date.now())` in a
+ *   render loop would (a) pass the local rate-limiter if within burst, (b)
+ *   force the gateway to ask control-plane for a verdict on every unique
+ *   name, and (c) amplify the CP `/event-governance/check` load quadratically
+ *   in the number of tabs firing the same bug. The bloom filter gives the
+ *   SDK enough information to drop novel names locally once the org hits
+ *   its cap, collapsing the amplification to zero.
+ *
+ * Design constraints:
+ *   • FAIL-OPEN — missing hint (Enterprise org, Redis outage) lets every
+ *     name through. The gateway is still the authoritative cap.
+ *   • FALSE-POSITIVE-SAFE — if the bloom says "known" for a name that isn't
+ *     actually registered, we send to gateway and the gateway's exact check
+ *     catches it. FPs cost one round trip, not a cap bypass.
+ *   • LOCAL-MEMO — a novel name that has already charged `remainingNewNames`
+ *     in this tab must NOT charge again on subsequent calls within the same
+ *     hint TTL. Without this, `track('new_btn_click')` fired 50 times would
+ *     drain 50 from the counter and block every OTHER legitimate novel name.
+ *     See `localNovelNames`.
+ *
+ * See docs/architecture/RFC_2026_04_SDK_GOVERNANCE_HINTS.md §3.3.
+ */
+/** Shape of the hint delivered by `/v1/sdk/bootstrap`. */
+export interface EventGovernanceHint {
+    bloom_algo: string;
+    seed_a: number;
+    seed_b: number;
+    k: number;
+    m: number;
+    bloom_b64: string;
+    remaining_new_names: number | null;
+    /**
+     * When true, the server is in its 7-day soft-cap grace window: it accepts
+     * novel event names past the cap. SDK must NOT drop locally in this mode —
+     * doing so would enforce harder than the server. See
+     * apps/control-plane/app/schemas/event_governance_hint.py for the canonical
+     * contract.
+     */
+    grace_active?: boolean;
+    ttl_seconds: number;
+}
+export interface DropReport {
+    /** Map of event_name → count of local drops since last drain. */
+    events: Record<string, number>;
+    /** Total events dropped across all names (sum of values). */
+    total: number;
+    /** When the report window started (ms since epoch). */
+    since: number;
+}
+export declare class NameGovernor {
+    private bloom;
+    private remainingNewNames;
+    private graceActive;
+    /**
+     * Names this SDK instance has seen AS NOVEL and already charged against
+     * `remainingNewNames`. Reset on every `ingestHint()` so we don't leak
+     * accounting across hint refreshes.
+     */
+    private localNovelNames;
+    /** Coalesced telemetry — flushed to the transport via drainDropReport(). */
+    private droppedSinceLastReport;
+    private reportWindowStart;
+    private hasWarnedThisSession;
+    /**
+     * Ingest a freshly-bootstrapped hint. Call on every successful bootstrap.
+     * Passing `null` disables governance (fail-open).
+     */
+    ingestHint(hint: EventGovernanceHint | null): void;
+    /**
+     * Decide whether a `track()` call should proceed.
+     *
+     * Returns true  = send to network (rate-limiter still runs after).
+     * Returns false = drop locally; caller should return early.
+     */
+    shouldSend(eventName: string): boolean;
+    /**
+     * Snapshot + reset the dropped-names counter. Called by the telemetry
+     * beacon on batch flush so the gateway gets visibility into client-side
+     * drops for ops dashboards.
+     */
+    drainDropReport(): DropReport | null;
+    /** @internal */
+    _debugState(): {
+        hasBloom: boolean;
+        remaining: number;
+        localNovel: number;
+        graceActive: boolean;
+    };
+}
+//# sourceMappingURL=name-governor.d.ts.map

package/dist/governance/name-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-governor.d.ts","sourceRoot":"","sources":["../../src/governance/name-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAeD,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,WAAW,CAAkB;IAErC;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA0B;IAEjD,4EAA4E;IAC5E,OAAO,CAAC,sBAAsB,CAAkC;IAChE,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,oBAAoB,CAAS;IAErC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,GAAG,IAAI;IA4BlD;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAqCtC;;;;OAIG;IACH,eAAe,IAAI,UAAU,GAAG,IAAI;IAkBpC,gBAAgB;IAChB,WAAW,IAAI;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,OAAO,CAAC;KACtB;CAQF"}

package/dist/governance/trait-governor.d.ts

@@ -0,0 +1,63 @@
+/**
+ * TraitGovernor — client-side guards for trait writes (P10.5).
+ *
+ * Runs the same 5 ingestion guards client-side that the cell-plane backend
+ * runs at the trait-write chokepoint (`record_attribute_keys`), so the SDK
+ * can warn developers about problematic keys/values BEFORE network send.
+ *
+ * Why two chokepoints:
+ *   - **Backend** (`record_attribute_keys` → DLQ): authoritative; rejects
+ *     payloads that bypass the SDK (direct HTTP, CSV import, integration
+ *     workers). Operators see rejections via /Validation tab.
+ *   - **SDK** (this file): developer-facing; warns in console.warn at dev
+ *     time so the issue is caught BEFORE the bad data hits production. We
+ *     normalize what we can (key casing, value truncation, date format)
+ *     and warn-then-drop what we can't (reserved prefixes).
+ *
+ * "First-3 per verdict per session" — we warn at most 3 times for each
+ * verdict per `(workspace_id, verdict)` key in any given page load. After
+ * that, silent — the developer got the message; further warnings would
+ * just spam the console and obscure other issues.
+ *
+ * Canonical contract: the verdict codes here MUST match
+ * `data_governance.ingestion_guards.GuardResult.verdict` codes + the
+ * `ingestion_dlq.verdict` DB CHECK + the FE `IngestionDLQVerdict` union.
+ * Real-env smoke asserts BE ↔ DB drift; TS narrowing catches FE drift;
+ * this file completes the four-surface drift protection.
+ */
+export type TraitVerdict = 'bad_key_format' | 'value_too_long' | 'bad_date_format' | 'name_too_long' | 'reserved_prefix';
+export interface TraitDrop {
+    /** Original key as the developer wrote it. */
+    originalKey: string;
+    /** What the guard decided. */
+    verdict: TraitVerdict;
+    /** Human-readable reason — same text we'd log to ingestion_dlq.reason. */
+    reason: string;
+}
+export interface TraitResult {
+    /**
+     * Sanitized traits to actually send. Reserved-prefix keys are absent;
+     * camelCase keys are rewritten to snake_case; long values truncated;
+     * ISO dates → epoch ms.
+     */
+    sanitized: Record<string, unknown>;
+    /** Keys that were dropped or modified (one row per change). */
+    drops: TraitDrop[];
+}
+export declare class TraitGovernor {
+    /** Cap warnings at 3 per (workspace_id, verdict) per session. */
+    private static readonly WARN_CAP;
+    /** workspace_id || '__no_workspace__' → verdict → count. */
+    private warnCounts;
+    /**
+     * Apply all guards to a traits object. Returns the sanitized payload
+     * to send + a list of drops/modifications.
+     *
+     * Pass `workspace_id` so warning rate-limits scope per workspace; an
+     * agency user switching workspaces won't have their warning budget
+     * consumed cross-workspace.
+     */
+    process(traits: Record<string, unknown> | null | undefined, workspace_id?: string | null): TraitResult;
+    private maybeWarn;
+}
+//# sourceMappingURL=trait-governor.d.ts.map

package/dist/governance/trait-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trait-governor.d.ts","sourceRoot":"","sources":["../../src/governance/trait-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,YAAY,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,+DAA+D;IAC/D,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AA+FD,qBAAa,aAAa;IACxB,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAK;IACrC,4DAA4D;IAC5D,OAAO,CAAC,UAAU,CAAqD;IAEvE;;;;;;;OAOG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,WAAW;IA+Fd,OAAO,CAAC,SAAS;CAgBlB"}