@prefactor/sdk 0.1.2 → 0.1.4

package/dist/tracing/tracer.d.ts

@@ -1,100 +0,0 @@
-import { type Partition } from '@prefactor/pfid';
-import type { Transport } from '../transport/base.js';
-import type { Span, SpanType, TokenUsage } from './span.js';
-/**
- * Options for starting a new span
- */
-export interface StartSpanOptions {
-    /** Name of the span */
-    name: string;
-    /** Type of operation this span represents */
-    spanType: SpanType;
-    /** Input data for this operation */
-    inputs: Record<string, unknown>;
-    /** ID of the parent span (optional) */
-    parentSpanId?: string;
-    /** Trace ID to use (optional, will generate if not provided) */
-    traceId?: string;
-    /** Additional metadata (optional) */
-    metadata?: Record<string, unknown>;
-    /** Tags for categorizing the span (optional) */
-    tags?: string[];
-}
-/**
- * Options for ending a span
- */
-export interface EndSpanOptions {
-    /** Output data from the operation */
-    outputs?: Record<string, unknown>;
-    /** Error that occurred (if any) */
-    error?: Error;
-    /** Token usage information (for LLM calls) */
-    tokenUsage?: TokenUsage;
-}
-/**
- * Tracer manages the lifecycle of spans.
- *
- * The tracer is responsible for:
- * - Creating spans with unique IDs
- * - Managing span lifecycle (start/end)
- * - Delegating to the transport layer for span emission
- * - Handling agent instance lifecycle
- *
- * @example
- * ```typescript
- * const tracer = new Tracer(transport);
- *
- * const span = tracer.startSpan({
- *   name: 'llm-call',
- *   spanType: SpanType.LLM,
- *   inputs: { prompt: 'Hello' }
- * });
- *
- * try {
- *   // ... do work ...
- *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
- * } catch (error) {
- *   tracer.endSpan(span, { error });
- * }
- * ```
- */
-export declare class Tracer {
-    private transport;
-    private partition;
-    /**
-     * Initialize the tracer.
-     *
-     * @param transport - The transport to use for emitting spans
-     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
-     */
-    constructor(transport: Transport, partition?: Partition);
-    /**
-     * Start a new span
-     *
-     * @param options - Span configuration options
-     * @returns The created span
-     */
-    startSpan(options: StartSpanOptions): Span;
-    /**
-     * End a span and emit it to the transport
-     *
-     * @param span - The span to end
-     * @param options - End span options (outputs, error, token usage)
-     */
-    endSpan(span: Span, options?: EndSpanOptions): void;
-    /**
-     * Signal the start of an agent instance execution
-     */
-    startAgentInstance(): void;
-    /**
-     * Signal the completion of an agent instance execution
-     */
-    finishAgentInstance(): void;
-    /**
-     * Close the tracer and flush any pending spans
-     *
-     * @returns Promise that resolves when the tracer is closed
-     */
-    close(): Promise<void>;
-}
-//# sourceMappingURL=tracer.d.ts.map

package/dist/tracing/tracer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,mCAAmC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IASL,OAAO,CAAC,SAAS;IAR7B,OAAO,CAAC,SAAS,CAAY;IAE7B;;;;;OAKG;gBACiB,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,SAAS;IAI/D;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAkC1C;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IA6BnD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAQ1B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/tracing/tracer.js

