@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/core/PlayScopeClient.d.ts

@@ -0,0 +1,46 @@
+import type { StoragePort, JsonTransport, TrackContext, PlayScopeOptions, Diagnostics } from './types';
+export declare function telemetryUuid(): string;
+export declare class PlayScopeHttpError extends Error {
+    readonly status: number;
+    readonly retryAfterMs: number;
+    constructor(status: number, retryAfterMs?: number);
+}
+/** 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 state;
+    private sessionId;
+    private busy;
+    private disposed;
+    private blocked;
+    private retryAt;
+    private failures;
+    private configAt;
+    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): void;
+    get diagnostics(): Diagnostics;
+    /** 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;
+    private persist;
+    flush(): Promise<void>;
+    private makeBatch;
+    private ensureToken;
+    private authorized;
+    private post;
+    dispose(): void;
+}
+/** Works on JSB runtimes that don't provide TextEncoder. */
+export declare function utf8Bytes(value: string): number;

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './PlayScopeClient';
+export * from './revenue';

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/core/revenue.d.ts

@@ -0,0 +1,25 @@
+import type { PlayScopeClient } from './PlayScopeClient';
+import type { TrackContext } from './types';
+export type AdPlacement = 'revive_video' | 'gameover_interstitial' | 'win_interstitial' | 'pause_interstitial' | 'hint_video' | 'win_double' | 'banner';
+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?: 'levelplay_sdk' | 'admob_sdk';
+    shownAt?: string;
+    adConfigRevision?: string;
+}
+/** Unknown/negative income is discarded; a real zero is preserved. No currency conversion is guessed. */
+export declare function trackAdRevenue(client: PlayScopeClient, fact: AdRevenueFact, context?: TrackContext): boolean;

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/core/types.d.ts

