langwatch 1.3.0 → 1.5.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.mjs';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, a as getLangWatchTracer } from './implementation-Bd2Z0kjH.mjs';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, a as getLangWatchTracer } from './implementation-Ro3LpjAt.mjs';
 import { z } from 'zod';
-import { p as paths, P as PromptResponse, C as CreatePromptBody, U as UpdatePromptBody, T as TagDefinition, a as CreatedTag, o as operations, b as PromptData, F as FetchPolicy, c as Prompt, L as LangWatchSpan, d as components } from './types-ruthADbq.mjs';
+import { p as paths, P as PromptResponse, C as CreatePromptBody, U as UpdatePromptBody, T as TagDefinition, a as CreatedTag, o as operations, b as PromptData, F as FetchPolicy, c as Prompt, L as LangWatchSpan, d as components } from './types-VoDc_AXK.mjs';
 import openApiCreateClient from 'openapi-fetch';
 export { l as attributes } from './types-VOZv9LYO.mjs';
 import { CliHandledErrorReason, CliHandledError } from '@langwatch/langy/cards/handled-error';
@@ -976,6 +976,105 @@ type EvaluateOptions$1 = {
     /** Metadata for the target */
     metadata?: TargetMetadata;
 };
+/**
+ * Per-candidate metric the judge can be asked to weigh alongside quality
+ *
+ * Duration is the one the SDK measures itself. Cost is not on offer: the
+ * platform works a target's cost out from its traces after the run, so there
+ * is nothing to show the judge at the moment a verdict is asked for.
+ */
+type ComparisonMetric = "duration";
+/**
+ * Outcome of a comparison
+ *
+ * - `decided`: the judge picked a winner
+ * - `tie`: the judge judged the candidates and found none clearly better
+ * - `inconclusive`: the judge judged the candidates and established no winner,
+ *   which under swap-and-reconcile means its two passes disagreed. A finding
+ *   about the candidates, and not a tie: a tie is a measurement, this is the
+ *   absence of one
+ * - `skipped`: fewer than two targets had an output, so no judge ran
+ * - `error`: the judge could not be reached or failed, so nothing was measured
+ *   about the candidates at all. Never conflated with `inconclusive`, which
+ *   says something about them
+ */
+type ComparisonStatus = "decided" | "tie" | "inconclusive" | "skipped" | "error";
+/**
+ * The result of comparing a row's targets
+ */
+type ComparisonVerdict = {
+    /** What the comparison concluded */
+    status: ComparisonStatus;
+    /** The winning target's name. Non-null only when `status` is `decided` */
+    winner: string | null;
+    /**
+     * The judge's reasoning, why the row established no winner, or the failure
+     * when `status` is `error`
+     */
+    reasoning: string | null;
+    /** The target names actually judged, in registration order */
+    candidates: string[];
+};
+/**
+ * Options for the compare() method
+ *
+ * Every option below is optional because the judge already has a default for
+ * it. An option left unset is absent from the request, so the judge's own
+ * default applies and there is exactly one place where each default is
+ * written down. The defaults are documented here for reference only, and are
+ * deliberately not restated in code.
+ */
+type ComparisonOptions = {
+    /**
+     * Row index in the dataset. Also seeds the judge's deterministic candidate
+     * shuffle.
+     *
+     * compare() takes the row the way log() does: inside a run() callback it is
+     * inferred from the row being processed, and outside one it is required.
+     */
+    index?: number;
+    /** Name the verdict is recorded under (default: "comparison") */
+    name?: string;
+    /**
+     * Restrict the comparison to these targets, in place of every target that
+     * recorded an output for the row. Naming a target with no output for the
+     * row is an error rather than a narrower comparison.
+     */
+    targets?: string[];
+    /** The task the candidates were answering, for the judge's framing */
+    input?: string;
+    /**
+     * Reference answer to judge the candidates against. Passing one is what
+     * turns on reference-answer judging; leave it out to have the candidates
+     * compared on their own merits.
+     */
+    golden?: string;
+    /**
+     * Judge prompt template, used verbatim. Placeholders: `{input}`,
+     * `{golden}`, `{candidates}`. Leave it out and the judge picks the shipped
+     * default that fits what the row actually carries.
+     */
+    prompt?: string;
+    /** Judge model (server default: the platform's configured judge model) */
+    model?: string;
+    /** Let the judge answer "tie" when no candidate is better (server default: true) */
+    allowTie?: boolean;
+    /** Shuffle candidate order per row to counter position bias (server default: true) */
+    randomizeOrder?: boolean;
+    /**
+     * Judge each row a second time with the candidate order reversed and report
+     * no verdict when the two disagree (server default: true). Doubles the
+     * judge-call cost per row.
+     */
+    swapAndReconcile?: boolean;
+    /**
+     * Per-candidate metrics to put in front of the judge, so it can prefer a
+     * faster candidate when quality is comparable (server default: none)
+     */
+    includeMetrics?: ComparisonMetric[];
+    /** Judge sampling temperature (server default: 0) */
+    temperature?: number;
+};
 /**
  * Context passed to the run() callback
  */
