raindrop-ai 0.1.1 → 0.1.2-otelv2

package/README.md

@@ -18,6 +18,27 @@ const raindrop = new Raindrop({
 });
 ```
 
+## Payload size limits
+
+Text fields (ai input/output, tool span I/O, span content) are capped at
+**1,000,000 characters per field by default** and truncated with a
+`...[truncated by raindrop]` marker. The cap is enforced before (or during)
+serialization, so oversized payloads cost the cap — not the payload — on your
+event loop, and large events land truncated instead of being silently dropped
+at the 1 MB ingest limit. Tune it via:
+
+```ts
+const raindrop = new Raindrop({
+  writeKey: "...",
+  maxTextFieldChars: 250_000,
+});
+```
+
+A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is still honored
+for span content. All outbound HTTP carries finite timeouts, and
+`raindrop.close()` runs under a 10s deadline so a dead network can never
+wedge your process exit.
+
 ## Notes
 
 - This package preserves the current dist structure and public exports.

package/dist/{chunk-DP5ED5DR.mjs → chunk-UICWZEYM.mjs}

@@ -1,4 +1,6 @@
-// ../core/dist/chunk-OLYXZCOK.js
+// ../core/dist/chunk-U5HUTMR5.js
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var MAX_RETRY_DELAY_MS = 3e4;
 function wait(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -6,6 +8,46 @@ function formatEndpoint(endpoint) {
   if (!endpoint) return void 0;
   return endpoint.endsWith("/") ? endpoint : `${endpoint}/`;
 }
+function redactUrlForLog(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch (e) {
+    return "<unparseable-url>";
+  }
+}
+var RATE_LIMITED_LOG_INTERVAL_MS = 3e4;
+var rateLimitedLogLast = /* @__PURE__ */ new Map();
+function rateLimitedLog(key, log) {
+  const now = Date.now();
+  const last = rateLimitedLogLast.get(key);
+  if (last !== void 0 && now - last < RATE_LIMITED_LOG_INTERVAL_MS) {
+    return false;
+  }
+  rateLimitedLogLast.set(key, now);
+  log();
+  return true;
+}
+async function raceWithTimeout(promise, timeoutMs) {
+  let timer;
+  const settledInTime = await Promise.race([
+    promise.then(
+      () => true,
+      () => true
+    ),
+    new Promise((resolve) => {
+      var _a;
+      timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+      (_a = timer.unref) == null ? void 0 : _a.call(timer);
+    })
+  ]);
+  if (timer) clearTimeout(timer);
+  return settledInTime;
+}
 function parseRetryAfter(headers) {
   var _a;
   const value = (_a = headers.get("Retry-After")) != null ? _a : headers.get("retry-after");
@@ -22,12 +64,12 @@ function parseRetryAfter(headers) {
 function getRetryDelayMs(attemptNumber, previousError) {
   if (previousError && typeof previousError === "object" && previousError !== null && "retryAfterMs" in previousError) {
     const v = previousError.retryAfterMs;
-    if (typeof v === "number") return Math.max(0, v);
+    if (typeof v === "number") return Math.min(Math.max(0, v), MAX_RETRY_DELAY_MS);
   }
   if (attemptNumber <= 1) return 0;
   const base = 500;
   const factor = Math.pow(2, attemptNumber - 2);
-  return base * factor;
+  return Math.min(base * factor, MAX_RETRY_DELAY_MS);
 }
 async function withRetry(operation, opName, opts) {
   const prefix = opts.sdkName ? `[raindrop-ai/${opts.sdkName}]` : "[raindrop-ai/core]";
@@ -62,7 +104,9 @@ async function withRetry(operation, opName, opts) {
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 async function postJson(url, body, headers, opts) {
-  const opName = `POST ${url}`;
+  var _a;
+  const opName = `POST ${redactUrlForLog(url)}`;
+  const timeoutMs = (_a = opts.timeoutMs) != null ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
   await withRetry(
     async () => {
       const resp = await fetch(url, {
@@ -71,7 +115,8 @@ async function postJson(url, body, headers, opts) {
           "Content-Type": "application/json",
           ...headers
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
       });
       if (!resp.ok) {
         const text = await resp.text().catch(() => "");
@@ -88,6 +133,108 @@ async function postJson(url, body, headers, opts) {
     opts
   );
 }
+var DEFAULT_MAX_TEXT_FIELD_CHARS = 1e6;
+var TRUNCATION_MARKER = "...[truncated by raindrop]";
+var BOUNDED_CLONE_MAX_DEPTH = 12;
+var BOUNDED_CLONE_SLACK = 256;
+var currentDefaultMaxTextFieldChars = DEFAULT_MAX_TEXT_FIELD_CHARS;
+function setDefaultMaxTextFieldChars(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    currentDefaultMaxTextFieldChars = Math.floor(value);
+  }
+}
+function resolveMaxTextFieldChars(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return currentDefaultMaxTextFieldChars;
+}
+function truncateToLimit(text, limit) {
+  if (limit > TRUNCATION_MARKER.length) {
+    return text.slice(0, limit - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+  }
+  return text.slice(0, Math.max(0, limit));
+}
+function capText(value, limit) {
+  if (typeof value !== "string") return value;
+  const max = limit != null ? limit : currentDefaultMaxTextFieldChars;
+  if (value.length <= max) return value;
+  return truncateToLimit(value, max);
+}
+function boundedClone(obj, charBudget) {
+  let budget = charBudget;
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk = (node, depth) => {
+    if (budget <= 0) return TRUNCATION_MARKER;
+    if (typeof node === "string") {
+      if (node.length > budget) {
+        const taken = node.slice(0, Math.max(0, budget)) + TRUNCATION_MARKER;
+        budget = 0;
+        return taken;
+      }
+      budget -= Math.max(node.length, 1);
+      return node;
+    }
+    if (node === null || typeof node === "number" || typeof node === "boolean") {
+      budget -= 8;
+      return node;
+    }
+    if (typeof node !== "object") {
+      budget -= 8;
+      return node;
+    }
+    if (seen.has(node)) return "[CIRCULAR]";
+    if (depth >= BOUNDED_CLONE_MAX_DEPTH) {
+      budget -= 16;
+      return `<max depth>`;
+    }
+    seen.add(node);
+    if (Array.isArray(node)) {
+      const out2 = [];
+      for (const v of node) {
+        if (budget <= 0) {
+          out2.push(TRUNCATION_MARKER);
+          break;
+        }
+        out2.push(walk(v, depth + 1));
+      }
+      return out2;
+    }
+    if (typeof node.toJSON === "function") {
+      budget -= 16;
+      return node;
+    }
+    const out = {};
+    for (const k in node) {
+      if (!Object.prototype.hasOwnProperty.call(node, k)) continue;
+      if (budget <= 0) {
+        out["..."] = TRUNCATION_MARKER;
+        break;
+      }
+      const key = walk(k, depth + 1);
+      out[key] = walk(node[k], depth + 1);
+    }
+    return out;
+  };
+  return walk(obj, 0);
+}
+function stringifyBounded(value, limit) {
+  const max = limit != null ? limit : currentDefaultMaxTextFieldChars;
+  if (typeof value === "string") {
+    return capText(value, max);
+  }
+  const pruned = boundedClone(value, max + TRUNCATION_MARKER.length + BOUNDED_CLONE_SLACK);
+  let json;
+  try {
+    json = JSON.stringify(pruned);
+  } catch (e) {
+    json = void 0;
+  }
+  if (json === void 0) {
+    return capText(String(value), max);
+  }
+  return json.length <= max ? json : truncateToLimit(json, max);
+}
 var LOCAL_DEBUGGER_ENV_VAR = "RAINDROP_LOCAL_DEBUGGER";
 var WORKSHOP_ENV_VAR = "RAINDROP_WORKSHOP";
 var DEFAULT_LOCAL_WORKSHOP_URL = "http://localhost:5899/v1/";
@@ -196,6 +343,13 @@ function sendLocalDebuggerLiveEvent(event, options = {}) {
   ).catch(() => {
   });
 }
+var SHUTDOWN_DEADLINE_MS = 1e4;
+var POST_SHUTDOWN_TIMEOUT_MS = 5e3;
+var DEFAULT_REDACT_ATTRIBUTE_KEYS = [
+  "ai.request.providerOptions",
+  "ai.response.providerMetadata"
+];
+var REDACT_JSON_ATTRIBUTE_KEYS = new Set(DEFAULT_REDACT_ATTRIBUTE_KEYS);
 
 // ../core/dist/index.node.js
 import { AsyncLocalStorage } from "async_hooks";
@@ -204,7 +358,7 @@ globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = AsyncLocalStorage;
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.1.1",
+  version: "0.1.2",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -362,12 +516,12 @@ function parseRetryAfter2(headers) {
 function getRetryDelayMs2(attemptNumber, previousError) {
   if (previousError && typeof previousError === "object" && previousError !== null && "retryAfterMs" in previousError) {
     const v = previousError.retryAfterMs;
-    if (typeof v === "number") return Math.max(0, v);
+    if (typeof v === "number") return Math.min(Math.max(0, v), MAX_RETRY_DELAY_MS);
   }
   if (attemptNumber <= 1) return 0;
   const base = 500;
   const factor = Math.pow(2, attemptNumber - 2);
-  return base * factor;
+  return Math.min(base * factor, MAX_RETRY_DELAY_MS);
 }
 async function withRetry2(operation, opName, opts) {
   let lastError = void 0;
@@ -399,7 +553,9 @@ async function withRetry2(operation, opName, opts) {
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 async function postJson2(url, body, headers, opts) {
-  const opName = `POST ${url}`;
+  var _a;
+  const opName = `POST ${redactUrlForLog(url)}`;
+  const timeoutMs = (_a = opts.timeoutMs) != null ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
   await withRetry2(
     async () => {
       const resp = await fetch(url, {
@@ -408,7 +564,8 @@ async function postJson2(url, body, headers, opts) {
           "Content-Type": "application/json",
           ...headers
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
       });
       if (!resp.ok) {
         const text = await resp.text().catch(() => "");
@@ -556,16 +713,19 @@ function getActiveTraceContext() {
 
 // src/tracing/direct/shipper.ts
 function serializeAssociationValue(value) {
-  if (typeof value === "string") {
-    return value;
-  }
-  const jsonValue = JSON.stringify(value);
-  return jsonValue === void 0 ? String(value) : jsonValue;
+  return stringifyBounded(value);
 }
 var DirectTraceShipper = class {
   constructor(opts) {
     this.queue = [];
     this.inFlight = /* @__PURE__ */ new Set();
+    /**
+     * Set once `shutdown()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    this.hasShutdown = false;
     var _a, _b, _c, _d, _e, _f;
     this.writeKey = opts.writeKey;
     this.baseUrl = (_a = formatEndpoint2(opts.endpoint)) != null ? _a : "https://api.raindrop.ai/v1/";
