@raindrop-ai/ai-sdk 0.0.19-beta.4 → 0.0.20

package/dist/index-DGziajf_.d.mts

@@ -0,0 +1,601 @@
+type OtlpAnyValue = {
+    stringValue?: string;
+    intValue?: string;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+};
+type OtlpKeyValue = {
+    key: string;
+    value: OtlpAnyValue;
+};
+declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+type OtlpSpanStatus = {
+    code: (typeof SpanStatusCode)[keyof typeof SpanStatusCode] | number;
+    message?: string;
+};
+type OtlpSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtlpKeyValue[];
+    status?: OtlpSpanStatus;
+};
+type SpanIds = {
+    traceIdB64: string;
+    spanIdB64: string;
+    parentSpanIdB64?: string;
+};
+
+type Attachment$1 = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput$1 = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment$1[];
+    isPending?: boolean;
+    timestamp?: string;
+};
+type SignalInput = {
+    eventId: string;
+    name: string;
+    type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
+    sentiment?: "POSITIVE" | "NEGATIVE";
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+    attachmentId?: string;
+    comment?: string;
+    after?: string;
+};
+type EventShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    libraryName?: string;
+    libraryVersion?: string;
+    defaultEventName?: string;
+};
+declare class EventShipper$1 {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    private sdkName;
+    private prefix;
+    private defaultEventName;
+    private context;
+    private buffers;
+    private sticky;
+    private timers;
+    private inFlight;
+    constructor(opts: EventShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    patch(eventId: string, patch: Patch): Promise<void>;
+    finish(eventId: string, patch: {
+        output?: string;
+        model?: string;
+        properties?: Record<string, unknown>;
+        userId?: string;
+    }): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    trackSignal(signal: SignalInput): Promise<void>;
+    identify(users: IdentifyInput$1 | IdentifyInput$1[]): Promise<void>;
+    private flushOne;
+}
+
+type InternalSpan = {
+    ids: SpanIds;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    sdkName?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+};
+declare class TraceShipper$1 {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private debugSpans;
+    private sdkName;
+    private prefix;
+    private serviceName;
+    private serviceVersion;
+    private flushIntervalMs;
+    private maxBatchSize;
+    private maxQueueSize;
+    private queue;
+    private timer;
+    private inFlight;
+    constructor(opts: TraceShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    startSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    endSpan(span: InternalSpan, extra?: {
+        attributes?: InternalSpan["attributes"];
+        error?: unknown;
+        status?: OtlpSpanStatus;
+        endTimeUnixNano?: string;
+    }): void;
+    createSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type ParentSpanContext = {
+    traceIdB64: string;
+    spanIdB64: string;
+    eventId: string;
+};
+interface ContextSpan {
+    readonly traceIdB64: string;
+    readonly spanIdB64: string;
+    readonly eventId: string;
+    log?(data: Record<string, unknown>): void;
+}
+interface AsyncLocalStorageLike<T> {
+    getStore(): T | undefined;
+    run<R>(store: T, callback: () => R): R;
+    enterWith?(store: T): void;
+}
+declare abstract class ContextManager {
+    abstract getParentSpanIds(): ParentSpanContext | undefined;
+    abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
+    abstract getCurrentSpan(): ContextSpan | undefined;
+    abstract isReady(): boolean;
+}
+declare global {
+    var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
+    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
+}
+declare function getContextManager(): ContextManager;
+declare function currentSpan(): ContextSpan;
+declare function withCurrent<R>(span: ContextSpan, callback: () => R): R;
+
+declare class EventShipper extends EventShipper$1 {
+    constructor(opts: ConstructorParameters<typeof EventShipper$1>[0]);
+}
+
+declare class TraceShipper extends TraceShipper$1 {
+    constructor(opts: ConstructorParameters<typeof TraceShipper$1>[0]);
+}
+
+/**
+ * Raindrop TelemetryIntegration for AI SDK v7+
+ *
+ * Implements the AI SDK's TelemetryIntegration interface to capture traces and
+ * events natively, replacing the Proxy-based wrapping used for v4-v6.
+ *
+ * Modeled after the upstream OpenTelemetryIntegration but uses Raindrop's
+ * TraceShipper (OTLP/HTTP) + EventShipper instead of the OTel Tracer API.
+ */
+
+type Listener<T> = (event: T) => PromiseLike<void> | void;
+interface TelemetryIntegration {
+    onStart?: Listener<any>;
+    onStepStart?: Listener<any>;
+    onToolCallStart?: Listener<any>;
+    onToolCallFinish?: Listener<any>;
+    onChunk?: Listener<any>;
+    onStepFinish?: Listener<any>;
+    onEmbedStart?: Listener<any>;
+    onEmbedFinish?: Listener<any>;
+    onFinish?: Listener<any>;
+    onError?: Listener<any>;
+    executeTool?: <T>(params: {
+        callId: string;
+        toolCallId: string;
+        execute: () => PromiseLike<T>;
+    }) => PromiseLike<T>;
+}
+type RaindropTelemetryIntegrationOptions = {
+    traceShipper: TraceShipper;
+    eventShipper: EventShipper;
+    sendTraces?: boolean;
+    sendEvents?: boolean;
+    debug?: boolean;
+    context?: {
+        userId?: string;
+        eventId?: string;
+        eventName?: string;
+        convoId?: string;
+        properties?: Record<string, unknown>;
+    };
+};
+declare class RaindropTelemetryIntegration implements TelemetryIntegration {
+    private readonly traceShipper;
+    private readonly eventShipper;
+    private readonly sendTraces;
+    private readonly sendEvents;
+    private readonly debug;
+    private readonly defaultContext;
+    private readonly callStates;
+    constructor(opts: RaindropTelemetryIntegrationOptions);
+    private getState;
+    private cleanup;
+    private spanParentRef;
+    private extractRaindropMetadata;
+    /**
+     * Extract the user-facing input text from an onStart event.
+     * Mirrors the logic in the v4-v6 Proxy path (lastUserMessageTextFromArgs / extractInputFromArgs).
+     */
+    private extractInputText;
+    onStart: (event: any) => void;
+    onStepStart: (event: any) => void;
+    onToolCallStart: (event: any) => void;
+    onToolCallFinish: (event: any) => void;
+    onChunk: (event: any) => void;
+    onStepFinish: (event: any) => void;
+    onEmbedStart: (event: any) => void;
+    onEmbedFinish: (event: any) => void;
+    onFinish: (event: any) => void;
+    private finishGenerate;
+    private finishEmbed;
+    onError: (error: unknown) => void;
+    executeTool: <T>({ callId, toolCallId, execute, }: {
+        callId: string;
+        toolCallId: string;
+        execute: () => PromiseLike<T>;
+    }) => Promise<T>;
+}
+
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+
+declare function _resetWarnedMissingUserId(): void;
+
+/**
+ * Options for creating event metadata for call-time context override.
+ */
+type EventMetadataOptions = {
+    /** User identifier (overrides wrap-time userId) */
+    userId?: string;
+    /** Event identifier. If not provided, a unique ID is generated. */
+    eventId?: string;
+    /** Conversation identifier to group related events */
+    convoId?: string;
+    /** Custom event name (overrides wrap-time eventName) */
+    eventName?: string;
+    /** Additional properties to merge with wrap-time properties */
+    properties?: Record<string, unknown>;
+};
+/**
+ * Creates metadata for use with the AI SDK's `experimental_telemetry.metadata` option.
+ * This allows per-call context override when using the wrapped AI SDK.
+ *
+ * Call-time values override wrap-time defaults. Properties are merged (call-time wins on conflicts).
+ *
+ * @example
+ * ```typescript
+ * import { generateText } from "ai";
+ * import { createRaindropAISDK, eventMetadata } from "@raindrop-ai/ai-sdk";
+ *
+ * const raindrop = createRaindropAISDK({ writeKey: "..." });
+ * const { generateText } = raindrop.wrap(ai, {
+ *   context: { userId: "default-user" }  // wrap-time defaults
+ * });
+ *
+ * // Override context per-call
+ * const result = await generateText({
+ *   model: openai("gpt-4"),
+ *   prompt: "Hello!",
+ *   experimental_telemetry: {
+ *     isEnabled: true,
+ *     metadata: eventMetadata({
+ *       convoId: "convo-123",      // add convoId for this call
+ *       eventName: "custom-chat",  // override eventName
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function eventMetadata(options: EventMetadataOptions): Record<string, string>;
+type AISDKChatRequestMessageLike = {
+    id?: string;
+    role?: string;
+    [key: string]: unknown;
+};
+type AISDKChatRequestLike = {
+    id?: string;
+    messageId?: string;
+    trigger?: string;
+    messages?: AISDKChatRequestMessageLike[];
+    [key: string]: unknown;
+};
+/**
+ * Creates stable Raindrop metadata from an AI SDK UI chat request body.
+ *
+ * This is useful for `useChat` applications that require multiple server round-trips
+ * for a single user turn, e.g. when the model triggers client-side tools.
+ *
+ * The helper derives:
+ * - `convoId` from the AI SDK chat request `id`
+ * - `eventId` from the latest user message id in `messages`
+ *
+ * Reusing the same derived `eventId` across tool handoff round-trips allows the
+ * wrapper to patch one logical event instead of creating a new event per POST.
+ */
+declare function eventMetadataFromChatRequest(options: EventMetadataOptions & {
+    request: AISDKChatRequestLike;
+}): Record<string, string>;
+type AgentCallMetadata = ReturnType<typeof eventMetadata>;
+type NormalizeUnknownAgentOptions<T> = T extends {
+    options: infer CallOptions;
+} ? unknown extends CallOptions ? Omit<T, "options"> & {
+    options?: never;
+} : T : T;
+/**
+ * Wraps an agent instance type so `generate()` and `stream()` accept optional
+ * Raindrop call metadata while preserving original return types.
+ */
+type AgentWithMetadata<A> = A extends {
+    generate: (...args: infer GenerateArgs) => infer GenerateReturn;
+    stream: (...args: infer StreamArgs) => infer StreamReturn;
+} ? Omit<A, "generate" | "stream"> & {
+    generate(...args: GenerateArgs extends [infer Options, ...infer Rest] ? [NormalizeUnknownAgentOptions<Options> & {
+        metadata?: AgentCallMetadata;
+    }, ...Rest] : GenerateArgs): GenerateReturn;
+    stream(...args: StreamArgs extends [infer Options, ...infer Rest] ? [NormalizeUnknownAgentOptions<Options> & {
+        metadata?: AgentCallMetadata;
+    }, ...Rest] : StreamArgs): StreamReturn;
+} : A;
+type AgentConstructor = abstract new (...args: any[]) => any;
+type WrapAgentExport<T extends object, K extends PropertyKey> = K extends keyof T ? T[K] extends AgentConstructor ? Omit<T, K> & {
+    [P in K]: new (...args: ConstructorParameters<T[K]>) => AgentWithMetadata<InstanceType<T[K]>>;
+} : T : T;
+/**
+ * Structural wrapper type for AI SDK modules.
+ *
+ * Rewrites AI SDK agent constructor exports so their instance `generate()` and
+ * `stream()` methods accept Raindrop `metadata` while preserving original
+ * return types. Covers the current and deprecated public export names.
+ */
+type WrappedAISDK<T extends object> = WrapAgentExport<WrapAgentExport<WrapAgentExport<T, "ToolLoopAgent">, "Experimental_Agent">, "Agent">;
+/**
+ * Backward-compatible alias for wrapped AI SDK module types.
+ *
+ * This alias intentionally avoids referencing `import("ai")` to satisfy type
+ * resolution without requiring `ai` to be installed.
+ *
+ * Prefer `WrappedAISDK<typeof ai>` in app code when you have an `ai` import.
+ */
+type WrappedAI<T extends object = any> = WrappedAISDK<T>;
+type Attachment = {
+    attachment_id?: string;
+    name?: string;
+    value: string;
+    role: "input" | "output";
+} & ({
+    type: "code";
+    language?: string;
+} | {
+    type: "text" | "image" | "iframe";
+});
+type RaindropAISDKOptions = {
+    /**
+     * API write key. If omitted, telemetry shipping is disabled but `wrap()` is
+     * still available for a consistent integration surface.
+     */
+    writeKey?: string;
+    endpoint?: string;
+    traces?: {
+        enabled?: boolean;
+        flushIntervalMs?: number;
+        maxBatchSize?: number;
+        maxQueueSize?: number;
+        debug?: boolean;
+        debugSpans?: boolean;
+    };
+    events?: {
+        enabled?: boolean;
+        partialFlushMs?: number;
+        debug?: boolean;
+    };
+};
+type RaindropAISDKContext = {
+    userId?: string;
+    eventId?: string;
+    eventName?: string;
+    convoId?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment[];
+};
+
+type BuildEventPatch = {
+    eventName?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment[];
+};
+/**
+ * Message format passed to `buildEvent`.
+ *
+ * This is intentionally "AI SDK shaped" but loosely typed:
+ * - works across AI SDK versions
+ * - avoids requiring users to import AI SDK types
+ */
+type AISDKMessage = {
+    role: "system" | "user" | "assistant" | "tool" | string;
+    content: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Build or override the Raindrop Event payload from an AI SDK conversation transcript.
+ *
+ * The wrapper calls this twice:
+ * - early with the input messages (system/user)
+ * - at the end with appended response messages (assistant/tool, incl tool-call + tool-result parts)
+ */
+type EventBuilder = (messages: AISDKMessage[]) => void | BuildEventPatch;
+type SelfDiagnosticsSignalDefinition = {
+    /**
+     * Human-readable meaning of this signal.
+     * Used in the injected tool schema and stored in signal properties.
+     */
+    description: string;
+    /**
+     * Optional default sentiment for this signal key.
+     * This can help dashboards classify negative/positive programmatic signals.
+     */
+    sentiment?: "POSITIVE" | "NEGATIVE";
+};
+type SelfDiagnosticsSignalDefinitions = Record<string, SelfDiagnosticsSignalDefinition>;
+type SelfDiagnosticsOptions = {
+    /** Enable automatic injection of the self diagnostics tool. Default: false */
+    enabled?: boolean;
+    /**
+     * Signal keys and descriptions exposed to the model.
+     * Defaults to a built-in set when omitted.
+     */
+    signals?: SelfDiagnosticsSignalDefinitions;
+    /**
+     * Optional extra guidance for when the model should emit self diagnostics.
+     * The SDK still generates a full tool prompt from `signals`.
+     */
+    guidance?: string;
+    /**
+     * Optional tool name override for the injected self diagnostics tool.
+     * Defaults to "__raindrop_report".
+     */
+    toolName?: string;
+};
+type WrapAISDKOptions = {
+    context: RaindropAISDKContext | ((info: {
+        operation: string;
+        args: unknown;
+    }) => RaindropAISDKContext);
+    buildEvent?: EventBuilder;
+    autoAttachment?: boolean;
+    selfDiagnostics?: SelfDiagnosticsOptions;
+    send?: {
+        events?: boolean;
+        traces?: boolean;
+    };
+    /**
+     * Use the AI SDK's native TelemetryIntegration instead of Proxy-based wrapping.
+     * Requires AI SDK v7+. Throws on older versions.
+     *
+     * When enabled, `wrap()` registers a `RaindropTelemetryIntegration` globally
+     * and returns the original module instead of a Proxy.
+     *
+     * Default: false (uses Proxy wrapping for backward compatibility).
+     */
+    nativeTelemetry?: boolean;
+};
+type EventPatch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment[];
+    isPending?: boolean;
+    timestamp?: string;
+};
+type RaindropAISDKClient = {
+    wrap<T extends object>(aiSDK: T, options?: WrapAISDKOptions): WrappedAISDK<T>;
+    /**
+     * Create a TelemetryIntegration instance for direct registration with AI SDK v7+.
+     * Use with `registerTelemetryIntegration()` from the `ai` package.
+     */
+    createTelemetryIntegration(context?: RaindropTelemetryIntegrationOptions["context"]): RaindropTelemetryIntegration;
+    events: {
+        patch(eventId: string, patch: EventPatch): Promise<void>;
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+        finish(eventId: string, patch: {
+            output?: string;
+            model?: string;
+            properties?: Record<string, unknown>;
+        }): Promise<void>;
+    };
+    users: {
+        identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    };
+    signals: {
+        track(signal: {
+            eventId: string;
+            name: "thumbs_up" | "thumbs_down" | string;
+            type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
+            sentiment?: "POSITIVE" | "NEGATIVE";
+            timestamp?: string;
+            properties?: Record<string, unknown>;
+            attachmentId?: string;
+            comment?: string;
+            after?: string;
+        }): Promise<void>;
+    };
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
+
+export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, type EventBuilder as E, type IdentifyInput as I, type RaindropAISDKClient as R, type SelfDiagnosticsOptions as S, type WrapAISDKOptions as W, _resetWarnedMissingUserId as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type EventMetadataOptions as g, type RaindropAISDKContext as h, type RaindropAISDKOptions as i, RaindropTelemetryIntegration as j, type RaindropTelemetryIntegrationOptions as k, type SelfDiagnosticsSignalDefinition as l, type SelfDiagnosticsSignalDefinitions as m, type WrappedAI as n, type WrappedAISDK as o, createRaindropAISDK as p, currentSpan as q, eventMetadata as r, eventMetadataFromChatRequest as s, getContextManager as t, withCurrent as w };