feat(trace): add advanced span filters (#2466)

resolves
https://linear.app/braintrustdata/issue/SDK-343/add-filters-on-traceget-spans-to-javascript-sdk

Add `filters` to `Trace.getSpans()` so callers can select spans by type,
name, error state, partial metadata, and duration without fetching the
whole trace and filtering it themselves.

```typescript
const spans = await trace.getSpans({
  filters: {
    spanType: ["tool"],
    name: ["search", "lookup"],
    hasError: true,
    metadata: { model: "gpt-5" },
    duration: { min: 0.5, max: 10 },
  },
});
```

Combine filter dimensions with AND and match any value within each name
or span-type list. Duration bounds are inclusive and measured in
seconds. Keep the existing top-level `spanType` option supported.

Apply consistent filtering to buffered spans, complete trace caches, and
BTQL queries. Validate metadata as cycle-free JSON data, check returned
metadata candidates locally to avoid backend type coercion, and avoid
caching partial filtered results as complete traces.

Author: AbhiPrasad

.changeset/advanced-span-filters.md

@@ -0,0 +1,5 @@
+---
+"braintrust": minor
+---
+
+feat: Add advanced filters to `Trace.getSpans()`

js/src/exports.ts

@@ -319,7 +319,13 @@ export {
   PromptDefinitionWithTools,
 } from "./prompt-schemas";
 
-export type { Trace, SpanData, GetThreadOptions } from "./trace";
+export type {
+  Trace,
+  SpanData,
+  SpanDurationFilter,
+  SpanFilters,
+  GetThreadOptions,
+} from "./trace";
 export { SpanFetcher, CachedSpanFetcher, LocalTrace } from "./trace";
 
 export type {