@streamscloud/streams-analytics-collector 2.0.10 → 4.0.0

package/dist/analytics-collector.d.ts

@@ -0,0 +1,24 @@
+import { AppearanceEventsTracker } from './appearance-events-tracker';
+import { MeasurementsBatcher } from './measurements-batcher';
+import { type AnalyticsMetadata, type AnalyticsSchema, type GqlDataSenderOptions, EventsReporter, MeasurementsReporter } from './reporting';
+export type AnalyticsCollectorInitOptions = {
+    gqlDataSenderOptions: GqlDataSenderOptions;
+    schema: AnalyticsSchema;
+    metadata?: AnalyticsMetadata | null;
+};
+declare class AnalyticsCollectorContainer {
+    private _eventsReporter?;
+    private _measurementsReporter?;
+    private _appearanceEventsTracker?;
+    private _measurementsBatcher?;
+    private _isInitialized;
+    initialize(options: AnalyticsCollectorInitOptions): void;
+    get eventsReporter(): EventsReporter;
+    get measurementsReporter(): MeasurementsReporter;
+    get appearanceEventsTracker(): AppearanceEventsTracker;
+    get measurementsBatcher(): MeasurementsBatcher;
+    get isInitialized(): boolean;
+    private assertInitialized;
+}
+export declare const AnalyticsCollector: AnalyticsCollectorContainer;
+export {};

package/dist/analytics-collector.js

@@ -0,0 +1,51 @@
+import { AppearanceEventsTracker } from './appearance-events-tracker.js';
+import { MeasurementsBatcher } from './measurements-batcher.js';
+import { EventsReporter } from './reporting/events-reporter.js';
+import { GqlDataSender } from './reporting/gql-data-sender.js';
+import { MeasurementsReporter } from './reporting/measurements-reporter.js';
+import './reporting/types.js';
+import { ViewportVisibilityTracker } from './viewport-visibility-tracker.js';
+
+class AnalyticsCollectorContainer {
+    _eventsReporter;
+    _measurementsReporter;
+    _appearanceEventsTracker;
+    _measurementsBatcher;
+    _isInitialized = false;
+    initialize(options) {
+        const gqlDataSender = new GqlDataSender(options.gqlDataSenderOptions);
+        const viewportVisibilityTracker = new ViewportVisibilityTracker();
+        this._eventsReporter = new EventsReporter(gqlDataSender, options.schema, options.metadata);
+        this._measurementsReporter = new MeasurementsReporter(gqlDataSender, options.schema, options.metadata);
+        this._appearanceEventsTracker = new AppearanceEventsTracker(viewportVisibilityTracker, this._eventsReporter);
+        this._measurementsBatcher = new MeasurementsBatcher(this._measurementsReporter);
+        this._isInitialized = true;
+    }
+    get eventsReporter() {
+        this.assertInitialized();
+        return this._eventsReporter;
+    }
+    get measurementsReporter() {
+        this.assertInitialized();
+        return this._measurementsReporter;
+    }
+    get appearanceEventsTracker() {
+        this.assertInitialized();
+        return this._appearanceEventsTracker;
+    }
+    get measurementsBatcher() {
+        this.assertInitialized();
+        return this._measurementsBatcher;
+    }
+    get isInitialized() {
+        return this._isInitialized;
+    }
+    assertInitialized() {
+        if (!this._isInitialized) {
+            throw new Error('AnalyticsCollector is not initialized. Call AnalyticsCollector.initialize() first.');
+        }
+    }
+}
+const AnalyticsCollector = new AnalyticsCollectorContainer();
+
+export { AnalyticsCollector };

package/dist/appearance-events-tracker.d.ts