@@ -0,0 +1,81 @@
+/** API v1 ports. No Cocos or game imports are required by the core. */
+export interface StoragePort {
+    getString(key: string): string | null;
+    setString(key: string, value: 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;
+    };
+}
+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;
+    /** Host validates its own config schema; the core never interprets game settings. */
+    restoreCache?: (saved: unknown) => unknown;
+    resolveConfiguration?: (context: ConfigurationContext) => Promise<number>;
+}
+export interface Diagnostics {
+    pending: number;
+    rejected: number;
+    droppedEvents: number;
+    lastError: string | null;
+    blocked: boolean;
+}
+export interface EventBatchResponse {
+    apiVersion: number;
+    acceptedEventIds: string[];
+    rejectedEvents: {
+        eventId: string;
+        code: string;
+        permanent: boolean;
+    }[];
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/exports.json

@@ -0,0 +1,89 @@
+{
+  "@virjay/playscope-cocos": [
+    "AdPlacement",
+    "AdRevenueEncoder",
+    "AdRevenueFact",
+    "ClientContext",
+    "ClientScope",
+    "ClientStatus",
+    "CocosLifecycle",
+    "CocosOptions",
+    "CocosPlayScope",
+    "CocosRuntime",
+    "CocosStorage",
+    "ConfigurationContext",
+    "ConfigurationResult",
+    "ConfigurationStatus",
+    "Diagnostics",
+    "EncodedRevenueEvent",
+    "EventBatchResponse",
+    "EventFact",
+    "EventSink",
+    "FlushResult",
+    "HttpResponse",
+    "InitializationErrorCode",
+    "JsonTransport",
+    "LocalStorageLike",
+    "PlayScopeClient",
+    "PlayScopeHttpError",
+    "PlayScopeInitializationError",
+    "PlayScopeOptions",
+    "PlayScopeOwnershipError",
+    "QuarantinedEvent",
+    "QueuePolicy",
+    "StoragePort",
+    "TrackContext",
+    "TrackResult",
+    "XhrJsonTransport",
+    "enqueueAdRevenue",
+    "init",
+    "telemetryUuid",
+    "trackAdRevenue",
+    "utf8Bytes"
+  ],
+  "@virjay/playscope-cocos/core": [
+    "AdPlacement",
+    "AdRevenueEncoder",
+    "AdRevenueFact",
+    "ClientContext",
+    "ClientScope",
+    "ClientStatus",
+    "ConfigurationContext",
+    "ConfigurationResult",
+    "ConfigurationStatus",
+    "Diagnostics",
+    "EncodedRevenueEvent",
+    "EventBatchResponse",
+    "EventFact",
+    "EventSink",
+    "FlushResult",
+    "HttpResponse",
+    "InitializationErrorCode",
+    "JsonTransport",
+    "PlayScopeClient",
+    "PlayScopeHttpError",
+    "PlayScopeInitializationError",
+    "PlayScopeOptions",
+    "PlayScopeOwnershipError",
+    "QuarantinedEvent",
+    "QueuePolicy",
+    "StoragePort",
+    "TrackContext",
+    "TrackResult",
+    "enqueueAdRevenue",
+    "telemetryUuid",
+    "trackAdRevenue",
+    "utf8Bytes"
+  ],
+  "@virjay/playscope-cocos/adapters/levelplay": [
+    "LevelPlayExposure",
+    "LevelPlayImpression",
+    "RevenueSink",
+    "forwardLevelPlayRevenue"
+  ],
+  "@virjay/playscope-cocos/protocols/game-v1": [
+    "GameV1AdPlacement",
+    "encodeGameV1AdRevenue",
+    "trackAdRevenue"
+  ]
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/public-api.d.ts

@@ -0,0 +1,281 @@
+// Documentation snapshot, 2026-11-12. Types only; not an SDK implementation.
+
+/** 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;
+}
+
+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 interface LevelPlayImpression {
+  revenue?: number | null;
+  precision?: string | null;
+  adNetwork?: string | null;
+  mediationAdUnitId?: string | null;
+  country?: string | null;
+}
+export type LevelPlayExposure = Omit<AdRevenueFact, 'amount' | 'currency' | 'precision' | 'provider' | 'network' | 'adUnitId' | 'country' | 'countrySource'>;
+export interface RevenueSink { trackAdRevenue(fact: AdRevenueFact, context?: TrackContext): boolean }
+/** Does not initialize ads or replace the game's native listener. Host supplies the original exposure context. */
+
+export interface CocosLifecycle {
+  onHide(callback: () => void): () => void;
+  onShow(callback: () => void): () => void;
+}
+export interface CocosRuntime {
+  storage: LocalStorageLike;
+  lifecycle?: CocosLifecycle;
+  transport?: JsonTransport;
+  now?: () => number;
+}
+export interface CocosOptions extends PlayScopeOptions {
+  /** Host decides consent/collection policy before calling init. */
+  collectionEnabled: boolean;
+  /** Defaults to the existing game-v1 revenue protocol. Does not alter already queued facts. */
+  adRevenueEncoder?: AdRevenueEncoder;
+}
+/** Host owns event semantics; this wrapper only schedules flush and releases its subscriptions. */
+
+export interface LocalStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem?(key: string): void;
+}
+/** Inject sys.localStorage; failures reach the outbox and prevent unsafe uploads. */
+
+
+export declare class PlayScopeClient {
+  constructor(options: PlayScopeOptions, storage: StoragePort, transport: JsonTransport, now?: () => number);
+  get installId(): string;
+  get cache(): unknown;
+  saveCache(value: unknown): boolean;
+  getQuarantinedEvents(): QuarantinedEvent[];
+  get diagnostics(): Diagnostics;
+  get status(): ClientStatus;
+  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;
+  flush(): Promise<void>;
+  flushWithResult(): Promise<FlushResult>;
+  refreshConfiguration(): Promise<ConfigurationResult>;
+  retryUploads(): Promise<FlushResult>;
+  dispose(): void;
+}
+export declare class CocosPlayScope {
+  constructor(options: CocosOptions, runtime: CocosRuntime);
+  start(): void;
+  get installId(): string | null;
+  getDiagnostics(): Diagnostics;
+  getQuarantinedEvents(): QuarantinedEvent[];
+  get status(): ClientStatus;
+  track(name: string, properties?: Record<string, unknown>, context?: TrackContext): boolean;
+  trackWithResult(name: string, properties?: Record<string, unknown>, context?: TrackContext): TrackResult;
+  trackAdRevenue(fact: AdRevenueFact, context?: TrackContext): boolean;
+  newSession(): void;
+  update(dt: number): void;
+  flush(): Promise<void>;
+  flushWithResult(): Promise<FlushResult>;
+  refreshConfiguration(): Promise<ConfigurationResult>;
+  retryUploads(): Promise<FlushResult>;
+  dispose(): void;
+}
+export declare function init(options: CocosOptions, runtime: CocosRuntime): CocosPlayScope;
+export declare class CocosStorage implements StoragePort {
+  constructor(storage: LocalStorageLike);
+  get ownershipScope(): object;
+  readonly removeString?: (key: string) => void;
+  getString(key: string): string | null;
+  setString(key: string, value: string): void;
+  flush(): void;
+}
+export declare class XhrJsonTransport implements JsonTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponse>;
+  dispose(): void;
+}
+export declare function telemetryUuid(): string;
+export declare function utf8Bytes(value: string): number;
+export declare function enqueueAdRevenue(client: EventSink, fact: AdRevenueFact, context: TrackContext, encode: AdRevenueEncoder): boolean;
+export declare function trackAdRevenue(client: EventSink, fact: AdRevenueFact, context?: TrackContext): boolean;
+export type GameV1AdPlacement = 'revive_video' | 'gameover_interstitial' | 'win_interstitial' | 'pause_interstitial' | 'hint_video' | 'win_double' | 'banner';
+export declare function encodeGameV1AdRevenue(fact: Readonly<AdRevenueFact>): EncodedRevenueEvent | null;
+export declare function forwardLevelPlayRevenue(sink: RevenueSink, impression: LevelPlayImpression, exposure: LevelPlayExposure, context?: TrackContext): boolean;
+export type InitializationErrorCode = 'storage_unavailable' | 'state_corrupt' | 'state_version_unsupported' | 'cache_restore_failed' | 'storage_capability_missing' | 'scope_mismatch' | 'scope_migration_required';
+export declare class PlayScopeInitializationError extends Error {
+  constructor(code: InitializationErrorCode);
+  readonly code: InitializationErrorCode;
+  readonly retryable: boolean;
+}
+export declare class PlayScopeOwnershipError extends Error {
+  constructor();
+  readonly code: 'duplicate_client';
+}
+export declare class PlayScopeHttpError extends Error {
+  constructor(status: number, retryAfterMs?: number, path?: string);
+  readonly status: number;
+  readonly retryAfterMs: number;
+  readonly path?: string;
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231//346/234/215/345/212/241/347/253/257/client-context.schema.json

@@ -0,0 +1,103 @@
+{
+  "type": "object",
+  "properties": {
+    "appVersion": {
+      "type": "string",
+      "maxLength": 256
+    },
+    "buildNumber": {
+      "type": "string",
+      "maxLength": 256
+    },
+    "platform": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "android",
+          "maxLength": 256
+        },
+        {
+          "type": "string",
+          "const": "ios",
+          "maxLength": 256
+        },
+        {
+          "type": "string",
+          "const": "web",
+          "maxLength": 256
+        },
+        {
+          "type": "string",
+          "const": "wechat",
+          "maxLength": 256
+        }
+      ]
+    },
+    "environment": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "production",
+          "maxLength": 256
+        },
+        {
+          "type": "string",
+          "const": "test",
+          "maxLength": 256
+        }
+      ]
+    },
+    "locale": {
+      "type": "string",
+      "maxLength": 256
+    },
+    "timezoneOffsetMinutes": {
+      "type": "integer",
+      "minimum": -840,
+      "maximum": 840
+    },
+    "device": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "android_id",
+          "maxLength": 256
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{16}$",
+          "not": {
+            "enum": [
+              "0000000000000000",
+              "9774d56d682e549c"
+            ]
+          }
+        }
+      },
+      "required": [
+        "type",
+        "id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "appVersion",
+    "buildNumber",
+    "platform",
+    "environment",
+    "locale",
+    "timezoneOffsetMinutes"
+  ],
+  "additionalProperties": false,
+  "dependentSchemas": {
+    "device": {
+      "properties": {
+        "platform": {
+          "const": "android"
+        }
+      }
+    }
+  }
+}