@@ -690,14 +850,19 @@ var DirectTraceShipper = class {
         if (this.debug) console.log(`[raindrop] direct: dropped ${batch.length} cloud spans (local-only)`);
         continue;
       }
+      const opts = this.requestOpts();
+      if (!opts) {
+        rateLimitedLog(
+          "js-sdk.direct.shutdown_deadline",
+          () => console.warn(
+            `[raindrop] direct: shutdown flush deadline exceeded; dropping ${batch.length} spans`
+          )
+        );
+        continue;
+      }
       const body = buildExportTraceServiceRequest2(batch);
       const url = `${this.baseUrl}traces`;
-      const p = postJson2(
-        url,
-        body,
-        { Authorization: `Bearer ${this.writeKey}` },
-        { maxAttempts: 3, debug: this.debug }
-      );
+      const p = postJson2(url, body, { Authorization: `Bearer ${this.writeKey}` }, opts);
       this.inFlight.add(p);
       try {
         try {
@@ -714,14 +879,48 @@ var DirectTraceShipper = class {
       }
     }
   }
+  /**
+   * Retry/timeout options for one batch POST, honoring the shutdown budget:
+   * outside shutdown, the normal 3-attempt schedule; during shutdown, a
+   * single attempt clamped to the remaining window; `null` once the window
+   * is exhausted (caller drops the batch). After shutdown() returns,
+   * stragglers run as a single short attempt.
+   */
+  requestOpts() {
+    if (this.shutdownDeadlineAt !== void 0) {
+      const remainingMs = this.shutdownDeadlineAt - Date.now();
+      if (remainingMs <= 0) return null;
+      return {
+        maxAttempts: 1,
+        debug: this.debug,
+        timeoutMs: Math.min(DEFAULT_REQUEST_TIMEOUT_MS, remainingMs)
+      };
+    }
+    if (this.hasShutdown) {
+      return { maxAttempts: 1, debug: this.debug, timeoutMs: POST_SHUTDOWN_TIMEOUT_MS };
+    }
+    return { maxAttempts: 3, debug: this.debug };
+  }
   async shutdown() {
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = void 0;
+    this.hasShutdown = true;
+    this.shutdownDeadlineAt = Date.now() + SHUTDOWN_DEADLINE_MS;
+    try {
+      if (this.timer) {
+        clearTimeout(this.timer);
+        this.timer = void 0;
+      }
+      const drain = async () => {
+        await this.flush();
+        await Promise.all([...this.inFlight].map((p) => p.catch(() => {
+        })));
+      };
+      const settled = await raceWithTimeout(drain(), SHUTDOWN_DEADLINE_MS);
+      if (!settled && this.debug) {
+        console.warn("[raindrop] direct: shutdown deadline exceeded; abandoning in-flight spans");
+      }
+    } finally {
+      this.shutdownDeadlineAt = void 0;
     }
-    await this.flush();
-    await Promise.all([...this.inFlight].map((p) => p.catch(() => {
-    })));
   }
 };
 
