@pixelume/sdk 0.5.0 → 0.6.0

package/dist/modules/analytics/AnalyticsProvider.d.ts

@@ -0,0 +1,51 @@
+import type { AnalyticsProperties } from './events.js';
+/** One validated, authorized event, ready for a transport. */
+export interface AnalyticsEvent {
+    readonly name: string;
+    readonly properties: AnalyticsProperties;
+    /** Local time (ms since epoch) when the game reported it. */
+    readonly timestamp: number;
+    /** Waited in the module's queue while the provider loaded: deliver with `timestamp`. */
+    readonly delayed?: true;
+}
+/**
+ * Identity the provider should use:
+ * - `player`: a signed-in Pixelume account (internal, non-sensitive id);
+ * - `null` with `separate: true`: the account is gone (logout, expiry): start a new anonymous id;
+ * - `null` with `separate: false`: a visitor; keep whatever anonymous id exists.
+ */
+export interface AnalyticsIdentity {
+    readonly player: string | null;
+    readonly separate: boolean;
+}
+/**
+ * Transport seam behind `pixelume.analytics`. The module validates events, applies consent and
+ * owns game sessions; a provider only delivers. Providers must never throw synchronously into the
+ * game: the module still guards every call. Internal: not part of the public API.
+ */
+export interface AnalyticsProvider {
+    readonly name: 'posthog' | 'none';
+    /** Prepares the transport. Called only after consent. Rejects when it cannot run here. */
+    load(): Promise<void>;
+    /** Consent granted (again): allow capture and persistence. */
+    optIn(): void;
+    /**
+     * Consent revoked: stop capturing, discard anything not yet sent and forget the analytics
+     * identifiers stored in the browser.
+     */
+    optOut(): void;
+    capture(event: AnalyticsEvent): void;
+    identify(identity: AnalyticsIdentity): void;
+    /** The owning client was destroyed: stop forwarding. Shared resources may stay for reuse. */
+    detach(): void;
+}
+/** Used when analytics is disabled or not configured: does nothing, loads nothing. */
+export declare class NoopAnalyticsProvider implements AnalyticsProvider {
+    readonly name = "none";
+    load(): Promise<void>;
+    optIn(): void;
+    optOut(): void;
+    capture(): void;
+    identify(): void;
+    detach(): void;
+}

package/dist/modules/analytics/AnalyticsProvider.js

@@ -0,0 +1,23 @@
+/** Used when analytics is disabled or not configured: does nothing, loads nothing. */
+export class NoopAnalyticsProvider {
+    name = 'none';
+    load() {
+        return Promise.resolve();
+    }
+    optIn() {
+        // Nothing to enable.
+    }
+    optOut() {
+        // Nothing stored.
+    }
+    capture() {
+        // Dropped by design.
+    }
+    identify() {
+        // No identity to keep.
+    }
+    detach() {
+        // Nothing to release.
+    }
+}
+//# sourceMappingURL=AnalyticsProvider.js.map

