@raindrop-ai/ai-sdk 0.0.27 → 0.0.29

package/dist/index.browser.d.ts

@@ -79,6 +79,11 @@ type EventShipperOptions = {
     libraryName?: string;
     libraryVersion?: string;
     defaultEventName?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
 };
 declare class EventShipper$1 {
     private baseUrl;
@@ -94,6 +99,8 @@ declare class EventShipper$1 {
     private sticky;
     private timers;
     private inFlight;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
@@ -111,6 +118,82 @@ declare class EventShipper$1 {
     private flushOne;
 }
 
+/**
+ * Built-in default list of property names considered secret. Matching is
+ * case-insensitive and normalizes camelCase / snake_case / kebab-case (so
+ * `apiKey`, `api_key`, and `API-KEY` all match). When `defaultRedactAttribute`
+ * (and the recursive `redactSecretsInObject` helper) walk a value, any object
+ * key whose normalized form is in this set has its value replaced with the
+ * redaction placeholder.
+ *
+ * Names were chosen to cover the documented Vercel AI Gateway BYOK credential
+ * shapes (OpenAI / Anthropic `apiKey`, Bedrock `secretAccessKey` +
+ * `sessionToken`, Vertex `privateKey` + `privateKeyId`, etc.) plus generic
+ * secret-shaped properties common across other providers. Keys that are not
+ * by themselves secret (e.g. AWS `accessKeyId` — analogous to a username, not
+ * usable without `secretAccessKey`) are intentionally NOT in this set.
+ */
+declare const DEFAULT_SECRET_KEY_NAMES: readonly string[];
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+/**
+ * Recursively walk `value` and replace any property whose (normalized) name
+ * matches one of `secretKeyNames` with `placeholder`. Returns a new object/
+ * array; does not mutate the input. Non-object inputs are returned untouched.
+ *
+ * Cycle-safe via a WeakSet — circular references resolve to `"[CIRCULAR]"`.
+ */
+declare function redactSecretsInObject(value: unknown, options?: {
+    secretKeyNames?: ReadonlyArray<string>;
+    placeholder?: string;
+}): unknown;
+/**
+ * Hook fired per OTLP span right before the span is shipped (to the Raindrop
+ * API and to a local debugger). Lets callers inspect, rewrite, or drop the
+ * entire span — not just individual attributes — which is more flexible than
+ * an attribute-level hook (you can rename attributes, add new ones, drop the
+ * span outright, etc.).
+ *
+ * Return values:
+ *   - `undefined` or the same span: ship the span unchanged.
+ *   - a new `OtlpSpan`: ship the returned span in place of the original.
+ *   - `null`: drop the span entirely from every ship path.
+ *
+ * The hook runs on the hot path — keep it synchronous and side-effect-free.
+ * If the hook throws, the span is dropped (fail-closed) so a buggy hook can
+ * never accidentally ship raw, un-redacted spans.
+ */
+type TransformSpanHook = (span: OtlpSpan) => OtlpSpan | null | undefined;
+/**
+ * The built-in OTLP span attributes that carry JSON-serialized user objects
+ * the SDK has no schema for (provider options, provider metadata). The
+ * default span transformer (`defaultTransformSpan`) parses, recursively
+ * scrubs secret-shaped properties, and re-serializes the value of any
+ * attribute whose key is in this set. Other attributes — including
+ * `ai.prompt.messages` and `ai.toolCall.args` — are passed through unchanged
+ * because they may legitimately contain content the caller wants logged;
+ * callers who need to scrub those should provide a custom `transformSpan`.
+ */
+declare const DEFAULT_REDACT_ATTRIBUTE_KEYS: readonly string[];
+/**
+ * Default span transformer. Walks the span's attributes; for every attribute
+ * whose key is in `DEFAULT_REDACT_ATTRIBUTE_KEYS`, parses the `stringValue`
+ * as JSON, recursively scrubs secret-shaped property names
+ * (`DEFAULT_SECRET_KEY_NAMES`), and re-serializes. Returns the same span
+ * reference when nothing changed (cheap no-op path); otherwise returns a new
+ * `OtlpSpan` with updated `attributes`.
+ */
+declare function defaultTransformSpan(span: OtlpSpan): OtlpSpan;
+/**
+ * If `key` is one of the JSON-blob attributes we redact by default and
+ * `value.stringValue` parses cleanly, return a new `OtlpAnyValue` carrying
+ * the scrubbed JSON. Otherwise return `undefined` (signal: no change).
+ *
+ * Exported because a caller's custom `transformSpan` may want to apply the
+ * same per-attribute redaction logic to additional attributes (e.g. their
+ * own provider-specific blob).
+ */
+declare function redactJsonAttributeValue(key: string, value: OtlpAnyValue): OtlpAnyValue | undefined;
+
 type InternalSpan = {
     ids: SpanIds;
     name: string;
@@ -135,6 +218,40 @@ type TraceShipperOptions = {
      * Pass `null` to opt out of all mirroring (including auto-detect).
      */
     localDebuggerUrl?: string | null;
+    /**
+     * Per-span hook that fires for every OTLP span right before the span is
+     * shipped (both to the Raindrop API and to a local debugger). Lets callers
+     * inspect, rewrite, or drop entire spans — rename attributes, add new ones,
+     * scrub additional secret-shaped values inside `ai.prompt.messages` /
+     * `ai.toolCall.args`, etc.
+     *
+     * Return values:
+     *   - `undefined` or the same span reference: ship the span unchanged.
+     *   - a new `OtlpSpan`: ship the returned span in place of the original.
+     *   - `null`: drop the span entirely from every ship path.
+     *
+     * The hook runs BEFORE the default redactor (which is the always-on floor
+     * for documented BYOK secrets). The default redactor still runs on the
+     * post-transform span unless `disableDefaultRedaction` is set, so even if
+     * a custom transform overlooks a secret-shaped attribute, the floor catches
+     * it.
+     *
+     * The hook runs on the hot path — keep it synchronous and side-effect-free.
+     * If the hook itself throws, the span is dropped (fail-closed) so a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    transformSpan?: TransformSpanHook;
+    /**
+     * Disable the built-in default span transformer (which scrubs documented
+     * secret-shaped properties — `apiKey`, `secretAccessKey`, `privateKey`,
+     * etc. — inside `ai.request.providerOptions` and
+     * `ai.response.providerMetadata`).
+     *
+     * Default: `false` (i.e. default redaction is on). Setting this to `true`
+     * disables the floor entirely; provide a custom `transformSpan` if you
+     * still want some redaction in that case.
+     */
+    disableDefaultRedaction?: boolean;
 };
 declare class TraceShipper$1 {
     private baseUrl;
@@ -154,7 +271,24 @@ declare class TraceShipper$1 {
     private inFlight;
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
+    private transformSpanHook;
+    private disableDefaultRedaction;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Apply the user `transformSpan` hook (if any) followed by the default
+     * redactor (unless disabled). Returns either the (possibly new) span to
+     * ship, or `null` to drop the span entirely.
+     *
+     * Ordering: user hook runs first so callers can rewrite the span freely
+     * (rename attrs, add new ones, scrub things the default doesn't know
+     * about). The default redactor then runs on whatever the user produced,
+     * acting as the always-on floor for documented BYOK secrets. If the user
+     * sets `disableDefaultRedaction: true`, the floor is skipped.
+     *
+     * Fail-closed: if the user hook throws, the span is dropped — a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    private redactSpan;
     isDebugEnabled(): boolean;
     private authHeaders;
     startSpan(args: {
@@ -168,6 +302,7 @@ declare class TraceShipper$1 {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;
@@ -528,6 +663,40 @@ type RaindropAISDKOptions = {
         maxQueueSize?: number;
         debug?: boolean;
         debugSpans?: boolean;
+        /**
+         * Per-span hook that fires for every OTLP span right before it's shipped
+         * (to the Raindrop API and to a local debugger). Lets callers inspect,
+         * rewrite, or drop entire spans — rename attributes, add new ones, scrub
+         * additional secret-shaped values inside `ai.prompt.messages` /
+         * `ai.toolCall.args`, etc.
+         *
+         * Return values:
+         *   - `undefined` or the same span reference: ship the span unchanged.
+         *   - a new `OtlpSpan`: ship the returned span in place of the original.
+         *   - `null`: drop the span entirely from every ship path.
+         *
+         * The hook runs BEFORE the default redactor (the always-on floor for
+         * documented BYOK secrets — `apiKey`, `secretAccessKey`, `privateKey`,
+         * `accessToken`, etc. — inside `ai.request.providerOptions` and
+         * `ai.response.providerMetadata`). The default redactor still runs on
+         * the post-transform span unless `disableDefaultRedaction` is set.
+         *
+         * The hook runs on the hot path — keep it synchronous and
+         * side-effect-free. If the hook throws, the span is dropped (fail-closed).
+         */
+        transformSpan?: TransformSpanHook;
+        /**
+         * Disable the always-on default redactor that scrubs documented secret-
+         * shaped keys (`apiKey`, `secretAccessKey`, `privateKey`, ...) inside
+         * `ai.request.providerOptions` and `ai.response.providerMetadata`.
+         *
+         * Default: `false` (built-in redaction is on — BYOK credentials inside
+         * `providerOptions` are stripped automatically). If you set this to
+         * `true`, raw provider options will be shipped — only do this if you've
+         * verified your callers never put secrets in `providerOptions` or you've
+         * supplied your own `transformSpan` hook.
+         */
+        disableDefaultRedaction?: boolean;
     };
     events?: {
         enabled?: boolean;
@@ -764,4 +933,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, defaultTransformSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithRaindropCallMetadata, withCurrent };