@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/dist/core/revenue.d.ts

@@ -0,0 +1,33 @@
+import type { TrackContext } from './types';
+/** Business placement names belong to the host game. */
+export type AdPlacement = string;
+export interface AdRevenueFact {
+    /** Unique per exposure, including each banner refresh. Never use just the banner object's ID. */
+    exposureId: string;
+    placement: AdPlacement;
+    businessPlacement?: string;
+    format: 'banner' | 'rewarded' | 'interstitial' | 'app_open';
+    provider: string;
+    network: string;
+    adUnitId: string;
+    amount: number;
+    currency: 'USD';
+    precision: string;
+    isTest: boolean;
+    isMock?: boolean;
+    isDemo?: boolean;
+    country?: string;
+    countrySource?: string;
+    shownAt?: string;
+    adConfigRevision?: string;
+}
+export interface EncodedRevenueEvent {
+    name: string;
+    properties: Record<string, unknown>;
+}
+export type AdRevenueEncoder = (fact: Readonly<AdRevenueFact>) => EncodedRevenueEvent | null;
+export interface EventSink {
+    track(name: string, properties: Record<string, unknown>, context?: TrackContext): boolean;
+}
+/** Validate the income fact; the explicit encoder owns event names and wire properties. */
+export declare function enqueueAdRevenue(client: EventSink, fact: AdRevenueFact, context: TrackContext, encode: AdRevenueEncoder): boolean;

package/dist/core/revenue.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enqueueAdRevenue = enqueueAdRevenue;
+/** Validate the income fact; the explicit encoder owns event names and wire properties. */
+function enqueueAdRevenue(client, fact, context, encode) {
+    if (!fact || ![fact.exposureId, fact.network, fact.adUnitId, fact.provider, fact.placement].every(value => typeof value === 'string' && value.trim().length > 0) ||
+        !Number.isFinite(fact.amount) || fact.amount < 0 || fact.currency !== 'USD' ||
+        typeof fact.precision !== 'string' || typeof fact.isTest !== 'boolean')
+        return false;
+    // All fact fields are scalar. The encoder cannot mutate the source exposure or its dedup identity.
+    const snapshot = Object.freeze({ ...fact });
+    let event;
+    try {
+        event = encode(snapshot);
+    }
+    catch {
+        return false;
+    }
+    if (!event || typeof event.name !== 'string' || !event.name || !event.properties ||
+        typeof event.properties !== 'object' || Array.isArray(event.properties))
+        return false;
+    return client.track(event.name, event.properties, { ...context, deduplicationKey: `ad_revenue:${snapshot.provider}:${snapshot.exposureId}` });
+}

package/dist/core/types.d.ts

