@goharvest/simforge 0.4.7 → 0.5.2

package/dist/client.test.js

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import * as baml from "./baml.js";
-import { Simforge, SimforgeError } from "./client";
+import { getCurrentSpan, Simforge } from "./client";
 // Mock fetch globally
 globalThis.fetch = vi.fn();
 // Mock BAML execution
@@ -16,9 +16,30 @@ describe("Simforge Client", () => {
             const client = new Simforge({ apiKey: "test-key" });
             expect(client).toBeInstanceOf(Simforge);
         });
-        it("should create client even with empty apiKey (validation happens at call time)", () => {
+        it("should auto-disable tracing with empty apiKey and log warning", () => {
+            const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
             const client = new Simforge({ apiKey: "" });
             expect(client).toBeInstanceOf(Simforge);
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("apiKey is empty"));
+            // Should behave as disabled — withSpan returns the original function
+            const fn = client.withSpan("test-key", () => "result");
+            expect(fn()).toBe("result");
+            warnSpy.mockRestore();
+        });
+        it("should auto-disable tracing with whitespace apiKey", () => {
+            const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+            const client = new Simforge({ apiKey: "   " });
+            const fn = client.withSpan("test-key", () => "result");
+            expect(fn()).toBe("result");
+            warnSpy.mockRestore();
+        });
+        it("should not warn when explicitly disabled with empty apiKey", () => {
+            const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+            const client = new Simforge({ apiKey: "", enabled: false });
+            expect(warnSpy).not.toHaveBeenCalled();
+            const fn = client.withSpan("test-key", () => "result");
+            expect(fn()).toBe("result");
+            warnSpy.mockRestore();
         });
         it("should use custom serviceUrl", () => {
             const client = new Simforge({
@@ -41,14 +62,7 @@ describe("Simforge Client", () => {
             });
             expect(client).toBeInstanceOf(Simforge);
         });
-        it("should accept executeLocally flag", () => {
-            const client = new Simforge({
-                apiKey: "test-key",
-                executeLocally: false,
-            });
-            expect(client).toBeInstanceOf(Simforge);
-        });
-        describe("call method - local execution", () => {
+        describe("call method", () => {
             beforeEach(() => {
                 // Reset BAML mock
                 vi.mocked(baml.runFunctionWithBaml).mockReset();
@@ -118,7 +132,6 @@ function ExtractName(text: string) -> Name {
                 });
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                     envVars: { OPENAI_API_KEY: "test-openai-key" },
                 });
                 const result = await client.call("ExtractName", {
@@ -151,7 +164,6 @@ function ExtractName(text: string) -> Name {
                 vi.mocked(baml.runFunctionWithBaml).mockRejectedValueOnce(new Error("Invalid argument: Expected type String, got Number(12345)"));
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                 });
                 await expect(
                 // biome-ignore lint/suspicious/noExplicitAny: Testing wrong type handling
@@ -175,7 +187,6 @@ function ExtractName(text: string) -> Name {
                 vi.mocked(baml.runFunctionWithBaml).mockRejectedValueOnce(new Error("Missing required parameter: text"));
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                 });
                 await expect(client.call("ExtractName", {})).rejects.toThrow("Missing required parameter");
             });
@@ -232,7 +243,6 @@ function ExtractPerson(text: string) -> Person {}
                 });
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                 });
                 const result = (await client.call("ExtractPerson", {
                     text: "John Doe, 30, john@example.com, 123 Main St, New York, 10001",
@@ -262,7 +272,6 @@ function ExtractPerson(text: string) -> Person {}
                 });
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                 });
                 await expect(client.call("ExtractName", { text: "test" })).rejects.toThrow("has no prompt");
             });
@@ -295,7 +304,6 @@ function ExtractPerson(text: string) -> Person {}
                 });
                 const client = new Simforge({
                     apiKey: "test-key",
-                    executeLocally: true,
                     envVars: {
                         OPENAI_API_KEY: "test-key",
                     },
@@ -309,50 +317,6 @@ function ExtractPerson(text: string) -> Person {}
             });
         });
     });