@@ -0,0 +1,15 @@
+import { type EventsReporter, type Entity, type EntityRelation } from './reporting';
+import type { ViewportVisibilityTracker } from './viewport-visibility-tracker';
+export type TrackingEntityElement = {
+    element: HTMLElement;
+    entity: Entity;
+    relatedEntities?: EntityRelation[] | null;
+    attributes?: Record<string, string> | null;
+};
+export declare class AppearanceEventsTracker {
+    private viewportVisibilityTracker;
+    private eventsReporter;
+    constructor(viewportVisibilityTracker: ViewportVisibilityTracker, eventsReporter: EventsReporter);
+    trackElementAppearance({ entity, element, relatedEntities, attributes }: TrackingEntityElement): () => void;
+    untrackElementAppearance(el: HTMLElement): void;
+}

package/dist/appearance-events-tracker.js

@@ -0,0 +1,27 @@
+import { EventType } from './reporting/types.js';
+
+class AppearanceEventsTracker {
+    viewportVisibilityTracker;
+    eventsReporter;
+    constructor(viewportVisibilityTracker, eventsReporter) {
+        this.viewportVisibilityTracker = viewportVisibilityTracker;
+        this.eventsReporter = eventsReporter;
+    }
+    trackElementAppearance({ entity, element, relatedEntities, attributes }) {
+        this.viewportVisibilityTracker.registerElement(element, getTrackingId(entity), () => this.eventsReporter.reportEvent({
+            entity,
+            eventType: EventType.Appeared,
+            relatedEntities,
+            attributes,
+        }));
+        return () => this.viewportVisibilityTracker.unregisterElement(element);
+    }
+    untrackElementAppearance(el) {
+        this.viewportVisibilityTracker.unregisterElement(el);
+    }
+}
+function getTrackingId(entity) {
+    return `${entity.type}::${entity.id}`;
+}
+
+export { AppearanceEventsTracker };

package/dist/graphql/report-event.graphql.js

@@ -0,0 +1,3 @@
+var ReportEvent = "mutation ReportEvent($input: ReportEventInput!) {\n  reportEvent(input: $input) {\n    void\n  }\n}\n";
+
+export { ReportEvent as default };

package/dist/graphql/report-external-event.graphql.js

@@ -0,0 +1,3 @@
+var ReportExternalEvent = "mutation ReportExternalEvent($input: ReportExternalEventInput!) {\n  reportExternalEvent(input: $input) {\n    void\n  }\n}\n";
+
+export { ReportExternalEvent as default };

package/dist/graphql/report-external-measurement.graphql.js

@@ -0,0 +1,3 @@
+var ReportExternalMeasurement = "mutation ReportExternalMeasurement($input: ReportExternalMeasurementInput!) {\n  reportExternalMeasurement(input: $input) {\n    void\n  }\n}\n";
+
+export { ReportExternalMeasurement as default };

package/dist/graphql/report-measurement.graphql.js

@@ -0,0 +1,3 @@
+var ReportMeasurement = "mutation ReportMeasurement($input: ReportMeasurementInput!) {\n  reportMeasurement(input: $input) {\n    void\n  }\n}\n";
+
+export { ReportMeasurement as default };

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export * as Types from "./types";
-export { AppEventsTracker, AppEventType, CommunityMessageStatus, } from "./analytics";
+export { EntityRelationType, EntityType, EventType, MeasurementType, type AnalyticsMetadata, type AnalyticsSchema, type Entity, type EntityRelation, } from './reporting/types';
+export { type AnalyticsCollectorInitOptions, AnalyticsCollector } from './analytics-collector';
+export { type TrackingEntityElement, AppearanceEventsTracker } from './appearance-events-tracker';
+export { ViewportVisibilityTracker } from './viewport-visibility-tracker';
+export { type BatchedMeasurement, type MeasurementsBatchReportResult, type FailedBatchedMeasurement, MeasurementsBatcher, } from './measurements-batcher';
+export { Schemas } from './schemas';

package/dist/index.js

