@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/dist/core/PersistentState.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayScopeInitializationError = void 0;
+exports.isEventFact = isEventFact;
+exports.loadState = loadState;
+exports.parseState = parseState;
+const uuid_1 = require("./uuid");
+/** Construction fails without overwriting stored data. Retry by constructing a new client. */
+class PlayScopeInitializationError extends Error {
+    constructor(code) {
+        super(`PlayScope initialization failed: ${code}`);
+        this.code = code;
+        this.name = 'PlayScopeInitializationError';
+        this.retryable = code === 'storage_unavailable';
+    }
+}
+exports.PlayScopeInitializationError = PlayScopeInitializationError;
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isEventFact(value) {
+    return object(value) && typeof value.eventId === 'string' && value.eventId.length > 0 && typeof value.name === 'string';
+}
+function integer(value) { return Number.isSafeInteger(value) && value >= 0; }
+function isClientScope(value) {
+    return object(value) && typeof value.baseUrl === 'string' && !!value.baseUrl.replace(/\/+$/, '') &&
+        typeof value.projectId === 'string' && !!value.projectId && ['production', 'test'].includes(value.environment);
+}
+function loadState(storage, key, now, restoreCache) {
+    let raw;
+    try {
+        raw = storage.getString(key);
+    }
+    catch {
+        throw new PlayScopeInitializationError('storage_unavailable');
+    }
+    return parseState(raw, now, restoreCache);
+}
+function parseState(raw, now, restoreCache) {
+    // Only an explicit missing key is a new installation. Empty/invalid data is preserved.
+    let state;
+    if (raw === null) {
+        state = { schemaVersion: 1, installId: (0, uuid_1.telemetryUuid)(), firstOpenedAt: new Date(now()).toISOString(),
+            firstOpenTracked: false, sequence: 0, token: null, cache: null, queue: [], quarantined: [], rejected: [], droppedEvents: 0 };
+    }
+    else {
+        let saved;
+        try {
+            saved = JSON.parse(raw);
+        }
+        catch {
+            throw new PlayScopeInitializationError('state_corrupt');
+        }
+        if (!object(saved))
+            throw new PlayScopeInitializationError('state_corrupt');
+        if (saved.schemaVersion !== undefined && saved.schemaVersion !== 1)
+            throw new PlayScopeInitializationError('state_version_unsupported');
+        if (typeof saved.installId !== 'string' || !/^[0-9a-f-]{36}$/i.test(saved.installId) ||
+            typeof saved.firstOpenedAt !== 'string' || !Number.isFinite(Date.parse(saved.firstOpenedAt)) ||
+            typeof saved.firstOpenTracked !== 'boolean' || !integer(saved.sequence) ||
+            !Array.isArray(saved.queue) || !saved.queue.every(isEventFact))
+            throw new PlayScopeInitializationError('state_corrupt');
+        const quarantine = saved.quarantined ?? [];
+        if (!Array.isArray(quarantine) || !quarantine.every(value => object(value) && isEventFact(value.event) &&
+            (value.reason === 'event_too_large' || value.reason === 'http_413') && typeof value.quarantinedAt === 'string'))
+            throw new PlayScopeInitializationError('state_corrupt');
+        const token = saved.token;
+        const scope = saved.scope;
+        if (scope !== undefined && !isClientScope(scope))
+            throw new PlayScopeInitializationError('state_corrupt');
+        // Versionless state is the original SDK/BlockDrop shape. Migration adds metadata;
+        // queued facts, IDs, sequence, first-open marker and identity are never recreated.
+        state = { schemaVersion: 1, installId: saved.installId, firstOpenedAt: saved.firstOpenedAt,
+            firstOpenTracked: saved.firstOpenTracked, sequence: saved.sequence, queue: saved.queue, quarantined: quarantine,
+            token: object(token) && typeof token.accessToken === 'string' && typeof token.expiresAt === 'string' &&
+                Number.isFinite(Date.parse(token.expiresAt)) ? { accessToken: token.accessToken, expiresAt: token.expiresAt } : null,
+            cache: saved.cache ?? null, droppedEvents: integer(saved.droppedEvents) ? saved.droppedEvents : 0,
+            rejected: Array.isArray(saved.rejected) ? saved.rejected.slice(-50) : [],
+            ...(Array.isArray(saved.deduplicationKeys)
+                ? { deduplicationKeys: saved.deduplicationKeys.filter((key) => typeof key === 'string').slice(-2000) } : {}),
+            ...(scope ? { scope: { baseUrl: scope.baseUrl, projectId: scope.projectId, environment: scope.environment } } : {}) };
+    }
+    if (restoreCache) {
+        try {
+            state.cache = restoreCache(state.cache);
+        }
+        catch {
+            throw new PlayScopeInitializationError('cache_restore_failed');
+        }
+    }
+    return state;
+}