@@ -0,0 +1,155 @@
+/** API v1 ports. No Cocos or game imports are required by the core. */
+export interface StoragePort {
+    /** Shared object identity for adapters wrapping the same underlying store in this JS runtime. */
+    readonly ownershipScope?: object;
+    /** null means absent. Read failures must throw; never convert them to null. */
+    getString(key: string): string | null;
+    /** Replace one key atomically; flush + read-back must expose that complete value or fail. */
+    setString(key: string, value: string): void;
+    /** Required only for segmented persistence; deletion failures must throw. */
+    removeString?(key: string): void;
+    flush(): void;
+}
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+    retryAfterMs?: number;
+}
+export interface JsonTransport {
+    post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponse>;
+    dispose?(): void;
+}
+export interface ClientContext {
+    appVersion: string;
+    buildNumber: string;
+    platform: 'android' | 'ios' | 'web' | 'wechat';
+    locale: string;
+    timezoneOffsetMinutes: number;
+    environment?: 'production' | 'test';
+    device?: {
+        type: 'android_id';
+        id: string;
+    };
+}
+/** Storage/delivery ownership, distinct from gameplay configuration and report attribution. */
+export interface ClientScope {
+    baseUrl: string;
+    projectId: string;
+    environment: 'production' | 'test';
+}
+export interface EventFact {
+    eventVersion: 1;
+    eventId: string;
+    name: string;
+    occurredAt: string;
+    sessionId: string;
+    sequence: number;
+    client: ClientContext;
+    samplingProbability: number;
+    run: unknown;
+    properties: Record<string, unknown>;
+}
+export interface TrackContext {
+    run?: unknown;
+    occurredAt?: string;
+    /** Used once at enqueue, never when replaying persisted facts. */
+    transform?: (event: EventFact) => EventFact;
+    /** Optional bounded, persistent duplicate callback guard. */
+    deduplicationKey?: string;
+}
+export interface ConfigurationContext {
+    readonly cache: unknown;
+    request(path: string, body: unknown): Promise<unknown>;
+    saveCache(value: unknown): void;
+}
+export interface PlayScopeOptions {
+    baseUrl: string;
+    projectId: string;
+    projectKey: string;
+    client: ClientContext;
+    /** Override only for an existing installation's historical storage namespace. */
+    storageKey?: string;
+    bootstrapClient?: ClientContext;
+    onIdentityReady?: (installId: string) => boolean | void;
+    queuePolicy?: QueuePolicy;
+    /** Snapshot remains the compatibility default. Segmented data stays segmented on subsequent opens. */
+    persistence?: 'snapshot' | 'segmented';
+    /** Explicit provenance assertion when adopting an existing state with no scope metadata. */
+    legacyScope?: ClientScope;
+    /** Host validates its own config schema; the core never interprets game settings. */
+    restoreCache?: (saved: unknown) => unknown;
+    resolveConfiguration?: (context: ConfigurationContext) => Promise<number>;
+}
+export interface QueuePolicy {
+    /** Pending fact capacity. Defaults to 2000; does not evict an existing queue. */
+    readonly maxEvents?: number;
+    /** UTF-8 JSON bytes retained in pending + quarantine, excluding config/identity. Default 4 MiB. */
+    readonly maxBytes?: number;
+    /** Queue length at which this input event name is refused; reserve capacity for other events. */
+    readonly eventLimits?: Readonly<Record<string, number>>;
+}
+export interface Diagnostics {
+    pending: number;
+    rejected: number;
+    droppedEvents: number;
+    lastError: string | null;
+    blocked: boolean;
+    quarantined: number;
+    pendingBytes: number;
+    quarantinedBytes: number;
+    maxQueueBytes: number;
+    persistence: 'snapshot' | 'segmented';
+    cleanupPending: boolean;
+}
+/** Original local fact retained for inspection; never uploaded automatically again. */
+export interface QuarantinedEvent {
+    event: EventFact;
+    reason: 'event_too_large' | 'http_413';
+    quarantinedAt: string;
+}
+export interface EventBatchResponse {
+    apiVersion: number;
+    acceptedEventIds: string[];
+    rejectedEvents: {
+        eventId: string;
+        code: string;
+        permanent: boolean;
+    }[];
+}
+/** Accepted facts may still be memory-only when storage is temporarily unavailable. */
+export type TrackResult = {
+    status: 'accepted';
+    eventId: string;
+    durability: 'persisted' | 'memory';
+} | {
+    status: 'duplicate' | 'queue_full' | 'queue_bytes_full' | 'event_too_large' | 'invalid_event' | 'collection_disabled' | 'disposed';
+};
+export interface FlushResult {
+    status: 'completed' | 'backoff' | 'blocked' | 'storage_unavailable' | 'failed' | 'disposed' | 'collection_disabled';
+    /** Counts only facts explicitly ACKed in this operation; quarantine is separate. */
+    accepted: number;
+    rejected: number;
+    quarantined: number;
+    pending: number;
+    /** True only after the current local state has passed the storage read-back check. */
+    durable: boolean;
+    retryAt: number;
+    error: string | null;
+}
+export interface ConfigurationStatus {
+    state: 'disabled' | 'idle' | 'syncing' | 'backoff' | 'disposed';
+    nextAttemptAt: number;
+    lastError: string | null;
+}
+export interface ConfigurationResult {
+    status: 'refreshed' | 'not_due' | 'failed' | 'disabled' | 'disposed' | 'storage_unavailable';
+    nextAttemptAt: number;
+    error: string | null;
+}
+export interface ClientStatus {
+    collection: 'enabled' | 'disabled' | 'disposed';
+    delivery: 'idle' | 'uploading' | 'backoff' | 'blocked' | 'storage_unavailable' | 'disposed' | 'disabled';
+    pendingDurability: 'persisted' | 'memory';
+    retryAt: number;
+    configuration: ConfigurationStatus;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/uuid.d.ts

@@ -0,0 +1 @@
+export declare function telemetryUuid(): string;

package/dist/core/uuid.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryUuid = telemetryUuid;
+function telemetryUuid() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const n = Math.floor(Math.random() * 16);
+        return (c === 'x' ? n : n & 3 | 8).toString(16);
+    });
+}

