@mpgd/analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imjlk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformTarget } from '@mpgd/platform';
+export type AnalyticsEventName = 'game_started' | 'stage_finished' | 'purchase_started' | 'purchase_completed' | 'purchase_granted' | 'purchase_rejected' | 'rewarded_ad_completed' | 'rewarded_ad_granted' | 'rewarded_ad_rejected' | 'leaderboard_submitted' | 'leaderboard_recorded';
+export type AnalyticsPropertyValue = string | number | boolean;
+export interface AnalyticsEvent {
+  readonly name: AnalyticsEventName;
+  readonly target: PlatformTarget | 'server';
+  readonly sessionId: string;
+  readonly occurredAt: string;
+  readonly properties: Record<string, AnalyticsPropertyValue>;
+}
+export interface AnalyticsSink {
+  track(event: AnalyticsEvent): Promise<void> | void;
+}
+export interface AnalyticsReporter {
+  track(input: {
+    readonly name: AnalyticsEventName;
+    readonly properties?: Record<string, AnalyticsPropertyValue | undefined>;
+    readonly occurredAt?: string;
+  }): Promise<void>;
+}
+export interface CreateAnalyticsReporterInput {
+  readonly target: PlatformTarget | 'server';
+  readonly sessionId: string;
+  readonly sink?: AnalyticsSink;
+  readonly now?: () => string;
+}
+export interface BufferedAnalyticsSink extends AnalyticsSink {
+  readonly events: readonly AnalyticsEvent[];
+}
+export declare const assertAnalyticsEvent: (input: unknown) => AnalyticsEvent;
+export declare function createNoopAnalyticsSink(): AnalyticsSink;
+export declare function createBufferedAnalyticsSink(): BufferedAnalyticsSink;
+export declare function createAnalyticsReporter(input: CreateAnalyticsReporterInput): AnalyticsReporter;

package/dist/index.js

