@illuma-ai/observability-core 0.1.0 → 0.2.1

package/dist/__tests__/core-client.test.js

@@ -0,0 +1,844 @@
+/**
+ * Integration tests for ObservabilityCoreClient.
+ *
+ * Validates event batching, auto-flush, manual flush, shutdown behavior,
+ * and the TraceClient -> SpanClient -> GenerationClient chaining API.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ObservabilityCoreClient, IngestionEventType, } from '../index.js';
+// ---------------------------------------------------------------------------
+// Concrete test implementation of the abstract core client
+// ---------------------------------------------------------------------------
+class TestClient extends ObservabilityCoreClient {
+    /** Captured fetch calls for assertions. */
+    fetchCalls = [];
+    /** Configurable mock response returned by fetchWithRetry. */
+    mockResponse = {
+        status: 200,
+        statusText: 'OK',
+        ok: true,
+        json: async () => ({ successes: [], errors: [] }),
+        text: async () => '',
+    };
+    async fetchWithRetry(url, options) {
+        this.fetchCalls.push({ url, options });
+        return this.mockResponse;
+    }
+    /** Helper to inspect the last request body sent. */
+    getLastRequestBody() {
+        const last = this.fetchCalls.at(-1);
+        if (!last?.options.body)
+            return undefined;
+        return JSON.parse(last.options.body);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function createClient(overrides = {}) {
+    return new TestClient({
+        publicKey: 'pk-test',
+        secretKey: 'sk-test',
+        baseUrl: 'https://observe.test',
+        flushAt: 5,
+        flushInterval: 0, // disable periodic flush timer in tests
+        ...overrides,
+    });
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('ObservabilityCoreClient', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    // -------------------------------------------------------------------------
+    // Event batching
+    // -------------------------------------------------------------------------
+    describe('event batching', () => {
+        it('should enqueue events into the internal queue', () => {
+            const client = createClient();
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.GENERATION_CREATE,
+                timestamp: '2024-01-01T00:00:01.000Z',
+                body: { id: 'gen-1', traceId: 'trace-1' },
+            });
+            const queue = client.getQueue();
+            expect(queue).toHaveLength(2);
+            expect(queue[0].id).toBe('evt-1');
+            expect(queue[1].id).toBe('evt-2');
+        });
+        it('should include all event fields in the batch payload', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1', name: 'test-trace', userId: 'user-42' },
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            expect(body).toBeDefined();
+            expect(body.batch).toHaveLength(1);
+            expect(body.batch[0].type).toBe('trace-create');
+            expect(body.batch[0].body).toMatchObject({
+                id: 'trace-1',
+                name: 'test-trace',
+                userId: 'user-42',
+            });
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Auto-flush at threshold
+    // -------------------------------------------------------------------------
+    describe('auto-flush at threshold', () => {
+        it('should auto-flush when queue reaches flushAt', async () => {
+            const client = createClient({ flushAt: 3 });
+            // Enqueue 3 events to hit the threshold
+            for (let i = 0; i < 3; i++) {
+                client.enqueue({
+                    id: `evt-${i}`,
+                    type: IngestionEventType.TRACE_CREATE,
+                    timestamp: '2024-01-01T00:00:00.000Z',
+                    body: { id: `trace-${i}` },
+                });
+            }
+            // flush() is called asynchronously — allow microtasks to settle
+            await vi.advanceTimersByTimeAsync(0);
+            expect(client.fetchCalls).toHaveLength(1);
+            const body = client.getLastRequestBody();
+            expect(body.batch).toHaveLength(3);
+            // Queue should be empty after flush
+            expect(client.getQueue()).toHaveLength(0);
+        });
+        it('should not flush before reaching the threshold', () => {
+            const client = createClient({ flushAt: 5 });
+            for (let i = 0; i < 4; i++) {
+                client.enqueue({
+                    id: `evt-${i}`,
+                    type: IngestionEventType.TRACE_CREATE,
+                    timestamp: '2024-01-01T00:00:00.000Z',
+                    body: { id: `trace-${i}` },
+                });
+            }
+            expect(client.fetchCalls).toHaveLength(0);
+            expect(client.getQueue()).toHaveLength(4);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Manual flush
+    // -------------------------------------------------------------------------
+    describe('manual flush', () => {
+        it('should flush all queued events when called explicitly', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.SPAN_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'span-1', traceId: 'trace-1' },
+            });
+            await client.flush();
+            expect(client.fetchCalls).toHaveLength(1);
+            expect(client.getQueue()).toHaveLength(0);
+        });
+        it('should be a no-op when the queue is empty', async () => {
+            const client = createClient();
+            await client.flush();
+            expect(client.fetchCalls).toHaveLength(0);
+        });
+        it('should send to the correct ingestion endpoint', async () => {
+            const client = createClient({ baseUrl: 'https://my-server.example.com' });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            expect(client.fetchCalls[0].url).toBe('https://my-server.example.com/api/public/ingestion');
+        });
+        it('should include Authorization header with Basic auth', async () => {
+            const client = createClient({
+                publicKey: 'pk-abc',
+                secretKey: 'sk-xyz',
+            });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            const authHeader = client.fetchCalls[0].options.headers['Authorization'];
+            // Basic base64("pk-abc:sk-xyz")
+            const expected = `Basic ${Buffer.from('pk-abc:sk-xyz').toString('base64')}`;
+            expect(authHeader).toBe(expected);
+        });
+        it('should include SDK metadata in the request body', async () => {
+            const client = createClient();
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            expect(body.metadata).toBeDefined();
+            expect(body.metadata.publicKey).toBe('pk-test');
+            expect(body.metadata.sdkName).toBe('@illuma-ai/observability-core');
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Shutdown flushes remaining events
+    // -------------------------------------------------------------------------
+    describe('shutdown', () => {
+        it('should flush remaining events on shutdown', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.GENERATION_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'gen-1' },
+            });
+            await client.shutdown();
+            expect(client.fetchCalls).toHaveLength(1);
+            const body = client.getLastRequestBody();
+            expect(body.batch).toHaveLength(2);
+            expect(client.getQueue()).toHaveLength(0);
+        });
+        it('should be safe to call shutdown with an empty queue', async () => {
+            const client = createClient();
+            await client.shutdown();
+            expect(client.fetchCalls).toHaveLength(0);
+        });
+        it('should clear the flush timer on shutdown', async () => {
+            // Enable periodic flush to test timer clearing
+            const client = createClient({ flushInterval: 5000 });
+            await client.shutdown();
+            // Advancing time should not trigger any additional flushes
+            client.enqueue({
+                id: 'evt-late',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-late' },
+            });
+            vi.advanceTimersByTime(10_000);
+            // Give any pending promises time to resolve
+            await vi.advanceTimersByTimeAsync(0);
+            // The event should still be in the queue (timer was cleared)
+            expect(client.getQueue()).toHaveLength(1);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Disabled client
+    // -------------------------------------------------------------------------
+    describe('disabled client', () => {
+        it('should not enqueue events when disabled', () => {
+            const client = createClient({ enabled: false });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            expect(client.getQueue()).toHaveLength(0);
+        });
+        it('should return a TraceClient even when disabled', () => {
+            const client = createClient({ enabled: false });
+            const trace = client.trace({ name: 'noop-trace' });
+            expect(trace).toBeDefined();
+            expect(trace.id).toBeDefined();
+        });
+    });
+    // -------------------------------------------------------------------------
+    // TraceClient chaining: trace -> generation -> score
+    // -------------------------------------------------------------------------
+    describe('TraceClient chaining', () => {
+        it('should create trace, generation, and score events via chaining', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'chat-workflow' });
+            const gen = trace.generation({
+                name: 'llm-call',
+                model: 'gpt-4o',
+                input: [{ role: 'user', content: 'Hello' }],
+            });
+            gen.end({
+                output: { role: 'assistant', content: 'Hi!' },
+                usage: { input: 10, output: 5, total: 15 },
+            });
+            trace.score({ name: 'quality', value: 0.95 });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            expect(body).toBeDefined();
+            const types = body.batch.map((e) => e.type);
+            expect(types).toContain('trace-create');
+            expect(types).toContain('generation-create');
+            expect(types).toContain('generation-update');
+            expect(types).toContain('score-create');
+            // Verify trace event
+            const traceEvent = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvent.body.name).toBe('chat-workflow');
+            // Verify generation-create has correct model and traceId
+            const genCreate = body.batch.find((e) => e.type === 'generation-create');
+            expect(genCreate.body.model).toBe('gpt-4o');
+            expect(genCreate.body.traceId).toBe(trace.id);
+            // Verify generation-update (from .end()) has usage
+            const genUpdate = body.batch.find((e) => e.type === 'generation-update');
+            expect(genUpdate.body.usage).toMatchObject({
+                input: 10,
+                output: 5,
+                total: 15,
+            });
+            // Verify score is attached to the trace
+            const scoreEvent = body.batch.find((e) => e.type === 'score-create');
+            expect(scoreEvent.body.name).toBe('quality');
+            expect(scoreEvent.body.value).toBe(0.95);
+            expect(scoreEvent.body.traceId).toBe(trace.id);
+        });
+        it('should support trace.update() for adding output after the fact', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'workflow' });
+            trace.update({ output: 'final result', tags: ['test'] });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            // Should have 2 trace-create events (initial + update/upsert)
+            const traceEvents = body.batch.filter((e) => e.type === 'trace-create');
+            expect(traceEvents).toHaveLength(2);
+            const updateEvent = traceEvents[1];
+            expect(updateEvent.body.output).toBe('final result');
+            expect(updateEvent.body.tags).toEqual(['test']);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // SpanClient nesting
+    // -------------------------------------------------------------------------
+    describe('SpanClient nesting', () => {
+        it('should support nested spans with correct parentObservationId', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'pipeline' });
+            const outerSpan = trace.span({ name: 'retrieval' });
+            const innerSpan = outerSpan.span({ name: 'vector-search' });
+            innerSpan.end({ output: { results: 5 } });
+            outerSpan.end();
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const spanCreates = body.batch.filter((e) => e.type === 'span-create');
+            expect(spanCreates).toHaveLength(2);
+            // Outer span: parent is the trace (no parentObservationId, just traceId)
+            const outer = spanCreates.find((e) => e.body.name === 'retrieval');
+            expect(outer.body.traceId).toBe(trace.id);
+            expect(outer.body.parentObservationId).toBeUndefined();
+            // Inner span: parentObservationId should be the outer span's ID
+            const inner = spanCreates.find((e) => e.body.name === 'vector-search');
+            expect(inner.body.traceId).toBe(trace.id);
+            expect(inner.body.parentObservationId).toBe(outerSpan.id);
+        });
+        it('should support creating generations under a span', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'agent' });
+            const span = trace.span({ name: 'tool-call' });
+            const gen = span.generation({
+                name: 'llm',
+                model: 'claude-3-opus',
+            });
+            gen.end({ output: 'response text' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const genCreate = body.batch.find((e) => e.type === 'generation-create');
+            expect(genCreate.body.traceId).toBe(trace.id);
+            expect(genCreate.body.parentObservationId).toBe(span.id);
+            expect(genCreate.body.model).toBe('claude-3-opus');
+        });
+        it('should support events under a span', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'workflow' });
+            const span = trace.span({ name: 'processing' });
+            span.event({ name: 'cache-hit', metadata: { key: 'doc-123' } });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const eventCreate = body.batch.find((e) => e.type === 'event-create');
+            expect(eventCreate.body.traceId).toBe(trace.id);
+            expect(eventCreate.body.parentObservationId).toBe(span.id);
+            expect(eventCreate.body.name).toBe('cache-hit');
+        });
+        it('should support scoring a span', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'workflow' });
+            const span = trace.span({ name: 'retrieval' });
+            span.score({ name: 'relevance', value: 0.8 });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const scoreEvent = body.batch.find((e) => e.type === 'score-create');
+            expect(scoreEvent.body.traceId).toBe(trace.id);
+            expect(scoreEvent.body.observationId).toBe(span.id);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // GenerationClient
+    // -------------------------------------------------------------------------
+    describe('GenerationClient', () => {
+        it('should create a generation with model and usage params', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'llm-call' });
+            trace.generation({
+                name: 'completion',
+                model: 'gpt-4o-mini',
+                input: { messages: [{ role: 'user', content: 'Hi' }] },
+                output: { role: 'assistant', content: 'Hello!' },
+                usage: { input: 5, output: 3, total: 8, unit: 'TOKENS' },
+                modelParameters: { temperature: 0.7, max_tokens: 100 },
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const gen = body.batch.find((e) => e.type === 'generation-create');
+            expect(gen.body.model).toBe('gpt-4o-mini');
+            expect(gen.body.usage).toMatchObject({
+                input: 5,
+                output: 3,
+                total: 8,
+                unit: 'TOKENS',
+            });
+            expect(gen.body.modelParameters).toMatchObject({
+                temperature: 0.7,
+                max_tokens: 100,
+            });
+        });
+        it('should support update() for streaming completions', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'stream' });
+            const gen = trace.generation({
+                name: 'streaming-completion',
+                model: 'gpt-4o',
+                input: 'prompt',
+            });
+            // Simulate streaming: update with output and usage after completion
+            gen.update({
+                output: 'streamed response',
+                usage: { input: 20, output: 50, total: 70 },
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const genUpdate = body.batch.find((e) => e.type === 'generation-update');
+            expect(genUpdate.body.output).toBe('streamed response');
+            expect(genUpdate.body.id).toBe(gen.id);
+        });
+        it('should support scoring a generation', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'eval' });
+            const gen = trace.generation({ model: 'gpt-4o' });
+            gen.score({ name: 'accuracy', value: 1.0, comment: 'Correct answer' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const score = body.batch.find((e) => e.type === 'score-create');
+            expect(score.body.observationId).toBe(gen.id);
+            expect(score.body.traceId).toBe(trace.id);
+            expect(score.body.name).toBe('accuracy');
+            expect(score.body.value).toBe(1.0);
+            expect(score.body.comment).toBe('Correct answer');
+        });
+        it('should support end() which sets endTime and merges params', async () => {
+            const client = createClient({ flushAt: 100 });
+            const trace = client.trace({ name: 'test' });
+            const gen = trace.generation({ model: 'claude-3-sonnet' });
+            gen.end({
+                output: 'done',
+                usage: { input: 100, output: 200 },
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const genUpdate = body.batch.find((e) => e.type === 'generation-update');
+            expect(genUpdate.body.endTime).toBeDefined();
+            expect(genUpdate.body.output).toBe('done');
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Constructor validation
+    // -------------------------------------------------------------------------
+    describe('constructor', () => {
+        it('should throw when publicKey is missing', () => {
+            expect(() => new TestClient({
+                publicKey: '',
+                secretKey: 'sk-test',
+            })).toThrow('publicKey and secretKey are required');
+        });
+        it('should throw when secretKey is missing', () => {
+            expect(() => new TestClient({
+                publicKey: 'pk-test',
+                secretKey: '',
+            })).toThrow('publicKey and secretKey are required');
+        });
+        it('should strip trailing slashes from baseUrl', async () => {
+            const client = createClient({
+                baseUrl: 'https://observe.test///',
+            });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            expect(client.fetchCalls[0].url).toBe('https://observe.test/api/public/ingestion');
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Constructor config defaults
+    // -------------------------------------------------------------------------
+    describe('config defaults', () => {
+        it('should use default baseUrl when not provided', async () => {
+            const client = new TestClient({
+                publicKey: 'pk-test',
+                secretKey: 'sk-test',
+                flushInterval: 0,
+            });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            expect(client.fetchCalls[0].url).toBe('http://localhost:3000/api/public/ingestion');
+        });
+        it('should set all config fields correctly', () => {
+            // The client doesn't expose config fields publicly, so we verify
+            // behavior that depends on them
+            const client = createClient({
+                publicKey: 'pk-custom',
+                secretKey: 'sk-custom',
+                baseUrl: 'https://custom.example.com',
+                flushAt: 2,
+                enabled: true,
+            });
+            // flushAt = 2 — enqueue 2 events should trigger auto-flush
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-2' },
+            });
+            // Auto-flush was triggered (async), verify URL has custom base
+            // The fetch is async, so just verify the queue was drained
+            // We can verify the URL after advancing timers
+            return vi.advanceTimersByTimeAsync(0).then(() => {
+                expect(client.fetchCalls[0].url).toBe('https://custom.example.com/api/public/ingestion');
+            });
+        });
+    });
+    // -------------------------------------------------------------------------
+    // getQueue() behavior
+    // -------------------------------------------------------------------------
+    describe('getQueue()', () => {
+        it('should return the current events in the queue', () => {
+            const client = createClient();
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            const queue = client.getQueue();
+            expect(queue).toHaveLength(1);
+            expect(queue[0].id).toBe('evt-1');
+        });
+        it('should return a read-only array', () => {
+            const client = createClient();
+            const queue = client.getQueue();
+            // ReadonlyArray does not have push at runtime, but the reference
+            // should reflect the internal array state
+            expect(Array.isArray(queue)).toBe(true);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // trace() with config environment/release/version
+    // -------------------------------------------------------------------------
+    describe('trace() config propagation', () => {
+        it('should include environment from config when not in params', async () => {
+            const client = createClient({ environment: 'production', flushAt: 100 });
+            client.trace({ name: 'test-trace' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.environment).toBe('production');
+        });
+        it('should include release from config when not in params', async () => {
+            const client = createClient({ release: 'v1.2.3', flushAt: 100 });
+            client.trace({ name: 'test-trace' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.release).toBe('v1.2.3');
+        });
+        it('should include version from release config when not in params', async () => {
+            const client = createClient({ release: 'v2.0.0', flushAt: 100 });
+            client.trace({ name: 'test-trace' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.version).toBe('v2.0.0');
+        });
+        it('should not override params.environment with config.environment', async () => {
+            const client = createClient({
+                environment: 'production',
+                flushAt: 100,
+            });
+            client.trace({ name: 'test', environment: 'staging' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.environment).toBe('staging');
+        });
+        it('should not override params.release with config.release', async () => {
+            const client = createClient({ release: 'v1.0.0', flushAt: 100 });
+            client.trace({ name: 'test', release: 'v2.0.0' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.release).toBe('v2.0.0');
+        });
+        it('should not override params.version with config.release', async () => {
+            const client = createClient({ release: 'v1.0.0', flushAt: 100 });
+            client.trace({ name: 'test', version: 'custom-version' });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const traceEvt = body.batch.find((e) => e.type === 'trace-create');
+            expect(traceEvt.body.version).toBe('custom-version');
+        });
+    });
+    // -------------------------------------------------------------------------
+    // 207 Multi-Status handling
+    // -------------------------------------------------------------------------
+    describe('207 Multi-Status response', () => {
+        it('should handle 207 response with errors by logging and accepting', async () => {
+            const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            const client = createClient({ flushAt: 100 });
+            client.mockResponse = {
+                status: 207,
+                statusText: 'Multi-Status',
+                ok: true,
+                json: async () => ({
+                    successes: [{ id: 'evt-1', status: 200 }],
+                    errors: [{ id: 'evt-2', status: 400, message: 'Invalid event' }],
+                }),
+                text: async () => '',
+            };
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-2' },
+            });
+            await client.flush();
+            // Batch accepted — queue should be empty
+            expect(client.getQueue()).toHaveLength(0);
+            consoleSpy.mockRestore();
+        });
+        it('should handle 207 response with no errors', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.mockResponse = {
+                status: 207,
+                statusText: 'Multi-Status',
+                ok: true,
+                json: async () => ({
+                    successes: [{ id: 'evt-1', status: 200 }],
+                    errors: [],
+                }),
+                text: async () => '',
+            };
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            expect(client.getQueue()).toHaveLength(0);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Flush clears queue after successful send
+    // -------------------------------------------------------------------------
+    describe('flush queue clearing', () => {
+        it('should clear queue after successful send', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.SPAN_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'span-1' },
+            });
+            expect(client.getQueue()).toHaveLength(2);
+            await client.flush();
+            expect(client.getQueue()).toHaveLength(0);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Concurrent flush guard
+    // -------------------------------------------------------------------------
+    describe('concurrent flush guard', () => {
+        it('should skip flush if one is already in progress', async () => {
+            const client = createClient({ flushAt: 100 });
+            // Make fetchWithRetry slow
+            let resolveFirst;
+            const originalMockResponse = client.mockResponse;
+            let callCount = 0;
+            // Override to add delay on first call
+            const origFetchCalls = client.fetchCalls;
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            // Start first flush (won't resolve immediately)
+            const firstFlush = client.flush();
+            // Enqueue more and try second flush while first is in progress
+            client.enqueue({
+                id: 'evt-2',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-2' },
+            });
+            // This should be a no-op since flush is already in progress
+            const secondFlush = client.flush();
+            await firstFlush;
+            await secondFlush;
+            // First flush sent 1 event, second was skipped
+            // evt-2 should still be in the queue
+            expect(client.getQueue()).toHaveLength(1);
+            expect(client.getQueue()[0].id).toBe('evt-2');
+        });
+    });
+    // -------------------------------------------------------------------------
+    // 4xx error handling (drop batch)
+    // -------------------------------------------------------------------------
+    describe('4xx error handling', () => {
+        it('should drop batch on 4xx client errors (not 429)', async () => {
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const client = createClient({ flushAt: 100, maxRetries: 0 });
+            client.mockResponse = {
+                status: 401,
+                statusText: 'Unauthorized',
+                ok: false,
+                json: async () => ({}),
+                text: async () => 'Invalid API key',
+            };
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            // 4xx errors drop the batch, not re-queue
+            expect(client.getQueue()).toHaveLength(0);
+            consoleSpy.mockRestore();
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Disabled client: score and flush
+    // -------------------------------------------------------------------------
+    describe('disabled client edge cases', () => {
+        it('should not enqueue scores when disabled', () => {
+            const client = createClient({ enabled: false });
+            client.score({ traceId: 'trace-1', name: 'test', value: 1 });
+            expect(client.getQueue()).toHaveLength(0);
+        });
+        it('should not send on flush when disabled', async () => {
+            const client = createClient({ enabled: false });
+            await client.flush();
+            expect(client.fetchCalls).toHaveLength(0);
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Flush error handling
+    // -------------------------------------------------------------------------
+    describe('flush error handling', () => {
+        it('should re-queue events when fetch throws an error', async () => {
+            const client = createClient({ flushAt: 100, maxRetries: 0 });
+            // Make fetch throw
+            client.mockResponse = {
+                status: 500,
+                statusText: 'Internal Server Error',
+                ok: false,
+                json: async () => ({}),
+                text: async () => 'server error',
+            };
+            // Suppress console.error from the logger
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            client.enqueue({
+                id: 'evt-1',
+                type: IngestionEventType.TRACE_CREATE,
+                timestamp: '2024-01-01T00:00:00.000Z',
+                body: { id: 'trace-1' },
+            });
+            await client.flush();
+            // Events should be re-queued after failure
+            expect(client.getQueue()).toHaveLength(1);
+            expect(client.getQueue()[0].id).toBe('evt-1');
+            consoleSpy.mockRestore();
+        });
+    });
+    // -------------------------------------------------------------------------
+    // Standalone score
+    // -------------------------------------------------------------------------
+    describe('standalone score', () => {
+        it('should enqueue a score event via client.score()', async () => {
+            const client = createClient({ flushAt: 100 });
+            client.score({
+                traceId: 'trace-external',
+                name: 'user-feedback',
+                value: 5,
+                comment: 'Great response',
+            });
+            await client.flush();
+            const body = client.getLastRequestBody();
+            const score = body.batch.find((e) => e.type === 'score-create');
+            expect(score.body.traceId).toBe('trace-external');
+            expect(score.body.name).toBe('user-feedback');
+            expect(score.body.value).toBe(5);
+        });
+    });
+});
+//# sourceMappingURL=core-client.test.js.map