@@ -1,4 +1,6 @@
-import * as types from './types.js';
-export { types as Types };
-export { AppEventsTracker } from './analytics/app-events-tracker.js';
-export { AppEventType, CommunityMessageStatus } from './analytics/types.js';
+export { EntityRelationType, EntityType, EventType, MeasurementType } from './reporting/types.js';
+export { AnalyticsCollector } from './analytics-collector.js';
+export { AppearanceEventsTracker } from './appearance-events-tracker.js';
+export { ViewportVisibilityTracker } from './viewport-visibility-tracker.js';
+export { MeasurementsBatcher } from './measurements-batcher.js';
+export { Schemas } from './schemas.js';

package/dist/measurements-batcher.d.ts

@@ -0,0 +1,24 @@
+import { type Entity, type MeasurementsReporter, type MeasurementType } from './reporting';
+export type BatchedMeasurement = {
+    entity: Entity;
+    measurementType: MeasurementType;
+    value: number;
+    attributes?: Record<string, string> | null;
+};
+export type FailedBatchedMeasurement = {
+    measurement: BatchedMeasurement;
+    error: unknown;
+};
+export type MeasurementsBatchReportResult = {
+    succeeded: BatchedMeasurement[];
+    failed: FailedBatchedMeasurement[];
+};
+export declare class MeasurementsBatcher {
+    private measurementsReporter;
+    private containerEntities;
+    constructor(measurementsReporter: MeasurementsReporter);
+    collect(containers: Entity[], measurement: BatchedMeasurement): void;
+    reportBatch(containers: Entity[]): Promise<MeasurementsBatchReportResult>;
+    clearBatch(containers: Entity[]): void;
+    reset(): void;
+}

package/dist/measurements-batcher.js

