@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/dist/esm/core/PlayScopeClient.js

@@ -0,0 +1,415 @@
+import { ConfigurationSync } from './ConfigurationSync.js';
+import { PlayScopeHttpError, StorageUnavailableError } from './HttpError.js';
+export { PlayScopeHttpError } from './HttpError.js';
+import { claimStorage } from './ClientOwnership.js';
+import { isEventFact, PlayScopeInitializationError } from './PersistentState.js';
+import { telemetryUuid } from './uuid.js';
+import { resolveQueuePolicy, resolveByteLimit } from './QueueAdmission.js';
+import { OutboxStore } from './OutboxStore.js';
+import { FactEncoding, utf8Bytes } from './FactEncoding.js';
+import { bindClientScope, resolveClientScope } from './ClientScope.js';
+export { utf8Bytes } from './FactEncoding.js';
+export { telemetryUuid } from './uuid.js';
+const MAX_BATCH_BYTES = 250 * 1024;
+/** Durable API v1 outbox, independent of game schema and rendering engine. */
+export class PlayScopeClient {
+    constructor(options, storage, transport, now = Date.now) {
+        this.options = options;
+        this.storage = storage;
+        this.transport = transport;
+        this.now = now;
+        this.encoding = new FactEncoding();
+        this.sessionId = telemetryUuid();
+        this.flushTask = null;
+        this.tokenTask = null;
+        this.disposed = false;
+        this.blocked = false;
+        this.retryAt = 0;
+        this.failures = 0;
+        this.batchLimit = 100;
+        this.lastError_ = null;
+        this.needsPersistence = false;
+        this.identityPublished = false;
+        const scope = resolveClientScope(options);
+        this.api = `${scope.baseUrl}/v1/projects/${encodeURIComponent(scope.projectId)}`;
+        this.clientContext = JSON.parse(JSON.stringify(options.client));
+        this.bootstrapContext = JSON.parse(JSON.stringify(options.bootstrapClient ?? options.client));
+        this.key = options.storageKey ?? `playscope:${options.projectId}`;
+        this.admissionLimit = resolveQueuePolicy(options.queuePolicy);
+        this.maxQueueBytes = resolveByteLimit(options.queuePolicy);
+        this.outbox = new OutboxStore(storage, this.key, options.persistence, this.encoding);
+        this.configuration = new ConfigurationSync(options.resolveConfiguration, async () => {
+            if (this.disposed)
+                throw new Error('disposed');
+            if (this.needsPersistence && !this.persist())
+                throw new StorageUnavailableError();
+            await this.ensureToken();
+            if (this.disposed)
+                throw new Error('disposed');
+            return { cache: this.cache,
+                request: (path, body) => this.authorized(path, body), saveCache: value => {
+                    if (!this.disposed && !this.saveCache(value))
+                        throw new StorageUnavailableError();
+                } };
+        }, now);
+        this.releaseOwnership = claimStorage(storage, this.key);
+        try {
+            this.state = this.outbox.load(now);
+            bindClientScope(this.state, scope, this.outbox.hasStoredState, options.legacyScope);
+            if (options.restoreCache) {
+                try {
+                    this.state.cache = options.restoreCache(this.state.cache);
+                }
+                catch {
+                    throw new PlayScopeInitializationError('cache_restore_failed');
+                }
+            }
+            this.persist();
+        }
+        catch (error) {
+            this.releaseOwnership();
+            throw error;
+        }
+    }
+    get installId() { return this.state.installId; }
+    get cache() { return JSON.parse(JSON.stringify(this.state.cache)); }
+    saveCache(value) {
+        if (this.disposed)
+            return false;
+        this.state.cache = JSON.parse(JSON.stringify(value));
+        return this.persist();
+    }
+    getQuarantinedEvents() { return JSON.parse(JSON.stringify(this.state.quarantined)); }
+    get diagnostics() {
+        return { pending: this.state.queue.length, rejected: this.state.rejected.length, droppedEvents: this.state.droppedEvents,
+            lastError: this.lastError_, blocked: this.blocked, quarantined: this.state.quarantined.length,
+            ...this.queueBytes(), maxQueueBytes: this.maxQueueBytes,
+            persistence: this.outbox.mode, cleanupPending: this.outbox.cleanupPending };
+    }
+    queueBytes() {
+        return { pendingBytes: this.state.queue.reduce((sum, event) => sum + this.encoding.get(event).bytes, 0),
+            quarantinedBytes: this.state.quarantined.reduce((sum, event) => sum + this.encoding.get(event).bytes, 0) };
+    }
+    get status() {
+        return { collection: this.disposed ? 'disposed' : 'enabled',
+            delivery: this.disposed ? 'disposed' : this.needsPersistence ? 'storage_unavailable' : this.flushTask ? 'uploading' :
+                this.blocked ? 'blocked' : this.now() < this.retryAt ? 'backoff' : 'idle',
+            pendingDurability: this.needsPersistence ? 'memory' : 'persisted', retryAt: this.retryAt,
+            configuration: this.configuration.status };
+    }
+    /** Configuration has its own failure budget and never waits for event delivery. */
+    refreshConfiguration() {
+        return this.configuration.refresh();
+    }
+    /** Explicit recovery after the host has repaired credentials, endpoint or permissions. */
+    retryUploads() {
+        if (!this.disposed && !this.flushTask && this.blocked) {
+            this.blocked = false;
+            this.retryAt = 0;
+            this.failures = 0;
+        }
+        return this.flushWithResult();
+    }
+    /** Call after collection is allowed. Existing first-open facts are never recreated. */
+    start(name = 'user_first_open', context = {}) {
+        if (this.disposed || this.state.firstOpenTracked)
+            return;
+        this.state.firstOpenTracked = true;
+        if (!this.track(name, {}, { ...context, occurredAt: this.state.firstOpenedAt })) {
+            this.state.firstOpenTracked = false;
+            this.persist();
+        }
+    }
+    newSession() { if (!this.disposed)
+        this.sessionId = telemetryUuid(); }
+    track(name, properties, context = {}) {
+        return this.trackWithResult(name, properties, context).status === 'accepted';
+    }
+    trackWithResult(name, properties, context = {}) {
+        if (this.disposed)
+            return { status: 'disposed' };
+        if (context.deduplicationKey && this.state.deduplicationKeys?.includes(context.deduplicationKey))
+            return { status: 'duplicate' };
+        if (this.state.queue.length >= this.admissionLimit(name)) {
+            this.state.droppedEvents++;
+            this.lastError_ = 'queue_full';
+            this.persist();
+            return { status: 'queue_full' };
+        }
+        let event;
+        try {
+            event = JSON.parse(JSON.stringify({ eventVersion: 1, eventId: telemetryUuid(), name,
+                occurredAt: context.occurredAt ?? new Date(this.now()).toISOString(), sessionId: this.sessionId,
+                sequence: ++this.state.sequence, client: this.clientContext, samplingProbability: 1,
+                run: context.run ?? null, properties }));
+            if (context.transform)
+                event = JSON.parse(JSON.stringify(context.transform(event)));
+        }
+        catch {
+            this.lastError_ = 'invalid_event';
+            return { status: 'invalid_event' };
+        }
+        // A JavaScript host can return an invalid object despite the TypeScript signature.
+        // Do not persist a fact that our own recovery path would reject on restart.
+        if (!isEventFact(event)) {
+            this.lastError_ = 'invalid_event';
+            return { status: 'invalid_event' };
+        }
+        // Validate the final wire fact, including any host transform and batch envelope.
+        if (!this.fitsSingleBatch(event)) {
+            this.state.droppedEvents++;
+            this.lastError_ = 'event_too_large';
+            this.persist();
+            return { status: 'event_too_large' };
+        }
+        const bytes = this.queueBytes();
+        if (bytes.pendingBytes + bytes.quarantinedBytes + this.encoding.get(event).bytes > this.maxQueueBytes) {
+            this.state.droppedEvents++;
+            this.lastError_ = 'queue_bytes_full';
+            this.persist();
+            return { status: 'queue_bytes_full' };
+        }
+        this.state.queue.push(event);
+        if (context.deduplicationKey)
+            this.state.deduplicationKeys =
+                [...(this.state.deduplicationKeys ?? []), context.deduplicationKey].slice(-2000);
+        const durable = this.persist();
+        if (this.state.queue.length >= 20)
+            void this.flush();
+        return { status: 'accepted', eventId: event.eventId, durability: durable ? 'persisted' : 'memory' };
+    }
+    persist() {
+        try {
+            this.outbox.save(this.state);
+            this.needsPersistence = false;
+        }
+        catch {
+            this.needsPersistence = true;
+            this.lastError_ = 'storage_unavailable';
+            return false;
+        }
+        if (!this.identityPublished && this.options.onIdentityReady) {
+            try {
+                this.identityPublished = this.options.onIdentityReady(this.state.installId) !== false;
+            }
+            catch { /* Optional report linkage retries without blocking durable telemetry. */ }
+        }
+        return true;
+    }
+    /** Compatibility wrapper: independently schedules config; resolves when this delivery pass finishes. */
+    async flush() {
+        await this.flushWithResult();
+    }
+    flushWithResult() {
+        if (this.disposed)
+            return Promise.resolve(this.flushResult('disposed'));
+        if (this.flushTask)
+            return this.flushTask;
+        if (this.needsPersistence && !this.persist())
+            return Promise.resolve(this.flushResult('storage_unavailable'));
+        // Config remains eligible even when event uploads are blocked or in backoff.
+        void this.refreshConfiguration();
+        if (this.blocked)
+            return Promise.resolve(this.flushResult('blocked'));
+        if (this.now() < this.retryAt)
+            return Promise.resolve(this.flushResult('backoff'));
+        const task = Promise.resolve().then(() => this.deliver());
+        this.flushTask = task;
+        void task.then(() => { if (this.flushTask === task)
+            this.flushTask = null; });
+        return task;
+    }
+    flushResult(status, accepted = 0, rejected = 0, quarantined = 0) {
+        return { status, accepted, rejected, quarantined, pending: this.state.queue.length,
+            durable: !this.needsPersistence, retryAt: this.retryAt, error: this.lastError_ };
+    }
+    async deliver() {
+        let accepted = 0, rejected = 0;
+        const initialQuarantined = this.state.quarantined.length;
+        const result = (status) => this.flushResult(status, accepted, rejected, this.state.quarantined.length - initialQuarantined);
+        let attemptedBatch = null;
+        try {
+            if (this.disposed)
+                return result('disposed');
+            await this.ensureToken();
+            if (this.disposed)
+                return result('disposed');
+            // Drain a bounded amount; large offline backlogs continue on the next tick.
+            for (let i = 0; i < 10 && this.state.queue.length && !this.disposed; i++) {
+                const batch = this.makeBatch();
+                // makeBatch may quarantine legacy facts; persist that transition before sending.
+                if (!this.persist())
+                    return result('storage_unavailable');
+                if (!batch)
+                    break;
+                attemptedBatch = batch;
+                const response = await this.authorized('/analytics/events', batch);
+                if (this.disposed)
+                    return result('disposed');
+                if (response?.apiVersion !== 1 || !Array.isArray(response.acceptedEventIds) || !Array.isArray(response.rejectedEvents) ||
+                    response.acceptedEventIds.some(id => typeof id !== 'string') ||
+                    response.rejectedEvents.some(r => !r || typeof r.eventId !== 'string' || typeof r.code !== 'string' || typeof r.permanent !== 'boolean'))
+                    throw new Error('invalid_ack');
+                const sent = new Set(batch.events.map(e => e.eventId));
+                const removed = new Set(response.acceptedEventIds.filter(id => sent.has(id)));
+                accepted += removed.size;
+                for (const rejection of response.rejectedEvents) {
+                    if (!sent.has(rejection.eventId) || rejection.permanent !== true)
+                        continue;
+                    if (removed.has(rejection.eventId))
+                        continue;
+                    removed.add(rejection.eventId);
+                    rejected++;
+                    const event = batch.events.find(e => e.eventId === rejection.eventId);
+                    this.state.rejected.push({ eventId: event.eventId, name: event.name, code: rejection.code });
+                }
+                this.state.rejected = this.state.rejected.slice(-50);
+                this.state.queue = this.state.queue.filter(e => !removed.has(e.eventId));
+                if (!this.persist())
+                    return result('storage_unavailable');
+                if (removed.size === 0 || removed.size < batch.events.length)
+                    throw new Error('incomplete_ack');
+            }
+            this.failures = 0;
+            this.retryAt = 0;
+            this.lastError_ = null;
+            return result('completed');
+        }
+        catch (error) {
+            if (this.disposed)
+                return result('disposed');
+            const http = error instanceof PlayScopeHttpError ? error : null;
+            if (http?.status === 413 && http.path === '/analytics/events' && attemptedBatch) {
+                if (attemptedBatch.events.length > 1)
+                    this.batchLimit = Math.max(1, Math.floor(attemptedBatch.events.length / 2));
+                else {
+                    // A server may enforce a smaller limit than our local admission budget.
+                    // Retain the exact fact separately and let later facts progress on retry.
+                    this.quarantine(attemptedBatch.events[0], 'http_413');
+                    this.persist();
+                }
+            }
+            else if (http && [400, 401, 403, 404, 413].includes(http.status))
+                this.blocked = true;
+            this.lastError_ = this.needsPersistence ? 'storage_unavailable' : http ? `http_${http.status}` :
+                error instanceof Error && ['incomplete_ack', 'invalid_ack'].includes(error.message) ? error.message : 'network_or_protocol_error';
+            this.retryAt = this.now() + Math.max(http?.retryAfterMs ?? 0, Math.min(60000, 1000 * 2 ** Math.min(++this.failures, 6)) * (0.75 + Math.random() * 0.5));
+            return result(this.needsPersistence ? 'storage_unavailable' : this.blocked ? 'blocked' : 'failed');
+        }
+    }
+    batchEnvelope(events) {
+        return { apiVersion: 1, installId: this.state.installId, batchId: telemetryUuid(),
+            sentAt: new Date(this.now()).toISOString(), events };
+    }
+    fitsSingleBatch(event) {
+        return utf8Bytes(JSON.stringify(this.batchEnvelope([]))) + this.encoding.get(event).bytes <= MAX_BATCH_BYTES;
+    }
+    quarantine(event, reason) {
+        const index = this.state.queue.indexOf(event);
+        if (index < 0)
+            return;
+        this.state.quarantined.push({ event, reason, quarantinedAt: new Date(this.now()).toISOString() });
+        this.state.queue.splice(index, 1);
+    }
+    makeBatch() {
+        const batch = this.batchEnvelope([]);
+        const envelopeBytes = utf8Bytes(JSON.stringify(batch));
+        let bytes = envelopeBytes;
+        // Inspect a snapshot because isolation removes facts from the pending queue.
+        for (const event of [...this.state.queue]) {
+            const factBytes = this.encoding.get(event).bytes;
+            if (envelopeBytes + factBytes > MAX_BATCH_BYTES) {
+                this.quarantine(event, 'event_too_large');
+                continue;
+            }
+            const nextBytes = bytes + factBytes + (batch.events.length ? 1 : 0);
+            if (nextBytes > MAX_BATCH_BYTES)
+                break;
+            batch.events.push(event);
+            bytes = nextBytes;
+            if (batch.events.length >= this.batchLimit)
+                break;
+        }
+        return batch.events.length ? batch : null;
+    }
+    ensureToken() {
+        if (this.disposed)
+            return Promise.reject(new Error('disposed'));
+        if (this.tokenTask)
+            return this.tokenTask;
+        if (this.state.token && Date.parse(this.state.token.expiresAt) > this.now() + 60000)
+            return Promise.resolve(this.state.token);
+        const task = Promise.resolve().then(() => this.bootstrap());
+        this.tokenTask = task;
+        void task.then(() => { if (this.tokenTask === task)
+            this.tokenTask = null; }, () => { if (this.tokenTask === task)
+            this.tokenTask = null; });
+        return task;
+    }
+    async bootstrap() {
+        if (this.disposed)
+            throw new Error('disposed');
+        const result = await this.post('/client/bootstrap', { 'X-Project-Key': this.options.projectKey }, {
+            apiVersion: 1, installId: this.state.installId, firstOpenedAt: this.state.firstOpenedAt, client: this.bootstrapContext,
+        });
+        if (this.disposed)
+            throw new Error('disposed');
+        if (result?.apiVersion !== 1 || typeof result.accessToken !== 'string' || !result.accessToken ||
+            !(Date.parse(result.expiresAt) > this.now()))
+            throw new Error('invalid_token');
+        this.state.token = { accessToken: result.accessToken, expiresAt: result.expiresAt };
+        if (!this.persist())
+            throw new StorageUnavailableError();
+        return this.state.token;
+    }
+    async authorized(path, body) {
+        if (this.disposed)
+            throw new Error('disposed');
+        // Keep the acquired token snapshot: another request can invalidate shared state while we resume.
+        const { accessToken: token } = await this.ensureToken();
+        if (this.disposed)
+            throw new Error('disposed');
+        if (this.needsPersistence && !this.persist())
+            throw new StorageUnavailableError();
+        try {
+            return await this.post(path, { Authorization: `Bearer ${token}` }, body);
+        }
+        catch (error) {
+            if (!(error instanceof PlayScopeHttpError) || error.status !== 401 || this.disposed)
+                throw error;
+            // Another request may already have refreshed this rejected token.
+            if (this.state.token?.accessToken === token)
+                this.state.token = null;
+            const refreshed = await this.ensureToken();
+            if (this.disposed)
+                throw new Error('disposed');
+            if (this.needsPersistence && !this.persist())
+                throw new StorageUnavailableError();
+            return this.post(path, { Authorization: `Bearer ${refreshed.accessToken}` }, body);
+        }
+    }
+    async post(path, headers, body) {
+        if (this.disposed)
+            throw new Error('disposed');
+        // A host-provided transport must never receive mutable references into cached immutable facts.
+        const response = await this.transport.post(this.api + path, { 'Content-Type': 'application/json', ...headers }, JSON.parse(JSON.stringify(body)));
+        if (this.disposed)
+            throw new Error('disposed');
+        if (response.status !== 200)
+            throw new PlayScopeHttpError(response.status, response.retryAfterMs, path);
+        return response.body;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.configuration.dispose();
+        try {
+            this.persist();
+            this.transport.dispose?.();
+        }
+        finally {
+            this.releaseOwnership();
+        }
+    }
+}

