@goharvest/simforge 0.4.7 → 0.5.2

package/dist/client.d.ts

@@ -2,7 +2,28 @@
  * Simforge client for provider-based API calls.
  */
 import { type AllowedEnvVars } from "./baml.js";
+import { SimforgeError } from "./http.js";
 import { SimforgeOpenAITracingProcessor } from "./tracing.js";
+/**
+ * A handle to the current active span, allowing runtime metadata to be set.
+ */
+export interface CurrentSpan {
+    /**
+     * Set custom metadata on this span. Merges with any existing metadata
+     * (both definition-time and previous runtime calls), with later values
+     * taking precedence on conflict.
+     */
+    setMetadata(metadata: Record<string, unknown>): void;
+}
+/**
+ * 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 declare function getCurrentSpan(): CurrentSpan | null;
 export interface SimforgeConfig {
     /** The API key for Simforge API authentication */
     apiKey: string;
@@ -12,19 +33,38 @@ export interface SimforgeConfig {
     timeout?: number;
     /** Environment variables for LLM provider API keys (only OPENAI_API_KEY is supported) */
     envVars?: AllowedEnvVars;
-    /** Whether to execute BAML locally on the client (default: true) */
-    executeLocally?: boolean;
-}
-export interface CallResponse<T = unknown> {
-    result?: T;
-    error?: string;
-    url?: string;
-    traceId?: string;
+    /** Whether the client is enabled. Defaults to true. When false, withSpan returns the original function unwrapped. */
+    enabled?: boolean;
 }
-export declare class SimforgeError extends Error {
-    readonly url?: string | undefined;
-    constructor(message: string, url?: string | undefined);
+/**
+ * Span types matching the backend enum.
+ * - llm: LLM API calls
+ * - agent: Autonomous orchestrators
+ * - function: Tool implementations
+ * - guardrail: Safety/validation checks
+ * - handoff: Agent-to-agent transfers
+ * - custom: Application-specific tracing (default)
+ */
+export type SpanType = "llm" | "agent" | "function" | "guardrail" | "handoff" | "custom";
+/**
+ * Options for configuring span behavior.
+ */
+export interface SpanOptions {
+    /**
+     * The name of the span. Defaults to the function name if available,
+     * otherwise falls back to the trace function key.
+     */
+    name?: string;
+    /**
+     * The type of span. Defaults to "custom" if not specified.
+     */
+    type?: SpanType;
+    /**
+     * Custom metadata to attach to the span. Stored as-is in span_data.
+     */
+    metadata?: Record<string, unknown>;
 }
+export { SimforgeError };
 /**
  * Client for making provider-based API calls via BAML.
  */
@@ -33,7 +73,8 @@ export declare class Simforge {
     private readonly serviceUrl;
     private readonly timeout;
     private readonly envVars;
-    private readonly executeLocally;
+    private readonly enabled;
+    private readonly httpClient;
     /**
      * Initialize the Simforge client.
      *
@@ -57,11 +98,6 @@ export declare class Simforge {
      * @throws {SimforgeError} If service_url is not set, or if an error occurs
      */
     call<T = unknown>(methodName: string, inputs?: Record<string, unknown>): Promise<T>;
-    /**
-     * Create a trace from a local execution result.
-     * Internal method to record traces when executing BAML locally.
-     */
-    private createTrace;
     /**
      * Get a tracing processor for OpenAI Agents SDK integration.
      *
@@ -80,5 +116,104 @@ export declare class Simforge {
      * @returns A SimforgeOpenAITracingProcessor instance configured for this client
      */
     getOpenAiTracingProcessor(): SimforgeOpenAITracingProcessor;
+    /**
+     * 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<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /**
+     * 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: string): SimforgeFunction;
+    /**
+     * Send a wrapper span from function execution.
+     * Internal method to record spans when using withSpan.
+     * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+     */
+    private sendWrapperSpan;
+}
+/**
+ * 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 declare class SimforgeFunction {
+    private readonly client;
+    private readonly traceFunctionKey;
+    constructor(client: Simforge, traceFunctionKey: string);
+    /**
+     * 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<TArgs extends unknown[], TReturn>(optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAA;AAoD7D,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yFAAyF;IACzF,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AA8BD,qBAAa,aAAc,SAAQ,KAAK;aAGpB,GAAG,CAAC,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,GAAG,CAAC,EAAE,MAAM,YAAA;CAK/B;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC;;;;OAIG;gBACS,MAAM,EAAE,cAAc;IAQlC;;;;;;OAMG;YACW,oBAAoB;IAyElC;;;;;;;OAOG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,CAAC,CAAC;IAuGb;;;OAGG;YACW,WAAW;IAqEzB;;;;;;;;;;;;;;;;OAgBG;IACH,yBAAyB;CAM1B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}