@@ -1,151 +0,0 @@
-import { generate, generatePartition } from '@prefactor/pfid';
-import { SpanStatus } from './span.js';
-/**
- * Tracer manages the lifecycle of spans.
- *
- * The tracer is responsible for:
- * - Creating spans with unique IDs
- * - Managing span lifecycle (start/end)
- * - Delegating to the transport layer for span emission
- * - Handling agent instance lifecycle
- *
- * @example
- * ```typescript
- * const tracer = new Tracer(transport);
- *
- * const span = tracer.startSpan({
- *   name: 'llm-call',
- *   spanType: SpanType.LLM,
- *   inputs: { prompt: 'Hello' }
- * });
- *
- * try {
- *   // ... do work ...
- *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
- * } catch (error) {
- *   tracer.endSpan(span, { error });
- * }
- * ```
- */
-export class Tracer {
-    transport;
-    partition;
-    /**
-     * Initialize the tracer.
-     *
-     * @param transport - The transport to use for emitting spans
-     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
-     */
-    constructor(transport, partition) {
-        this.transport = transport;
-        this.partition = partition ?? generatePartition();
-    }
-    /**
-     * Start a new span
-     *
-     * @param options - Span configuration options
-     * @returns The created span
-     */
-    startSpan(options) {
-        const spanId = generate(this.partition);
-        const traceId = options.traceId ?? generate(this.partition);
-        const span = {
-            spanId,
-            parentSpanId: options.parentSpanId ?? null,
-            traceId,
-            name: options.name,
-            spanType: options.spanType,
-            startTime: Date.now(),
-            endTime: null,
-            status: SpanStatus.RUNNING,
-            inputs: options.inputs,
-            outputs: null,
-            tokenUsage: null,
-            error: null,
-            metadata: options.metadata ?? {},
-            tags: options.tags ?? [],
-        };
-        // AGENT spans are emitted immediately for real-time tracking
-        // They will be finished later with finishSpan()
-        if (options.spanType === 'agent') {
-            try {
-                this.transport.emit(span);
-            }
-            catch (error) {
-                console.error('Failed to emit agent span:', error);
-            }
-        }
-        return span;
-    }
-    /**
-     * End a span and emit it to the transport
-     *
-     * @param span - The span to end
-     * @param options - End span options (outputs, error, token usage)
-     */
-    endSpan(span, options) {
-        span.endTime = Date.now();
-        span.outputs = options?.outputs ?? null;
-        span.tokenUsage = options?.tokenUsage ?? null;
-        if (options?.error) {
-            span.status = SpanStatus.ERROR;
-            span.error = {
-                errorType: options.error.constructor.name,
-                message: options.error.message,
-                stacktrace: options.error.stack ?? '',
-            };
-        }
-        else {
-            span.status = SpanStatus.SUCCESS;
-        }
-        try {
-            // AGENT spans use finishSpan API (they were already emitted on start)
-            // Other span types are emitted here
-            if (span.spanType === 'agent') {
-                this.transport.finishSpan(span.spanId, span.endTime);
-            }
-            else {
-                this.transport.emit(span);
-            }
-        }
-        catch (error) {
-            console.error('Failed to emit/finish span:', error);
-        }
-    }
-    /**
-     * Signal the start of an agent instance execution
-     */
-    startAgentInstance() {
-        try {
-            this.transport.startAgentInstance();
-        }
-        catch (error) {
-            console.error('Failed to start agent instance:', error);
-        }
-    }
-    /**
-     * Signal the completion of an agent instance execution
-     */
-    finishAgentInstance() {
-        try {
-            this.transport.finishAgentInstance();
-        }
-        catch (error) {
-            console.error('Failed to finish agent instance:', error);
-        }
-    }
-    /**
-     * Close the tracer and flush any pending spans
-     *
-     * @returns Promise that resolves when the tracer is closed
-     */
-    async close() {
-        try {
-            await this.transport.close();
-        }
-        catch (error) {
-            console.error('Failed to close transport:', error);
-        }
-    }
-}
-//# sourceMappingURL=tracer.js.map

package/dist/tracing/tracer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"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"}

package/dist/transport/base.d.ts

@@ -1,38 +0,0 @@
-import type { Span } from '../tracing/span.js';
-/**
- * Transport interface for emitting spans to different backends
- *
- * Transports are responsible for sending span data to a destination
- * (e.g., stdout, HTTP API). They implement the strategy pattern to allow
- * pluggable backends.
- */
-export interface Transport {
-    /**
-     * Emit a span to the transport destination
-     *
-     * @param span - The span to emit
-     */
-    emit(span: Span): void;
-    /**
-     * Finish a previously emitted span (for long-running spans like AGENT spans)
-     *
-     * @param spanId - ID of the span to finish
-     * @param endTime - End time in milliseconds since Unix epoch
-     */
-    finishSpan(spanId: string, endTime: number): void;
-    /**
-     * Signal the start of an agent instance execution
-     */
-    startAgentInstance(): void;
-    /**
-     * Signal the completion of an agent instance execution
-     */
-    finishAgentInstance(): void;
-    /**
-     * Close the transport and flush any pending data
-     *
-     * @returns Promise that resolves when the transport is fully closed
-     */
-    close(): void | Promise<void>;
-}
-//# sourceMappingURL=base.d.ts.map