@@ -0,0 +1,123 @@
+import * as _a from "typia/lib/internal/_assertGuard";
+import * as _b from "typia/lib/internal/_accessExpressionAsString";
+const __typia_transform__accessExpressionAsString = _b._accessExpressionAsString;
+import typia from 'typia';
+export const assertAnalyticsEvent = (() => {
+    const _iv0 = new Set(["game_started", "leaderboard_recorded", "leaderboard_submitted", "purchase_completed", "purchase_granted", "purchase_rejected", "purchase_started", "rewarded_ad_completed", "rewarded_ad_granted", "rewarded_ad_rejected", "stage_finished"]);
+    const _av0 = new Set(["game_started", "leaderboard_recorded", "leaderboard_submitted", "purchase_completed", "purchase_granted", "purchase_rejected", "purchase_started", "rewarded_ad_completed", "rewarded_ad_granted", "rewarded_ad_rejected", "stage_finished"]);
+    const _ae0 = "(\"game_started\" | \"leaderboard_recorded\" | \"leaderboard_submitted\" | \"purchase_completed\" | \"purchase_granted\" | \"purchase_rejected\" | \"purchase_started\" | \"rewarded_ad_completed\" | \"rewarded_ad_granted\" | \"rewarded_ad_rejected\" | \"stage_finished\")";
+    const _ao0 = (input, _path, _exceptionable = true) => (true === _av0.has(input.name) || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".name",
+        expected: _ae0,
+        value: input.name
+    }, _errorFactory)) && ("ait" === input.target || "android" === input.target || "browser" === input.target || "ios" === input.target || "reddit" === input.target || "server" === input.target || "tauri" === input.target || "telegram" === input.target || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".target",
+        expected: "(\"ait\" | \"android\" | \"browser\" | \"ios\" | \"reddit\" | \"server\" | \"tauri\" | \"telegram\")",
+        value: input.target
+    }, _errorFactory)) && ("string" === typeof input.sessionId || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".sessionId",
+        expected: "string",
+        value: input.sessionId
+    }, _errorFactory)) && ("string" === typeof input.occurredAt || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".occurredAt",
+        expected: "string",
+        value: input.occurredAt
+    }, _errorFactory)) && (("object" === typeof input.properties && null !== input.properties && false === Array.isArray(input.properties) || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".properties",
+        expected: "Record<string, AnalyticsPropertyValue>",
+        value: input.properties
+    }, _errorFactory)) && _ao1(input.properties, _path + ".properties", true && _exceptionable) || _a._assertGuard(_exceptionable, {
+        method: "typia.createAssert",
+        path: _path + ".properties",
+        expected: "Record<string, AnalyticsPropertyValue>",
+        value: input.properties
+    }, _errorFactory));
+    const _ao1 = (input, _path, _exceptionable = true) => false === _exceptionable || Object.keys(input).every(key => {
+        const value = input[key];
+        if (undefined === value)
+            return true;
+        return "string" === typeof value || "number" === typeof value || "boolean" === typeof value || _a._assertGuard(_exceptionable, {
+            method: "typia.createAssert",
+            path: _path + __typia_transform__accessExpressionAsString(key),
+            expected: "(boolean | number | string)",
+            value: value
+        }, _errorFactory);
+    });
+    const _io0 = input => true === _iv0.has(input.name) && ("ait" === input.target || "android" === input.target || "browser" === input.target || "ios" === input.target || "reddit" === input.target || "server" === input.target || "tauri" === input.target || "telegram" === input.target) && "string" === typeof input.sessionId && "string" === typeof input.occurredAt && ("object" === typeof input.properties && null !== input.properties && false === Array.isArray(input.properties) && _io1(input.properties));
+    const _io1 = input => Object.keys(input).every(key => {
+        const value = input[key];
+        if (undefined === value)
+            return true;
+        return "string" === typeof value || "number" === typeof value || "boolean" === typeof value;
+    });
+    const __is = input => "object" === typeof input && null !== input && _io0(input);
+    let _errorFactory;
+    return (input, errorFactory) => {
+        if (false === __is(input)) {
+            _errorFactory = errorFactory;
+            ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _a._assertGuard(true, {
+                method: "typia.createAssert",
+                path: _path + "",
+                expected: "AnalyticsEvent",
+                value: input
+            }, _errorFactory)) && _ao0(input, _path + "", true) || _a._assertGuard(true, {
+                method: "typia.createAssert",
+                path: _path + "",
+                expected: "AnalyticsEvent",
+                value: input
+            }, _errorFactory))(input, "$input", true);
+        }
+        return input;
+    };
+})();
+export function createNoopAnalyticsSink() {
+    return {
+        track() { },
+    };
+}
+export function createBufferedAnalyticsSink() {
+    const events = [];
+    return {
+        get events() {
+            return events;
+        },
+        track(event) {
+            events.push(assertAnalyticsEvent(event));
+        },
+    };
+}
+export function createAnalyticsReporter(input) {
+    const sink = input.sink ?? createNoopAnalyticsSink();
+    const now = input.now ?? (() => new Date().toISOString());
+    return {
+        async track(eventInput) {
+            const event = assertAnalyticsEvent({
+                name: eventInput.name,
+                target: input.target,
+                sessionId: input.sessionId,
+                occurredAt: eventInput.occurredAt ?? now(),
+                properties: compactProperties(eventInput.properties ?? {}),
+            });
+            try {
+                await sink.track(event);
+            }
+            catch {
+                // Analytics is best-effort and must not break gameplay or ledger flows.
+            }
+        },
+    };
+}
+function compactProperties(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined) {
+            output[key] = value;
+        }
+    }
+    return output;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mpgd/analytics",
+  "version": "0.1.0",
+  "description": "Typed analytics event schema and sink helpers for mpgd platform integrations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjlk/mpgd-kit.git",
+    "directory": "packages/analytics"
+  },
+  "bugs": {
+    "url": "https://github.com/imjlk/mpgd-kit/issues"
+  },
+  "homepage": "https://github.com/imjlk/mpgd-kit#readme",
+  "keywords": [
+    "mpgd",
+    "phaser",
+    "vite",
+    "typescript",
+    "capacitor",
+    "apps-in-toss",
+    "game-development",
+    "game-distribution"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "typia": "rc",
+    "@mpgd/platform": "0.1.0"
+  },
+  "devDependencies": {
+    "ttsc": "0.16.9",
+    "typescript": "7.0.1-rc"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "ttsc --noEmit",
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/analytics/src/index.test.ts",
+    "lint": "ttsc --noEmit",
+    "format": "ttsc format",
+    "fix": "ttsc fix"
+  }
+}