@goharvest/simforge 0.4.7 → 0.5.2

package/dist/client.js

@@ -1,57 +1,93 @@
 /**
  * Simforge client for provider-based API calls.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { runFunctionWithBaml, } from "./baml.js";
-import { __version__, DEFAULT_SERVICE_URL } from "./constants.js";
+import { DEFAULT_SERVICE_URL } from "./constants.js";
+import { HttpClient, SimforgeError } from "./http.js";
+import { serializeValue } from "./serialize.js";
 import { SimforgeOpenAITracingProcessor } from "./tracing.js";
-// Global set to track pending trace creation promises
-// This prevents promises from being garbage collected before they complete
-const pendingTracePromises = new Set();
+// Zone.js property key for storing span stack
+const SPAN_STACK_KEY = "simforgeSpanStack";
 /**
- * Track a promise to prevent it from being garbage collected.
- * The promise will be removed from tracking when it completes (success or failure).
- * Useful for fire-and-forget operations that need to complete before process exit.
+ * Async context propagation for nested spans.
  *
- * @param promise - The promise to track
- * @returns The same promise (for chaining)
+ * Uses AsyncLocalStorage in Node.js (preferred) or Zone.js in browsers
+ * to track parent-child relationships across concurrent async operations.
  */
-function awaitOnExit(promise) {
-    pendingTracePromises.add(promise);
-    promise.finally(() => {
-        pendingTracePromises.delete(promise);
-    });
-    return promise;
+let asyncLocalStorage = null;
+// Try to use AsyncLocalStorage (Node.js)
+try {
+    asyncLocalStorage = new AsyncLocalStorage();
 }
-// Register beforeExit handler to wait for pending traces (Node.js only)
-// This ensures traces are sent before the process exits (for scripts)
-if (typeof process !== "undefined" &&
-    process.versions != null &&
-    process.versions.node != null) {
-    let isFlushing = false;
-    process.on("beforeExit", () => {
-        if (pendingTracePromises.size > 0 && !isFlushing) {
-            isFlushing = true;
-            // Wait for all pending traces to complete
-            // This keeps the event loop alive until promises resolve
-            Promise.allSettled(Array.from(pendingTracePromises).map((p) => p.catch(() => {
-                // Silently ignore individual trace failures
-            })))
-                .then(() => {
-                isFlushing = false;
-            })
-                .catch(() => {
-                isFlushing = false;
-            });
-        }
+catch {
+    // Not in Node.js - Zone.js will be used via globalThis.Zone if available
+    import("zone.js").catch(() => {
+        // zone.js not available, will fall back to no context tracking
     });
 }
-export class SimforgeError extends Error {
-    constructor(message, url) {
-        super(message);
-        this.url = url;
-        this.name = "SimforgeError";
+/**
+ * Get the current span stack from async context.
+ * Uses AsyncLocalStorage in Node.js, Zone.js in browsers.
+ */
+function getSpanStack() {
+    // Node.js: use AsyncLocalStorage
+    if (asyncLocalStorage) {
+        return asyncLocalStorage.getStore() ?? [];
     }
+    // Browser: use Zone.js
+    const zone = globalThis.Zone;
+    if (zone) {
+        return zone.current.get(SPAN_STACK_KEY) ?? [];
+    }
+    return [];
 }
+/**
+ * Run a function with a new span stack context.
+ * Uses AsyncLocalStorage in Node.js, Zone.js in browsers.
+ */
+function runWithSpanStack(stack, fn) {
+    // Node.js: use AsyncLocalStorage
+    if (asyncLocalStorage) {
+        return asyncLocalStorage.run(stack, fn);
+    }
+    // Browser: use Zone.js
+    const zone = globalThis.Zone;
+    if (zone) {
+        const childZone = zone.current.fork({
+            name: "simforgeSpan",
+            properties: { [SPAN_STACK_KEY]: stack },
+        });
+        return childZone.run(fn);
+    }
+    // Fallback (should not reach here if zone.js is loaded)
+    return fn();
+}
+/**
+ * Get a handle to the current active span.
+ *
+ * Call this from inside a traced function (wrapped with `withSpan`) to get
+ * a span handle that allows setting metadata at runtime.
+ *
+ * Returns `null` if called outside of a span context.
+ */
+export function getCurrentSpan() {
+    const stack = getSpanStack();
+    const current = stack[stack.length - 1];
+    if (!current) {
+        return null;
+    }
+    return {
+        setMetadata(metadata) {
+            if (typeof metadata !== "object" || metadata === null) {
+                return;
+            }
+            current.metadata = { ...current.metadata, ...metadata };
+        },
+    };
+}
+// Re-export SimforgeError for backwards compatibility
+export { SimforgeError };
 /**
  * Client for making provider-based API calls via BAML.
  */
@@ -66,7 +102,19 @@ export class Simforge {
         this.serviceUrl = config.serviceUrl ?? DEFAULT_SERVICE_URL;
         this.timeout = config.timeout ?? 120000;
         this.envVars = config.envVars ?? {};
-        this.executeLocally = config.executeLocally ?? true;
+        const enabled = config.enabled ?? true;
+        if (enabled && (!config.apiKey || config.apiKey.trim() === "")) {
+            console.warn("Simforge: apiKey is empty — tracing is disabled. Provide a valid API key to enable tracing.");
+            this.enabled = false;
+        }
+        else {
+            this.enabled = enabled;
+        }
+        this.httpClient = new HttpClient({
+            apiKey: this.apiKey,
+            serviceUrl: this.serviceUrl,
+            timeout: this.timeout,
+        });
     }
     /**
      * Fetch the function with its current version and BAML prompt from the server.
@@ -76,57 +124,16 @@ export class Simforge {
      * @throws {SimforgeError} If the function is not found or an error occurs
      */
     async fetchFunctionVersion(methodName) {
-        const url = `${this.serviceUrl}/api/sdk/functions/lookup`;
-        const payload = { name: methodName };
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        try {
-            const response = await fetch(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${this.apiKey}`,
-                },
-                body: JSON.stringify(payload),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new SimforgeError(`HTTP ${response.status}: ${errorText.slice(0, 500)}`);
-            }
-            const result = await response.json();
-            // Check if function was not found
-            if (result.id === null) {
-                throw new SimforgeError(`Function "${methodName}" not found. Create it at: ${this.serviceUrl}/functions`, "/functions");
-            }
-            // Check if function has no prompt
-            if (!result.prompt) {
-                throw new SimforgeError(`Function "${methodName}" has no prompt configured. Add one at: ${this.serviceUrl}/functions/${result.id}`, `/functions/${result.id}`);
-            }
-            // Check for errors in the response
-            if (result.error) {
-                if (result.url) {
-                    throw new SimforgeError(`${result.error} Configure it at: ${this.serviceUrl}${result.url}`, result.url);
-                }
-                throw new SimforgeError(result.error);
-            }
-            return result;
+        const result = await this.httpClient.lookupFunction(methodName);
+        // Check if function was not found
+        if (result.id === null) {
+            throw new SimforgeError(`Function "${methodName}" not found. Create it at: ${this.serviceUrl}/functions`, "/functions");
         }
-        catch (error) {
-            if (error instanceof SimforgeError) {
-                throw error;
-            }
-            if (error instanceof Error) {
-                if (error.name === "AbortError") {
-                    throw new SimforgeError(`Request timed out after ${this.timeout}ms`);
-                }
-                throw new SimforgeError(error.message);
-            }
-            throw new SimforgeError("Unknown error occurred");
-        }
-        finally {
-            clearTimeout(timeoutId);
+        // Check if function has no prompt
+        if (!result.prompt) {
+            throw new SimforgeError(`Function "${methodName}" has no prompt configured. Add one at: ${this.serviceUrl}/functions/${result.id}`, `/functions/${result.id}`);
         }
+        return result;
     }
     /**
      * Call a method with the given named arguments via BAML execution.
@@ -137,144 +144,32 @@ export class Simforge {
      * @throws {SimforgeError} If service_url is not set, or if an error occurs
      */
     async call(methodName, inputs = {}) {
-        // If executeLocally is true, fetch the BAML and execute it locally
-        if (this.executeLocally) {
-            try {
-                const functionVersion = await this.fetchFunctionVersion(methodName);
-                const executionResult = await runFunctionWithBaml(functionVersion.prompt, inputs, functionVersion.providers, this.envVars);
-                // Create trace for the local execution
-                const resultStr = typeof executionResult.result === "string"
-                    ? executionResult.result
-                    : JSON.stringify(executionResult.result);
-                // Create trace in background so user doesn't have to wait
-                // Track the promise to prevent garbage collection
-                void awaitOnExit(this.createTrace({
-                    functionId: functionVersion.id,
-                    result: resultStr,
-                    inputs: Object.keys(inputs).length > 0 ? inputs : undefined,
-                    rawCollector: executionResult.rawCollector,
-                })).catch(() => {
-                    console.error("Failed to create trace");
-                    // Silently ignore trace creation failures
-                });
-                return executionResult.result;
-            }
-            catch (error) {
-                if (error instanceof SimforgeError) {
-                    throw error;
-                }
-                if (error instanceof Error) {
-                    throw new SimforgeError(error.message);
-                }
-                throw new SimforgeError("Unknown error occurred during local execution");
-            }
-        }
-        // Otherwise, fall back to server-side execution
-        const url = `${this.serviceUrl}/api/sdk/call`;
-        const payload = {
-            name: methodName,
-            inputs,
-            sdkVersion: __version__,
-        };
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
         try {
-            const response = await fetch(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${this.apiKey}`,
-                },
-                body: JSON.stringify(payload),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new SimforgeError(`HTTP ${response.status}: ${errorText.slice(0, 500)}`);
-            }
-            const result = await response.json();
-            // Check for errors in the response
-            if (result.error) {
-                if (result.url) {
-                    throw new SimforgeError(`${result.error} Configure it at: ${this.serviceUrl}${result.url}`, result.url);
-                }
-                throw new SimforgeError(result.error);
-            }
-            return result.result;
-        }
-        catch (error) {
-            if (error instanceof SimforgeError) {
-                throw error;
-            }
-            if (error instanceof Error) {
-                if (error.name === "AbortError") {
-                    throw new SimforgeError(`Request timed out after ${this.timeout}ms`);
-                }
-                throw new SimforgeError(error.message);
-            }
-            throw new SimforgeError("Unknown error occurred");
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    }
-    /**
-     * Create a trace from a local execution result.
-     * Internal method to record traces when executing BAML locally.
-     */
-    async createTrace(params) {
-        const url = `${this.serviceUrl}/api/sdk/functions/${params.functionId}/traces`;
-        const payload = {
-            result: params.result,
-            source: params.source ?? "typescript-sdk",
-            sdkVersion: __version__,
-        };
-        if (params.inputs !== undefined) {
-            payload.inputs = params.inputs;
-        }
-        if (params.rawCollector !== undefined && params.rawCollector !== null) {
-            payload.rawCollector = params.rawCollector;
-        }
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 30000);
-        try {
-            const response = await fetch(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${this.apiKey}`,
-                },
-                body: JSON.stringify(payload),
-                signal: controller.signal,
+            const functionVersion = await this.fetchFunctionVersion(methodName);
+            const executionResult = await runFunctionWithBaml(functionVersion.prompt, inputs, functionVersion.providers, this.envVars);
+            // Create trace for the local execution
+            const resultStr = typeof executionResult.result === "string"
+                ? executionResult.result
+                : JSON.stringify(executionResult.result);
+            // Create trace in background so user doesn't have to wait
+            this.httpClient.sendInternalTrace(functionVersion.id, {
+                result: resultStr,
+                source: "typescript-sdk",
+                ...(Object.keys(inputs).length > 0 && { inputs }),
+                ...(executionResult.rawCollector != null && {
+                    rawCollector: executionResult.rawCollector,
+                }),
             });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new SimforgeError(`HTTP ${response.status}: ${errorText.slice(0, 500)}`);
-            }
-            const result = await response.json();
-            // Check for errors in the response
-            if (result.error) {
-                if (result.url) {
-                    throw new SimforgeError(`${result.error} Configure it at: ${this.serviceUrl}${result.url}`, result.url);
-                }
-                throw new SimforgeError(result.error);
-            }
-            return result;
+            return executionResult.result;
         }
         catch (error) {
             if (error instanceof SimforgeError) {
                 throw error;
             }
             if (error instanceof Error) {
-                if (error.name === "AbortError") {
-                    throw new SimforgeError("Request timed out after 30000ms");
-                }
                 throw new SimforgeError(error.message);
             }
-            throw new SimforgeError("Unknown error occurred");
-        }
-        finally {
-            clearTimeout(timeoutId);
+            throw new SimforgeError("Unknown error occurred during local execution");
         }
     }
     /**
@@ -300,5 +195,233 @@ export class Simforge {
             serviceUrl: this.serviceUrl,
         });
     }
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Simforge in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Simforge({ apiKey: 'your-api-key' });
+     *
+     * async function processOrder(orderId: string, items: string[]): Promise<{ total: number }> {
+     *   // ... process order
+     *   return { total: 100 };
+     * }
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = client.withSpan('order-processing', processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = client.withSpan('order-processing', { type: 'function' }, processOrder);
+     *
+     * // Call the wrapped function normally
+     * const result = await tracedProcessOrder('order-123', ['item-1', 'item-2']);
+     * // Span is automatically sent to Simforge
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans (e.g., 'order-processing', 'user-auth')
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans for inputs and outputs
+     */
+    withSpan(traceFunctionKey, optionsOrFn, maybeFn) {
+        if (!this.enabled) {
+            const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+            return fn;
+        }
+        // Handle overloaded signature
+        const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+        const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+        const self = this;
+        return function (...args) {
+            // Get current span stack to determine trace context
+            const currentStack = getSpanStack();
+            const parentContext = currentStack[currentStack.length - 1];
+            // Generate trace ID (new if root, inherit if nested)
+            const traceId = parentContext?.traceId ?? crypto.randomUUID();
+            const spanId = crypto.randomUUID();
+            const parentSpanId = parentContext?.spanId ?? null;
+            // Create new context for this span
+            const newContext = { traceId, spanId };
+            const newStack = [...currentStack, newContext];
+            // Capture inputs and start time
+            const inputs = args;
+            const startedAt = new Date().toISOString();
+            // Shared span parameters
+            const functionName = fn.name !== "" ? fn.name : undefined;
+            const baseSpanParams = {
+                traceFunctionKey,
+                functionName,
+                spanName: options.name ?? functionName ?? traceFunctionKey,
+                traceId,
+                spanId,
+                parentSpanId,
+                inputs,
+                startedAt,
+                spanType: options.type ?? "custom",
+                metadata: options.metadata,
+            };
+            // Helper to send span in background (fire-and-forget).
+            // Wrapped in try/catch so span errors never crash the host app.
+            const sendSpan = (params) => {
+                try {
+                    // Merge runtime metadata (from setSpanMetadata) with definition-time metadata
+                    const runtimeMetadata = newContext.metadata;
+                    const mergedMetadata = runtimeMetadata
+                        ? { ...options.metadata, ...runtimeMetadata }
+                        : options.metadata;
+                    self.sendWrapperSpan({
+                        ...baseSpanParams,
+                        ...params,
+                        metadata: mergedMetadata,
+                        endedAt: new Date().toISOString(),
+                    });
+                }
+                catch {
+                    // Silently ignore — user's result/exception takes priority
+                }
+            };
+            // Execute function within new span context
+            const executeWithContext = () => {
+                const result = fn(...args);
+                // Check if result is a Promise (async function)
+                if (result instanceof Promise) {
+                    return result
+                        .then((resolvedResult) => {
+                        sendSpan({ result: resolvedResult });
+                        return resolvedResult;
+                    })
+                        .catch((error) => {
+                        sendSpan({
+                            result: undefined,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        throw error;
+                    });
+                }
+                // Sync function - create span in background
+                sendSpan({ result });
+                return result;
+            };
+            return runWithSpanStack(newStack, executeWithContext);
+        };
+    }
+    /**
+     * Get a function wrapper for a specific trace function key.
+     *
+     * This provides a fluent API alternative to calling withSpan directly,
+     * allowing you to bind the traceFunctionKey once and wrap multiple functions.
+     *
+     * Example usage:
+     * ```typescript
+     * const client = new Simforge({ apiKey: 'your-api-key' });
+     *
+     * const orderFunc = client.getFunction('order-processing');
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+     * ```
+     *
+     * @param traceFunctionKey - A string identifier for grouping spans
+     * @returns A SimforgeFunction instance for wrapping functions
+     */
+    getFunction(traceFunctionKey) {
+        return new SimforgeFunction(this, traceFunctionKey);
+    }
+    /**
+     * Send a wrapper span from function execution.
+     * Internal method to record spans when using withSpan.
+     * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+     */
+    sendWrapperSpan(params) {
+        // Serialize inputs and result with superjson for type preservation
+        const serializedInputs = serializeValue(params.inputs);
+        const serializedResult = serializeValue(params.result);
+        // Format as an external span with the wrapper format
+        const externalSpan = {
+            id: params.spanId,
+            trace_id: params.traceId,
+            started_at: params.startedAt,
+            ended_at: params.endedAt,
+            span_data: {
+                name: params.spanName,
+                type: params.spanType,
+                input: serializedInputs.json,
+                output: serializedResult.json,
+                // Include superjson meta for type preservation
+                ...(serializedInputs.meta !== undefined && {
+                    input_meta: serializedInputs.meta,
+                }),
+                ...(serializedResult.meta !== undefined && {
+                    output_meta: serializedResult.meta,
+                }),
+                ...(params.functionName !== undefined && {
+                    function_name: params.functionName,
+                }),
+                ...(params.error !== undefined && { error: params.error }),
+                ...(params.metadata !== undefined && { metadata: params.metadata }),
+            },
+        };
+        // Add parent_id for nested spans
+        if (params.parentSpanId) {
+            externalSpan.parent_id = params.parentSpanId;
+        }
+        this.httpClient.sendExternalSpan({
+            type: "sdk-function",
+            source: "typescript-sdk-function",
+            sourceTraceId: params.traceId,
+            traceFunctionKey: params.traceFunctionKey,
+            rawSpan: externalSpan,
+        });
+    }
+}
+/**
+ * Represents a Simforge function that can wrap user functions for tracing.
+ *
+ * This provides a fluent API for binding a traceFunctionKey once and
+ * then wrapping multiple functions with that key.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new Simforge({ apiKey: 'your-api-key' });
+ *
+ * const orderFunc = client.getFunction('order-processing');
+ * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+ * const tracedValidateOrder = orderFunc.withSpan(validateOrder);
+ * ```
+ */
+export class SimforgeFunction {
+    constructor(client, traceFunctionKey) {
+        this.client = client;
+        this.traceFunctionKey = traceFunctionKey;
+    }
+    /**
+     * Wrap a function to automatically create a span for its inputs and outputs.
+     *
+     * The wrapped function behaves identically to the original, but sends
+     * span data to Simforge in the background after each call.
+     *
+     * Example usage:
+     * ```typescript
+     * const orderFunc = client.getFunction('order-processing');
+     *
+     * // Basic usage (defaults to "custom" span type)
+     * const tracedProcessOrder = orderFunc.withSpan(processOrder);
+     *
+     * // With explicit span type
+     * const tracedProcessOrder = orderFunc.withSpan({ type: 'function' }, processOrder);
+     * ```
+     *
+     * @param optionsOrFn - Either SpanOptions or the function to wrap
+     * @param maybeFn - The function to wrap if options were provided
+     * @returns A wrapped function with the same signature that creates spans
+     */
+    withSpan(optionsOrFn, maybeFn) {
+        // Handle overloaded signature
+        const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+        const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+        return this.client.withSpan(this.traceFunctionKey, options, fn);
+    }
 }
 //# sourceMappingURL=client.js.map