Batching & Offline Support

The SDK automatically manages batching, retries, and offline scenarios.

Automatic Batching

Events are automatically batched as NDJSON and flushed based on:

• Time threshold: flushIntervalMs (default: 5000ms)
• Size threshold: maxBatchBytes (default: 100_000 bytes)

Lumina.init({
  flushIntervalMs: 2000,  // Flush every 2 seconds
  maxBatchBytes: 512_000, // Or when batch reaches 512KB
});

Manual Flush

Force an immediate flush:

await Lumina.flush();

Useful for:

• Before page unload
• End of critical user flows
• Testing and debugging

Retry Logic

The SDK implements retry logic for failed requests:

1. First retry: 300ms delay
2. Second retry: 600ms delay
3. Third retry: 900ms delay
4. Max retries: 3 attempts

Failed batches are re-queued and will be retried on the next flush.

Offline Handling

Queue Management

When offline, events are:

• Queued in memory (up to memory limits)
• Automatically sent when connection restored
• Preserved across flushes

Testing Offline Behavior

// Simulate offline
window.dispatchEvent(new Event('offline'));
 
// SDK will queue events
const session = await Lumina.session.start()
const turn = session.turn()
// ... capture turn data
 
// Simulate back online
window.dispatchEvent(new Event('online'));
// SDK automatically flushes queued events

Best Practices

1. Flush on Navigation

// Next.js example
useEffect(() => {
  const handleBeforeUnload = () => {
    Lumina.flush();
  };
  
  window.addEventListener('beforeunload', handleBeforeUnload);
  return () => window.removeEventListener('beforeunload', handleBeforeUnload);
}, []);

2. Monitor Queue Size

// Check if events are queued
const queueSize = Lumina.getQueueSize();
if (queueSize > 100) {
  console.warn(`Large event queue: ${queueSize} events`);
}

3. Handle Critical Events

For critical events, wait for flush completion:

const session = await Lumina.session.start()
const turn = session.turn()
// ... capture turn
await turn.finish()
await Lumina.flush(); // Wait for send

Performance Considerations

Batch Size Tuning

• Smaller batches (50KB): Lower latency, more requests
• Larger batches (500KB): Better throughput, higher latency

Sampling

Reduce data volume in high-traffic applications:

Lumina.init({
  sampling: { 
    turn: 0.1  // Sample 10% of turns
  }
});

Dynamic sampling based on user tier:

const samplingRate = user.tier === "enterprise" ? 1.0 : 0.1;
 
Lumina.init({
  sampling: { turn: samplingRate }
});