package/dist/esm/core/QueueAdmission.js

@@ -0,0 +1,25 @@
+/** Admission only: restored/unacknowledged facts are never evicted to meet a new limit. */
+export function resolveQueuePolicy(policy = {}) {
+    resolveByteLimit(policy);
+    const maxEvents = policy.maxEvents === undefined ? 2000 : policy.maxEvents;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1)
+        throw new RangeError('queuePolicy.maxEvents must be a positive safe integer');
+    const limits = new Map();
+    if (policy.eventLimits !== undefined) {
+        if (!policy.eventLimits || typeof policy.eventLimits !== 'object' || Array.isArray(policy.eventLimits))
+            throw new TypeError('queuePolicy.eventLimits must be an event-name map');
+        for (const [name, limit] of Object.entries(policy.eventLimits)) {
+            if (!name || !Number.isSafeInteger(limit) || limit < 0 || limit > maxEvents)
+                throw new RangeError('queuePolicy event limits must be safe integers between zero and maxEvents');
+            limits.set(name, limit);
+        }
+    }
+    // Own a snapshot. Later mutations of the host's options cannot change admission.
+    return eventName => limits.get(eventName) ?? maxEvents;
+}
+export function resolveByteLimit(policy = {}) {
+    const value = policy.maxBytes === undefined ? 4 * 1024 * 1024 : policy.maxBytes;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError('queuePolicy.maxBytes must be a positive safe integer');
+    return value;
+}

