@goharvest/simforge 0.4.7 → 0.5.0

package/dist/client.d.ts

@@ -2,6 +2,7 @@
  * Simforge client for provider-based API calls.
  */
 import { type AllowedEnvVars } from "./baml.js";
+import { SimforgeError } from "./http.js";
 import { SimforgeOpenAITracingProcessor } from "./tracing.js";
 export interface SimforgeConfig {
     /** The API key for Simforge API authentication */
@@ -21,10 +22,31 @@ export interface CallResponse<T = unknown> {
     url?: string;
     traceId?: string;
 }
-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;
 }
+export { SimforgeError };
 /**
  * Client for making provider-based API calls via BAML.
  */
@@ -34,6 +56,7 @@ export declare class Simforge {
     private readonly timeout;
     private readonly envVars;
     private readonly executeLocally;
+    private readonly httpClient;
     /**
      * Initialize the Simforge client.
      *
@@ -57,11 +80,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 +98,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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"}