@@ -1064,8 +1163,7 @@ declare class Experiment {
     private cumulativeEntries;
     private runUrl;
     private targets;
-    private currentTraceId;
-    private currentIndex;
+    private capturedOutputs;
     private iterationUsedWithTarget;
     private evaluationUsesTargets;
     private constructor();
@@ -1123,6 +1221,10 @@ declare class Experiment {
      * ```
      */
     log(metric: string, options: LogOptions): void;
+    /**
+     * Queue an evaluation result for the next batch
+     */
+    private pushEvaluation;
     /**
      * Run a built-in evaluator
      *
@@ -1150,6 +1252,76 @@ declare class Experiment {
      * ```
      */
     evaluate(evaluatorSlug: string, options: EvaluateOptions$1): Promise<void>;
+    /**
+     * Call an evaluator and return its raw result
+     */
+    private callEvaluator;
+    /**
+     * Compare a row's targets and pick the best one
+     *
+     * Every target that recorded an output for the row is judged together in a
+     * single call, and the winner comes back named with the target name you
+     * registered. Call it once the row's withTarget() calls have all settled,
+     * which under the usual Promise.all is right after the await.
+     *
+     * The verdict grades no single target, so it is recorded against the row.
+     *
+     * The row is named the way log() names it: inside a run() callback it is
+     * inferred from the row being processed, and outside one it is required.
+     *
+     * A row with fewer than two outputs cannot be compared: it is recorded as
+     * skipped, naming the targets that produced nothing, and the run carries on.
+     * A judge that fails or cannot be reached comes back as an `error` verdict
+     * for the same reason, and stays distinct from `inconclusive`, which is the
+     * judge telling you something about your candidates. Naming a target that
+     * produced no output is a different thing again, and throws, because a
+     * two-way verdict read as the three-way one you asked for is worse than a
+     * failure.
+     *
+     * @param options - How the judge should read the row, and which row when
+     *                  it cannot be inferred
+     * @returns The verdict, including the candidates it actually saw
+     *
+     * @example
+     * ```typescript
+     * await experiment.run(dataset, async ({ item }) => {
+     *   await Promise.all([
+     *     experiment.withTarget('gpt-5-mini', () => askGpt(item.question)),
+     *     experiment.withTarget('claude-sonnet-5', () => askClaude(item.question)),
+     *   ]);
+     *
+     *   const verdict = await experiment.compare({ input: item.question });
+     *   console.log(verdict.winner);
+     * });
+     * ```
+     */
+    compare(options?: ComparisonOptions): Promise<ComparisonVerdict>;
+    /**
+     * The row a comparison is about
+     *
+     * Inferred from the row being processed, the same way withTarget() and
+     * log() infer theirs, so a comparison inside a run() callback never repeats
+     * an index the SDK already has. It reads that row from the iteration's own
+     * context, which is what keeps a run of many rows at once from handing one
+     * row's comparison the row a neighbour happens to be on.
+     *
+     * What it deliberately does not do is fall back to a row: judging row 0
+     * because no row was named would hand back a confident verdict about
+     * candidates the caller never asked about.
+     */
+    private resolveComparisonRow;
+    /**
+     * Record a comparison verdict against the row
+     *
+     * The verdict the caller is handed is the only input, so the row can never
+     * say one thing while the return value says another.
+     *
+     * Deliberately not routed through log(): a comparison grades no single
+     * target, so it must not pick one up from an ambient withTarget() context,
+     * and it is recorded under the judge's own evaluator id so the results page
+     * can tell it apart from a hand-logged metric.
+     */
+    private recordComparison;
     /**
      * Execute code within a target context with automatic tracing
      *
@@ -1186,6 +1358,15 @@ declare class Experiment {
      */
     withTarget<R>(targetName: string, metadata: TargetMetadata | null, callback: TargetCallback<R>): Promise<TargetResult<R>>;
     withTarget<R>(targetName: string, callback: TargetCallback<R>): Promise<TargetResult<R>>;
+    /**
+     * Keep a target's output for the row so compare() can reach it later
+     *
+     * The batch this output also went into is flushed on a timer and cleared, so
+     * a comparison that read its candidates from there would find them missing
+     * whenever the flush landed first. A target that produced nothing is not
+     * captured at all: it has no output to judge.
+     */
+    private captureTargetOutput;
     /**
      * Register a target for multi-target comparison
      */
@@ -1535,6 +1716,17 @@ declare class TargetMetadataConflictError extends ExperimentError {
     readonly newMetadata: Record<string, unknown>;
     constructor(targetName: string, existingMetadata: Record<string, unknown>, newMetadata: Record<string, unknown>);
 }
+/**
+ * Thrown when a comparison cannot produce a verdict the caller asked for
+ *
+ * A row that is simply too thin to judge is skipped instead, so this is
+ * reserved for a mismatch between what the caller named and what the run
+ * actually recorded.
+ */
+declare class ComparisonError extends ExperimentError {
+    readonly missingTargets: string[];
+    constructor(message: string, missingTargets?: string[]);
+}
 /**
  * Thrown when an evaluator call fails
  */
@@ -1768,6 +1960,21 @@ type SuiteResponse = NonNullable<paths["/api/suites"]["get"]["responses"]["200"]
 type CreateSuiteBody = NonNullable<paths["/api/suites"]["post"]["requestBody"]>["content"]["application/json"];
 type UpdateSuiteBody = NonNullable<paths["/api/suites/{id}"]["patch"]["requestBody"]>["content"]["application/json"];
 type SuiteRunResult = paths["/api/suites/{id}/run"]["post"]["responses"]["200"]["content"]["application/json"];
+/** Options for `POST /api/suites/{id}/run`. */
+interface SuiteRunOptions {
+    /**
+     * Key that makes the request safe to retry. Generated per call when omitted,
+     * so two retries of the same command schedule two runs unless the caller
+     * pins one.
+     */
+    idempotencyKey?: string;
+    /**
+     * Constant values applied to every scenario in the run, e.g. a fixture id or
+     * a tenant. A value supplied here overrides the scenario's own default for
+     * that name.
+     */
+    parameters?: Record<string, string | number | boolean>;
+}
 declare class SuitesApiService {
     private readonly apiClient;
     constructor(config?: Pick<InternalConfig, "langwatchApiClient">);
@@ -1777,7 +1984,12 @@ declare class SuitesApiService {
     create(params: CreateSuiteBody): Promise<SuiteResponse>;
     update(id: string, params: UpdateSuiteBody): Promise<SuiteResponse>;
     duplicate(id: string): Promise<SuiteResponse>;
-    run(id: string, idempotencyKey?: string): Promise<SuiteRunResult>;
+    run(id: string, options?: SuiteRunOptions): Promise<SuiteRunResult>;
+    /**
+     * @deprecated Pass `{ idempotencyKey }` instead. The options object is what
+     * carries run parameters, and a positional key cannot reach them.
+     */
+    run(id: string, idempotencyKey: string): Promise<SuiteRunResult>;
     delete(id: string): Promise<{
         id: string;
         archived: boolean;
@@ -2154,10 +2366,19 @@ interface VirtualKey {
     display_prefix: string;
     principal_user_id: string | null;
     /**
-     * Where an org- or team-owned key's traces and costs land. Not a
-     * scope: it grants no access to the key.
+     * Where this key's traces and costs land. Not a scope: it grants no
+     * access to the key. Decided when the key is written and stored on it,
+     * so editing what the key is scoped to never moves it. Null only on a
+     * key created before this was stored, in an organization that had no
+     * governance project to fall back to.
      */
     trace_project_id: string | null;
+    /**
+     * True when the project in `trace_project_id` has been deleted. The key
+     * goes on sending its traces there, so the data stays whole and
+     * reappears if the project is restored, and traffic is never refused.
+     */
+    trace_project_archived: boolean;
     scopes: VirtualKeyScope[];
     routing_policy_id: string | null;
     routing_mode: VirtualKeyRoutingMode;
@@ -2638,7 +2859,16 @@ interface SpendEvent {
     };
 }
 interface SpendSummaryRow {
+    /**
+     * The FIRST grouping dimension's value. Unchanged from when a rollup could
+     * only be grouped one way, so existing code keeps reading what it did. With
+     * two dimensions, two rows can share a key: read `group` to tell them apart.
+     */
     key: string;
+    /** Every grouping dimension by name, e.g. `{ model: "gpt-5-mini" }`. */
+    group: Record<string, string>;
+    /** Start of the time bucket in the requested zone, null when unbucketed. */
+    bucket_start: string | null;
     /** Priced outcomes (confirmed and failed). */
     event_count: number;
     /** Unpriced settled requests, counted separately: never in cost sums. */
@@ -2662,6 +2892,75 @@ interface SpendSummaryRow {
  * `success` and `error` are the coarse outcome pair over those.
  */
 type SpendEventStatus = "success" | "error" | "admitted" | "confirmed" | "failed" | "settled";
+/**
+ * The states a ROLLUP can be filtered by. A rollup sums the cost of requests
+ * past admission, so `admitted` is refused there rather than answered with a
+ * zero; list the events to see those. Derived by exclusion so the two stay one
+ * vocabulary.
+ */
+type SpendSummaryStatus = Exclude<SpendEventStatus, "admitted">;
+/** A dimension a rollup can be grouped by. */
+type SpendGroupBy = "virtual_key" | "end_user" | "project" | "model" | "provider" | "principal" | "request_type";
+/**
+ * The filters BOTH spend reads accept. A reconciliation checksums the rollups
+ * and diffs the events when a checksum disagrees, so the two take the same
+ * vocabulary and a divergence can be walked on exactly the narrowing that
+ * produced it.
+ *
+ * Every field takes one value or many; many means "any of these". Naming two
+ * different fields narrows.
+ */
+interface SpendFilterOptions {
+    projectId?: string | string[];
+    /** Resolved to the projects the team owns. A team with none matches nothing. */
+    teamId?: string | string[];
+    /** Your own id for a virtual key. One nobody minted matches nothing. */
+    externalId?: string | string[];
+    virtualKeyId?: string | string[];
+    endUserId?: string | string[];
+    principalUserId?: string | string[];
+    model?: string | string[];
+    providerKey?: string | string[];
+    requestType?: string | string[];
+    label?: string | string[];
+    /**
+     * Your own request metadata, e.g. `{ customer_tier: "gold" }`. Several
+     * values for one key widen it; several keys narrow.
+     */
+    metadata?: Record<string, string | string[]>;
+    status?: SpendEventStatus;
+}
+/**
+ * What a rollup is grouped by, and over what window.
+ *
+ * Grouping by `model` or `provider`, or into time buckets, is REFUSED with
+ * `gateway_spend_group_by_unstable` over a window recent enough that outcomes
+ * can still arrive: until a request settles, the model and provider recorded
+ * against it are the ones that were asked for, and they are replaced by the
+ * ones that actually served it. A page walk over a group that can move counts
+ * some requests twice and misses others.
+ *
+ * Reconcile closed periods and this never fires. For a live view where an
+ * approximate shape is enough, send `allowUnstable`.
+ */
+interface SpendSummariesOptions extends Omit<SpendFilterOptions, "status"> {
+    /**
+     * One lifecycle status, minus `admitted`: a rollup sums the cost of requests
+     * past admission, and an admitted request has none yet. List the events for
+     * those.
+     */
+    status?: SpendSummaryStatus;
+    /** One or two dimensions. Two rows can share `key`; read `group`. */
+    groupBy: SpendGroupBy | SpendGroupBy[];
+    from: number;
+    to: number;
+    /** Adds a time column. Counts as movable, so the same refusal applies. */
+    bucket?: "none" | "hour" | "day";
+    /** IANA zone the bucket boundary falls on, e.g. "Europe/Amsterdam". */
+    timezone?: string;
+    /** Serve a movable grouping anyway, accepting an inexact walk. */
+    allowUnstable?: boolean;
+}
 interface SpendSummariesPage {
     data: SpendSummaryRow[];
     /**
@@ -2734,6 +3033,14 @@ declare class SpendEventsApiError extends Error {
  * query filter rather than scoping on a header, so the project belongs to the
  * call, not to the client.
  *
+ * The key MUST be an organization API key (`sk-lw-{id}_{secret}`, from
+ * Settings > API Keys). A project API key is refused before any permission is
+ * consulted, with `credential_class_mismatch`, and no header makes it work:
+ * these are organization-scoped routes and a project key names one project.
+ * The same organization key also reaches the project-scoped surfaces when
+ * given `X-Project-Id`, so one key covers both families and a project key
+ * covers only one.
+ *
  * Neither collection on this service offers an eager whole-set read. The
  * ledger is unbounded, and materialising a window of it is the very
  * under-counting and out-of-memory footgun the page docstrings warn about:
@@ -2756,17 +3063,12 @@ declare class SpendEventsApiService {
      * stops on the first page silently under-counts the window, so read every
      * page or stream them with `iterate()`.
      */
-    listPage(options: {
+    listPage(options: SpendFilterOptions & {
         /** Required: the pull is a ranged read by contract. */
         from: number;
         to: number;
         cursor?: string;
         limit?: number;
-        virtualKeyId?: string;
-        endUserId?: string;
-        projectId?: string;
-        model?: string;
-        status?: SpendEventStatus;
     }): Promise<SpendEventsPage>;
     /**
      * Every spend event in the window, one row at a time, fetching each page
@@ -2777,17 +3079,12 @@ declare class SpendEventsApiService {
      * collect it into an array. Raises rather than looping forever on a cursor
      * chain that never ends.
      */
-    iterate(options: {
+    iterate(options: SpendFilterOptions & {
         /** Required: the pull is a ranged read by contract. */
         from: number;
         to: number;
         cursor?: string;
         limit?: number;
-        virtualKeyId?: string;
-        endUserId?: string;
-        projectId?: string;
-        model?: string;
-        status?: SpendEventStatus;
     }): AsyncGenerator<SpendEvent>;
     /**
      * ONE page of per-key spend rollups for a window, paged by group key
@@ -2798,13 +3095,7 @@ declare class SpendEventsApiService {
      * reconciler that reads only the first page silently under-counts every
      * tenant past the limit.
      */
-    summariesPage(options: {
-        groupBy: "virtual_key" | "end_user";
-        from: number;
-        to: number;
-        projectId?: string;
-        /** Narrow the rollup to one key, exact match. */
-        virtualKeyId?: string;
+    summariesPage(options: SpendSummariesOptions & {
         cursor?: string;
         limit?: number;
     }): Promise<SpendSummariesPage>;
@@ -2816,13 +3107,7 @@ declare class SpendEventsApiService {
      * covers, so there is deliberately no eager whole-set read here either: a
      * checksum that quietly covers part of the window is worse than none.
      */
-    iterSummaries(options: {
-        groupBy: "virtual_key" | "end_user";
-        from: number;
-        to: number;
-        projectId?: string;
-        /** Narrow the rollup to one key, exact match. */
-        virtualKeyId?: string;
+    iterSummaries(options: SpendSummariesOptions & {
         cursor?: string;
         limit?: number;
     }): AsyncGenerator<SpendSummaryRow>;
@@ -2846,9 +3131,43 @@ declare class SpendEventsApiService {
     }): Promise<EndUserSpend>;
 }
 
+/** Where an endpoint delivers. */
+type WebhookDestinationKind = "http" | "sqs";
+/** The queue an `sqs` endpoint delivers to, as any read surface sees it: the
+ *  secret half of a static key pair is never returned. */
+interface WebhookSqsDestination {
+    queue_url: string;
+    /** Read off the queue URL, never configured beside it. */
+    region: string;
+    /** Whose queue it is. */
+    account_id: string;
+    queue_name: string;
+    credential_mode: "assume_role" | "static" | "ambient";
+    role_arn: string | null;
+    /** Generated at save time, to paste into the role's trust policy. */
+    external_id: string | null;
+    access_key_id: string | null;
+}
+/** The queue half of a create or update body. */
+interface WebhookSqsDestinationInput {
+    queue_url: string;
+    /** The role to assume, with an external id we generate. The recommended
+     *  way to grant access: nothing long-lived is stored, and the customer
+     *  revokes by editing their own trust policy. */
+    role_arn?: string;
+    external_id?: string;
+    /** A static key pair instead. The secret is stored encrypted and never
+     *  returned. */
+    access_key_id?: string;
+    secret_access_key?: string;
+}
 interface WebhookEndpointSummary {
     id: string;
-    url: string;
+    destination_kind: WebhookDestinationKind;
+    /** The receiver URL on an `http` endpoint, null on every other kind. */
+    url: string | null;
+    /** The queue on an `sqs` endpoint, null on every other kind. */
+    sqs: WebhookSqsDestination | null;
     max_batch_size: number;
     max_batch_delay_ms: number;
     max_in_flight: number;
@@ -2866,9 +3185,8 @@ interface WebhookEndpointWithSecret extends WebhookEndpointSummary {
     /** Present only on create and roll-secret responses; never again. */
     secret: string;
 }
-/** The POST body, exactly as the wire takes it. */
-interface CreateWebhookEndpointInput {
-    url: string;
+/** Everything a create body carries that is not the destination. */
+interface CreateWebhookEndpointBase {
     enabled_events: string[];
     /** Envelopes per delivery. The receiver always gets an array. */
     max_batch_size?: number;
@@ -2877,9 +3195,39 @@ interface CreateWebhookEndpointInput {
     /** Concurrent in-flight deliveries to this endpoint. */
     max_in_flight?: number;
 }
+/**
+ * The POST body, exactly as the wire takes it.
+ *
+ * A destination is one kind and one address, so the two are a union rather
+ * than independent optional fields: the type refuses `{destination_kind:
+ * "sqs"}` with no queue, and `{url, sqs}` together, which is what the server
+ * refuses too. `destination_kind` is optional only on the http branch, where
+ * absent has always meant http.
+ */
+type WebhookDestinationInput = {
+    destination_kind?: "http";
+    url: string;
+    sqs?: never;
+} | {
+    destination_kind: "sqs";
+    sqs: WebhookSqsDestinationInput;
+    url?: never;
+};
+type CreateWebhookEndpointInput = CreateWebhookEndpointBase & WebhookDestinationInput;
 /** The PATCH body, exactly as the wire takes it. Omitted fields are left alone. */
 interface UpdateWebhookEndpointInput {
     url?: string;
+    /** Only the queue's own fields; the destination kind cannot change, because
+     *  batches already planned against the old transport are in flight. Create
+     *  a new endpoint and archive this one once it has drained. A credential
+     *  field sent as null is CLEARED; omitted keeps what is stored. */
+    sqs?: Partial<{
+        queue_url: string;
+        role_arn: string | null;
+        external_id: string | null;
+        access_key_id: string | null;
+        secret_access_key: string | null;
+    }>;
     enabled_events?: string[];
     status?: "active" | "disabled";
     max_batch_size?: number;
@@ -2954,6 +3302,13 @@ declare class WebhooksApiError extends Error {
  * rejected by the server. The surface is anchored on the organization alone,
  * so there is no project id to give this client.
  *
+ * The key MUST be an organization API key (`sk-lw-{id}_{secret}`, from
+ * Settings > API Keys). A project API key is refused with
+ * `credential_class_mismatch` before any permission is consulted, and no
+ * header makes it work. The same organization key also reaches the
+ * project-scoped surfaces when given `X-Project-Id`, so one key covers both
+ * families and a project key covers only one.
+ *
  * The endpoint entity and the create/update bodies mirror the wire verbatim,
  * so their fields are lowercase snake_case: virtual keys and gateway budgets
  * already take the wire body as it is, and translating field by field here
@@ -3020,10 +3375,11 @@ declare class WebhooksApiService {
      * that missed a delivery reads the window back from here. Walk the whole
      * window with `iterEvents()`.
      */
-    eventsPage(options?: {
+    eventsPage(options: {
         type?: string;
-        from?: number;
-        to?: number;
+        /** Required: the log is a ranged read by contract. Epoch milliseconds. */
+        from: number;
+        to: number;
         cursor?: string;
         limit?: number;
     }): Promise<EmittedEventsPage>;
@@ -3031,10 +3387,11 @@ declare class WebhooksApiService {
      * Every emitted event matching the filter, one at a time, fetching each
      * page only when the consumer reaches it.
      */
-    iterEvents(options?: {
+    iterEvents(options: {
         type?: string;
-        from?: number;
-        to?: number;
+        /** Required: the log is a ranged read by contract. Epoch milliseconds. */
+        from: number;
+        to: number;
         cursor?: string;
         limit?: number;
     }): AsyncGenerator<EmittedEvent>;
@@ -3047,6 +3404,158 @@ declare class WebhooksApiService {
     getEvent(id: string): Promise<EmittedEvent>;
 }
 
+/**
+ * The vocabulary the management REST families share on the wire.
+ *
+ * A role binding grants a scoped role, and the same three words appear on
+ * roles, role bindings, groups, teams and API keys. Declared once here so the
+ * CLI's flag parsers validate against one list rather than five copies that
+ * can disagree with the platform.
+ */
+/** The role a binding grants at its scope. `CUSTOM` defers to a custom role. */
+declare const MANAGEMENT_ROLES: readonly ["ADMIN", "MEMBER", "VIEWER", "CUSTOM"];
+type ManagementRole = (typeof MANAGEMENT_ROLES)[number];
+
+interface Team {
+    id: string;
+    name: string;
+    slug: string;
+    organizationId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TeamPagination {
+    page: number;
+    limit: number;
+    total: number;
+}
+interface ListTeamsResponse {
+    data: Team[];
+    pagination: TeamPagination;
+}
+interface ArchivedTeam {
+    id: string;
+    name: string;
+    archivedAt: string | null;
+}
+interface TeamMember {
+    userId: string | null;
+    name: string | null;
+    email: string | null;
+    role: ManagementRole;
+}
+declare class TeamsApiError extends Error {
+    readonly operation: string;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, operation: string, originalError?: unknown | undefined);
+}
+declare class TeamsApiService {
+    #private;
+    constructor(config?: {
+        endpoint?: string;
+        apiKey?: string;
+    });
+    list(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ListTeamsResponse>;
+    get(id: string): Promise<Team>;
+    create(input: {
+        name: string;
+    }): Promise<Team>;
+    update({ id, input, }: {
+        id: string;
+        input: {
+            name?: string;
+        };
+    }): Promise<Team>;
+    archive(id: string): Promise<ArchivedTeam>;
+    listMembers(teamId: string): Promise<{
+        data: TeamMember[];
+    }>;
+    addMember({ teamId, input, }: {
+        teamId: string;
+        input: {
+            userId: string;
+            role?: ManagementRole;
+        };
+    }): Promise<{
+        success: boolean;
+    }>;
+    removeMember({ teamId, userId, }: {
+        teamId: string;
+        userId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    language: string;
+    framework: string;
+    teamId: string;
+    piiRedactionLevel: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateProjectInput {
+    name: string;
+    language: string;
+    framework: string;
+    teamId?: string;
+    newTeamName?: string;
+}
+interface UpdateProjectInput {
+    name?: string;
+    language?: string;
+    framework?: string;
+    piiRedactionLevel?: "STRICT" | "ESSENTIAL" | "DISABLED";
+}
+interface ProjectWithServiceKey extends Project {
+    serviceApiKey: string;
+    serviceApiKeyId: string;
+}
+interface PaginatedProjects {
+    data: Project[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+interface ArchivedProject {
+    id: string;
+    name: string;
+    archivedAt: string;
+}
+declare class ProjectsApiError extends Error {
+    readonly operation: string;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, operation: string, originalError?: unknown | undefined);
+}
+declare class ProjectsApiService {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(config?: {
+        endpoint?: string;
+        apiKey?: string;
+    });
+    private headers;
+    private request;
+    list(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedProjects>;
+    get(id: string): Promise<Project>;
+    create(input: CreateProjectInput): Promise<ProjectWithServiceKey>;
+    update(id: string, input: UpdateProjectInput): Promise<Project>;
+    archive(id: string): Promise<ArchivedProject>;
+}
+
 interface GetTraceParams {
     includeSpans?: boolean;
 }
@@ -3124,6 +3633,21 @@ declare class LangWatch {
     readonly webhooks: WebhooksApiService;
     constructor(options?: LangWatchConstructorOptions);
     get apiClient(): LangwatchApiClient;
+    /**
+     * Teams, which group projects and the members who can reach them. These
+     * routes want an organization API key.
+     *
+     * Built on first use rather than in the constructor: the management
+     * families resolve their credential when constructed and refuse an empty
+     * one, so building this eagerly would make `new LangWatch()` throw for
+     * every caller that never touches a team.
+     */
+    get teams(): TeamsApiService;
+    /**
+     * Projects, including provisioning one with its own service API key. These
+     * routes want an organization API key.
+     */
+    get projects(): ProjectsApiService;
 }
 
 /**
@@ -3361,4 +3885,4 @@ declare const logger: {
     NoOpLogger: typeof NoOpLogger;
 };
 
-export { type BatchCreateRecordsResponse, type BudgetOnBreach, type BudgetScopeKind, type BudgetWindow, type CreateDatasetOptions, type CreateEvaluatorBody, type CreateFromUploadResponse, type CreateGatewayBudgetInput, type CreateGatewayBudgetScope, type CreateVirtualKeyInput, type CreateWebhookEndpointInput, type Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, type EmittedEvent, type EmittedEventsPage, type EndUserCap, type EndUserSpend, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, type ExperimentRowResult, type ExperimentRunWithResults, ExperimentsFacade, FetchPolicy, type GatewayBudget, type GatewayBudgetPage, GatewayBudgetsApiError, GatewayBudgetsApiService, type GetDatasetOptions, type GetPromptOptions, IDEMPOTENCY_KEY_HEADER, IDEMPOTENT_REPLAY_HEADER, type IdempotentCreateOptions, LangWatch, LangWatchApiError, LangWatchHandledError, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type LogOptions, type MutationOptions, type PaginatedResponse, type Pagination, type RunCallback, type RunContext, type RunOptions, type RunWithResultsOptions, type SpendEvent, type SpendEventStatus, SpendEventsApiError, SpendEventsApiService, type SpendEventsPage, type SpendReplayResult, type SpendSummariesPage, type SpendSummaryRow, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type UpdateDatasetOptions, type UpdateGatewayBudgetInput, type UpdateVirtualKeyInput, type UpdateWebhookEndpointInput, type UploadResponse, type VerifyWebhookSignatureOptions, type VirtualKey, type VirtualKeyBudgetInput, type VirtualKeyPage, type VirtualKeyRoutingMode, type VirtualKeyScope, type VirtualKeyScopeType, type VirtualKeySpendSummary, type VirtualKeyWithSecret, VirtualKeysApiError, VirtualKeysApiService, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_SIGNATURE_HEADER, type WebhookDeliveryPage, type WebhookDeliveryRecord, type WebhookEndpointHealth, type WebhookEndpointSummary, type WebhookEndpointWithSecret, type WebhookEventType, type WebhookSignatureFailureCode, WebhookSignatureVerificationError, type WebhookTestResult, WebhooksApiError, WebhooksApiService, isLangWatchHandledError, logger, verifyWebhookSignature };
+export { type ArchivedProject, type ArchivedTeam, type BatchCreateRecordsResponse, type BudgetOnBreach, type BudgetScopeKind, type BudgetWindow, ComparisonError, type ComparisonMetric, type ComparisonOptions, type ComparisonStatus, type ComparisonVerdict, type CreateDatasetOptions, type CreateEvaluatorBody, type CreateFromUploadResponse, type CreateGatewayBudgetInput, type CreateGatewayBudgetScope, type CreateProjectInput, type CreateVirtualKeyInput, type CreateWebhookEndpointInput, type Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, type EmittedEvent, type EmittedEventsPage, type EndUserCap, type EndUserSpend, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, type ExperimentRowResult, type ExperimentRunWithResults, ExperimentsFacade, FetchPolicy, type GatewayBudget, type GatewayBudgetPage, GatewayBudgetsApiError, GatewayBudgetsApiService, type GetDatasetOptions, type GetPromptOptions, IDEMPOTENCY_KEY_HEADER, IDEMPOTENT_REPLAY_HEADER, type IdempotentCreateOptions, LangWatch, LangWatchApiError, LangWatchHandledError, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type ListTeamsResponse, type LogOptions, type MutationOptions, type PaginatedProjects, type PaginatedResponse, type Pagination, type Project, type ProjectWithServiceKey, ProjectsApiError, ProjectsApiService, type RunCallback, type RunContext, type RunOptions, type RunWithResultsOptions, type SpendEvent, type SpendEventStatus, SpendEventsApiError, SpendEventsApiService, type SpendEventsPage, type SpendFilterOptions, type SpendGroupBy, type SpendReplayResult, type SpendSummariesOptions, type SpendSummariesPage, type SpendSummaryRow, type SpendSummaryStatus, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type Team, type TeamMember, type TeamPagination, TeamsApiError, TeamsApiService, type UpdateDatasetOptions, type UpdateGatewayBudgetInput, type UpdateProjectInput, type UpdateVirtualKeyInput, type UpdateWebhookEndpointInput, type UploadResponse, type VerifyWebhookSignatureOptions, type VirtualKey, type VirtualKeyBudgetInput, type VirtualKeyPage, type VirtualKeyRoutingMode, type VirtualKeyScope, type VirtualKeyScopeType, type VirtualKeySpendSummary, type VirtualKeyWithSecret, VirtualKeysApiError, VirtualKeysApiService, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_SIGNATURE_HEADER, type WebhookDeliveryPage, type WebhookDeliveryRecord, type WebhookEndpointHealth, type WebhookEndpointSummary, type WebhookEndpointWithSecret, type WebhookEventType, type WebhookSignatureFailureCode, WebhookSignatureVerificationError, type WebhookTestResult, WebhooksApiError, WebhooksApiService, isLangWatchHandledError, logger, verifyWebhookSignature };