package/dist/modules/analytics/AnalyticsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyticsProvider.js","sourceRoot":"","sources":["../../../src/modules/analytics/AnalyticsProvider.ts"],"names":[],"mappings":"AA6CA,sFAAsF;AACtF,MAAM,OAAO,qBAAqB;IACvB,IAAI,GAAG,MAAM,CAAC;IAEvB,IAAI;QACF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,qBAAqB;IACvB,CAAC;IAED,MAAM;QACJ,kBAAkB;IACpB,CAAC;IAED,OAAO;QACL,qBAAqB;IACvB,CAAC;IAED,QAAQ;QACN,uBAAuB;IACzB,CAAC;IAED,MAAM;QACJ,sBAAsB;IACxB,CAAC;CACF","sourcesContent":["import type { AnalyticsProperties } from './events.js';\n\n/** One validated, authorized event, ready for a transport. */\nexport interface AnalyticsEvent {\n  readonly name: string;\n  readonly properties: AnalyticsProperties;\n  /** Local time (ms since epoch) when the game reported it. */\n  readonly timestamp: number;\n  /** Waited in the module's queue while the provider loaded: deliver with `timestamp`. */\n  readonly delayed?: true;\n}\n\n/**\n * Identity the provider should use:\n * - `player`: a signed-in Pixelume account (internal, non-sensitive id);\n * - `null` with `separate: true`: the account is gone (logout, expiry): start a new anonymous id;\n * - `null` with `separate: false`: a visitor; keep whatever anonymous id exists.\n */\nexport interface AnalyticsIdentity {\n  readonly player: string | null;\n  readonly separate: boolean;\n}\n\n/**\n * Transport seam behind `pixelume.analytics`. The module validates events, applies consent and\n * owns game sessions; a provider only delivers. Providers must never throw synchronously into the\n * game: the module still guards every call. Internal: not part of the public API.\n */\nexport interface AnalyticsProvider {\n  readonly name: 'posthog' | 'none';\n  /** Prepares the transport. Called only after consent. Rejects when it cannot run here. */\n  load(): Promise<void>;\n  /** Consent granted (again): allow capture and persistence. */\n  optIn(): void;\n  /**\n   * Consent revoked: stop capturing, discard anything not yet sent and forget the analytics\n   * identifiers stored in the browser.\n   */\n  optOut(): void;\n  capture(event: AnalyticsEvent): void;\n  identify(identity: AnalyticsIdentity): void;\n  /** The owning client was destroyed: stop forwarding. Shared resources may stay for reuse. */\n  detach(): void;\n}\n\n/** Used when analytics is disabled or not configured: does nothing, loads nothing. */\nexport class NoopAnalyticsProvider implements AnalyticsProvider {\n  readonly name = 'none';\n\n  load(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  optIn(): void {\n    // Nothing to enable.\n  }\n\n  optOut(): void {\n    // Nothing stored.\n  }\n\n  capture(): void {\n    // Dropped by design.\n  }\n\n  identify(): void {\n    // No identity to keep.\n  }\n\n  detach(): void {\n    // Nothing to release.\n  }\n}\n"]}

package/dist/modules/analytics/PostHogAnalyticsProvider.d.ts

@@ -0,0 +1,39 @@
+import type { PostHogConfig } from 'posthog-js/dist/module.slim.no-external.js';
+import type { AnalyticsEvent, AnalyticsIdentity, AnalyticsProvider } from './AnalyticsProvider.js';
+/** The part of the `posthog-js` instance API the provider relies on. */
+export interface PostHogInstanceLike {
+    init(token: string, config: Partial<PostHogConfig>): unknown;
+    capture(event: string, properties?: Record<string, unknown> | null, options?: {
+        readonly timestamp?: Date;
+    }): unknown;
+    identify(distinctId: string): void;
+    reset(resetDeviceId?: boolean): void;
+    opt_in_capturing(options?: {
+        readonly captureEventName?: false | null;
+    }): void;
+    opt_out_capturing(): void;
+    has_opted_out_capturing(): boolean;
+    get_distinct_id(): string;
+    get_property(key: string): unknown;
+}
+export interface PostHogModuleLike {
+    readonly PostHog: new () => PostHogInstanceLike;
+}
+export interface PostHogProviderOptions {
+    readonly token: string;
+    readonly host: string;
+    readonly gameId: string;
+    /** Test seam; defaults to a dynamic import of the slim, self-contained posthog-js bundle. */
+    readonly loadModule?: () => Promise<PostHogModuleLike>;
+}
+export declare class PostHogAnalyticsProvider implements AnalyticsProvider {
+    #private;
+    readonly name = "posthog";
+    constructor(options: PostHogProviderOptions);
+    load(): Promise<void>;
+    optIn(): void;
+    optOut(): void;
+    capture(event: AnalyticsEvent): void;
+    identify(identity: AnalyticsIdentity): void;
+    detach(): void;
+}

package/dist/modules/analytics/PostHogAnalyticsProvider.js

@@ -0,0 +1,255 @@
+/**
+ * Slim build without extensions (no autocapture, replay, surveys, toolbar...) and without
+ * `loadExternalDependency`: it never injects `<script>` tags. The dynamic import keeps posthog-js
+ * out of the game's main bundle and out of Node/SSR: it only runs after consent, in a browser.
+ */
+// Typed against the real posthog-js declarations: an upgrade that changes a method we rely on
+// fails the type check here.
+const defaultLoadModule = () => import('posthog-js/dist/module.slim.no-external.js');
+/** Provider events that may leave the browser; every other `$event` is dropped. */
+const ALLOWED_PROVIDER_EVENTS = new Set(['$identify', '$set']);
+/** Properties removed from every outgoing event. */
+const DROPPED_PROVIDER_PROPERTIES = ['$raw_user_agent'];
+/**
+ * posthog-js has no teardown: every initialized instance keeps its page listeners for the life of
+ * the page. Instances are therefore created once per (host, token, game) and reused by later
+ * clients (SPA remounts, hot reload) instead of being initialized again.
+ */
+const sharedInstances = new Map();
+export class PostHogAnalyticsProvider {
+    name = 'posthog';
+    #options;
+    #shared = null;
+    #instance = null;
+    #attached = true;
+    constructor(options) {
+        this.#options = options;
+    }
+    async load() {
+        if (this.#instance !== null)
+            return;
+        if (!hasBrowserGlobals())
+            throw new Error('PostHog analytics needs a browser environment');
+        const shared = this.#sharedInstance();
+        this.#shared = shared;
+        const instance = await shared.ready;
+        if (this.#attached)
+            this.#instance = instance;
+    }
+    optIn() {
+        const instance = this.#instance;
+        if (instance === null || this.#shared === null)
+            return;
+        this.#shared.gate.open = true;
+        // Undo a previous revocation; never capture posthog's own `$opt_in` event.
+        if (instance.has_opted_out_capturing())
+            instance.opt_in_capturing({ captureEventName: false });
+    }
+    optOut() {
+        // Also reached before `load()`: another client of the same game may have opened the instance.
+        const shared = this.#shared ?? sharedInstances.get(this.#key()) ?? null;
+        if (shared === null)
+            return;
+        shared.gate.open = false;
+        const instance = shared.instance;
+        if (instance === null)
+            return;
+        discardPendingRequests(instance);
+        // `reset()` clears posthog's consent state, so it must come first; then opting out disables
+        // persistence and removes what posthog stored (`opt_out_persistence_by_default`).
+        instance.reset(true);
+        instance.opt_out_capturing();
+        // Disabling persistence leaves the tab's window id in sessionStorage; remove it as well.
+        removeSessionKeys(`ph_pixelume_${this.#options.gameId}`);
+    }
+    capture(event) {
+        const instance = this.#instance;
+        if (instance === null || !this.#attached || this.#shared?.gate.open !== true)
+            return;
+        // Any options object makes posthog-js skip its batch and send at once, so live events go
+        // without one (posthog stamps them); only events that waited for the load keep their time.
+        if (event.delayed === true) {
+            instance.capture(event.name, { ...event.properties }, { timestamp: new Date(event.timestamp) });
+        }
+        else {
+            instance.capture(event.name, { ...event.properties });
+        }
+    }
+    identify(identity) {
+        const instance = this.#instance;
+        if (instance === null || !this.#attached || this.#shared?.gate.open !== true)
+            return;
+        const identified = instance.get_property('$user_state') === 'identified';
+        if (identity.player === null) {
+            if (identity.separate && identified)
+                instance.reset();
+            return;
+        }
+        if (identified && instance.get_distinct_id() === identity.player)
+            return;
+        // Another account was identified on this browser: never merge two players.
+        if (identified)
+            instance.reset();
+        // From an anonymous id, `identify` links the visitor's earlier events to the player.
+        instance.identify(identity.player);
+    }
+    detach() {
+        this.#attached = false;
+        this.#instance = null;
+    }
+    #key() {
+        const { token, host, gameId } = this.#options;
+        return `${host}\n${token}\n${gameId}`;
+    }
+    #sharedInstance() {
+        const { token, host, gameId } = this.#options;
+        const key = this.#key();
+        const existing = sharedInstances.get(key);
+        if (existing !== undefined)
+            return existing;
+        const gate = { open: true };
+        const loadModule = this.#options.loadModule ?? defaultLoadModule;
+        const ready = loadModule().then((module) => {
+            const instance = new module.PostHog();
+            instance.init(token, posthogConfig(host, gameId, gate));
+            shared.instance = instance;
+            return instance;
+        });
+        const shared = { ready, instance: null, gate };
+        sharedInstances.set(key, shared);
+        // A failed chunk download (offline, CSP) must not poison later attempts.
+        ready.catch(() => {
+            if (sharedInstances.get(key) === shared)
+                sharedInstances.delete(key);
+        });
+        return shared;
+    }
+}
+/**
+ * Everything implicit is off: only events sent through `pixelume.analytics` (and `$identify`)
+ * reach PostHog. No remote config or flags request, no external scripts, no cookies.
+ */
+function posthogConfig(host, gameId, gate) {
+    return {
+        api_host: host,
+        // Separate storage from any other PostHog installation on the same site.
+        persistence: 'localStorage',
+        persistence_name: `pixelume_${gameId}`,
+        consent_persistence_name: `__ph_opt_in_out_pixelume_${gameId}`,
+        opt_out_capturing_persistence_type: 'localStorage',
+        opt_out_persistence_by_default: true,
+        cross_subdomain_cookie: false,
+        person_profiles: 'identified_only',
+        autocapture: false,
+        rageclick: false,
+        capture_pageview: false,
+        capture_pageleave: false,
+        capture_exceptions: false,
+        capture_performance: false,
+        capture_heatmaps: false,
+        enable_heatmaps: false,
+        capture_dead_clicks: false,
+        disable_scroll_properties: true,
+        disable_session_recording: true,
+        disable_surveys: true,
+        disable_surveys_automatic_display: true,
+        disable_product_tours: true,
+        disable_conversations: true,
+        disable_web_experiments: true,
+        disable_external_dependency_loading: true,
+        advanced_disable_flags: true,
+        advanced_disable_decide: true,
+        advanced_disable_feature_flags: true,
+        advanced_disable_feature_flags_on_first_load: true,
+        remote_config_refresh_interval_ms: 0,
+        save_referrer: false,
+        save_campaign_params: false,
+        mask_personal_data_properties: true,
+        debug: false,
+        before_send: (event) => {
+            if (event === null || !gate.open)
+                return null;
+            if (event.event.startsWith('$') && !ALLOWED_PROVIDER_EVENTS.has(event.event))
+                return null;
+            try {
+                const properties = event.properties;
+                scrub(properties);
+                scrub(event.$set);
+                scrub(event.$set_once);
+                if (typeof properties === 'object' && properties !== null) {
+                    scrub(properties.$set);
+                    scrub(properties.$set_once);
+                }
+                return event;
+            }
+            catch {
+                // Fail closed: an event that cannot be cleaned is not sent.
+                return null;
+            }
+        },
+    };
+}
+/** Strips query strings and fragments (which may carry codes or personal data) from URLs. */
+function scrub(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return;
+    const properties = value;
+    for (const key of DROPPED_PROVIDER_PROPERTIES)
+        Reflect.deleteProperty(properties, key);
+    for (const [key, value] of Object.entries(properties)) {
+        if (!key.startsWith('$') || typeof value !== 'string' || !/^https?:\/\//iu.test(value)) {
+            continue;
+        }
+        try {
+            const url = new URL(value);
+            properties[key] = `${url.origin}${url.pathname}`;
+        }
+        catch {
+            Reflect.deleteProperty(properties, key);
+        }
+    }
+}
+/**
+ * `opt_out_capturing()` stops new captures but does not empty posthog's batch and retry queues,
+ * which would still be sent (seen with 1.435.8). Revocation must not leak them, so they are cleared
+ * here. The fields are internal to posthog-js: the version is pinned and a test runs this path
+ * against the real library.
+ */
+function discardPendingRequests(instance) {
+    for (const name of ['_requestQueue', '_retryQueue']) {
+        try {
+            const queue = instance[name];
+            if (queue !== undefined && Array.isArray(queue._queue))
+                queue._queue = [];
+        }
+        catch {
+            // Best effort; the gate in `before_send` already blocks new events.
+        }
+    }
+}
+/**
+ * Removes `prefix` and `prefix_*`. Game ids never contain `_`, so another game whose id merely
+ * starts with this one (`rail` / `rail-puzzle`) keeps its keys.
+ */
+function removeSessionKeys(prefix) {
+    try {
+        const storage = globalThis.sessionStorage;
+        const keys = [];
+        for (let index = 0; index < storage.length; index += 1) {
+            const key = storage.key(index);
+            if (key !== null && (key === prefix || key.startsWith(`${prefix}_`)))
+                keys.push(key);
+        }
+        for (const key of keys)
+            storage.removeItem(key);
+    }
+    catch {
+        // Blocked storage: nothing was written there either.
+    }
+}
+function hasBrowserGlobals() {
+    return (typeof globalThis.window === 'object' &&
+        typeof globalThis.document === 'object' &&
+        typeof globalThis.navigator === 'object');
+}
+//# sourceMappingURL=PostHogAnalyticsProvider.js.map

package/dist/modules/analytics/PostHogAnalyticsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostHogAnalyticsProvider.js","sourceRoot":"","sources":["../../../src/modules/analytics/PostHogAnalyticsProvider.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,8FAA8F;AAC9F,6BAA6B;AAC7B,MAAM,iBAAiB,GAAG,GAA+B,EAAE,CACzD,MAAM,CAAC,4CAA4C,CAAC,CAAC;AAEvD,mFAAmF;AACnF,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AACpF,oDAAoD;AACpD,MAAM,2BAA2B,GAAG,CAAC,iBAAiB,CAAU,CAAC;AAUjE;;;;GAIG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,EAA0B,CAAC;AAE1D,MAAM,OAAO,wBAAwB;IAC1B,IAAI,GAAG,SAAS,CAAC;IACjB,QAAQ,CAAyB;IAC1C,OAAO,GAA0B,IAAI,CAAC;IACtC,SAAS,GAA+B,IAAI,CAAC;IAC7C,SAAS,GAAG,IAAI,CAAC;IAEjB,YAAY,OAA+B;QACzC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO;QACpC,IAAI,CAAC,iBAAiB,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;QACpC,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAChD,CAAC;IAED,KAAK;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,OAAO;QACvD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAC9B,2EAA2E;QAC3E,IAAI,QAAQ,CAAC,uBAAuB,EAAE;YAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,MAAM;QACJ,8FAA8F;QAC9F,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI,CAAC;QACxE,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO;QAC9B,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QACjC,4FAA4F;QAC5F,kFAAkF;QAClF,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrB,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QAC7B,yFAAyF;QACzF,iBAAiB,CAAC,eAAe,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,CAAC,KAAqB;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QACrF,yFAAyF;QACzF,2FAA2F;QAC3F,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3B,QAAQ,CAAC,OAAO,CACd,KAAK,CAAC,IAAI,EACV,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,EACvB,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CACzC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,QAA2B;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QACrF,MAAM,UAAU,GAAG,QAAQ,CAAC,YAAY,CAAC,aAAa,CAAC,KAAK,YAAY,CAAC;QACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC7B,IAAI,QAAQ,CAAC,QAAQ,IAAI,UAAU;gBAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;YACtD,OAAO;QACT,CAAC;QACD,IAAI,UAAU,IAAI,QAAQ,CAAC,eAAe,EAAE,KAAK,QAAQ,CAAC,MAAM;YAAE,OAAO;QACzE,2EAA2E;QAC3E,IAAI,UAAU;YAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjC,qFAAqF;QACrF,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED,IAAI;QACF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9C,OAAO,GAAG,IAAI,KAAK,KAAK,KAAK,MAAM,EAAE,CAAC;IACxC,CAAC;IAED,eAAe;QACb,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAC5C,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,IAAI,iBAAiB,CAAC;QACjE,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACzC,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACtC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YACxD,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAmB,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC/D,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACjC,yEAAyE;QACzE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACf,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;gBAAE,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,aAAa,CACpB,IAAY,EACZ,MAAc,EACd,IAAgC;IAEhC,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,yEAAyE;QACzE,WAAW,EAAE,cAAc;QAC3B,gBAAgB,EAAE,YAAY,MAAM,EAAE;QACtC,wBAAwB,EAAE,4BAA4B,MAAM,EAAE;QAC9D,kCAAkC,EAAE,cAAc;QAClD,8BAA8B,EAAE,IAAI;QACpC,sBAAsB,EAAE,KAAK;QAC7B,eAAe,EAAE,iBAAiB;QAClC,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,KAAK;QAChB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,KAAK;QACzB,mBAAmB,EAAE,KAAK;QAC1B,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;QACtB,mBAAmB,EAAE,KAAK;QAC1B,yBAAyB,EAAE,IAAI;QAC/B,yBAAyB,EAAE,IAAI;QAC/B,eAAe,EAAE,IAAI;QACrB,iCAAiC,EAAE,IAAI;QACvC,qBAAqB,EAAE,IAAI;QAC3B,qBAAqB,EAAE,IAAI;QAC3B,uBAAuB,EAAE,IAAI;QAC7B,mCAAmC,EAAE,IAAI;QACzC,sBAAsB,EAAE,IAAI;QAC5B,uBAAuB,EAAE,IAAI;QAC7B,8BAA8B,EAAE,IAAI;QACpC,4CAA4C,EAAE,IAAI;QAClD,iCAAiC,EAAE,CAAC;QACpC,aAAa,EAAE,KAAK;QACpB,oBAAoB,EAAE,KAAK;QAC3B,6BAA6B,EAAE,IAAI;QACnC,KAAK,EAAE,KAAK;QACZ,WAAW,EAAE,CAAC,KAA2B,EAAwB,EAAE;YACjE,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC9C,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC1F,IAAI,CAAC;gBACH,MAAM,UAAU,GAAY,KAAK,CAAC,UAAU,CAAC;gBAC7C,KAAK,CAAC,UAAU,CAAC,CAAC;gBAClB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAClB,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACvB,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;oBAC1D,KAAK,CAAE,UAAsC,CAAC,IAAI,CAAC,CAAC;oBACpD,KAAK,CAAE,UAAsC,CAAC,SAAS,CAAC,CAAC;gBAC3D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;YAAC,MAAM,CAAC;gBACP,4DAA4D;gBAC5D,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAChF,MAAM,UAAU,GAAG,KAAgC,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,2BAA2B;QAAE,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACvF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACvF,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;YAC3B,UAAU,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAAC,QAA6B;IAC3D,KAAK,MAAM,IAAI,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,KAAK,GAAI,QAAwE,CAAC,IAAI,CAAC,CAAC;YAC9F,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBAAE,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,MAAc;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC;QAC1C,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACvD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,qDAAqD;IACvD,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO,CACL,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ;QACrC,OAAO,UAAU,CAAC,QAAQ,KAAK,QAAQ;QACvC,OAAO,UAAU,CAAC,SAAS,KAAK,QAAQ,CACzC,CAAC;AACJ,CAAC","sourcesContent":["import type { CaptureResult, PostHogConfig } from 'posthog-js/dist/module.slim.no-external.js';\nimport type { AnalyticsEvent, AnalyticsIdentity, AnalyticsProvider } from './AnalyticsProvider.js';\n\n/** The part of the `posthog-js` instance API the provider relies on. */\nexport interface PostHogInstanceLike {\n  init(token: string, config: Partial<PostHogConfig>): unknown;\n  capture(\n    event: string,\n    properties?: Record<string, unknown> | null,\n    options?: { readonly timestamp?: Date },\n  ): unknown;\n  identify(distinctId: string): void;\n  reset(resetDeviceId?: boolean): void;\n  opt_in_capturing(options?: { readonly captureEventName?: false | null }): void;\n  opt_out_capturing(): void;\n  has_opted_out_capturing(): boolean;\n  get_distinct_id(): string;\n  get_property(key: string): unknown;\n}\n\nexport interface PostHogModuleLike {\n  readonly PostHog: new () => PostHogInstanceLike;\n}\n\nexport interface PostHogProviderOptions {\n  readonly token: string;\n  readonly host: string;\n  readonly gameId: string;\n  /** Test seam; defaults to a dynamic import of the slim, self-contained posthog-js bundle. */\n  readonly loadModule?: () => Promise<PostHogModuleLike>;\n}\n\n/**\n * Slim build without extensions (no autocapture, replay, surveys, toolbar...) and without\n * `loadExternalDependency`: it never injects `<script>` tags. The dynamic import keeps posthog-js\n * out of the game's main bundle and out of Node/SSR: it only runs after consent, in a browser.\n */\n// Typed against the real posthog-js declarations: an upgrade that changes a method we rely on\n// fails the type check here.\nconst defaultLoadModule = (): Promise<PostHogModuleLike> =>\n  import('posthog-js/dist/module.slim.no-external.js');\n\n/** Provider events that may leave the browser; every other `$event` is dropped. */\nconst ALLOWED_PROVIDER_EVENTS: ReadonlySet<string> = new Set(['$identify', '$set']);\n/** Properties removed from every outgoing event. */\nconst DROPPED_PROVIDER_PROPERTIES = ['$raw_user_agent'] as const;\n\ninterface SharedInstance {\n  readonly ready: Promise<PostHogInstanceLike>;\n  /** Set once `ready` resolves. */\n  instance: PostHogInstanceLike | null;\n  /** Shared by every provider of this instance; closed while consent is not granted. */\n  readonly gate: { open: boolean };\n}\n\n/**\n * posthog-js has no teardown: every initialized instance keeps its page listeners for the life of\n * the page. Instances are therefore created once per (host, token, game) and reused by later\n * clients (SPA remounts, hot reload) instead of being initialized again.\n */\nconst sharedInstances = new Map<string, SharedInstance>();\n\nexport class PostHogAnalyticsProvider implements AnalyticsProvider {\n  readonly name = 'posthog';\n  readonly #options: PostHogProviderOptions;\n  #shared: SharedInstance | null = null;\n  #instance: PostHogInstanceLike | null = null;\n  #attached = true;\n\n  constructor(options: PostHogProviderOptions) {\n    this.#options = options;\n  }\n\n  async load(): Promise<void> {\n    if (this.#instance !== null) return;\n    if (!hasBrowserGlobals()) throw new Error('PostHog analytics needs a browser environment');\n    const shared = this.#sharedInstance();\n    this.#shared = shared;\n    const instance = await shared.ready;\n    if (this.#attached) this.#instance = instance;\n  }\n\n  optIn(): void {\n    const instance = this.#instance;\n    if (instance === null || this.#shared === null) return;\n    this.#shared.gate.open = true;\n    // Undo a previous revocation; never capture posthog's own `$opt_in` event.\n    if (instance.has_opted_out_capturing()) instance.opt_in_capturing({ captureEventName: false });\n  }\n\n  optOut(): void {\n    // Also reached before `load()`: another client of the same game may have opened the instance.\n    const shared = this.#shared ?? sharedInstances.get(this.#key()) ?? null;\n    if (shared === null) return;\n    shared.gate.open = false;\n    const instance = shared.instance;\n    if (instance === null) return;\n    discardPendingRequests(instance);\n    // `reset()` clears posthog's consent state, so it must come first; then opting out disables\n    // persistence and removes what posthog stored (`opt_out_persistence_by_default`).\n    instance.reset(true);\n    instance.opt_out_capturing();\n    // Disabling persistence leaves the tab's window id in sessionStorage; remove it as well.\n    removeSessionKeys(`ph_pixelume_${this.#options.gameId}`);\n  }\n\n  capture(event: AnalyticsEvent): void {\n    const instance = this.#instance;\n    if (instance === null || !this.#attached || this.#shared?.gate.open !== true) return;\n    // Any options object makes posthog-js skip its batch and send at once, so live events go\n    // without one (posthog stamps them); only events that waited for the load keep their time.\n    if (event.delayed === true) {\n      instance.capture(\n        event.name,\n        { ...event.properties },\n        { timestamp: new Date(event.timestamp) },\n      );\n    } else {\n      instance.capture(event.name, { ...event.properties });\n    }\n  }\n\n  identify(identity: AnalyticsIdentity): void {\n    const instance = this.#instance;\n    if (instance === null || !this.#attached || this.#shared?.gate.open !== true) return;\n    const identified = instance.get_property('$user_state') === 'identified';\n    if (identity.player === null) {\n      if (identity.separate && identified) instance.reset();\n      return;\n    }\n    if (identified && instance.get_distinct_id() === identity.player) return;\n    // Another account was identified on this browser: never merge two players.\n    if (identified) instance.reset();\n    // From an anonymous id, `identify` links the visitor's earlier events to the player.\n    instance.identify(identity.player);\n  }\n\n  detach(): void {\n    this.#attached = false;\n    this.#instance = null;\n  }\n\n  #key(): string {\n    const { token, host, gameId } = this.#options;\n    return `${host}\\n${token}\\n${gameId}`;\n  }\n\n  #sharedInstance(): SharedInstance {\n    const { token, host, gameId } = this.#options;\n    const key = this.#key();\n    const existing = sharedInstances.get(key);\n    if (existing !== undefined) return existing;\n    const gate = { open: true };\n    const loadModule = this.#options.loadModule ?? defaultLoadModule;\n    const ready = loadModule().then((module) => {\n      const instance = new module.PostHog();\n      instance.init(token, posthogConfig(host, gameId, gate));\n      shared.instance = instance;\n      return instance;\n    });\n    const shared: SharedInstance = { ready, instance: null, gate };\n    sharedInstances.set(key, shared);\n    // A failed chunk download (offline, CSP) must not poison later attempts.\n    ready.catch(() => {\n      if (sharedInstances.get(key) === shared) sharedInstances.delete(key);\n    });\n    return shared;\n  }\n}\n\n/**\n * Everything implicit is off: only events sent through `pixelume.analytics` (and `$identify`)\n * reach PostHog. No remote config or flags request, no external scripts, no cookies.\n */\nfunction posthogConfig(\n  host: string,\n  gameId: string,\n  gate: { readonly open: boolean },\n): Partial<PostHogConfig> {\n  return {\n    api_host: host,\n    // Separate storage from any other PostHog installation on the same site.\n    persistence: 'localStorage',\n    persistence_name: `pixelume_${gameId}`,\n    consent_persistence_name: `__ph_opt_in_out_pixelume_${gameId}`,\n    opt_out_capturing_persistence_type: 'localStorage',\n    opt_out_persistence_by_default: true,\n    cross_subdomain_cookie: false,\n    person_profiles: 'identified_only',\n    autocapture: false,\n    rageclick: false,\n    capture_pageview: false,\n    capture_pageleave: false,\n    capture_exceptions: false,\n    capture_performance: false,\n    capture_heatmaps: false,\n    enable_heatmaps: false,\n    capture_dead_clicks: false,\n    disable_scroll_properties: true,\n    disable_session_recording: true,\n    disable_surveys: true,\n    disable_surveys_automatic_display: true,\n    disable_product_tours: true,\n    disable_conversations: true,\n    disable_web_experiments: true,\n    disable_external_dependency_loading: true,\n    advanced_disable_flags: true,\n    advanced_disable_decide: true,\n    advanced_disable_feature_flags: true,\n    advanced_disable_feature_flags_on_first_load: true,\n    remote_config_refresh_interval_ms: 0,\n    save_referrer: false,\n    save_campaign_params: false,\n    mask_personal_data_properties: true,\n    debug: false,\n    before_send: (event: CaptureResult | null): CaptureResult | null => {\n      if (event === null || !gate.open) return null;\n      if (event.event.startsWith('$') && !ALLOWED_PROVIDER_EVENTS.has(event.event)) return null;\n      try {\n        const properties: unknown = event.properties;\n        scrub(properties);\n        scrub(event.$set);\n        scrub(event.$set_once);\n        if (typeof properties === 'object' && properties !== null) {\n          scrub((properties as Record<string, unknown>).$set);\n          scrub((properties as Record<string, unknown>).$set_once);\n        }\n        return event;\n      } catch {\n        // Fail closed: an event that cannot be cleaned is not sent.\n        return null;\n      }\n    },\n  };\n}\n\n/** Strips query strings and fragments (which may carry codes or personal data) from URLs. */\nfunction scrub(value: unknown): void {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return;\n  const properties = value as Record<string, unknown>;\n  for (const key of DROPPED_PROVIDER_PROPERTIES) Reflect.deleteProperty(properties, key);\n  for (const [key, value] of Object.entries(properties)) {\n    if (!key.startsWith('$') || typeof value !== 'string' || !/^https?:\\/\\//iu.test(value)) {\n      continue;\n    }\n    try {\n      const url = new URL(value);\n      properties[key] = `${url.origin}${url.pathname}`;\n    } catch {\n      Reflect.deleteProperty(properties, key);\n    }\n  }\n}\n\n/**\n * `opt_out_capturing()` stops new captures but does not empty posthog's batch and retry queues,\n * which would still be sent (seen with 1.435.8). Revocation must not leak them, so they are cleared\n * here. The fields are internal to posthog-js: the version is pinned and a test runs this path\n * against the real library.\n */\nfunction discardPendingRequests(instance: PostHogInstanceLike): void {\n  for (const name of ['_requestQueue', '_retryQueue']) {\n    try {\n      const queue = (instance as unknown as Record<string, { _queue?: unknown } | undefined>)[name];\n      if (queue !== undefined && Array.isArray(queue._queue)) queue._queue = [];\n    } catch {\n      // Best effort; the gate in `before_send` already blocks new events.\n    }\n  }\n}\n\n/**\n * Removes `prefix` and `prefix_*`. Game ids never contain `_`, so another game whose id merely\n * starts with this one (`rail` / `rail-puzzle`) keeps its keys.\n */\nfunction removeSessionKeys(prefix: string): void {\n  try {\n    const storage = globalThis.sessionStorage;\n    const keys: string[] = [];\n    for (let index = 0; index < storage.length; index += 1) {\n      const key = storage.key(index);\n      if (key !== null && (key === prefix || key.startsWith(`${prefix}_`))) keys.push(key);\n    }\n    for (const key of keys) storage.removeItem(key);\n  } catch {\n    // Blocked storage: nothing was written there either.\n  }\n}\n\nfunction hasBrowserGlobals(): boolean {\n  return (\n    typeof globalThis.window === 'object' &&\n    typeof globalThis.document === 'object' &&\n    typeof globalThis.navigator === 'object'\n  );\n}\n"]}

package/dist/modules/analytics/events.d.ts

@@ -0,0 +1,30 @@
+import type { PixelumeAnalyticsIssue } from '../../core/types.js';
+/**
+ * Stable event catalog. Names are part of the public contract: dashboards are built on them, so
+ * they are only ever added, never renamed.
+ */
+export declare const ANALYTICS_EVENTS: Readonly<{
+    readonly sessionStarted: "game_session_started";
+    readonly sessionEnded: "game_session_ended";
+    readonly levelStarted: "level_started";
+    readonly levelCompleted: "level_completed";
+    readonly levelFailed: "level_failed";
+}>;
+export declare const MAX_PROPERTIES = 25;
+export declare const MAX_STRING_LENGTH = 200;
+/** Metadata added by the SDK to every event; games cannot override it. */
+export declare const METADATA_PROPERTIES: ReadonlySet<string>;
+export type AnalyticsPropertyValue = string | number | boolean | null;
+export type AnalyticsProperties = Record<string, AnalyticsPropertyValue>;
+export type IssueReporter = (code: PixelumeAnalyticsIssue['code'], event: string | null, property?: string | null) => void;
+export declare function isValidEventName(name: unknown): name is string;
+export declare function isCatalogEvent(name: string): boolean;
+/** A level is a finite number or a 1–64 character string; always sent as a string. */
+export declare function normalizeLevel(level: unknown): string | null;
+export declare function normalizeReason(reason: unknown): string | null;
+/**
+ * Keeps only flat, small, non-sensitive values supplied by the game: snake_case keys, strings up
+ * to 200 characters, finite numbers, booleans and `null`; at most 25 keys. `undefined` is removed
+ * silently; anything else is dropped and reported. `protectedKeys` are set by the SDK itself.
+ */
+export declare function sanitizeProperties(event: string, input: unknown, protectedKeys: ReadonlySet<string>, report: IssueReporter): AnalyticsProperties;

package/dist/modules/analytics/events.js

@@ -0,0 +1,153 @@
+/**
+ * Stable event catalog. Names are part of the public contract: dashboards are built on them, so
+ * they are only ever added, never renamed.
+ */
+export const ANALYTICS_EVENTS = Object.freeze({
+    sessionStarted: 'game_session_started',
+    sessionEnded: 'game_session_ended',
+    levelStarted: 'level_started',
+    levelCompleted: 'level_completed',
+    levelFailed: 'level_failed',
+});
+const CATALOG = new Set(Object.values(ANALYTICS_EVENTS));
+/** snake_case, starts with a letter, 1–64 characters. Excludes provider names such as `$pageview`. */
+const NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+export const MAX_PROPERTIES = 25;
+export const MAX_STRING_LENGTH = 200;
+const MAX_LEVEL_LENGTH = 64;
+/** Metadata added by the SDK to every event; games cannot override it. */
+export const METADATA_PROPERTIES = new Set([
+    'game_id',
+    'game_version',
+    'sdk_version',
+    'session_id',
+    'platform',
+]);
+/** Keys the provider treats specially. */
+const PROVIDER_PROPERTIES = new Set([
+    'distinct_id',
+    'token',
+    'timestamp',
+    'uuid',
+    'event',
+]);
+/**
+ * Best-effort guard against personal data and credentials. It complements, and does not replace,
+ * the rule that games never send them.
+ */
+const SENSITIVE_KEYS = new Set([
+    'email',
+    'e_mail',
+    'password',
+    'secret',
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'authorization',
+    'cookie',
+    'ip',
+    'ip_address',
+    'phone',
+    'cpf',
+    'cnpj',
+    'address',
+    'name',
+    'username',
+    'user_name',
+    'display_name',
+    'full_name',
+    'first_name',
+    'last_name',
+]);
+const SENSITIVE_SUFFIX = /_(?:email|password|secret|access_token|refresh_token|id_token)$/u;
+const EMAIL_VALUE = /[^\s@]+@[^\s@]+\.[^\s@]+/u;
+const CREDENTIAL_VALUE = /^(?:Bearer\s|eyJ[\w-]+\.[\w-]+\.)/u;
+export function isValidEventName(name) {
+    return typeof name === 'string' && NAME_PATTERN.test(name);
+}
+export function isCatalogEvent(name) {
+    return CATALOG.has(name);
+}
+/** A level is a finite number or a 1–64 character string; always sent as a string. */
+export function normalizeLevel(level) {
+    if (typeof level === 'number')
+        return Number.isFinite(level) ? String(level) : null;
+    if (typeof level !== 'string')
+        return null;
+    const trimmed = level.trim();
+    return trimmed.length === 0 || trimmed.length > MAX_LEVEL_LENGTH ? null : trimmed;
+}
+export function normalizeReason(reason) {
+    if (typeof reason !== 'string')
+        return null;
+    const trimmed = reason.trim();
+    return trimmed.length === 0 || trimmed.length > MAX_LEVEL_LENGTH ? null : trimmed;
+}
+/**
+ * Keeps only flat, small, non-sensitive values supplied by the game: snake_case keys, strings up
+ * to 200 characters, finite numbers, booleans and `null`; at most 25 keys. `undefined` is removed
+ * silently; anything else is dropped and reported. `protectedKeys` are set by the SDK itself.
+ */
+export function sanitizeProperties(event, input, protectedKeys, report) {
+    const output = {};
+    if (input === undefined || input === null)
+        return output;
+    if (!isPlainObject(input)) {
+        report('invalid_property', event);
+        return output;
+    }
+    let count = 0;
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined)
+            continue;
+        if (!NAME_PATTERN.test(key)) {
+            report('invalid_property', event);
+            continue;
+        }
+        if (METADATA_PROPERTIES.has(key) || PROVIDER_PROPERTIES.has(key) || protectedKeys.has(key)) {
+            report('reserved_property', event, key);
+            continue;
+        }
+        if (SENSITIVE_KEYS.has(key) || SENSITIVE_SUFFIX.test(key)) {
+            report('sensitive_property', event, key);
+            continue;
+        }
+        const normalized = normalizeValue(value);
+        if (normalized === INVALID) {
+            report('invalid_property', event, key);
+            continue;
+        }
+        if (typeof normalized === 'string' && looksSensitive(normalized)) {
+            report('sensitive_property', event, key);
+            continue;
+        }
+        if (count >= MAX_PROPERTIES) {
+            report('too_many_properties', event, key);
+            continue;
+        }
+        output[key] = normalized;
+        count += 1;
+    }
+    return output;
+}
+const INVALID = Symbol('invalid');
+function normalizeValue(value) {
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : INVALID;
+    if (typeof value === 'string')
+        return value.length <= MAX_STRING_LENGTH ? value : INVALID;
+    return INVALID;
+}
+function looksSensitive(value) {
+    return EMAIL_VALUE.test(value) || CREDENTIAL_VALUE.test(value);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=events.js.map

package/dist/modules/analytics/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/modules/analytics/events.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PixelumeAnalyticsIssue } from '../../core/types.js';\n\n/**\n * Stable event catalog. Names are part of the public contract: dashboards are built on them, so\n * they are only ever added, never renamed.\n */\nexport const ANALYTICS_EVENTS = Object.freeze({\n  sessionStarted: 'game_session_started',\n  sessionEnded: 'game_session_ended',\n  levelStarted: 'level_started',\n  levelCompleted: 'level_completed',\n  levelFailed: 'level_failed',\n} as const);\n\nconst CATALOG: ReadonlySet<string> = new Set(Object.values(ANALYTICS_EVENTS));\n/** snake_case, starts with a letter, 1–64 characters. Excludes provider names such as `$pageview`. */\nconst NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;\nexport const MAX_PROPERTIES = 25;\nexport const MAX_STRING_LENGTH = 200;\nconst MAX_LEVEL_LENGTH = 64;\n\n/** Metadata added by the SDK to every event; games cannot override it. */\nexport const METADATA_PROPERTIES: ReadonlySet<string> = new Set([\n  'game_id',\n  'game_version',\n  'sdk_version',\n  'session_id',\n  'platform',\n]);\n/** Keys the provider treats specially. */\nconst PROVIDER_PROPERTIES: ReadonlySet<string> = new Set([\n  'distinct_id',\n  'token',\n  'timestamp',\n  'uuid',\n  'event',\n]);\n/**\n * Best-effort guard against personal data and credentials. It complements, and does not replace,\n * the rule that games never send them.\n */\nconst SENSITIVE_KEYS: ReadonlySet<string> = new Set([\n  'email',\n  'e_mail',\n  'password',\n  'secret',\n  'token',\n  'access_token',\n  'refresh_token',\n  'id_token',\n  'authorization',\n  'cookie',\n  'ip',\n  'ip_address',\n  'phone',\n  'cpf',\n  'cnpj',\n  'address',\n  'name',\n  'username',\n  'user_name',\n  'display_name',\n  'full_name',\n  'first_name',\n  'last_name',\n]);\nconst SENSITIVE_SUFFIX = /_(?:email|password|secret|access_token|refresh_token|id_token)$/u;\nconst EMAIL_VALUE = /[^\\s@]+@[^\\s@]+\\.[^\\s@]+/u;\nconst CREDENTIAL_VALUE = /^(?:Bearer\\s|eyJ[\\w-]+\\.[\\w-]+\\.)/u;\n\nexport type AnalyticsPropertyValue = string | number | boolean | null;\nexport type AnalyticsProperties = Record<string, AnalyticsPropertyValue>;\nexport type IssueReporter = (\n  code: PixelumeAnalyticsIssue['code'],\n  event: string | null,\n  property?: string | null,\n) => void;\n\nexport function isValidEventName(name: unknown): name is string {\n  return typeof name === 'string' && NAME_PATTERN.test(name);\n}\n\nexport function isCatalogEvent(name: string): boolean {\n  return CATALOG.has(name);\n}\n\n/** A level is a finite number or a 1–64 character string; always sent as a string. */\nexport function normalizeLevel(level: unknown): string | null {\n  if (typeof level === 'number') return Number.isFinite(level) ? String(level) : null;\n  if (typeof level !== 'string') return null;\n  const trimmed = level.trim();\n  return trimmed.length === 0 || trimmed.length > MAX_LEVEL_LENGTH ? null : trimmed;\n}\n\nexport function normalizeReason(reason: unknown): string | null {\n  if (typeof reason !== 'string') return null;\n  const trimmed = reason.trim();\n  return trimmed.length === 0 || trimmed.length > MAX_LEVEL_LENGTH ? null : trimmed;\n}\n\n/**\n * Keeps only flat, small, non-sensitive values supplied by the game: snake_case keys, strings up\n * to 200 characters, finite numbers, booleans and `null`; at most 25 keys. `undefined` is removed\n * silently; anything else is dropped and reported. `protectedKeys` are set by the SDK itself.\n */\nexport function sanitizeProperties(\n  event: string,\n  input: unknown,\n  protectedKeys: ReadonlySet<string>,\n  report: IssueReporter,\n): AnalyticsProperties {\n  const output: AnalyticsProperties = {};\n  if (input === undefined || input === null) return output;\n  if (!isPlainObject(input)) {\n    report('invalid_property', event);\n    return output;\n  }\n  let count = 0;\n  for (const [key, value] of Object.entries(input)) {\n    if (value === undefined) continue;\n    if (!NAME_PATTERN.test(key)) {\n      report('invalid_property', event);\n      continue;\n    }\n    if (METADATA_PROPERTIES.has(key) || PROVIDER_PROPERTIES.has(key) || protectedKeys.has(key)) {\n      report('reserved_property', event, key);\n      continue;\n    }\n    if (SENSITIVE_KEYS.has(key) || SENSITIVE_SUFFIX.test(key)) {\n      report('sensitive_property', event, key);\n      continue;\n    }\n    const normalized = normalizeValue(value);\n    if (normalized === INVALID) {\n      report('invalid_property', event, key);\n      continue;\n    }\n    if (typeof normalized === 'string' && looksSensitive(normalized)) {\n      report('sensitive_property', event, key);\n      continue;\n    }\n    if (count >= MAX_PROPERTIES) {\n      report('too_many_properties', event, key);\n      continue;\n    }\n    output[key] = normalized;\n    count += 1;\n  }\n  return output;\n}\n\nconst INVALID = Symbol('invalid');\n\nfunction normalizeValue(value: unknown): AnalyticsPropertyValue | typeof INVALID {\n  if (value === null || typeof value === 'boolean') return value;\n  if (typeof value === 'number') return Number.isFinite(value) ? value : INVALID;\n  if (typeof value === 'string') return value.length <= MAX_STRING_LENGTH ? value : INVALID;\n  return INVALID;\n}\n\nfunction looksSensitive(value: string): boolean {\n  return EMAIL_VALUE.test(value) || CREDENTIAL_VALUE.test(value);\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  const prototype = Object.getPrototypeOf(value) as unknown;\n  return prototype === Object.prototype || prototype === null;\n}\n"]}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Version of the SDK package. Kept in sync with `package.json` (checked by tests and by the release workflow). */
-export declare const SDK_VERSION = "0.5.0";
+export declare const SDK_VERSION = "0.6.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Version of the SDK package. Kept in sync with `package.json` (checked by tests and by the release workflow). */
-export const SDK_VERSION = '0.5.0';
+export const SDK_VERSION = '0.6.0';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC","sourcesContent":["/** Version of the SDK package. Kept in sync with `package.json` (checked by tests and by the release workflow). */\nexport const SDK_VERSION = '0.5.0';\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC","sourcesContent":["/** Version of the SDK package. Kept in sync with `package.json` (checked by tests and by the release workflow). */\nexport const SDK_VERSION = '0.6.0';\n"]}