-    describe("call method - server-side execution", () => {
-        it("should make successful API call", async () => {
-            const mockResponse = "success";
-            globalThis.fetch.mockResolvedValueOnce({
-                ok: true,
-                json: async () => ({ result: mockResponse }),
-            });
-            const client = new Simforge({
-                apiKey: "test-key",
-                executeLocally: false,
-            });
-            const result = await client.call("testMethod", { input: "test" });
-            expect(result).toEqual(mockResponse);
-            expect(globalThis.fetch).toHaveBeenCalledWith(expect.stringContaining("/api/sdk/call"), expect.objectContaining({
-                method: "POST",
-                headers: expect.objectContaining({
-                    Authorization: "Bearer test-key",
-                    "Content-Type": "application/json",
-                }),
-            }));
-        });
-        it("should handle API errors", async () => {
-            ;
-            globalThis.fetch.mockResolvedValueOnce({
-                ok: false,
-                status: 400,
-                json: async () => ({ error: "Bad request" }),
-            });
-            const client = new Simforge({
-                apiKey: "test-key",
-                executeLocally: false,
-            });
-            await expect(client.call("testMethod", {})).rejects.toThrow(SimforgeError);
-        });
-        it("should handle network errors", async () => {
-            ;
-            globalThis.fetch.mockRejectedValueOnce(new Error("Network error"));
-            const client = new Simforge({
-                apiKey: "test-key",
-                executeLocally: false,
-            });
-            await expect(client.call("testMethod", {})).rejects.toThrow(SimforgeError);
-        });
-    });
     describe("trace creation with source field", () => {
         it("should include source='typescript-sdk' by default when creating traces", async () => {
             const mockFetch = vi.mocked(fetch);
@@ -387,7 +351,6 @@ function ExtractPerson(text: string) -> Person {}
             });
             const client = new Simforge({
                 apiKey: "test-key",
-                executeLocally: true,
             });
             await client.call("testMethod", {});
             // Verify trace creation was called with source field
@@ -440,7 +403,6 @@ function ExtractPerson(text: string) -> Person {}
             });
             const client = new Simforge({
                 apiKey: "test-key",
-                executeLocally: true,
             });
             await client.call("testMethod", {});
             // Verify trace creation includes both source and rawCollector
@@ -450,5 +412,838 @@ function ExtractPerson(text: string) -> Person {}
             expect(traceBody.rawCollector).toEqual(mockCollector);
         });
     });