package/dist/core/PlayScopeClient.d.ts

@@ -0,0 +1,65 @@
+import type { StoragePort, JsonTransport, TrackContext, PlayScopeOptions, Diagnostics, QuarantinedEvent, TrackResult, FlushResult, ClientStatus, ConfigurationResult } from './types';
+export { PlayScopeHttpError } from './HttpError';
+export { utf8Bytes } from './FactEncoding';
+export { telemetryUuid } from './uuid';
+/** Durable API v1 outbox, independent of game schema and rendering engine. */
+export declare class PlayScopeClient {
+    private readonly options;
+    private readonly storage;
+    private readonly transport;
+    private readonly now;
+    private readonly key;
+    private readonly api;
+    private readonly clientContext;
+    private readonly bootstrapContext;
+    private state;
+    private readonly releaseOwnership;
+    private readonly admissionLimit;
+    private readonly maxQueueBytes;
+    private readonly encoding;
+    private readonly outbox;
+    private sessionId;
+    private flushTask;
+    private tokenTask;
+    private readonly configuration;
+    private disposed;
+    private blocked;
+    private retryAt;
+    private failures;
+    private batchLimit;
+    private lastError_;
+    private needsPersistence;
+    private identityPublished;
+    constructor(options: PlayScopeOptions, storage: StoragePort, transport: JsonTransport, now?: () => number);
+    get installId(): string;
+    get cache(): unknown;
+    saveCache(value: unknown): boolean;
+    getQuarantinedEvents(): QuarantinedEvent[];
+    get diagnostics(): Diagnostics;
+    private queueBytes;
+    get status(): ClientStatus;
+    /** Configuration has its own failure budget and never waits for event delivery. */
+    refreshConfiguration(): Promise<ConfigurationResult>;
+    /** Explicit recovery after the host has repaired credentials, endpoint or permissions. */
+    retryUploads(): Promise<FlushResult>;
+    /** Call after collection is allowed. Existing first-open facts are never recreated. */
+    start(name?: string, context?: TrackContext): void;
+    newSession(): void;
+    track(name: string, properties: Record<string, unknown>, context?: TrackContext): boolean;
+    trackWithResult(name: string, properties: Record<string, unknown>, context?: TrackContext): TrackResult;
+    private persist;
+    /** Compatibility wrapper: independently schedules config; resolves when this delivery pass finishes. */
+    flush(): Promise<void>;
+    flushWithResult(): Promise<FlushResult>;
+    private flushResult;
+    private deliver;
+    private batchEnvelope;
+    private fitsSingleBatch;
+    private quarantine;
+    private makeBatch;
+    private ensureToken;
+    private bootstrap;
+    private authorized;
+    private post;
+    dispose(): void;
+}