@@ -743,7 +942,7 @@ function getPropertiesFromContext(context5) {
     ...context5.properties || {}
   };
   if (context5.attachments && context5.attachments.length > 0) {
-    properties.attachments = JSON.stringify(context5.attachments);
+    properties.attachments = stringifyBounded(context5.attachments);
   }
   return properties;
 }
@@ -761,11 +960,7 @@ function serializeAssociationProperties(properties) {
   );
 }
 function serializeSpanValue(value) {
-  if (typeof value === "string") {
-    return value;
-  }
-  const jsonValue = JSON.stringify(value);
-  return jsonValue === void 0 ? String(value) : jsonValue;
+  return stringifyBounded(value);
 }
 function getLocalDebuggerMetadata(context5) {
   return {
@@ -1044,7 +1239,7 @@ var LiveInteraction = class {
         error = err instanceof Error ? err.message : String(err);
         const endTimeMs2 = Date.now();
         const durationMs2 = endTimeMs2 - startTimeMs;
-        const inputStr2 = params.inputParameters ? JSON.stringify(params.inputParameters) : void 0;
+        const inputStr2 = params.inputParameters ? stringifyBounded(params.inputParameters) : void 0;
         this.directShipper.sendToolSpan({
           name: toolName,
           spanId: spanIdB64,
@@ -1073,8 +1268,8 @@ var LiveInteraction = class {
       }
       const endTimeMs = Date.now();
       const durationMs = endTimeMs - startTimeMs;
-      const inputStr = params.inputParameters ? JSON.stringify(params.inputParameters) : void 0;
-      const outputStr = result !== void 0 ? typeof result === "string" ? result : JSON.stringify(result) : void 0;
+      const inputStr = params.inputParameters ? stringifyBounded(params.inputParameters) : void 0;
+      const outputStr = result !== void 0 ? stringifyBounded(result) : void 0;
       this.directShipper.sendToolSpan({
         name: toolName,
         spanId: spanIdB64,
@@ -1311,8 +1506,8 @@ var LiveInteraction = class {
       const traceIdB64 = this.ensureTraceId(activeContext.traceIdB64);
       const { parentSpanIdB64 } = activeContext;
       const spanIdB64 = base64Encode2(randomBytes2(8));
-      const inputStr = input !== void 0 ? typeof input === "string" ? input : JSON.stringify(input) : void 0;
-      const outputStr = output !== void 0 ? typeof output === "string" ? output : JSON.stringify(output) : void 0;
+      const inputStr = input !== void 0 ? stringifyBounded(input) : void 0;
+      const outputStr = output !== void 0 ? stringifyBounded(output) : void 0;
       this.directShipper.sendToolSpan({
         name,
         spanId: spanIdB64,
@@ -1359,12 +1554,10 @@ var LiveInteraction = class {
     span.setAttribute("traceloop.span.kind", "tool");
     setAssociationProperties(span, properties);
     if (input !== void 0) {
-      const inputStr = typeof input === "string" ? input : JSON.stringify(input);
-      span.setAttribute("traceloop.entity.input", inputStr);
+      span.setAttribute("traceloop.entity.input", stringifyBounded(input));
     }
     if (output !== void 0) {
-      const outputStr = typeof output === "string" ? output : JSON.stringify(output);
-      span.setAttribute("traceloop.entity.output", outputStr);
+      span.setAttribute("traceloop.entity.output", stringifyBounded(output));
     }
     if (durationMs !== void 0) {
       span.setAttribute("traceloop.entity.duration_ms", durationMs);
@@ -1452,8 +1645,8 @@ var LiveTracer = class {
     if (this.directShipper) {
       const { traceIdB64, parentSpanIdB64 } = getActiveTraceContext();
       const spanIdB64 = base64Encode2(randomBytes2(8));
-      const inputStr = input !== void 0 ? typeof input === "string" ? input : JSON.stringify(input) : void 0;
-      const outputStr = output !== void 0 ? typeof output === "string" ? output : JSON.stringify(output) : void 0;
+      const inputStr = input !== void 0 ? stringifyBounded(input) : void 0;
+      const outputStr = output !== void 0 ? stringifyBounded(output) : void 0;
       this.directShipper.sendToolSpan({
         name,
         spanId: spanIdB64,
@@ -1497,12 +1690,10 @@ var LiveTracer = class {
     });
     span.setAttribute("traceloop.span.kind", "tool");
     if (input !== void 0) {
-      const inputStr = typeof input === "string" ? input : JSON.stringify(input);
-      span.setAttribute("traceloop.entity.input", inputStr);
+      span.setAttribute("traceloop.entity.input", stringifyBounded(input));
     }
     if (output !== void 0) {
-      const outputStr = typeof output === "string" ? output : JSON.stringify(output);
-      span.setAttribute("traceloop.entity.output", outputStr);
+      span.setAttribute("traceloop.entity.output", stringifyBounded(output));
     }
     if (durationMs !== void 0) {
       span.setAttribute("traceloop.entity.duration_ms", durationMs);
@@ -1934,6 +2125,7 @@ function getCurrentTraceId() {
   return (_a = trace4.getSpan(context4.active())) == null ? void 0 : _a.spanContext().traceId;
 }
 var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
+  process.env.TRACELOOP_TELEMETRY = "false";
   const {
     logLevel,
     useExternalOtel,
@@ -2213,8 +2405,19 @@ var tracing = (analytics, apiUrl, writeKey, options, isDebug = false) => {
 };
 
 export {
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  MAX_RETRY_DELAY_MS,
+  redactUrlForLog,
+  rateLimitedLog,
+  raceWithTimeout,
+  setDefaultMaxTextFieldChars,
+  resolveMaxTextFieldChars,
+  capText,
+  stringifyBounded,
   resolveLocalDebuggerBaseUrl,
   mirrorPartialEventToLocalDebugger,
+  SHUTDOWN_DEADLINE_MS,
+  POST_SHUTDOWN_TIMEOUT_MS,
   package_default,
   tracing
 };

package/dist/index.d.mts

@@ -735,6 +735,16 @@ interface AnalyticsConfig {
     debugLogs?: boolean;
     endpoint?: string;
     redactPii?: boolean;
+    /**
+     * Per-field character cap applied to ai input/output and serialized
+     * tool/span content BEFORE buffering or serialization, so oversized
+     * payloads cost the cap — not the payload — on the calling code path
+     * (`JSON.stringify` of a multi-MB payload blocks the event loop).
+     * Truncated fields end with `...[truncated by raindrop]` and never exceed
+     * the cap, marker included. Defaults to 1,000,000 (matching the Python SDK's
+     * `max_text_field_chars`).
+     */
+    maxTextFieldChars?: number;
     /**
      * Force-enable (or opt out of) Workshop / local-debugger mirroring.
      *
@@ -855,6 +865,20 @@ declare class Raindrop {
     private partialEventBuffer;
     private partialEventTimeouts;
     private inFlightRequests;
+    private maxTextFieldChars;
+    /**
+     * Epoch ms deadline while `close()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush so a dead or
+     * slow network can never wedge process exit.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `close()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
     debugLogs: boolean;
     constructor(config: AnalyticsConfig);
     private get localOnly();
@@ -964,6 +988,15 @@ declare class Raindrop {
     private saveToBuffer;
     private flush;
     private mirrorBatchToLocalDebugger;
+    /**
+     * Attempts/timeout budget for one POST, honoring the close() deadline.
+     * Returns `null` when the shutdown budget is exhausted — the caller must
+     * drop the payload instead of issuing a request that could outlive
+     * process exit. Checked fresh on every send so a deadline that expires
+     * mid-drain takes effect immediately.
+     */
+    private requestBudget;
+    private warnShutdownDrop;
     private sendBatchToApi;
     private getContext;
     private formatZodError;
@@ -1000,6 +1033,7 @@ declare class Raindrop {
      */
     forceFlush(): Promise<void>;
     close(): Promise<void>;
+    private closeWithinDeadline;
 }
 
 export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, type LocalDebuggerLiveEventInput, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropProperties, type RaindropPropertyLeaf, type RaindropPropertyValue, type RaindropSpanProcessor, type SelfDiagnoseOptions, type SelfDiagnosticsExecuteContext, type SelfDiagnosticsExecuteResult, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInputSchema, type SelfDiagnosticsToolOptions, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };

package/dist/index.d.ts

@@ -735,6 +735,16 @@ interface AnalyticsConfig {
     debugLogs?: boolean;
     endpoint?: string;
     redactPii?: boolean;
+    /**
+     * Per-field character cap applied to ai input/output and serialized
+     * tool/span content BEFORE buffering or serialization, so oversized
+     * payloads cost the cap — not the payload — on the calling code path
+     * (`JSON.stringify` of a multi-MB payload blocks the event loop).
+     * Truncated fields end with `...[truncated by raindrop]` and never exceed
+     * the cap, marker included. Defaults to 1,000,000 (matching the Python SDK's
+     * `max_text_field_chars`).
+     */
+    maxTextFieldChars?: number;
     /**
      * Force-enable (or opt out of) Workshop / local-debugger mirroring.
      *
@@ -855,6 +865,20 @@ declare class Raindrop {
     private partialEventBuffer;
     private partialEventTimeouts;
     private inFlightRequests;
+    private maxTextFieldChars;
+    /**
+     * Epoch ms deadline while `close()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush so a dead or
+     * slow network can never wedge process exit.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `close()` begins and never cleared. Sends issued after the
+     * drain window (stragglers, or flush work the deadline abandoned
+     * mid-drain) run as a single short attempt instead of regaining the full
+     * retry schedule.
+     */
+    private hasShutdown;
     debugLogs: boolean;
     constructor(config: AnalyticsConfig);
     private get localOnly();
@@ -964,6 +988,15 @@ declare class Raindrop {
     private saveToBuffer;
     private flush;
     private mirrorBatchToLocalDebugger;
+    /**
+     * Attempts/timeout budget for one POST, honoring the close() deadline.
+     * Returns `null` when the shutdown budget is exhausted — the caller must
+     * drop the payload instead of issuing a request that could outlive
+     * process exit. Checked fresh on every send so a deadline that expires
+     * mid-drain takes effect immediately.
+     */
+    private requestBudget;
+    private warnShutdownDrop;
     private sendBatchToApi;
     private getContext;
     private formatZodError;
@@ -1000,6 +1033,7 @@ declare class Raindrop {
      */
     forceFlush(): Promise<void>;
     close(): Promise<void>;
+    private closeWithinDeadline;
 }
 
 export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, type LocalDebuggerLiveEventInput, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropProperties, type RaindropPropertyLeaf, type RaindropPropertyValue, type RaindropSpanProcessor, type SelfDiagnoseOptions, type SelfDiagnosticsExecuteContext, type SelfDiagnosticsExecuteResult, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInputSchema, type SelfDiagnosticsToolOptions, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };