skillprint-js-sdk 1.1.0-beta.8 → 1.1.0-beta.9

package/README.md

@@ -201,7 +201,7 @@ manager.logEvent('ROTATE_CLOCKWISE');
 manager.logEvent(GameEvent.LEVEL_COMPLETE, { level: 3, score: 1200 });
 ```
 
-Events are queued and sent with the next screenshot upload, or on their own when there is no screenshot to send. `stopGameSession()` sends the rest with the closing upload, so they arrive before the session closes. `logEvent` never throws, and with no active session it only logs a warning.
+Events are queued, and each screenshot upload carries the ones logged up to its last screenshot. Later events wait for the upload with the screenshots after them, and `stopGameSession()` sends the rest with the closing upload. The SDK decides which events go with which upload; the server keeps each upload's events with its screenshots and does no time arithmetic. If no screenshots come for a long while, events only go on their own once more than one upload's worth (1000) has piled up. `logEvent` never throws, and with no active session it only logs a warning.
 
 ### Universal and game-specific events
 
@@ -232,7 +232,7 @@ Each event can carry data (`{ level: 3, score: 1200 }`). `event` and `timestamp`
 
 Each screenshot upload can carry, beside the images:
 - `offset_ms<n>`: when the n-th screenshot was captured, in ms from session start
-- `events`: a JSON array of the events since the last upload (at most 1000), e.g. `[{"event": "ROTATE_CLOCKWISE", "timestamp": 1250}]`, where `timestamp` is ms from session start
+- `events`: a JSON array of the events logged up to the upload's last screenshot (at most 1000), e.g. `[{"event": "ROTATE_CLOCKWISE", "timestamp": 1250}]`, where `timestamp` is ms from session start
 
 ### Pages that upload their own frames
 
@@ -250,7 +250,7 @@ timeline.record('ROTATE_CLOCKWISE');       // when the player acts
 
 await client.postScreenshots(sessionId, [frame], false, {
   offsetsMs: [offset],
-  events: timeline.takeEvents()
+  events: timeline.eventsForUpload(offset)   // null for the closing upload
 });
 ```
 

package/dist/index.cjs

@@ -516,7 +516,7 @@ var SkillprintAPIClient = class {
         formData.append(`offset_ms${i}`, String(Math.round(offset)));
       }
     });