package/dist/esm/adapters/levelplay/index.js

@@ -0,0 +1,11 @@
+/** Does not initialize ads or replace the game's native listener. Host supplies the original exposure context. */
+export function forwardLevelPlayRevenue(sink, impression, exposure, context = {}) {
+    if (typeof impression.revenue !== 'number' || !Number.isFinite(impression.revenue) || impression.revenue < 0 ||
+        !impression.adNetwork || !impression.mediationAdUnitId || typeof impression.precision !== 'string')
+        return false;
+    const country = impression.country?.trim().toUpperCase();
+    return sink.trackAdRevenue({ ...exposure, provider: 'levelplay', amount: impression.revenue, currency: 'USD',
+        precision: impression.precision, network: impression.adNetwork, adUnitId: impression.mediationAdUnitId,
+        ...(country && /^[A-Z]{2}$/.test(country) ? { country, countrySource: 'levelplay_sdk' } : {}),
+    }, context);
+}

package/dist/esm/cocos/Storage.js

@@ -0,0 +1,12 @@
+/** Inject sys.localStorage; failures reach the outbox and prevent unsafe uploads. */
+export class CocosStorage {
+    get ownershipScope() { return this.storage; }
+    constructor(storage) {
+        this.storage = storage;
+        if (storage.removeItem)
+            this.removeString = key => storage.removeItem(key);
+    }
+    getString(key) { return this.storage.getItem(key); }
+    setString(key, value) { this.storage.setItem(key, value); }
+    flush() { }
+}

package/dist/esm/cocos/XhrJsonTransport.js