package/dist/core/PlayScopeClient.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayScopeClient = exports.telemetryUuid = exports.utf8Bytes = exports.PlayScopeHttpError = void 0;
+const ConfigurationSync_1 = require("./ConfigurationSync");
+const HttpError_1 = require("./HttpError");
+var HttpError_2 = require("./HttpError");
+Object.defineProperty(exports, "PlayScopeHttpError", { enumerable: true, get: function () { return HttpError_2.PlayScopeHttpError; } });
+const ClientOwnership_1 = require("./ClientOwnership");
+const PersistentState_1 = require("./PersistentState");
+const uuid_1 = require("./uuid");
+const QueueAdmission_1 = require("./QueueAdmission");
+const OutboxStore_1 = require("./OutboxStore");
+const FactEncoding_1 = require("./FactEncoding");
+const ClientScope_1 = require("./ClientScope");
+var FactEncoding_2 = require("./FactEncoding");
+Object.defineProperty(exports, "utf8Bytes", { enumerable: true, get: function () { return FactEncoding_2.utf8Bytes; } });
+var uuid_2 = require("./uuid");
+Object.defineProperty(exports, "telemetryUuid", { enumerable: true, get: function () { return uuid_2.telemetryUuid; } });
+const MAX_BATCH_BYTES = 250 * 1024;
+/** Durable API v1 outbox, independent of game schema and rendering engine. */
+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_1.FactEncoding();
+        this.sessionId = (0, uuid_1.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 = (0, ClientScope_1.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 = (0, QueueAdmission_1.resolveQueuePolicy)(options.queuePolicy);
+        this.maxQueueBytes = (0, QueueAdmission_1.resolveByteLimit)(options.queuePolicy);
+        this.outbox = new OutboxStore_1.OutboxStore(storage, this.key, options.persistence, this.encoding);
+        this.configuration = new ConfigurationSync_1.ConfigurationSync(options.resolveConfiguration, async () => {
+            if (this.disposed)
+                throw new Error('disposed');
+            if (this.needsPersistence && !this.persist())
+                throw new HttpError_1.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 HttpError_1.StorageUnavailableError();
+                } };
+        }, now);
+        this.releaseOwnership = (0, ClientOwnership_1.claimStorage)(storage, this.key);
+        try {
+            this.state = this.outbox.load(now);
+            (0, ClientScope_1.bindClientScope)(this.state, scope, this.outbox.hasStoredState, options.legacyScope);
+            if (options.restoreCache) {
+                try {
+                    this.state.cache = options.restoreCache(this.state.cache);
+                }
+                catch {
+                    throw new PersistentState_1.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 = (0, uuid_1.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: (0, uuid_1.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 (!(0, PersistentState_1.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 HttpError_1.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: (0, uuid_1.telemetryUuid)(),
+            sentAt: new Date(this.now()).toISOString(), events };
+    }
+    fitsSingleBatch(event) {
+        return (0, FactEncoding_1.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 = (0, FactEncoding_1.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 HttpError_1.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 HttpError_1.StorageUnavailableError();
+        try {
+            return await this.post(path, { Authorization: `Bearer ${token}` }, body);
+        }
+        catch (error) {
+            if (!(error instanceof HttpError_1.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 HttpError_1.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 HttpError_1.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();
+        }
+    }
+}
+exports.PlayScopeClient = PlayScopeClient;

package/dist/core/QueueAdmission.d.ts

@@ -0,0 +1,4 @@
+import type { QueuePolicy } from './types';
+/** Admission only: restored/unacknowledged facts are never evicted to meet a new limit. */
+export declare function resolveQueuePolicy(policy?: QueuePolicy): (eventName: string) => number;
+export declare function resolveByteLimit(policy?: QueuePolicy): number;

package/dist/core/QueueAdmission.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQueuePolicy = resolveQueuePolicy;
+exports.resolveByteLimit = resolveByteLimit;
+/** Admission only: restored/unacknowledged facts are never evicted to meet a new limit. */
+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;
+}
+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/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './PlayScopeClient';
+export * from './revenue';
+export { trackAdRevenue } from '../protocols/game-v1';
+export { PlayScopeInitializationError } from './PersistentState';
+export type { InitializationErrorCode } from './PersistentState';
+export { PlayScopeOwnershipError } from './ClientOwnership';

package/dist/core/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayScopeOwnershipError = exports.PlayScopeInitializationError = exports.trackAdRevenue = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./PlayScopeClient"), exports);
+__exportStar(require("./revenue"), exports);
+// Keep the existing /core helper available while its protocol implementation lives outside the core.
+var game_v1_1 = require("../protocols/game-v1");
+Object.defineProperty(exports, "trackAdRevenue", { enumerable: true, get: function () { return game_v1_1.trackAdRevenue; } });
+var PersistentState_1 = require("./PersistentState");
+Object.defineProperty(exports, "PlayScopeInitializationError", { enumerable: true, get: function () { return PersistentState_1.PlayScopeInitializationError; } });
+var ClientOwnership_1 = require("./ClientOwnership");
+Object.defineProperty(exports, "PlayScopeOwnershipError", { enumerable: true, get: function () { return ClientOwnership_1.PlayScopeOwnershipError; } });