@@ -0,0 +1,91 @@
+import { EntityRelationType } from './reporting/types.js';
+
+class MeasurementsBatcher {
+    measurementsReporter;
+    containerEntities = new Map();
+    constructor(measurementsReporter) {
+        this.measurementsReporter = measurementsReporter;
+    }
+    collect(containers, measurement) {
+        if (containers.length === 0) {
+            throw new Error('At least one container entity is required.');
+        }
+        const groupKey = getContainerGroupKey(containers);
+        let entitiesInGroup = this.containerEntities.get(groupKey);
+        if (!entitiesInGroup) {
+            entitiesInGroup = new Map();
+            this.containerEntities.set(groupKey, entitiesInGroup);
+        }
+        entitiesInGroup.set(getMeasurementKey(measurement), measurement);
+    }
+    async reportBatch(containers) {
+        if (containers.length === 0) {
+            throw new Error('At least one container entity is required.');
+        }
+        const groupKey = getContainerGroupKey(containers);
+        const entitiesInGroup = this.containerEntities.get(groupKey);
+        if (!entitiesInGroup || entitiesInGroup.size === 0) {
+            return { succeeded: [], failed: [] };
+        }
+        const containerRelations = getContainerRelations(containers);
+        const entries = Array.from(entitiesInGroup.entries());
+        const succeeded = [];
+        const failed = [];
+        await Promise.all(entries.map(async ([key, measurement]) => {
+            try {
+                await this.measurementsReporter.reportMeasurement({
+                    entity: measurement.entity,
+                    measurementType: measurement.measurementType,
+                    value: measurement.value,
+                    relatedEntities: containerRelations,
+                    attributes: measurement.attributes
+                });
+                succeeded.push(measurement);
+                entitiesInGroup.delete(key);
+            }
+            catch (error) {
+                failed.push({ measurement, error });
+            }
+        }));
+        if (entitiesInGroup.size === 0) {
+            this.containerEntities.delete(groupKey);
+        }
+        return { succeeded, failed };
+    }
+    clearBatch(containers) {
+        const groupKey = getContainerGroupKey(containers);
+        this.containerEntities.delete(groupKey);
+    }
+    reset() {
+        this.containerEntities.clear();
+    }
+}
+function getEntityKey(entity) {
+    return `${entity.type}::${entity.id}`;
+}
+function getMeasurementKey(container) {
+    return `${getEntityKey(container.entity)}::${container.measurementType}`;
+}
+function normalizeContainers(containers) {
+    const uniq = new Map();
+    for (const c of containers) {
+        uniq.set(getEntityKey(c), c);
+    }
+    return Array.from(uniq.values()).sort((a, b) => {
+        const ka = getEntityKey(a);
+        const kb = getEntityKey(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+}
+function getContainerGroupKey(containers) {
+    const keys = normalizeContainers(containers).map(getEntityKey);
+    return keys.join('||');
+}
+function getContainerRelations(containers) {
+    return normalizeContainers(containers).map((c) => ({
+        relationType: EntityRelationType.NestedIn,
+        entity: c,
+    }));
+}
+
+export { MeasurementsBatcher };

package/dist/reporting/events-reporter.d.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsSchema, AnalyticsMetadata, EventType, EntityRelation, Entity } from './types';
+import type { GqlDataSender } from './gql-data-sender';
+export type ReportedEvent = {
+    entity: Entity;
+    eventType: EventType;
+    relatedEntities?: EntityRelation[] | null;
+    attributes?: Record<string, string> | null;
+};
+export declare class EventsReporter {
+    private gqlDataSender;
+    private analyticsSchema;
+    private analyticsMetadata?;
+    constructor(gqlDataSender: GqlDataSender, analyticsSchema: AnalyticsSchema, analyticsMetadata?: AnalyticsMetadata | null);
+    reportEvent({ entity, eventType, relatedEntities, attributes }: ReportedEvent): Promise<void>;
+}

package/dist/reporting/events-reporter.js

@@ -0,0 +1,33 @@
+class EventsReporter {
+    gqlDataSender;
+    analyticsSchema;
+    analyticsMetadata;
+    constructor(gqlDataSender, analyticsSchema, analyticsMetadata) {
+        this.gqlDataSender = gqlDataSender;
+        this.analyticsSchema = analyticsSchema;
+        this.analyticsMetadata = analyticsMetadata;
+    }
+    async reportEvent({ entity, eventType, relatedEntities, attributes }) {
+        const input = {
+            entityType: entity.type,
+            entityId: entity.id,
+            eventType,
+            relatedEntities: relatedEntities
+                ?.map(({ relationType, entity }) => ({
+                relationType,
+                entityType: entity.type,
+                entityId: entity.id,
+            })) ?? null,
+            installation: this.analyticsMetadata?.installationId
+                ? {
+                    id: this.analyticsMetadata.installationId,
+                } : null,
+            attributes: attributes
+                ? Object.entries(attributes).map(([key, value]) => ({ key, value }))
+                : null,
+        };
+        await this.gqlDataSender.send(this.analyticsSchema.reportEvent, { input });
+    }
+}
+
+export { EventsReporter };

package/dist/reporting/gql-data-sender.d.ts

@@ -0,0 +1,12 @@
+import type { Client } from '@urql/core';
+export type GqlDataSenderOptions = {
+    client: Client;
+} | {
+    endpoint: string;
+};
+export declare class GqlDataSender {
+    private gqlEndpoint;
+    private client;
+    constructor(options: GqlDataSenderOptions);
+    send(query: string, variables?: object): Promise<void>;
+}

package/dist/reporting/gql-data-sender.js

@@ -0,0 +1,35 @@
+class GqlDataSender {
+    gqlEndpoint = null;
+    client = null;
+    constructor(options) {
+        if ('client' in options) {
+            this.client = options.client;
+            this.gqlEndpoint = null;
+        }
+        else {
+            this.gqlEndpoint = options.endpoint;
+            this.client = null;
+        }
+    }
+    async send(query, variables) {
+        if (this.gqlEndpoint) {
+            await sendGqlBeacon(this.gqlEndpoint, query, variables);
+        }
+        else if (this.client) {
+            await this.client.mutation(query, variables).toPromise();
+        }
+        else {
+            console.error('GqlDataSender not properly initialized.');
+        }
+    }
+}
+async function sendGqlBeacon(endpoint, query, variables) {
+    const body = JSON.stringify({ query, variables });
+    const blob = new Blob([body], { type: 'application/json' });
+    const accepted = navigator.sendBeacon(endpoint, blob);
+    if (!accepted) {
+        throw new Error('Failed to queue analytics beacon.');
+    }
+}
+
+export { GqlDataSender };

package/dist/reporting/index.d.ts

@@ -0,0 +1,4 @@
+export { type ReportedEvent, EventsReporter } from './events-reporter';
+export { type GqlDataSenderOptions, GqlDataSender } from './gql-data-sender';
+export { type ReportedMeasurement, MeasurementsReporter } from './measurements-reporter';
+export { EntityRelationType, EntityType, EventType, MeasurementType, type AnalyticsMetadata, type AnalyticsSchema, type Entity, type EntityRelation, } from './types';

package/dist/reporting/measurements-reporter.d.ts

@@ -0,0 +1,16 @@
+import type { AnalyticsSchema, AnalyticsMetadata, MeasurementType, EntityRelation, Entity } from './types';
+import type { GqlDataSender } from './gql-data-sender';
+export type ReportedMeasurement = {
+    entity: Entity;
+    measurementType: MeasurementType;
+    value: number;
+    relatedEntities?: EntityRelation[] | null;
+    attributes?: Record<string, string> | null;
+};
+export declare class MeasurementsReporter {
+    private gqlDataSender;
+    private analyticsSchema;
+    private analyticsMetadata?;
+    constructor(gqlDataSender: GqlDataSender, analyticsSchema: AnalyticsSchema, analyticsMetadata?: AnalyticsMetadata | null);
+    reportMeasurement({ entity, measurementType, value, relatedEntities, attributes }: ReportedMeasurement): Promise<void>;
+}

package/dist/reporting/measurements-reporter.js

@@ -0,0 +1,34 @@
+class MeasurementsReporter {
+    gqlDataSender;
+    analyticsSchema;
+    analyticsMetadata;
+    constructor(gqlDataSender, analyticsSchema, analyticsMetadata) {
+        this.gqlDataSender = gqlDataSender;
+        this.analyticsSchema = analyticsSchema;
+        this.analyticsMetadata = analyticsMetadata;
+    }
+    async reportMeasurement({ entity, measurementType, value, relatedEntities, attributes }) {
+        const input = {
+            entityType: entity.type,
+            entityId: entity.id,
+            measurementType,
+            value,
+            relatedEntities: relatedEntities
+                ?.map(({ relationType, entity }) => ({
+                relationType,
+                entityType: entity.type,
+                entityId: entity.id,
+            })) ?? null,
+            installation: this.analyticsMetadata?.installationId
+                ? {
+                    id: this.analyticsMetadata.installationId,
+                } : null,
+            attributes: attributes
+                ? Object.entries(attributes).map(([key, value]) => ({ key, value }))
+                : null,
+        };
+        await this.gqlDataSender.send(this.analyticsSchema.reportMeasurement, { input });
+    }
+}
+
+export { MeasurementsReporter };

package/dist/reporting/types.d.ts

@@ -0,0 +1,58 @@
+export declare enum EntityType {
+    Article = "ARTICLE",
+    Audio = "AUDIO",
+    Event = "EVENT",
+    Media = "MEDIA",
+    Moment = "MOMENT",
+    Link = "LINK",
+    ShortVideo = "SHORT_VIDEO",
+    Text = "TEXT",
+    Video = "VIDEO",
+    Product = "PRODUCT",
+    Stream = "STREAM",
+    StreamPage = "STREAM_PAGE",
+    Ad = "AD",
+    MediaPage = "MEDIA_PAGE"
+}
+export declare enum EventType {
+    Appeared = "APPEARED",
+    Viewed = "VIEWED",
+    Clicked = "CLICKED"
+}
+export declare enum MeasurementType {
+    ScrollDepth = "SCROLL_DEPTH",
+    EngagementTime = "ENGAGEMENT_TIME",
+    Progress = "PROGRESS"
+}
+export declare enum EntityRelationType {
+    NestedIn = "NESTED_IN"
+}
+export type AnalyticsSchema = {
+    reportEvent: string;
+    reportMeasurement: string;
+};
+export type AnalyticsMetadata = {
+    installationId?: string | null;
+};
+export type Entity = {
+    type: EntityType;
+    id: string;
+};
+export type EntityRelation = {
+    relationType: EntityRelationType;
+    entity: Entity;
+};
+export type EntityRelationInput = {
+    relationType: EntityRelationType;
+    entityType: EntityType;
+    entityId: string;
+};
+export type InstallationInput = {
+    id: string;
+    device?: string | null;
+    browser?: string | null;
+};
+export type KeyValuePair<TKey, TValue> = {
+    key: TKey;
+    value: TValue;
+};

package/dist/reporting/types.js

@@ -0,0 +1,35 @@
+var EntityType;
+(function (EntityType) {
+    EntityType["Article"] = "ARTICLE";
+    EntityType["Audio"] = "AUDIO";
+    EntityType["Event"] = "EVENT";
+    EntityType["Media"] = "MEDIA";
+    EntityType["Moment"] = "MOMENT";
+    EntityType["Link"] = "LINK";
+    EntityType["ShortVideo"] = "SHORT_VIDEO";
+    EntityType["Text"] = "TEXT";
+    EntityType["Video"] = "VIDEO";
+    EntityType["Product"] = "PRODUCT";
+    EntityType["Stream"] = "STREAM";
+    EntityType["StreamPage"] = "STREAM_PAGE";
+    EntityType["Ad"] = "AD";
+    EntityType["MediaPage"] = "MEDIA_PAGE";
+})(EntityType || (EntityType = {}));
+var EventType;
+(function (EventType) {
+    EventType["Appeared"] = "APPEARED";
+    EventType["Viewed"] = "VIEWED";
+    EventType["Clicked"] = "CLICKED";
+})(EventType || (EventType = {}));
+var MeasurementType;
+(function (MeasurementType) {
+    MeasurementType["ScrollDepth"] = "SCROLL_DEPTH";
+    MeasurementType["EngagementTime"] = "ENGAGEMENT_TIME";
+    MeasurementType["Progress"] = "PROGRESS";
+})(MeasurementType || (MeasurementType = {}));
+var EntityRelationType;
+(function (EntityRelationType) {
+    EntityRelationType["NestedIn"] = "NESTED_IN";
+})(EntityRelationType || (EntityRelationType = {}));
+
+export { EntityRelationType, EntityType, EventType, MeasurementType };

package/dist/schemas.d.ts

@@ -0,0 +1,5 @@
+import type { AnalyticsSchema } from './reporting';
+export declare const Schemas: {
+    internal: AnalyticsSchema;
+    external: AnalyticsSchema;
+};

package/dist/schemas.js

@@ -0,0 +1,17 @@
+import ReportEvent from './graphql/report-event.graphql.js';
+import ReportExternalEvent from './graphql/report-external-event.graphql.js';
+import ReportMeasurement from './graphql/report-measurement.graphql.js';
+import ReportExternalMeasurement from './graphql/report-external-measurement.graphql.js';
+
+const Schemas = {
+    internal: {
+        reportEvent: ReportEvent,
+        reportMeasurement: ReportMeasurement,
+    },
+    external: {
+        reportEvent: ReportExternalEvent,
+        reportMeasurement: ReportExternalMeasurement,
+    },
+};
+
+export { Schemas };

package/dist/viewport-visibility-tracker.d.ts

@@ -0,0 +1,13 @@
+export declare class ViewportVisibilityTracker {
+    private trackedIds;
+    private targetToElements;
+    private elementToTargetId;
+    private callbacks;
+    private observer;
+    registerElement(el: HTMLElement, targetId: string, callback: (id: string) => void): void;
+    unregisterElement(el: HTMLElement): void;
+    unregisterAllElements(targetId: string): void;
+    reset(): void;
+    private getObserver;
+    private handleIntersections;
+}