package/dist/transport/base.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/transport/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,kBAAkB,IAAI,IAAI,CAAC;IAE3B;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAC;IAE5B;;;;OAIG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B"}

package/dist/transport/base.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=base.js.map

package/dist/transport/base.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/transport/base.ts"],"names":[],"mappings":""}

package/dist/transport/http.d.ts

@@ -1,90 +0,0 @@
-import type { Transport } from './base.js';
-import type { HttpTransportConfig } from '../config.js';
-import type { Span } from '../tracing/span.js';
-/**
- * HTTP transport sends spans to a remote API endpoint.
- *
- * Features:
- * - Queue-based async processing
- * - Exponential backoff retry logic
- * - Span ID mapping (SDK ID → backend ID)
- * - Agent instance lifecycle management
- * - Graceful shutdown with timeout
- *
- * @example
- * ```typescript
- * const transport = new HttpTransport({
- *   apiUrl: 'https://api.prefactor.ai',
- *   apiToken: process.env.PREFACTOR_API_TOKEN!,
- * });
- * ```
- */
-export declare class HttpTransport implements Transport {
-    private config;
-    private queue;
-    private processing;
-    private closed;
-    private agentInstanceId;
-    private spanIdMap;
-    constructor(config: HttpTransportConfig);
-    /**
-     * Emit a span (adds to queue for async processing)
-     *
-     * @param span - The span to emit
-     */
-    emit(span: Span): void;
-    /**
-     * Finish a previously emitted span (for AGENT spans)
-     *
-     * @param spanId - ID of the span to finish
-     * @param endTime - End time in milliseconds since Unix epoch
-     */
-    finishSpan(spanId: string, endTime: number): void;
-    /**
-     * Signal the start of an agent instance execution
-     */
-    startAgentInstance(): void;
-    /**
-     * Signal the completion of an agent instance execution
-     */
-    finishAgentInstance(): void;
-    /**
-     * Start background queue processing
-     */
-    private startProcessing;
-    /**
-     * Send a span to the API
-     */
-    private sendSpan;
-    /**
-     * Transform span to backend API format (snake_case)
-     */
-    private transformSpanToApiFormat;
-    /**
-     * Get default schema (v1.0.0) with span schemas for all supported types
-     */
-    private getDefaultSchema;
-    /**
-     * Ensure an agent instance is registered
-     */
-    private ensureAgentRegistered;
-    /**
-     * Start agent instance execution
-     */
-    private startAgentInstanceHttp;
-    /**
-     * Finish agent instance execution
-     */
-    private finishAgentInstanceHttp;
-    /**
-     * Finish a span via HTTP
-     */
-    private finishSpanHttp;
-    /**
-     * Close the transport and wait for queue to drain
-     *
-     * @returns Promise that resolves when transport is closed
-     */
-    close(): Promise<void>;
-}
-//# sourceMappingURL=http.d.ts.map

package/dist/transport/http.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transport/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAa/C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,YAAW,SAAS;IAOjC,OAAO,CAAC,MAAM;IAN1B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,SAAS,CAA6B;gBAE1B,MAAM,EAAE,mBAAmB;IAI/C;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAOtB;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQjD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAO1B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAO3B;;OAEG;YACW,eAAe;IAuC7B;;OAEG;YACW,QAAQ;IAmDtB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;OAEG;YACW,qBAAqB;IA6DnC;;OAEG;YACW,sBAAsB;IA6BpC;;OAEG;YACW,uBAAuB;IA2BrC;;OAEG;YACW,cAAc;IA4B5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAc7B"}