package/dist/esm/core/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './PlayScopeClient.js';
+export * from './revenue.js';
+// Keep the existing /core helper available while its protocol implementation lives outside the core.
+export { trackAdRevenue } from '../protocols/game-v1/index.js';
+export { PlayScopeInitializationError } from './PersistentState.js';
+export { PlayScopeOwnershipError } from './ClientOwnership.js';

package/dist/esm/core/revenue.js

@@ -0,0 +1,20 @@
+/** Validate the income fact; the explicit encoder owns event names and wire properties. */
+export 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/esm/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/core/uuid.js

@@ -0,0 +1,6 @@
+export 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/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/protocols/game-v1/index.js

@@ -0,0 +1,21 @@
+import { enqueueAdRevenue } from '../../core/revenue.js';
+/** API v1 field encoding. Kept byte-compatible with the original SDK's revenue properties. */
+export function encodeGameV1AdRevenue(fact) {
+    // This protocol's fixed rate of one is only valid for the original USD fact.
+    if (!fact || fact.currency !== 'USD' || !Number.isFinite(fact.amount) || fact.amount < 0)
+        return null;
+    return { name: 'ad_revenue', properties: {
+            placement: fact.placement, business_placement: fact.businessPlacement ?? fact.placement,
+            ad_request_id: fact.exposureId, ad_format: fact.format, provider: fact.provider,
+            ad_unit_id: fact.adUnitId, network: fact.network, revenue: fact.amount, currency: fact.currency,
+            exchange_rate_usd: 1, revenue_precision: fact.precision, is_test: fact.isTest,
+            is_mock: fact.isMock === true, is_demo: fact.isDemo === true,
+            ...(fact.country ? { country: fact.country, ...(fact.countrySource ? { country_source: fact.countrySource } : {}) } : {}),
+            ...(fact.shownAt ? { ad_shown_at: fact.shownAt } : {}),
+            ...(fact.adConfigRevision ? { ad_config_revision: fact.adConfigRevision } : {}),
+        } };
+}
+/** Compatibility helper for existing callers; new integrations can select an encoder explicitly. */
+export function trackAdRevenue(client, fact, context = {}) {
+    return enqueueAdRevenue(client, fact, context, encodeGameV1AdRevenue);
+}

