@goharvest/simforge 0.5.0 → 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
@@ -912,6 +874,264 @@ function ExtractPerson(text: string) -> Person {}
             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" });