@@ -0,0 +1,61 @@
+/** XMLHttpRequest is supported by browsers and Cocos JSB Android/iOS. */
+export class XhrJsonTransport {
+    constructor() {
+        this.pending = new Map();
+        this.disposed = false;
+    }
+    post(url, headers, body) {
+        return new Promise((resolve, reject) => {
+            if (this.disposed) {
+                reject(new Error('disposed'));
+                return;
+            }
+            const xhr = new XMLHttpRequest();
+            const finish = () => { this.pending.delete(xhr); xhr.onload = xhr.onerror = xhr.ontimeout = xhr.onabort = null; };
+            const fail = (error) => { finish(); reject(error); };
+            this.pending.set(xhr, fail);
+            try {
+                xhr.open('POST', url, true);
+                xhr.timeout = 10000;
+                for (const [key, value] of Object.entries(headers))
+                    xhr.setRequestHeader(key, value);
+                xhr.onload = () => {
+                    try {
+                        const rawRetry = xhr.getResponseHeader('Retry-After');
+                        const retryAfterMs = rawRetry ? /^\d+$/.test(rawRetry) ? Number(rawRetry) * 1000 : Math.max(0, Date.parse(rawRetry) - Date.now()) : 0;
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(xhr.responseText);
+                        }
+                        catch {
+                            parsed = null;
+                        }
+                        const status = xhr.status;
+                        finish();
+                        resolve({ status, body: parsed, retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : 0 });
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                };
+                xhr.onerror = xhr.ontimeout = xhr.onabort = () => fail(new Error('request_failed'));
+                xhr.send(JSON.stringify(body));
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+    }
+    dispose() {
+        this.disposed = true;
+        for (const [xhr, fail] of [...this.pending]) {
+            try {
+                xhr.abort();
+            }
+            catch { /* A broken abort must not strand other requests. */ }
+            finally {
+                fail(new Error('disposed'));
+            }
+        }
+    }
+}

package/dist/esm/cocos/index.js

@@ -0,0 +1,115 @@
+import { PlayScopeClient, enqueueAdRevenue } from '../core/index.js';
+import { encodeGameV1AdRevenue } from '../protocols/game-v1/index.js';
+import { CocosStorage } from './Storage.js';
+import { XhrJsonTransport } from './XhrJsonTransport.js';
+export * from '../core/index.js';
+export * from './Storage.js';
+export * from './XhrJsonTransport.js';
+/** Host owns event semantics; this wrapper only schedules flush and releases its subscriptions. */
+export class CocosPlayScope {
+    constructor(options, runtime) {
+        this.off = [];
+        this.elapsed = 0;
+        this.disposed = false;
+        this.revenueEncoder = options.adRevenueEncoder ?? encodeGameV1AdRevenue;
+        this.client = options.collectionEnabled ? new PlayScopeClient(options, new CocosStorage(runtime.storage), runtime.transport ?? new XhrJsonTransport(), runtime.now) : null;
+        if (this.client && runtime.lifecycle) {
+            try {
+                this.off.push(runtime.lifecycle.onHide(() => { void this.flush(); }));
+                this.off.push(runtime.lifecycle.onShow(() => { void this.flush(); }));
+            }
+            catch (error) {
+                // Preserve the registration error while releasing any partially acquired resources.
+                try {
+                    this.dispose();
+                }
+                catch { /* All cleanup steps have already been attempted. */ }
+                throw error;
+            }
+        }
+    }
+    start() { if (!this.disposed) {
+        this.client?.start();
+        void this.flush();
+    } }
+    get installId() { return this.client?.installId ?? null; }
+    getDiagnostics() {
+        return this.client?.diagnostics ??
+            { pending: 0, rejected: 0, droppedEvents: 0, lastError: null, blocked: false, quarantined: 0,
+                pendingBytes: 0, quarantinedBytes: 0, maxQueueBytes: 0, persistence: 'snapshot', cleanupPending: false };
+    }
+    getQuarantinedEvents() { return this.client?.getQuarantinedEvents() ?? []; }
+    get status() {
+        if (this.client)
+            return this.client.status;
+        return { collection: this.disposed ? 'disposed' : 'disabled', delivery: this.disposed ? 'disposed' : 'disabled',
+            pendingDurability: 'persisted', retryAt: 0,
+            configuration: { state: this.disposed ? 'disposed' : 'disabled', nextAttemptAt: 0, lastError: null } };
+    }
+    track(name, properties = {}, context = {}) {
+        return this.trackWithResult(name, properties, context).status === 'accepted';
+    }
+    trackWithResult(name, properties = {}, context = {}) {
+        if (this.disposed)
+            return { status: 'disposed' };
+        return this.client?.trackWithResult(name, properties, context) ?? { status: 'collection_disabled' };
+    }
+    trackAdRevenue(fact, context = {}) {
+        return !this.disposed && !!this.client && enqueueAdRevenue(this.client, fact, context, this.revenueEncoder);
+    }
+    newSession() { if (!this.disposed)
+        this.client?.newSession(); }
+    /** Call from a persistent Cocos component's update(dt), in seconds. */
+    update(dt) {
+        if (this.disposed || !Number.isFinite(dt) || dt <= 0 || dt > 1)
+            return;
+        this.elapsed += dt;
+        if (this.elapsed >= 5) {
+            this.elapsed = 0;
+            void this.flush();
+        }
+    }
+    async flush() { if (!this.disposed)
+        await this.client?.flush(); }
+    flushWithResult() {
+        return this.client?.flushWithResult() ?? Promise.resolve(this.inactiveFlushResult());
+    }
+    retryUploads() {
+        return this.client?.retryUploads() ?? Promise.resolve(this.inactiveFlushResult());
+    }
+    refreshConfiguration() {
+        return this.client?.refreshConfiguration() ?? Promise.resolve({ status: this.disposed ? 'disposed' : 'disabled',
+            nextAttemptAt: 0, error: null });
+    }
+    inactiveFlushResult() {
+        return { status: this.disposed ? 'disposed' : 'collection_disabled', accepted: 0, rejected: 0, quarantined: 0,
+            pending: 0, durable: true, retryAt: 0, error: null };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        let failed = false, firstError;
+        const cleanup = (release) => {
+            try {
+                release();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    firstError = error;
+                }
+            }
+        };
+        for (const off of this.off.splice(0))
+            cleanup(off);
+        cleanup(() => this.client?.dispose());
+        if (failed)
+            throw firstError;
+    }
+}
+export function init(options, runtime) {
+    const sdk = new CocosPlayScope(options, runtime);
+    sdk.start();
+    return sdk;
+}

package/dist/esm/core/ClientOwnership.js

@@ -0,0 +1,34 @@
+// Symbol.for shares ownership across this package's ESM and CommonJS entries.
+// The registry covers one JS runtime, not other tabs or native processes.
+const registryKey = Symbol.for('playscope.storageOwners.v1');
+const runtime = globalThis;
+const owners = runtime[registryKey] ?? (runtime[registryKey] = new WeakMap());
+export class PlayScopeOwnershipError extends Error {
+    constructor() {
+        super('PlayScope already has an active writer for this storage scope');
+        this.code = 'duplicate_client';
+        this.name = 'PlayScopeOwnershipError';
+    }
+}
+export function claimStorage(storage, key) {
+    const scope = storage.ownershipScope ?? storage;
+    let keys = owners.get(scope);
+    if (!keys) {
+        keys = new Map();
+        owners.set(scope, keys);
+    }
+    if (keys.has(key))
+        throw new PlayScopeOwnershipError();
+    const token = {};
+    keys.set(key, token);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (keys.get(key) === token)
+            keys.delete(key);
+        if (!keys.size && owners.get(scope) === keys)
+            owners.delete(scope);
+    };
+}

package/dist/esm/core/ClientScope.js

@@ -0,0 +1,30 @@
+import { PlayScopeInitializationError } from './PersistentState.js';
+export function resolveClientScope(options) {
+    const scope = { baseUrl: options.baseUrl, projectId: options.projectId,
+        environment: options.client.environment ?? 'production' };
+    return normalize(scope);
+}
+function normalize(scope) {
+    if (!scope || typeof scope.baseUrl !== 'string' || !scope.baseUrl.replace(/\/+$/, '') ||
+        typeof scope.projectId !== 'string' || !scope.projectId || !['production', 'test'].includes(scope.environment))
+        throw new TypeError('Invalid client scope');
+    return { baseUrl: scope.baseUrl.replace(/\/+$/, ''), projectId: scope.projectId, environment: scope.environment };
+}
+function equal(a, b) {
+    return a.baseUrl === b.baseUrl && a.projectId === b.projectId && a.environment === b.environment;
+}
+/** Never change an installation identity, token, queue, or storage key to repair a scope conflict. */
+export function bindClientScope(state, expected, existed, legacy) {
+    if (state.scope) {
+        if (!equal(normalize(state.scope), expected))
+            throw new PlayScopeInitializationError('scope_mismatch');
+        return;
+    }
+    if (existed) {
+        if (!legacy)
+            throw new PlayScopeInitializationError('scope_migration_required');
+        if (!equal(normalize(legacy), expected))
+            throw new PlayScopeInitializationError('scope_mismatch');
+    }
+    state.scope = { ...expected };
+}

package/dist/esm/core/ConfigurationSync.js

@@ -0,0 +1,62 @@
+import { PlayScopeHttpError, StorageUnavailableError } from './HttpError.js';
+/** Optional scheduler with its own in-flight task, failures and Retry-After budget. */
+export class ConfigurationSync {
+    constructor(resolve, context, now) {
+        this.resolve = resolve;
+        this.context = context;
+        this.now = now;
+        this.task = null;
+        this.nextAttemptAt = 0;
+        this.failures = 0;
+        this.lastError = null;
+        this.disposed = false;
+    }
+    get status() {
+        return { state: this.disposed ? 'disposed' : !this.resolve ? 'disabled' : this.task ? 'syncing' :
+                this.lastError && this.now() < this.nextAttemptAt ? 'backoff' : 'idle',
+            nextAttemptAt: this.nextAttemptAt, lastError: this.lastError };
+    }
+    refresh() {
+        if (this.disposed)
+            return Promise.resolve(this.result('disposed'));
+        if (!this.resolve)
+            return Promise.resolve(this.result('disabled'));
+        if (this.task)
+            return this.task;
+        if (this.now() < this.nextAttemptAt)
+            return Promise.resolve(this.result('not_due'));
+        // Defer execution until task ownership is established, including synchronous host callbacks.
+        const task = Promise.resolve().then(() => this.run());
+        this.task = task;
+        void task.then(() => { if (this.task === task)
+            this.task = null; });
+        return task;
+    }
+    result(status) {
+        return { status, nextAttemptAt: this.nextAttemptAt, error: this.lastError };
+    }
+    async run() {
+        try {
+            const context = await this.context();
+            if (this.disposed)
+                return this.result('disposed');
+            const refresh = await this.resolve(context);
+            if (this.disposed)
+                return this.result('disposed');
+            this.nextAttemptAt = this.now() + Math.max(60, Math.min(86400, Number.isFinite(refresh) && refresh > 0 ? refresh : 3600)) * 1000;
+            this.failures = 0;
+            this.lastError = null;
+            return this.result('refreshed');
+        }
+        catch (error) {
+            if (this.disposed)
+                return this.result('disposed');
+            const http = error instanceof PlayScopeHttpError ? error : null;
+            const storageUnavailable = error instanceof StorageUnavailableError;
+            this.lastError = http ? `http_${http.status}` : storageUnavailable ? 'storage_unavailable' : 'configuration_error';
+            this.nextAttemptAt = this.now() + Math.max(http?.retryAfterMs ?? 0, Math.min(3600000, 60000 * 2 ** Math.min(this.failures++, 6)));
+            return this.result(storageUnavailable ? 'storage_unavailable' : 'failed');
+        }
+    }
+    dispose() { this.disposed = true; }
+}

package/dist/esm/core/FactEncoding.js

@@ -0,0 +1,24 @@
+/** JSB-compatible UTF-8 accounting without TextEncoder. */
+export function utf8Bytes(value) {
+    let bytes = 0;
+    for (const ch of value) {
+        const n = ch.codePointAt(0);
+        bytes += n <= 0x7f ? 1 : n <= 0x7ff ? 2 : n <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+/** Only immutable, SDK-owned snapshots may be cached here. */
+export class FactEncoding {
+    constructor() {
+        this.cache = new WeakMap();
+    }
+    get(value) {
+        let encoded = this.cache.get(value);
+        if (!encoded) {
+            const json = JSON.stringify(value);
+            encoded = { json, bytes: utf8Bytes(json) };
+            this.cache.set(value, encoded);
+        }
+        return encoded;
+    }
+}

package/dist/esm/core/HttpError.js

@@ -0,0 +1,12 @@
+export class PlayScopeHttpError extends Error {
+    constructor(status, retryAfterMs = 0, path) {
+        super(`PlayScope HTTP ${status}`);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.path = path;
+    }
+}
+/** Internal storage barrier, distinct from transport/protocol failures. */
+export class StorageUnavailableError extends Error {
+    constructor() { super('storage_unavailable'); }
+}