package/dist/protocols/game-v1/index.d.ts

@@ -0,0 +1,8 @@
+import type { AdRevenueFact, EncodedRevenueEvent, EventSink } from '../../core/revenue';
+import type { TrackContext } from '../../core/types';
+/** Existing product protocol vocabulary; optional for games which want this narrower type. */
+export type GameV1AdPlacement = 'revive_video' | 'gameover_interstitial' | 'win_interstitial' | 'pause_interstitial' | 'hint_video' | 'win_double' | 'banner';
+/** API v1 field encoding. Kept byte-compatible with the original SDK's revenue properties. */
+export declare function encodeGameV1AdRevenue(fact: Readonly<AdRevenueFact>): EncodedRevenueEvent | null;
+/** Compatibility helper for existing callers; new integrations can select an encoder explicitly. */
+export declare function trackAdRevenue(client: EventSink, fact: AdRevenueFact, context?: TrackContext): boolean;

package/dist/protocols/game-v1/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeGameV1AdRevenue = encodeGameV1AdRevenue;
+exports.trackAdRevenue = trackAdRevenue;
+const revenue_1 = require("../../core/revenue");
+/** API v1 field encoding. Kept byte-compatible with the original SDK's revenue properties. */
+function encodeGameV1AdRevenue(fact) {
+    // This protocol's fixed rate of one is only valid for the original USD fact.
+    if (!fact || fact.currency !== 'USD' || !Number.isFinite(fact.amount) || fact.amount < 0)
+        return null;
+    return { name: 'ad_revenue', properties: {
+            placement: fact.placement, business_placement: fact.businessPlacement ?? fact.placement,
+            ad_request_id: fact.exposureId, ad_format: fact.format, provider: fact.provider,
+            ad_unit_id: fact.adUnitId, network: fact.network, revenue: fact.amount, currency: fact.currency,
+            exchange_rate_usd: 1, revenue_precision: fact.precision, is_test: fact.isTest,
+            is_mock: fact.isMock === true, is_demo: fact.isDemo === true,
+            ...(fact.country ? { country: fact.country, ...(fact.countrySource ? { country_source: fact.countrySource } : {}) } : {}),
+            ...(fact.shownAt ? { ad_shown_at: fact.shownAt } : {}),
+            ...(fact.adConfigRevision ? { ad_config_revision: fact.adConfigRevision } : {}),
+        } };
+}
+/** Compatibility helper for existing callers; new integrations can select an encoder explicitly. */
+function trackAdRevenue(client, fact, context = {}) {
+    return (0, revenue_1.enqueueAdRevenue)(client, fact, context, encodeGameV1AdRevenue);
+}

package/doc/README.md

@@ -0,0 +1,4 @@
+# PlayScope SDK 文档
+
+接入开发者与执行接入的 AI 请从 [完整使用指南](使用指南/README.md) 开始阅读。
+该目录附带 API 类型、服务端字典、完整示例和验收清单，可整体交付。