-    if (events.length > 0) {
+    if (options.events !== void 0) {
       formData.append("events", JSON.stringify(events));
     }
     try {
@@ -851,6 +851,7 @@ var SessionTimeline = class {
   constructor(now = defaultNow, maxQueued = 5e3) {
     this.startedAt = null;
     this.queue = [];
+    this.recordedAny = false;
     this.now = now;
     this.maxQueued = maxQueued;
   }
@@ -858,11 +859,13 @@ var SessionTimeline = class {
   start() {
     this.startedAt = this.now();
     this.queue = [];
+    this.recordedAny = false;
   }
   /** Stops the clock and empties the queue. */
   reset() {
     this.startedAt = null;
     this.queue = [];
+    this.recordedAny = false;
   }
   get isStarted() {
     return this.startedAt !== null;
@@ -889,15 +892,47 @@ var SessionTimeline = class {
     if (this.queue.length >= this.maxQueued) return null;
     const entry = { ...data, event, timestamp: this.offsetMs(at) };
     this.queue.push(entry);
+    this.recordedAny = true;
     return entry;
   }
   get pendingEvents() {
     return this.queue.length;
   }
-  /** Removes and returns the oldest queued events, at most `max` of them. */
+  /** True once this session has recorded any event. */
+  get hasRecorded() {
+    return this.recordedAny;
+  }
+  /** Removes and returns the earliest queued events, at most `max`, in session-time order. */
   takeEvents(max = MAX_EVENTS_PER_UPLOAD) {
+    this.sortQueue();
     return this.queue.splice(0, max);
   }
+  /**
+   * Removes and returns the queued events logged up to `offsetMs`
+   * (inclusive), at most `max`, in session-time order. Later ones stay
+   * queued for the upload that carries the screenshots after them.
+   */
+  takeEventsThrough(offsetMs, max = MAX_EVENTS_PER_UPLOAD) {
+    this.sortQueue();
+    let n = 0;
+    while (n < this.queue.length && n < max && this.queue[n].timestamp <= offsetMs) n++;
+    return this.queue.splice(0, n);
+  }
+  /**
+   * The `events` for an upload whose last screenshot was taken at
+   * `lastFrameOffsetMs`: the events logged up to then, or every queued
+   * event for the closing upload (pass null). An empty list once the
+   * session has recorded any event, so the server can tell a quiet stretch
+   * from a game that doesn't log events; undefined before that.
+   */
+  eventsForUpload(lastFrameOffsetMs) {
+    if (!this.recordedAny) return void 0;
+    return lastFrameOffsetMs === null ? this.takeEvents() : this.takeEventsThrough(lastFrameOffsetMs);
+  }
+  // Events stamped with `at` can arrive out of order; uploads send them in order.
+  sortQueue() {
+    this.queue.sort((a, b) => a.timestamp - b.timestamp);
+  }
   /** Puts events back at the front of the queue, e.g. after a failed upload. */
   requeue(events) {
     const room = Math.max(0, this.maxQueued - this.queue.length);
@@ -1200,6 +1235,7 @@ var _SkillprintManager = class _SkillprintManager {
     }
     const sessionId = this.currentSessionId;
     const remaining = this.screenshotQueue;
+    const recorded = this.timeline.hasRecorded;
     const events = this.timeline.takeEvents(Number.MAX_SAFE_INTEGER);
     const inFlightPost = this.inFlightPost;
     const apiClient = this.apiClient;
@@ -1222,22 +1258,34 @@ var _SkillprintManager = class _SkillprintManager {
     if (inFlightPost) await inFlightPost;
     const batchSize = this.postBatchSize();
     try {
-      while (events.length > MAX_EVENTS_PER_UPLOAD) {
-        await apiClient.postScreenshots(sessionId, [], false, { events: events.splice(0, MAX_EVENTS_PER_UPLOAD) });
-      }
+      const eventsUpTo = (lastFrameOffsetMs) => {
+        if (!recorded) return void 0;
+        const n = lastFrameOffsetMs === null ? events.length : events.findIndex((e) => e.timestamp > lastFrameOffsetMs);
+        return events.splice(0, Math.min(n === -1 ? events.length : n, MAX_EVENTS_PER_UPLOAD));
+      };
       if (remaining.length === 0) {
-        await apiClient.postScreenshots(sessionId, [], true, { events });
+        while (events.length > MAX_EVENTS_PER_UPLOAD) {
+          await apiClient.postScreenshots(sessionId, [], false, { events: events.splice(0, MAX_EVENTS_PER_UPLOAD) });
+        }
+        await apiClient.postScreenshots(sessionId, [], true, { events: eventsUpTo(null) });
       } else {
         for (let i = 0; i < remaining.length; i += batchSize) {
           const batch = remaining.slice(i, i + batchSize);
           const isLastChunk = i + batchSize >= remaining.length;
+          if (isLastChunk) {
+            while (events.length > MAX_EVENTS_PER_UPLOAD) {
+              await apiClient.postScreenshots(sessionId, [], false, { events: events.splice(0, MAX_EVENTS_PER_UPLOAD) });
+            }
+          }
+          const lastOffset = Math.max(...batch.map((s) => s.offsetMs));
           await apiClient.postScreenshots(sessionId, batch.map((s) => s.blob), isLastChunk, {
             offsetsMs: batch.map((s) => s.offsetMs),
-            events: isLastChunk ? events : []
+            events: eventsUpTo(isLastChunk ? null : lastOffset)
           });
         }
       }
-      this.log(`Skillprint session stopped. Flushed ${remaining.length} queued screenshots and ${events.length} events.`);
+      const flushed = remaining.length;
+      this.log(`Skillprint session stopped. Flushed ${flushed} queued screenshots.`);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       this.log(`Failed to flush screenshots on session stop: ${message}`, "error" /* ERROR */);
@@ -1287,23 +1335,23 @@ var _SkillprintManager = class _SkillprintManager {
   startScreenshotPostLoop() {
     this.screenshotPostTimer = setInterval(async () => {
       if (!this.isSessionActive || !this.apiClient || !this.currentSessionId) return;
-      if (this.screenshotQueue.length === 0 && this.timeline.pendingEvents === 0) return;
+      if (this.screenshotQueue.length === 0 && this.timeline.pendingEvents <= MAX_EVENTS_PER_UPLOAD) return;
       const batch = this.screenshotQueue.splice(0, Math.min(this.screenshotQueue.length, this.postBatchSize()));
-      const events = this.timeline.takeEvents();
+      const events = batch.length > 0 ? this.timeline.eventsForUpload(Math.max(...batch.map((s) => s.offsetMs))) : this.timeline.takeEvents();
       const apiClient = this.apiClient;
       const sessionId = this.currentSessionId;
-      this.log(`Posting ${batch.length} screenshots and ${events.length} events...`);
+      this.log(`Posting ${batch.length} screenshots and ${events?.length ?? 0} events...`);
       const post = (async () => {
         try {
           const result = await apiClient.postScreenshots(sessionId, batch.map((s) => s.blob), false, {
             offsetsMs: batch.map((s) => s.offsetMs),
             events
           });
-          this.log(`Successfully posted ${batch.length} screenshots and ${events.length} events. Response: ${result.data}`);
+          this.log(`Successfully posted ${batch.length} screenshots and ${events?.length ?? 0} events. Response: ${result.data}`);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           this.log(`Failed to post screenshots: ${message}`, "error" /* ERROR */);
-          this.requeueEvents(events, error, sessionId);
+          this.requeueEvents(events ?? [], error, sessionId);
         }
       })();
       this.inFlightPost = post;