+    describe("withSpan", () => {
+        it("should wrap an async function and trace its execution", async () => {
+            const mockFetch = vi.mocked(fetch);
+            // Mock wrapper trace creation
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-123" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const originalFn = async (name, count) => {
+                return { greeting: `Hello ${name}!`, count };
+            };
+            const wrappedFn = client.withSpan("greeting-service", originalFn);
+            const result = await wrappedFn("World", 42);
+            // Verify the function returns the correct result
+            expect(result).toEqual({ greeting: "Hello World!", count: 42 });
+            // Verify wrapper trace was created
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            expect(traceCall).toBeDefined();
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.traceFunctionKey).toBe("greeting-service");
+            expect(traceBody.source).toBe("typescript-sdk-function");
+            // Inputs and result are in externalSpan.span_data
+            expect(traceBody.rawSpan.span_data.input).toEqual(["World", 42]);
+            expect(traceBody.rawSpan.span_data.output).toEqual({
+                greeting: "Hello World!",
+                count: 42,
+            });
+            // No meta needed for basic types
+            expect(traceBody.rawSpan.span_data.input_meta).toBeUndefined();
+            expect(traceBody.rawSpan.span_data.output_meta).toBeUndefined();
+        });
+        it("should wrap a sync function and trace its execution", async () => {
+            const mockFetch = vi.mocked(fetch);
+            // Mock wrapper trace creation
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-456" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const originalFn = (a, b) => a + b;
+            const wrappedFn = client.withSpan("calculator", originalFn);
+            const result = wrappedFn(5, 3);
+            // Verify the function returns the correct result
+            expect(result).toBe(8);
+            // Wait for the background trace to be sent
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            // Verify wrapper trace was created
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            expect(traceCall).toBeDefined();
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.traceFunctionKey).toBe("calculator");
+            // Result is in externalSpan.span_data.output
+            expect(traceBody.rawSpan.span_data.output).toBe(8);
+        });
+        it("should preserve the original function's return type", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-789" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const getUser = async (id) => ({
+                id,
+                name: "Test User",
+            });
+            const wrappedGetUser = client.withSpan("user-service", getUser);
+            // TypeScript should know the return type is Promise<User>
+            const user = await wrappedGetUser("user-123");
+            expect(user.id).toBe("user-123");
+            expect(user.name).toBe("Test User");
+        });
+        it("should handle string results without double-serialization", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-str" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const getString = async () => "Hello, World!";
+            const wrappedFn = client.withSpan("string-service", getString);
+            const result = await wrappedFn();
+            expect(result).toBe("Hello, World!");
+            // Wait for trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Result is in externalSpan.span_data.output
+            expect(traceBody.rawSpan.span_data.output).toBe("Hello, World!");
+        });
+        it("should handle functions with no arguments", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-noargs" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const getTimestamp = async () => Date.now();
+            const wrappedFn = client.withSpan("timestamp-service", getTimestamp);
+            const result = await wrappedFn();
+            expect(typeof result).toBe("number");
+            // Wait for trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Empty array for no-arg functions
+            expect(traceBody.rawSpan.span_data.input).toEqual([]);
+        });
+        it("should include superjson meta for special types like Date", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "wrapper-trace-date" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const testDate = new Date("2024-01-15T10:30:00.000Z");
+            const getDateResult = async (inputDate) => ({
+                timestamp: inputDate,
+                formatted: inputDate.toISOString(),
+            });
+            const wrappedFn = client.withSpan("date-service", getDateResult);
+            const result = await wrappedFn(testDate);
+            expect(result.timestamp).toEqual(testDate);
+            // Wait for trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Result should have JSON data and meta for Date type
+            expect(traceBody.rawSpan.span_data.output.timestamp).toBe("2024-01-15T10:30:00.000Z");
+            expect(traceBody.rawSpan.span_data.output.formatted).toBe("2024-01-15T10:30:00.000Z");
+            expect(traceBody.rawSpan.span_data.output_meta).toBeDefined();
+            expect(traceBody.rawSpan.span_data.output_meta.values.timestamp).toEqual([
+                "Date",
+            ]);
+            // Inputs should also have meta for the Date argument (array format)
+            expect(traceBody.rawSpan.span_data.input[0]).toBe("2024-01-15T10:30:00.000Z");
+            expect(traceBody.rawSpan.span_data.input_meta).toBeDefined();
+            expect(traceBody.rawSpan.span_data.input_meta.values["0"]).toEqual([
+                "Date",
+            ]);
+        });
+        it("should not throw if trace creation fails", async () => {
+            const mockFetch = vi.mocked(fetch);
+            const consoleErrorSpy = vi
+                .spyOn(console, "error")
+                .mockImplementation(() => { });
+            // Mock trace creation to fail
+            mockFetch.mockRejectedValueOnce(new Error("Network error"));
+            const client = new Simforge({ apiKey: "test-key" });
+            const originalFn = async () => "success";
+            const wrappedFn = client.withSpan("failing-trace", originalFn);
+            // Function should still return normally
+            const result = await wrappedFn();
+            expect(result).toBe("success");
+            // Allow microtasks to run so the promise rejection can be caught
+            await new Promise((resolve) => queueMicrotask(resolve));
+            await new Promise((resolve) => queueMicrotask(resolve));
+            // Wait for console.error to be called - this ensures the .catch() handler has run
+            await vi.waitFor(() => {
+                expect(consoleErrorSpy).toHaveBeenCalledWith("Failed to create external span");
+            }, { timeout: 1000 });
+            consoleErrorSpy.mockRestore();
+        });
+        it("should share trace ID for nested withSpan calls", async () => {
+            const mockFetch = vi.mocked(fetch);
+            // Mock responses for both spans
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "shared-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const innerFn = async () => "inner result";
+            const outerFn = async () => {
+                const wrappedInner = client.withSpan("inner-span", innerFn);
+                return wrappedInner();
+            };
+            const wrappedOuter = client.withSpan("outer-span", outerFn);
+            await wrappedOuter();
+            // Wait for background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            // Get all span creation calls
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            expect(spanCalls.length).toBe(2);
+            const spanBodies = spanCalls.map((call) => JSON.parse(call[1].body));
+            // Both spans should share the same trace ID
+            const traceId = spanBodies[0].rawSpan.trace_id;
+            expect(spanBodies[1].rawSpan.trace_id).toBe(traceId);
+        });
+        it("should include parent_id for child spans", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "nested-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const innerFn = async () => "inner";
+            const outerFn = async () => {
+                const wrappedInner = client.withSpan("inner-span", innerFn);
+                return wrappedInner();
+            };
+            const wrappedOuter = client.withSpan("outer-span", outerFn);
+            await wrappedOuter();
+            // Wait for background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBodies = spanCalls.map((call) => JSON.parse(call[1].body));
+            // Find the inner and outer spans
+            const innerSpan = spanBodies.find((b) => b.traceFunctionKey === "inner-span");
+            const outerSpan = spanBodies.find((b) => b.traceFunctionKey === "outer-span");
+            // Inner span should have parent_id pointing to outer span
+            expect(innerSpan.rawSpan.parent_id).toBe(outerSpan.rawSpan.id);
+            // Outer span (root) should not have parent_id
+            expect(outerSpan.rawSpan.parent_id).toBeUndefined();
+        });
+        it("should generate new trace ID for independent calls", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "independent-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn1 = async () => "result1";
+            const fn2 = async () => "result2";
+            const wrapped1 = client.withSpan("span-1", fn1);
+            const wrapped2 = client.withSpan("span-2", fn2);
+            await wrapped1();
+            await wrapped2();
+            // Wait for background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBodies = spanCalls.map((call) => JSON.parse(call[1].body));
+            // Each independent call should have a different trace ID
+            expect(spanBodies[0].rawSpan.trace_id).not.toBe(spanBodies[1].rawSpan.trace_id);
+        });
+        it("should include function name in span data", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "func-name-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function myNamedFunction(x) {
+                return x * 2;
+            }
+            const wrappedFn = client.withSpan("math-service", myNamedFunction);
+            await wrappedFn(5);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.rawSpan.span_data.function_name).toBe("myNamedFunction");
+        });
+        it("should handle anonymous functions without function name", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "anon-func-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const wrappedFn = client.withSpan("anon-service", async (x) => x * 2);
+            await wrappedFn(5);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Anonymous arrow functions don't have a name, so function_name should be undefined
+            expect(traceBody.rawSpan.span_data.function_name).toBeUndefined();
+        });
+        it("should use function name as span name when function has a name", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "named-span-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function processOrder(id) {
+                return `processed-${id}`;
+            }
+            const wrappedFn = client.withSpan("order-service", processOrder);
+            await wrappedFn("123");
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Span name should be the function name, not the trace function key
+            expect(traceBody.rawSpan.span_data.name).toBe("processOrder");
+            expect(traceBody.rawSpan.span_data.function_name).toBe("processOrder");
+        });
+        it("should fall back to trace function key as span name for anonymous functions", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "anon-span-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const wrappedFn = client.withSpan("anonymous-service", async (x) => x * 2);
+            await wrappedFn(5);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Span name should fall back to trace function key for anonymous functions
+            expect(traceBody.rawSpan.span_data.name).toBe("anonymous-service");
+            expect(traceBody.rawSpan.span_data.function_name).toBeUndefined();
+        });
+        it("should use explicit name option over function name", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "explicit-name-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function myFunction(id) {
+                return `result-${id}`;
+            }
+            const wrappedFn = client.withSpan("my-service", { name: "CustomSpanName" }, myFunction);
+            await wrappedFn("123");
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Span name should be the explicit name, not the function name
+            expect(traceBody.rawSpan.span_data.name).toBe("CustomSpanName");
+            // function_name should still be the actual function name
+            expect(traceBody.rawSpan.span_data.function_name).toBe("myFunction");
+        });
+        it("should use explicit name option for anonymous functions", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "anon-explicit-name-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const wrappedFn = client.withSpan("anon-service", { name: "AnonymousHandler" }, async (x) => x * 2);
+            await wrappedFn(5);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            // Span name should be the explicit name
+            expect(traceBody.rawSpan.span_data.name).toBe("AnonymousHandler");
+            // No function_name for anonymous functions
+            expect(traceBody.rawSpan.span_data.function_name).toBeUndefined();
+        });
+        it("should still send span on error", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "error-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const failingFn = async () => {
+                throw new Error("Test error");
+            };
+            const wrappedFn = client.withSpan("failing-fn", failingFn);
+            await expect(wrappedFn()).rejects.toThrow("Test error");
+            // Wait for background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            expect(spanCalls.length).toBe(1);
+            const spanBody = JSON.parse(spanCalls[0][1].body);
+            expect(spanBody.rawSpan.span_data.error).toBe("Test error");
+        });
+        it("should default type to 'custom' when no options provided", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "default-type-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = async () => "result";
+            const wrappedFn = client.withSpan("test-service", fn);
+            await wrappedFn();
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.rawSpan.span_data.type).toBe("custom");
+        });
+        it("should use provided type from options", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "function-type-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = async () => "result";
+            const wrappedFn = client.withSpan("tool-service", { type: "function" }, fn);
+            await wrappedFn();
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.rawSpan.span_data.type).toBe("function");
+        });
+        it("should support all span types", async () => {
+            const mockFetch = vi.mocked(fetch);
+            const client = new Simforge({ apiKey: "test-key" });
+            const spanTypes = [
+                "llm",
+                "agent",
+                "function",
+                "guardrail",
+                "handoff",
+                "custom",
+            ];
+            for (const spanType of spanTypes) {
+                mockFetch.mockClear();
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    status: 200,
+                    json: async () => ({ traceId: `${spanType}-trace` }),
+                });
+                const fn = async () => spanType;
+                const wrappedFn = client.withSpan(`${spanType}-service`, { type: spanType }, fn);
+                await wrappedFn();
+                // Wait for background trace
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+                const traceBody = JSON.parse(traceCall[1].body);
+                expect(traceBody.rawSpan.span_data.type).toBe(spanType);
+            }
+        });
+        it("should work with type option and sync functions", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "sync-type-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = (a, b) => a + b;
+            const wrappedFn = client.withSpan("calculator", { type: "function" }, fn);
+            const result = wrappedFn(5, 3);
+            expect(result).toBe(8);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const traceCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const traceBody = JSON.parse(traceCall[1].body);
+            expect(traceBody.rawSpan.span_data.type).toBe("function");
+            expect(traceBody.rawSpan.span_data.input).toEqual([5, 3]);
+            expect(traceBody.rawSpan.span_data.output).toBe(8);
+        });
+    });
+    describe("enabled option", () => {
+        it("should default enabled to true", () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "enabled-default-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = async () => "result";
+            const wrappedFn = client.withSpan("test-service", fn);
+            // If enabled defaults to true, the wrapped function should send spans
+            // We can verify by checking that it's not the same reference as the original
+            expect(wrappedFn).not.toBe(fn);
+        });
+        it("should return unwrapped function when enabled is false", () => {
+            const client = new Simforge({ apiKey: "test-key", enabled: false });
+            const fn = async () => "result";
+            const wrappedFn = client.withSpan("test-service", fn);
+            // When disabled, withSpan should return the original function
+            expect(wrappedFn).toBe(fn);
+        });
+        it("should not send spans when enabled is false", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockClear();
+            const client = new Simforge({ apiKey: "test-key", enabled: false });
+            const fn = async (x) => x * 2;
+            const wrappedFn = client.withSpan("test-service", fn);
+            const result = await wrappedFn(5);
+            expect(result).toBe(10);
+            // Wait for any potential background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            // No fetch calls should have been made
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            expect(spanCalls.length).toBe(0);
+        });
+        it("should return unwrapped function via getFunction when enabled is false", () => {
+            const client = new Simforge({ apiKey: "test-key", enabled: false });
+            const func = client.getFunction("my-function");
+            const fn = async () => "result";
+            const wrappedFn = func.withSpan(fn);
+            // When disabled, should return the original function
+            expect(wrappedFn).toBe(fn);
+        });
+        it("should return unwrapped function with options when enabled is false", () => {
+            const client = new Simforge({ apiKey: "test-key", enabled: false });
+            const fn = async () => "result";
+            const wrappedFn = client.withSpan("test-service", { type: "function" }, fn);
+            expect(wrappedFn).toBe(fn);
+        });
+    });
+    describe("metadata", () => {
+        it("metadata is included in span_data when provided", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "metadata-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function processOrder(id) {
+                return { id };
+            }
+            const wrapped = client.withSpan("my-service", {
+                type: "function",
+                metadata: { user_id: "u-123", region: "us-east" },
+            }, processOrder);
+            await wrapped("123");
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toEqual({ user_id: "u-123", region: "us-east" });
+        });
+        it("metadata is omitted from span_data when not provided", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "no-metadata-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function myFn() {
+                return "result";
+            }
+            const wrapped = client.withSpan("my-service", myFn);
+            await wrapped();
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toBeUndefined();
+        });
+        it("metadata works with getFunction fluent API", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "fluent-metadata-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const service = client.getFunction("order-processing");
+            async function processOrder(id) {
+                return { id };
+            }
+            const wrapped = service.withSpan({
+                type: "function",
+                metadata: { env: "staging", version: "1.2.3" },
+            }, processOrder);
+            await wrapped("123");
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toEqual({ env: "staging", version: "1.2.3" });
+        });
+    });
+    describe("runtime metadata (getCurrentSpan)", () => {
+        it("sets metadata at runtime from inside a span", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "runtime-meta-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function processOrder(id) {
+                getCurrentSpan()?.setMetadata({
+                    request_id: "req-789",
+                    user_id: "u-456",
+                });
+                return { id };
+            }
+            const wrapped = client.withSpan("my-service", { type: "function" }, processOrder);
+            await wrapped("123");
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toEqual({
+                request_id: "req-789",
+                user_id: "u-456",
+            });
+        });
+        it("merges runtime metadata with definition-time metadata (runtime wins)", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "merge-meta-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            async function processOrder(id) {
+                getCurrentSpan()?.setMetadata({
+                    region: "eu-west",
+                    request_id: "req-789",
+                });
+                return { id };
+            }
+            const wrapped = client.withSpan("my-service", { type: "function", metadata: { user_id: "u-123", region: "us-east" } }, processOrder);
+            await wrapped("123");
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toEqual({
+                user_id: "u-123",
+                region: "eu-west",
+                request_id: "req-789",
+            });
+        });
+        it("getCurrentSpan returns null outside of a span", () => {
+            expect(getCurrentSpan()).toBeNull();
+        });
+        it("works with getFunction fluent API", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "fluent-runtime-meta" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const service = client.getFunction("order-processing");
+            async function processOrder(id) {
+                getCurrentSpan()?.setMetadata({ computed_at: "2024-01-01" });
+                return { id };
+            }
+            const wrapped = service.withSpan({ type: "function" }, processOrder);
+            await wrapped("123");
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            const spanCall = mockFetch.mock.calls.find((c) => String(c[0]).includes("/sdk/externalSpans"));
+            expect(spanCall).toBeDefined();
+            const traceBody = JSON.parse(spanCall[1]?.body ?? "{}");
+            const spanData = traceBody.rawSpan
+                .span_data;
+            expect(spanData.metadata).toEqual({ computed_at: "2024-01-01" });
+        });
+    });
+    describe("error resilience", () => {
+        it("should not crash the host app when span sending throws synchronously", async () => {
+            const mockFetch = vi.mocked(fetch);
+            // Make fetch throw synchronously (simulating serialization failure)
+            mockFetch.mockImplementation(() => {
+                throw new Error("Serialization error");
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = async (x) => x * 2;
+            const wrappedFn = client.withSpan("resilient-service", fn);
+            // Function should still return normally
+            const result = await wrappedFn(5);
+            expect(result).toBe(10);
+        });
+        it("should propagate user errors even when SDK has internal errors", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockImplementation(() => {
+                throw new Error("SDK internal error");
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const failingFn = async () => {
+                throw new Error("User error");
+            };
+            const wrappedFn = client.withSpan("error-service", failingFn);
+            await expect(wrappedFn()).rejects.toThrow("User error");
+        });
+        it("should not crash with sync functions when span sending throws", () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockImplementation(() => {
+                throw new Error("Serialization error");
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const fn = (a, b) => a + b;
+            const wrappedFn = client.withSpan("sync-resilient", fn);
+            const result = wrappedFn(5, 3);
+            expect(result).toBe(8);
+        });
+        it("should propagate user errors from sync functions even when SDK has internal errors", () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockImplementation(() => {
+                throw new Error("SDK internal error");
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const failingFn = () => {
+                throw new Error("Sync user error");
+            };
+            const wrappedFn = client.withSpan("sync-error-service", failingFn);
+            expect(() => wrappedFn()).toThrow("Sync user error");
+        });
+    });
+    describe("getFunction", () => {
+        it("should return a SimforgeFunction instance", () => {
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("my-function");
+            expect(func).toBeDefined();
+            expect(typeof func.withSpan).toBe("function");
+        });
+        it("should wrap functions with the bound traceFunctionKey", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "getfunc-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("bound-key");
+            const originalFn = async (x) => x * 2;
+            const wrappedFn = func.withSpan(originalFn);
+            const result = await wrappedFn(5);
+            expect(result).toBe(10);
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBody = JSON.parse(spanCall[1].body);
+            expect(spanBody.traceFunctionKey).toBe("bound-key");
+        });
+        it("should allow wrapping multiple functions with the same key", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "multi-trace" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("shared-key");
+            const fn1 = async () => "one";
+            const fn2 = async () => "two";
+            const wrapped1 = func.withSpan(fn1);
+            const wrapped2 = func.withSpan(fn2);
+            await wrapped1();
+            await wrapped2();
+            // Wait for background traces
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCalls = mockFetch.mock.calls.filter((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBodies = spanCalls.map((call) => JSON.parse(call[1].body));
+            // Both should have the same traceFunctionKey
+            expect(spanBodies[0].traceFunctionKey).toBe("shared-key");
+            expect(spanBodies[1].traceFunctionKey).toBe("shared-key");
+        });
+        it("should default type to 'custom' when no options provided via getFunction", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "func-default-type" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("default-type-key");
+            const originalFn = async () => "result";
+            const wrappedFn = func.withSpan(originalFn);
+            await wrappedFn();
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBody = JSON.parse(spanCall[1].body);
+            expect(spanBody.rawSpan.span_data.type).toBe("custom");
+        });
+        it("should use provided type from options via getFunction", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "func-agent-type" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("agent-key");
+            const originalFn = async () => "agent result";
+            const wrappedFn = func.withSpan({ type: "agent" }, originalFn);
+            await wrappedFn();
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBody = JSON.parse(spanCall[1].body);
+            expect(spanBody.rawSpan.span_data.type).toBe("agent");
+        });
+        it("should support guardrail type via getFunction", async () => {
+            const mockFetch = vi.mocked(fetch);
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({ traceId: "func-guardrail-type" }),
+            });
+            const client = new Simforge({ apiKey: "test-key" });
+            const func = client.getFunction("safety-check");
+            const checkContent = async (content) => ({
+                safe: true,
+                content,
+            });
+            const wrappedFn = func.withSpan({ type: "guardrail" }, checkContent);
+            const result = await wrappedFn("test content");
+            expect(result).toEqual({ safe: true, content: "test content" });
+            // Wait for background trace
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const spanCall = mockFetch.mock.calls.find((call) => call[0].toString().includes("/sdk/externalSpans"));
+            const spanBody = JSON.parse(spanCall[1].body);
+            expect(spanBody.rawSpan.span_data.type).toBe("guardrail");
+            expect(spanBody.rawSpan.span_data.input).toEqual(["test content"]);
+            expect(spanBody.rawSpan.span_data.output).toEqual({
+                safe: true,
+                content: "test content",
+            });
+        });
+    });
 });
 //# sourceMappingURL=client.test.js.map