langwatch 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.js';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, a as getLangWatchTracer } from './implementation-Psro9xt4.js';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, a as getLangWatchTracer } from './implementation-D_v0fUvU.js';
 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-DGBGlP9B.js';
+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-av2kmt_i.js';
 import openApiCreateClient from 'openapi-fetch';
 export { l as attributes } from './types-VOZv9LYO.js';
 import { CliHandledErrorReason, CliHandledError } from '@langwatch/langy/cards/handled-error';
@@ -28,7 +28,7 @@ declare const localPromptConfigSchema: z.ZodObject<{
         }>;
         content: z.ZodString;
     }, z.core.$loose>>;
-    parameters: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    parameters: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>>;
 }, z.core.$loose>;
 type LocalPromptConfig = z.infer<typeof localPromptConfigSchema>;
 
@@ -39,7 +39,16 @@ type PromptDependency = string | {
 type PromptsConfig = {
     prompts: Record<string, PromptDependency>;
 };
-type RuntimeParameters = Record<string, unknown>;
+/**
+ * A JSON value: what runtime parameters actually persist and what the API
+ * schema declares (the spec's recursive JsonValue component). Structurally
+ * identical to the generated client's RecursiveJsonValue, so values flow
+ * between hand-written and generated types without casts.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type RuntimeParameters = Record<string, JsonValue>;
 type MaterializedPrompt = {
     id: string;
     name: string;
@@ -2064,184 +2073,69 @@ declare class SecretsApiService {
     delete(id: string): Promise<SecretDeleteResponse>;
 }
 
-interface GetTraceParams {
-    includeSpans?: boolean;
-}
-type GetTraceResponse = NonNullable<paths["/api/trace/{id}"]["get"]["responses"]["200"]["content"]["application/json"]>;
-
-declare class TracesFacade {
-    #private;
-    constructor(config: InternalConfig);
-    get(traceId: string, params?: GetTraceParams): Promise<GetTraceResponse>;
-}
-
-interface LangWatchConstructorOptions {
-    apiKey?: string;
-    endpoint?: string;
-    options?: {
-        logger?: Logger;
-    };
-}
-declare class LangWatch {
-    #private;
-    private readonly config;
-    readonly prompts: PromptsFacade;
-    readonly traces: TracesFacade;
-    readonly datasets: DatasetsFacade;
-    /**
-     * Run experiments on LangWatch platform or via SDK.
-     *
-     * Platform experiments (CI/CD):
-     * ```typescript
-     * const result = await langwatch.experiments.run("my-experiment-slug");
-     * result.printSummary();
-     * ```
-     *
-     * SDK-defined experiments:
-     * ```typescript
-     * const experiment = await langwatch.experiments.init("my-experiment");
-     * // ... run evaluators using experiment.evaluate()
-     * ```
-     */
-    readonly experiments: ExperimentsFacade;
-    /**
-     * Run evaluators and guardrails in real-time (Online Evaluations).
-     *
-     * @example
-     * ```typescript
-     * const guardrail = await langwatch.evaluations.evaluate("presidio/pii_detection", {
-     *   data: { input: userInput, output: generatedResponse },
-     *   name: "PII Detection",
-     *   asGuardrail: true,
-     * });
-     *
-     * if (!guardrail.passed) {
-     *   return "I'm sorry, I can't do that.";
-     * }
-     * ```
-     */
-    readonly evaluations: EvaluationsFacade;
-    readonly evaluators: EvaluatorsApiService;
-    readonly scenarios: ScenariosApiService;
-    readonly suites: SuitesApiService;
-    readonly workflows: WorkflowsApiService;
-    readonly agents: AgentsApiService;
-    readonly annotations: AnnotationsApiService;
-    readonly dashboards: DashboardsApiService;
-    readonly modelProviders: ModelProvidersApiService;
-    readonly analytics: AnalyticsApiService;
-    readonly triggers: TriggersApiService;
-    readonly graphs: GraphsApiService;
-    readonly simulationRuns: SimulationRunsApiService;
-    readonly monitors: MonitorsApiService;
-    readonly secrets: SecretsApiService;
-    constructor(options?: LangWatchConstructorOptions);
-    get apiClient(): LangwatchApiClient;
-}
-
 /**
- * A failure the platform NAMED.
- *
- * The API does not merely fail — when it declines a request it says precisely
- * why, as a `HandledError` with a serialisable `kind` (`dataset_not_found`,
- * `validation_error`), the HTTP status it answers with, and a `meta` bag of the
- * context that makes the failure actionable. Until now the SDK collapsed all of
- * that into an English sentence on a generic error, so a caller could read the
- * failure but never react to it: a 404 "dataset not found" — a fact you can
- * offer to fix — was indistinguishable from a 500.
- *
- * This is that structure, kept. Narrow with {@link isLangWatchHandledError} (or
- * `instanceof`) and switch on `code`; `body` is the escape hatch to whatever the
- * platform sent that this class did not model.
+ * The per-call options every mutating call on the billing surfaces takes.
  *
- * ```ts
- * try {
- *   await langwatch.datasets.get("nope");
- * } catch (error) {
- *   if (isLangWatchHandledError(error) && error.code === "dataset_not_found") {
- *     // Actionable: we know WHAT was not found, and can offer the list.
- *     console.error(error.meta.id, error.traceId);
- *   }
- *   throw error;
- * }
- * ```
+ * WHERE THEY GO. A call whose arguments already ride in an options bag
+ * (`disable(id, { reason })`, `reset(id, { endUserId })`) gains these fields in
+ * that same bag: one bag per call is what a caller expects. A call that takes a
+ * request BODY (`create(input)`, `update(id, input)`) gets a separate trailing
+ * parameter instead, because those body types mirror the wire verbatim and must
+ * not grow keys the wire has never heard of.
  *
- * ONLY raised for a failure the platform named. An infrastructure failure — a
- * 5xx, a dead socket, a proxy's HTML error page — still raises the generic
- * service error it always did, because presenting one of those as a domain
- * error would blame the user for our outage.
+ * They are an interface rather than a bare `signal` so that the next thing a
+ * call needs per invocation is an added field rather than an added parameter.
  */
-declare class LangWatchHandledError extends Error {
+/** The request header the control plane deduplicates creates on. */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * The response header a replayed create carries. Only ever `"true"`, and
+ * ABSENT rather than false on a first execution, so its presence is the whole
+ * signal.
+ */
+declare const IDEMPOTENT_REPLAY_HEADER = "X-Idempotent-Replay";
+interface MutationOptions {
     /**
-     * The discriminant. A boolean brand rather than `instanceof` alone because a
-     * bundled CLI and a consumer's `node_modules` copy of the SDK can hold two
-     * different copies of this class, and `instanceof` is false across that seam —
-     * the same reason the platform's own error handler tests for `code` rather
-     * than class identity.
+     * Cancel the call. Without one, the request is bounded by the SDK's own
+     * 30 second timeout so a hung control plane fails rather than freezes.
      */
-    readonly isLangWatchHandledError: true;
-    /** The platform's serialisable discriminant, e.g. `dataset_not_found`. */
-    readonly code: string;
+    signal?: AbortSignal;
+}
+interface IdempotentCreateOptions extends MutationOptions {
     /**
-     * @deprecated Back-compat alias of `code`, kept while the platform's
-     * `DomainError` → `HandledError` rename rolls out. Read `code` in new code.
+     * Makes the create safe to retry. A dropped connection after the write but
+     * before the response looks exactly like a dropped request, and sending it
+     * again without a key mints a SECOND resource. Send the same key on the
+     * retry and the server answers with the first response instead, byte for
+     * byte, including the one-time secret a create hands back.
+     *
+     * Any string of 8 to 255 characters; a UUID minted per logical create is the
+     * usual choice. Receipts answer for 24 hours, and only successful creates
+     * leave one, so a create that failed is safe to run again either way.
+     *
+     * Reusing a key with a DIFFERENT body is refused with `idempotency_error`
+     * rather than quietly answering for the wrong request.
      */
-    readonly kind: string;
-    /** The status the platform answered with. */
-    readonly httpStatus: number;
-    /** The context the platform attached: ids, field errors — whatever makes it actionable. */
-    readonly meta: Record<string, unknown>;
-    /** The OTel trace to quote at support. Absent unless the route sent one. */
-    readonly traceId: string | undefined;
-    /** A clickable link to that trace, when the route sent one. */
-    readonly traceUrl: string | undefined;
-    /** A clickable link to the logs for that trace, when the route sent one. */
-    readonly logsUrl: string | undefined;
-    /** The failure behind the failure, when the route sent the chain. */
-    readonly reasons: CliHandledErrorReason[] | undefined;
-    /** What the user can DO about it, when the platform sent next steps. */
-    readonly suggestions: string[] | undefined;
-    /** The docs page that explains the failure, when the platform sent one. */
-    readonly docUrl: string | undefined;
-    /** The raw response body, verbatim — the escape hatch for anything unmodelled. */
-    readonly body: unknown;
-    /** What the SDK was doing, e.g. `get dataset "abc"`. */
-    readonly operation: string | undefined;
+    idempotencyKey?: string;
     /**
-     * Alias of {@link httpStatus}, and the raw body again under the name the
-     * per-service `*ApiError` classes use.
+     * Called when the response came from a receipt rather than a fresh write,
+     * i.e. this exact create had already succeeded.
      *
-     * Not redundancy for its own sake: this class is thrown from the SAME code
-     * path that used to throw `TracesApiError` & friends, so anything that reads
-     * `.status` or `.originalError` off a caught SDK error — including the CLI's
-     * own telemetry reader — keeps working unchanged.
+     * A hook rather than a field on the returned resource: the resource is
+     * identical either way, so nothing about handling it changes, and the
+     * distinction is something a caller logs rather than branches on. Keeping it
+     * off the return type also keeps the wire-shaped entities free of fields the
+     * wire does not have.
      */
-    readonly status: number;
-    readonly originalError: unknown;
-    constructor({ handled, body, operation, message, }: {
-        handled: CliHandledError;
-        body: unknown;
-        operation?: string;
-        message: string;
-    });
-}
-/** Narrows any caught value to a {@link LangWatchHandledError}. */
-declare const isLangWatchHandledError: (error: unknown) => error is LangWatchHandledError;
-declare class LangWatchApiError extends Error {
-    readonly httpStatus: number;
-    readonly httpStatusText: string;
-    apiError: string | undefined;
-    body: unknown;
-    constructor(message: string, response: Response);
-    safeParseBody(response: Response): Promise<void>;
+    onIdempotentReplay?: () => void;
 }
 
-type VirtualKeyScopeType = "ORGANIZATION" | "TEAM" | "PROJECT";
+type VirtualKeyScopeType = "organization" | "team" | "project";
 interface VirtualKeyScope {
     scope_type: VirtualKeyScopeType;
     scope_id: string;
 }
-type VirtualKeyRoutingMode = "NONE" | "FALLBACK_ALL" | "POLICY";
+type VirtualKeyRoutingMode = "none" | "fallback_all" | "policy";
 /**
  * The snake DTO the server returns (`toVirtualKeySnakeDto`). The token
  * format is `vk-lw-<ulid>` with no live/test discriminator; the gateway
@@ -2252,7 +2146,8 @@ interface VirtualKey {
     organization_id: string;
     name: string;
     description: string | null;
-    status: "active" | "revoked";
+    /** `disabled` is the reversible stop; `revoked` is terminal. */
+    status: "active" | "disabled" | "revoked";
     /** "langy" marks a product-managed key; customers can only mint "user". */
     purpose: "user" | "langy";
     /** e.g. "vk-lw-01HZX9" — the only secret material kept after creation. */
@@ -2280,8 +2175,8 @@ interface VirtualKey {
  */
 interface VirtualKeyBudgetInput {
     limit_usd: string | number;
-    window: "DAY" | "WEEK" | "MONTH";
-    on_breach?: "BLOCK" | "WARN";
+    window: "day" | "week" | "month";
+    on_breach?: "block" | "warn";
     name?: string;
 }
 interface CreateVirtualKeyInput {
@@ -2300,6 +2195,18 @@ interface CreateVirtualKeyInput {
     /** Optional cap created atomically with the key. */
     budget?: VirtualKeyBudgetInput | null;
     config?: Record<string, unknown>;
+    /**
+     * Your own identifier for this key, unique within the organization. Lets
+     * you look the key up by the id your system already has instead of storing
+     * ours alongside it.
+     */
+    external_id?: string | null;
+    /**
+     * Free-form string labels, up to 40 of them. Sent WHOLE on an update: the
+     * map you pass replaces the stored one rather than merging into it, and
+     * `{}` clears it.
+     */
+    metadata?: Record<string, string>;
 }
 interface UpdateVirtualKeyInput {
     name?: string;
@@ -2311,19 +2218,43 @@ interface UpdateVirtualKeyInput {
     /** Undefined leaves the cap alone; a value upserts it; null archives it. */
     budget?: VirtualKeyBudgetInput | null;
     config?: Record<string, unknown>;
+    /**
+     * Your own identifier for this key, unique within the organization. Lets
+     * you look the key up by the id your system already has instead of storing
+     * ours alongside it.
+     */
+    external_id?: string | null;
+    /**
+     * Free-form string labels, up to 40 of them. Sent WHOLE on an update: the
+     * map you pass replaces the stored one rather than merging into it, and
+     * `{}` clears it.
+     */
+    metadata?: Record<string, string>;
 }
 interface VirtualKeyWithSecret {
     virtual_key: VirtualKey;
     secret: string;
 }
+/** One page of the virtual-key listing, exactly as the wire serves it. */
+interface VirtualKeyPage {
+    data: VirtualKey[];
+    /**
+     * Pass back as `cursor` for the next page. Null means the walk is
+     * exhausted. Neither page length tells you anything here: visibility is
+     * applied to each page AFTER it is read, so a page can hold fewer rows
+     * than `limit` with more still to come.
+     */
+    next_cursor: string | null;
+}
 /** Aggregate spend for one key over a window, from the cost path. */
 interface VirtualKeySpendSummary {
     virtual_key_id: string;
     spent_usd: string;
     requests: number;
+    /** Epoch milliseconds, the unit every spend surface takes and returns. */
     window: {
-        from: string;
-        to: string;
+        from: number;
+        to: number;
     };
 }
 declare class VirtualKeysApiError extends Error {
@@ -2331,35 +2262,102 @@ declare class VirtualKeysApiError extends Error {
     readonly originalError?: unknown | undefined;
     constructor(message: string, operation: string, originalError?: unknown | undefined);
 }
+/**
+ * Client for the gateway virtual-key surface (/api/gateway/v1).
+ *
+ * Entity types and the create/update bodies mirror the wire verbatim, so
+ * their fields are lowercase snake_case. Call options this SDK invents (query
+ * filters, per-call behaviour, action arguments) are camelCase like the rest
+ * of the SDK.
+ */
 declare class VirtualKeysApiService {
     private readonly endpoint;
     private readonly apiKey;
+    private readonly projectId;
     constructor(config?: {
         endpoint?: string;
         apiKey?: string;
+        projectId?: string;
     });
     private headers;
     private request;
-    list(): Promise<VirtualKey[]>;
+    /**
+     * ONE page of the virtual keys visible to the caller, newest first. Pass
+     * `next_cursor` back as `cursor` for the next page, verbatim: a cursor this
+     * endpoint did not issue answers 400 rather than restarting the walk.
+     *
+     * `limit` is the page size (server default 50, capped at 200), and it caps
+     * the rows READ, not the rows returned: the visibility filter runs on the
+     * page afterwards. Prefer `list()` unless you mean to page deliberately.
+     */
+    listPage(options?: {
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): Promise<VirtualKeyPage>;
+    /**
+     * Every virtual key visible to the caller: keys scoped to this project, to
+     * its team, or to the whole organization.
+     *
+     * The endpoint pages; this follows `next_cursor` until it comes back null.
+     * Stopping on a short page would be wrong here specifically, because the
+     * server filters each page for visibility after reading it, so a page can
+     * hold fewer rows than the limit with more still to come.
+     *
+     * `limit` sizes each request in the walk, it does NOT cap what comes back.
+     * `cursor` resumes an interrupted walk. Take a single page with
+     * `listPage()`, or stream the walk with `iterate()`.
+     */
+    list(options?: {
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): Promise<VirtualKey[]>;
+    /**
+     * Every visible virtual key, one row at a time, fetching each page only
+     * when the consumer reaches it. Stop early and the rest is never read,
+     * which `list()` cannot offer because it materialises the whole listing
+     * first. Raises rather than looping forever on a cursor chain that never
+     * ends, exactly like `list()`.
+     */
+    iterate(options?: {
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): AsyncGenerator<VirtualKey>;
     get(id: string): Promise<VirtualKey>;
-    create(input: CreateVirtualKeyInput): Promise<VirtualKeyWithSecret>;
-    update(id: string, input: UpdateVirtualKeyInput): Promise<VirtualKey>;
-    rotate(id: string): Promise<VirtualKeyWithSecret>;
-    revoke(id: string): Promise<VirtualKey>;
-    /**
-     * Aggregate spend for one key. Defaults to the current UTC calendar
-     * month server-side. Reads the same cost path the dashboard reads, so
-     * this number and the UI agree by construction.
-     */
-    spend(id: string, window?: {
-        from?: string;
-        to?: string;
+    /**
+     * Mint a key. The response carries the secret ONCE; nothing ever serves it
+     * again, so a create that times out is recovered with `idempotencyKey`
+     * rather than by listing.
+     */
+    create(input: CreateVirtualKeyInput, options?: IdempotentCreateOptions): Promise<VirtualKeyWithSecret>;
+    update(id: string, input: UpdateVirtualKeyInput, options?: MutationOptions): Promise<VirtualKey>;
+    rotate(id: string, options?: MutationOptions): Promise<VirtualKeyWithSecret>;
+    revoke(id: string, options?: MutationOptions): Promise<VirtualKey>;
+    /** Reversible stop; enable() restores the key exactly as it was. */
+    disable(id: string, options?: {
+        reason?: string;
+    } & MutationOptions): Promise<VirtualKey>;
+    enable(id: string, options?: MutationOptions): Promise<VirtualKey>;
+    /**
+     * Aggregate spend for one key over a window in epoch milliseconds.
+     * Defaults to the current UTC calendar month server-side. Reads the same
+     * cost path the dashboard reads, so this number and the UI agree by
+     * construction.
+     */
+    spend(id: string, options?: {
+        from?: number;
+        to?: number;
     }): Promise<VirtualKeySpendSummary>;
 }
 
-type BudgetScopeKind = "ORGANIZATION" | "TEAM" | "PROJECT" | "VIRTUAL_KEY" | "PRINCIPAL" | "GROUP";
-type BudgetWindow = "MINUTE" | "HOUR" | "DAY" | "WEEK" | "MONTH" | "TOTAL";
-type BudgetOnBreach = "BLOCK" | "WARN";
+type BudgetScopeKind = "organization" | "team" | "project" | "virtual_key" | "principal" | "group" | "attributed_user";
+type BudgetWindow = "minute" | "hour" | "day" | "week" | "month" | "total" | "manual";
+type BudgetOnBreach = "block" | "warn";
 interface GatewayBudget {
     id: string;
     organization_id: string;
@@ -2370,49 +2368,82 @@ interface GatewayBudget {
     window: BudgetWindow;
     on_breach: BudgetOnBreach;
     /**
-     * For GROUP rows this is the PER-MEMBER allowance, not a group total;
+     * For `group` rows this is the PER-MEMBER allowance, not a group total;
      * `spent_usd` sums the whole group and `member_count` says how many
-     * members the allowance currently covers.
+     * members the allowance currently covers. For `attributed_user` rows it is
+     * the PER-PERSON cap, and `end_users_seen` / `end_users_over` carry the
+     * standing instead of `spent_usd`.
      */
     limit_usd: string;
-    spent_usd: string;
+    /** Canonical integer limit, nano-USD. Null past the safe integer range. */
+    limit_nano_usd: number | null;
+    /**
+     * Display value. NULL when `spend_available` is false: spend could not be
+     * totalled, so there is no figure, and the API sends null rather than a
+     * stale one a caller could mistake for real money.
+     */
+    spent_usd: string | null;
+    /** Canonical integer spend, nano-USD. Null whenever `spent_usd` is. */
+    spent_nano_usd: number | null;
     timezone: string | null;
     /** ModelProvider id the budget counts; null counts every provider. */
     provider_key: string | null;
     current_period_started_at: string;
     resets_at: string;
+    /** Instant the cycle is phased from; null means calendar aligned. */
+    cycle_anchor_at: string | null;
     last_reset_at: string | null;
     archived_at: string | null;
     created_at: string;
-    /** GROUP rows only. */
+    /** `group` rows only. */
     member_count?: number;
+    /** `attributed_user` rows only: end users with spend this period. */
+    end_users_seen?: number;
+    /** `attributed_user` rows only: how many of those are at or over the cap. */
+    end_users_over?: number;
 }
-interface GatewayBudgetList {
-    budgets: GatewayBudget[];
+/**
+ * One page of the budget listing, exactly as the wire serves it.
+ *
+ * Budgets come back in an envelope where virtual keys come back as a bare
+ * array because `spend_available` is a correctness flag about the whole page,
+ * and an array cannot carry it.
+ */
+interface GatewayBudgetPage {
+    data: GatewayBudget[];
     /**
-     * False when spend could not be totalled — render "unavailable" rather
+     * False when spend could not be totalled: render "unavailable" rather
      * than trusting `spent_usd` as real spend.
      */
     spend_available: boolean;
+    /**
+     * Pass back as `cursor` for the next page. Null means the walk is
+     * exhausted; a FULL page does not by itself mean there is more.
+     */
+    next_cursor: string | null;
 }
 type CreateGatewayBudgetScope = {
-    kind: "ORGANIZATION";
+    kind: "organization";
     organization_id: string;
 } | {
-    kind: "TEAM";
+    kind: "team";
     team_id: string;
 } | {
-    kind: "PROJECT";
+    kind: "project";
     project_id: string;
 } | {
-    kind: "VIRTUAL_KEY";
+    kind: "virtual_key";
     virtual_key_id: string;
 } | {
-    kind: "PRINCIPAL";
+    kind: "principal";
     principal_user_id: string;
 } | {
-    kind: "GROUP";
+    kind: "group";
     group_id: string;
+} | {
+    kind: "attributed_user";
+    anchor_virtual_key_id?: string;
+    anchor_project_id?: string;
 };
 interface CreateGatewayBudgetInput {
     scope: CreateGatewayBudgetScope;
@@ -2424,6 +2455,24 @@ interface CreateGatewayBudgetInput {
     timezone?: string | null;
     /** ModelProvider id to pin the budget to one provider. */
     provider_key?: string | null;
+    /**
+     * RFC3339 instant that phases the budget's cycle instead of the calendar:
+     * a `month` budget anchored `2026-01-17T09:00:00Z` rolls every 17th at
+     * 09:00 UTC. Omit for calendar alignment. Immutable once created, and
+     * rejected on the windows that never cycle (`total`, `manual`).
+     */
+    cycle_anchor_at?: string;
+    /**
+     * Your own identifier for this budget. Lets you look it up by the id your
+     * system already has instead of storing ours alongside it.
+     */
+    external_id?: string | null;
+    /**
+     * Free-form string labels, up to 40 of them. Sent WHOLE on an update: the
+     * map you pass replaces the stored one rather than merging into it, and
+     * `{}` clears it.
+     */
+    metadata?: Record<string, string>;
 }
 interface UpdateGatewayBudgetInput {
     name?: string;
@@ -2437,30 +2486,879 @@ declare class GatewayBudgetsApiError extends Error {
     readonly originalError?: unknown | undefined;
     constructor(message: string, operation: string, originalError?: unknown | undefined);
 }
+/**
+ * Client for the gateway budget surface (/api/gateway/v1).
+ *
+ * Entity types and the create/update bodies mirror the wire verbatim, so
+ * their fields are lowercase snake_case. Call options this SDK invents (query
+ * filters, per-call behaviour, action arguments) are camelCase like the rest
+ * of the SDK.
+ */
 declare class GatewayBudgetsApiService {
     private readonly endpoint;
     private readonly apiKey;
+    private readonly projectId;
     constructor(config?: {
         endpoint?: string;
         apiKey?: string;
+        projectId?: string;
     });
     private headers;
     private request;
     /**
-     * Every non-archived budget in the organization across all six scope
+     * ONE page of non-archived budgets, exactly as the wire serves it. Pass
+     * `next_cursor` back as `cursor` for the next page, verbatim: a cursor this
+     * endpoint did not issue answers 400 rather than restarting the walk.
+     *
+     * `limit` is the page size (server default 50, capped at 200). Prefer
+     * `list()` unless you mean to page deliberately: a full page is not a
+     * promise of more, and a null `next_cursor` is the only end of the walk.
+     */
+    listPage(options?: {
+        scopeTypes?: BudgetScopeKind[];
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): Promise<GatewayBudgetPage>;
+    /**
+     * Every non-archived budget in the organization across all seven scope
      * types, optionally filtered by `scopeTypes`.
+     *
+     * The endpoint pages; this follows `next_cursor` until it comes back null,
+     * so the result is the complete listing and carries no cursor of its own.
+     * Callers that count, total, or decide an all-clear on this list need that
+     * completeness for correctness, not just for display.
+     *
+     * `limit` sizes each request in the walk, it does NOT cap what comes back.
+     * `cursor` resumes an interrupted walk. Take a single page with
+     * `listPage()`, or stream the walk with `iterate()`.
+     *
+     * A plain array, like every other exhaustive `list()` in the SDK: a walk
+     * that ran to the end has no cursor left to report. Null `spent_usd` /
+     * `spent_nano_usd` on a row is not by itself "spend unavailable": an
+     * `attributed_user` template row serves null deliberately, because one
+     * allowance per person has no single total. Use `listPage()` when you need
+     * `spend_available` stated outright.
      */
     list(options?: {
         scopeTypes?: BudgetScopeKind[];
-    }): Promise<GatewayBudgetList>;
-    create(input: CreateGatewayBudgetInput): Promise<GatewayBudget>;
-    update(id: string, input: UpdateGatewayBudgetInput): Promise<GatewayBudget>;
-    archive(id: string): Promise<GatewayBudget>;
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): Promise<GatewayBudget[]>;
+    /**
+     * Every non-archived budget, one row at a time, fetching each page only
+     * when the consumer reaches it.
+     *
+     * A null `spent_usd` means spend could not be totalled rather than that
+     * nothing was spent.
+     */
+    iterate(options?: {
+        scopeTypes?: BudgetScopeKind[];
+        cursor?: string;
+        limit?: number;
+        /** Exact match on your own identifier, not a prefix or a search. */
+        externalId?: string;
+    }): AsyncGenerator<GatewayBudget>;
+    /**
+     * One budget by id, in the same row shape the listing serves.
+     *
+     * Archived budgets are not served, so a budget that existed yesterday can
+     * answer 404 today. A null `spent_usd` means spend could not be totalled
+     * rather than that nothing was spent, which is the same signal the listing
+     * carries as `spend_available`.
+     */
+    get(id: string): Promise<GatewayBudget>;
+    create(input: CreateGatewayBudgetInput, options?: IdempotentCreateOptions): Promise<GatewayBudget>;
+    update(id: string, input: UpdateGatewayBudgetInput, options?: MutationOptions): Promise<GatewayBudget>;
+    archive(id: string, options?: MutationOptions): Promise<GatewayBudget>;
+    /**
+     * Move the budget's period boundary to now. Recorded spend is never
+     * mutated; with `endUserId` only that end-user bucket's boundary moves.
+     */
+    reset(id: string, options?: {
+        endUserId?: string;
+        reason?: string;
+    } & MutationOptions): Promise<GatewayBudget>;
+}
+
+interface SpendEvent {
+    id: string;
+    type: string;
+    created: string;
+    schema_version: string;
+    data: {
+        /** Type-suffixed, unique per (request, event type): a settled and a
+         *  completed event for one request never share an id. */
+        event_id: string;
+        /** "gateway.request.completed" (confirmed and failed outcomes) or
+         *  "gateway.request.settled" (confirmation never arrived). */
+        event_type: string;
+        /** The join key across a settled/completed pair: a completed event
+         *  SUPERSEDES an earlier settled one for the same request; replace the
+         *  figure, never sum the pair. */
+        gateway_request_id: string;
+        occurred_at: string;
+        organization_id: string;
+        project_id: string;
+        virtual_key_id: string;
+        principal_user_id: string | null;
+        end_user_id: string | null;
+        trace_id: string;
+        model: string | null;
+        model_provider_id: string | null;
+        request_type: string | null;
+        /** Null on settled events: unknown is not zero. */
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_input_tokens: number;
+            cache_creation_input_tokens: number;
+            reasoning_tokens: number;
+        } | null;
+        /** Null on settled events: unknown is not zero. */
+        cost: {
+            total_usd: string;
+            nano_usd: number;
+            rate_version: string | null;
+        } | null;
+        /** "success" | "error" on completed events, "settled" on settled ones. */
+        status: string;
+        needs_reconciliation: boolean | null;
+        settle_reason: string | null;
+        error: {
+            class: string;
+            http_status: number | null;
+        } | null;
+        duration_ms: number | null;
+        labels: string[];
+        metadata: Record<string, unknown>;
+    };
+}
+interface SpendSummaryRow {
+    key: string;
+    /** Priced outcomes (confirmed and failed). */
+    event_count: number;
+    /** Unpriced settled requests, counted separately: never in cost sums. */
+    settled_count: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens: number;
+        cache_creation_input_tokens: number;
+        reasoning_tokens: number;
+    };
+    cost: {
+        total_usd: string;
+        nano_usd: number;
+    };
+}
+/**
+ * The states a request can be filtered by, which is more than the two a
+ * caller usually thinks in: a request is `admitted` when it starts,
+ * `confirmed` or `failed` when it ends, and `settled` once its cost is final.
+ * `success` and `error` are the coarse outcome pair over those.
+ */
+type SpendEventStatus = "success" | "error" | "admitted" | "confirmed" | "failed" | "settled";
+interface SpendSummariesPage {
+    data: SpendSummaryRow[];
+    /**
+     * Pass back as `cursor` for the next page; null means the walk is done.
+     * A full page does NOT mean there is more, so follow this until null
+     * rather than stopping when a page comes back short.
+     */
+    next_cursor: string | null;
+}
+interface SpendEventsPage {
+    data: SpendEvent[];
+    next_cursor: string | null;
+}
+interface SpendReplayResult {
+    endpoint_id: string;
+    replay_id: string;
+    replayed: number;
+    window: {
+        from: string;
+        to: string;
+    };
+}
+interface EndUserSpend {
+    end_user_id: string;
+    window: string;
+    from: string;
+    to: string;
+    cost: {
+        total_usd: string;
+        nano_usd?: number;
+    };
+    request_count: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_input_tokens: number;
+        cache_creation_input_tokens: number;
+        reasoning_tokens: number;
+    };
+    /**
+     * The attributed-user template caps that apply to this end user, each
+     * with its boundary-aware current-period spend. Empty when the
+     * organization runs no templates; never null.
+     */
+    caps: EndUserCap[];
 }
+interface EndUserCap {
+    budget_id: string;
+    anchor_id: string;
+    window: string;
+    on_breach: "block" | "warn";
+    limit_usd: string;
+    spent_usd: string;
+    period_started_at: string;
+}
+declare class SpendEventsApiError extends Error {
+    readonly operation: string;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, operation: string, originalError?: unknown | undefined);
+}
+/**
+ * Client for the gateway spend reconciliation surface (/api/gateway/v1).
+ * Authenticates with an ORGANIZATION API key (sk-lw-*).
+ *
+ * Entity types mirror the wire verbatim, so their fields are lowercase
+ * snake_case. Call options this SDK invents (query filters, per-call
+ * behaviour, action arguments) are camelCase like the rest of the SDK.
+ *
+ * There is no project id here: `/spend-summaries` takes `project_id` as a
+ * query filter rather than scoping on a header, so the project belongs to the
+ * call, not to the client.
+ *
+ * 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:
+ * take pages, or stream with `iterate()` / `iterSummaries()`.
+ */
+declare class SpendEventsApiService {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(config?: {
+        endpoint?: string;
+        apiKey?: string;
+    });
+    private request;
+    /**
+     * ONE page of the per-request spend ledger for a window. Pass `next_cursor`
+     * back as `cursor` for the next page, verbatim.
+     *
+     * A full page does NOT mean there is more and a short page does NOT mean
+     * there is no more: only a null cursor ends the walk. A reconciler that
+     * stops on the first page silently under-counts the window, so read every
+     * page or stream them with `iterate()`.
+     */
+    listPage(options: {
+        /** 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
+     * only when the consumer reaches it.
+     *
+     * This is how a reconciler reads a whole window without holding it: the
+     * ledger is unbounded, so there is deliberately no eager `list()` to
+     * collect it into an array. Raises rather than looping forever on a cursor
+     * chain that never ends.
+     */
+    iterate(options: {
+        /** 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
+     * ascending.
+     *
+     * The page is a step of a walk, not a whole answer: follow `next_cursor`
+     * until it comes back null, or stream the walk with `iterSummaries()`. A
+     * 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;
+        cursor?: string;
+        limit?: number;
+    }): Promise<SpendSummariesPage>;
+    /**
+     * Every rollup row for the window, one at a time, fetching each page only
+     * when the consumer reaches it.
+     *
+     * The rollup has one row per tenant seen in the window, which no bound
+     * 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;
+        cursor?: string;
+        limit?: number;
+    }): AsyncGenerator<SpendSummaryRow>;
+    /**
+     * Re-deliver a window's spend envelopes to ONE endpoint through the
+     * normal delivery path. Envelope ids are unchanged (your consumer's
+     * dedup key); mind your downstream billing system's finite dedup
+     * window before replaying old ranges. The window is capped server-side
+     * at 7 days per call.
+     */
+    replay(options: {
+        from: number;
+        to: number;
+        endpointId: string;
+    } & MutationOptions): Promise<SpendReplayResult>;
+    endUserSpend(endUserId: string, options?: {
+        window?: "day" | "week" | "month";
+        from?: number;
+        to?: number;
+        virtualKeyId?: string;
+    }): Promise<EndUserSpend>;
+}
+
+interface WebhookEndpointSummary {
+    id: string;
+    url: string;
+    max_batch_size: number;
+    max_batch_delay_ms: number;
+    max_in_flight: number;
+    enabled_events: string[];
+    status: "active" | "disabled";
+    disabled_reason: string | null;
+    disabled_at: string | null;
+    failing_since: string | null;
+    last_success_at: string | null;
+    last_failure_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+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;
+    enabled_events: string[];
+    /** Envelopes per delivery. The receiver always gets an array. */
+    max_batch_size?: number;
+    /** How long a partial batch waits for company before it is sent. */
+    max_batch_delay_ms?: number;
+    /** Concurrent in-flight deliveries to this endpoint. */
+    max_in_flight?: number;
+}
+/** The PATCH body, exactly as the wire takes it. Omitted fields are left alone. */
+interface UpdateWebhookEndpointInput {
+    url?: string;
+    enabled_events?: string[];
+    status?: "active" | "disabled";
+    max_batch_size?: number;
+    max_batch_delay_ms?: number;
+    max_in_flight?: number;
+}
+interface WebhookDeliveryRecord {
+    id: string;
+    dispatch_id: string;
+    attempt: number;
+    event_count: number;
+    outcome: string;
+    response_status: number | null;
+    latency_ms: number | null;
+    error: string | null;
+    fired_at: string;
+}
+interface WebhookTestResult {
+    delivered: boolean;
+    response_status: number | null;
+    response_body?: string;
+    error?: string;
+}
+interface WebhookEndpointHealth {
+    status: "active" | "disabled";
+    disabled_reason: string | null;
+    failing_since: string | null;
+    last_success_at: string | null;
+    last_failure_at: string | null;
+    /** The headline: age of the oldest envelope still buffered or retrying;
+     *  null when the feed is fully delivered. */
+    oldest_undelivered_age_ms: number | null;
+    dlq_depth: number;
+    sends_per_minute: number;
+    success_rate: number | null;
+    p95_latency_ms: number | null;
+}
+interface WebhookEventType {
+    type: string;
+    family: string;
+    schema_version: string;
+    is_emitting: boolean;
+    description: string;
+}
+interface EmittedEvent {
+    id: string;
+    type: string;
+    created: string;
+    schema_version: string;
+    data: Record<string, unknown>;
+}
+/** One page of the organization's emitted-events log. */
+interface EmittedEventsPage {
+    data: EmittedEvent[];
+    /** Pass back as `cursor` for the next page; null ends the walk. */
+    next_cursor: string | null;
+}
+/** One page of an endpoint's delivery log, newest first. */
+interface WebhookDeliveryPage {
+    data: WebhookDeliveryRecord[];
+    /** Pass back as `cursor` for the next page; null ends the walk. */
+    next_cursor: string | null;
+}
+declare class WebhooksApiError extends Error {
+    readonly operation: string;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, operation: string, originalError?: unknown | undefined);
+}
+/**
+ * Client for the org-anchored webhook platform surface (/api/webhooks/v1).
+ * Authenticates with an ORGANIZATION API key (sk-lw-*); project keys are
+ * rejected by the server. The surface is anchored on the organization alone,
+ * so there is no project id to give this client.
+ *
+ * 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
+ * only made the request bodies of the four billing surfaces disagree. Call
+ * options this SDK invents (query filters, per-call behaviour, action
+ * arguments) stay camelCase like the rest of the SDK.
+ */
+declare class WebhooksApiService {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(config?: {
+        endpoint?: string;
+        apiKey?: string;
+    });
+    private request;
+    list(): Promise<WebhookEndpointSummary[]>;
+    get(id: string): Promise<WebhookEndpointSummary>;
+    /**
+     * The signing secret comes back on this response and never again, so a
+     * create that times out is recovered with `idempotencyKey`: the replay
+     * carries the same secret, and nothing else ever will.
+     */
+    create(input: CreateWebhookEndpointInput, options?: IdempotentCreateOptions): Promise<WebhookEndpointWithSecret>;
+    update(id: string, input: UpdateWebhookEndpointInput, options?: MutationOptions): Promise<WebhookEndpointSummary>;
+    /**
+     * Retire an endpoint: the server soft-archives the row, stamping
+     * `archived_at` and dropping the status to disabled, so the delivery
+     * history stays readable for audit while nothing more is ever sent. The
+     * row is archived, not removed, and `gatewayBudgets.archive()` already
+     * names that operation, so the billing surfaces agree on the verb.
+     *
+     * Nothing comes back: the response body carries only an `archived: true`
+     * acknowledgement, and a non-2xx already raises.
+     */
+    archive(id: string, options?: MutationOptions): Promise<void>;
+    rollSecret(id: string, options?: MutationOptions): Promise<WebhookEndpointWithSecret>;
+    test(id: string, options?: MutationOptions): Promise<WebhookTestResult>;
+    /**
+     * ONE page of the endpoint's delivery attempts, newest first.
+     *
+     * The cursor is why this is a page: the route has always served one, and
+     * dropping it truncated the delivery log at whatever the first page held,
+     * with nothing in the result to say the rest existed. Pass `next_cursor`
+     * back as `cursor`, or walk the whole log with `iterDeliveries()`.
+     */
+    deliveriesPage(id: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<WebhookDeliveryPage>;
+    /**
+     * Every recorded delivery attempt for the endpoint, one at a time,
+     * fetching each page only when the consumer reaches it.
+     */
+    iterDeliveries(id: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncGenerator<WebhookDeliveryRecord>;
+    health(id: string): Promise<WebhookEndpointHealth>;
+    eventTypes(): Promise<WebhookEventType[]>;
+    /**
+     * ONE page of the organization's emitted-events log, newest first.
+     *
+     * Webhooks are a push over this log, never the only copy of it: a consumer
+     * that missed a delivery reads the window back from here. Walk the whole
+     * window with `iterEvents()`.
+     */
+    eventsPage(options?: {
+        type?: string;
+        from?: number;
+        to?: number;
+        cursor?: string;
+        limit?: number;
+    }): Promise<EmittedEventsPage>;
+    /**
+     * Every emitted event matching the filter, one at a time, fetching each
+     * page only when the consumer reaches it.
+     */
+    iterEvents(options?: {
+        type?: string;
+        from?: number;
+        to?: number;
+        cursor?: string;
+        limit?: number;
+    }): AsyncGenerator<EmittedEvent>;
+    /**
+     * One emitted event by id, the envelope exactly as it was delivered.
+     *
+     * A 404 covers every reason the log cannot answer: never emitted, past the
+     * retention horizon, or belonging to another organization.
+     */
+    getEvent(id: string): Promise<EmittedEvent>;
+}
+
+interface GetTraceParams {
+    includeSpans?: boolean;
+}
+type GetTraceResponse = NonNullable<paths["/api/trace/{id}"]["get"]["responses"]["200"]["content"]["application/json"]>;
+
+declare class TracesFacade {
+    #private;
+    constructor(config: InternalConfig);
+    get(traceId: string, params?: GetTraceParams): Promise<GetTraceResponse>;
+}
+
+interface LangWatchConstructorOptions {
+    apiKey?: string;
+    endpoint?: string;
+    options?: {
+        logger?: Logger;
+    };
+}
+declare class LangWatch {
+    #private;
+    private readonly config;
+    readonly prompts: PromptsFacade;
+    readonly traces: TracesFacade;
+    readonly datasets: DatasetsFacade;
+    /**
+     * Run experiments on LangWatch platform or via SDK.
+     *
+     * Platform experiments (CI/CD):
+     * ```typescript
+     * const result = await langwatch.experiments.run("my-experiment-slug");
+     * result.printSummary();
+     * ```
+     *
+     * SDK-defined experiments:
+     * ```typescript
+     * const experiment = await langwatch.experiments.init("my-experiment");
+     * // ... run evaluators using experiment.evaluate()
+     * ```
+     */
+    readonly experiments: ExperimentsFacade;
+    /**
+     * Run evaluators and guardrails in real-time (Online Evaluations).
+     *
+     * @example
+     * ```typescript
+     * const guardrail = await langwatch.evaluations.evaluate("presidio/pii_detection", {
+     *   data: { input: userInput, output: generatedResponse },
+     *   name: "PII Detection",
+     *   asGuardrail: true,
+     * });
+     *
+     * if (!guardrail.passed) {
+     *   return "I'm sorry, I can't do that.";
+     * }
+     * ```
+     */
+    readonly evaluations: EvaluationsFacade;
+    readonly evaluators: EvaluatorsApiService;
+    readonly scenarios: ScenariosApiService;
+    readonly suites: SuitesApiService;
+    readonly workflows: WorkflowsApiService;
+    readonly agents: AgentsApiService;
+    readonly annotations: AnnotationsApiService;
+    readonly dashboards: DashboardsApiService;
+    readonly modelProviders: ModelProvidersApiService;
+    readonly analytics: AnalyticsApiService;
+    readonly triggers: TriggersApiService;
+    readonly graphs: GraphsApiService;
+    readonly simulationRuns: SimulationRunsApiService;
+    readonly monitors: MonitorsApiService;
+    readonly secrets: SecretsApiService;
+    readonly virtualKeys: VirtualKeysApiService;
+    readonly gatewayBudgets: GatewayBudgetsApiService;
+    readonly spendEvents: SpendEventsApiService;
+    readonly webhooks: WebhooksApiService;
+    constructor(options?: LangWatchConstructorOptions);
+    get apiClient(): LangwatchApiClient;
+}
+
+/**
+ * A failure the platform NAMED.
+ *
+ * The API does not merely fail — when it declines a request it says precisely
+ * why, as a `HandledError` with a serialisable `kind` (`dataset_not_found`,
+ * `validation_error`), the HTTP status it answers with, and a `meta` bag of the
+ * context that makes the failure actionable. Until now the SDK collapsed all of
+ * that into an English sentence on a generic error, so a caller could read the
+ * failure but never react to it: a 404 "dataset not found" — a fact you can
+ * offer to fix — was indistinguishable from a 500.
+ *
+ * This is that structure, kept. Narrow with {@link isLangWatchHandledError} (or
+ * `instanceof`) and switch on `code`; `body` is the escape hatch to whatever the
+ * platform sent that this class did not model.
+ *
+ * ```ts
+ * try {
+ *   await langwatch.datasets.get("nope");
+ * } catch (error) {
+ *   if (isLangWatchHandledError(error) && error.code === "dataset_not_found") {
+ *     // Actionable: we know WHAT was not found, and can offer the list.
+ *     console.error(error.meta.id, error.traceId);
+ *   }
+ *   throw error;
+ * }
+ * ```
+ *
+ * ONLY raised for a failure the platform named. An infrastructure failure — a
+ * 5xx, a dead socket, a proxy's HTML error page — still raises the generic
+ * service error it always did, because presenting one of those as a domain
+ * error would blame the user for our outage.
+ */
+declare class LangWatchHandledError extends Error {
+    /**
+     * The discriminant. A boolean brand rather than `instanceof` alone because a
+     * bundled CLI and a consumer's `node_modules` copy of the SDK can hold two
+     * different copies of this class, and `instanceof` is false across that seam —
+     * the same reason the platform's own error handler tests for `code` rather
+     * than class identity.
+     */
+    readonly isLangWatchHandledError: true;
+    /** The platform's serialisable discriminant, e.g. `dataset_not_found`. */
+    readonly code: string;
+    /**
+     * @deprecated Back-compat alias of `code`, kept while the platform's
+     * `DomainError` → `HandledError` rename rolls out. Read `code` in new code.
+     */
+    readonly kind: string;
+    /** The status the platform answered with. */
+    readonly httpStatus: number;
+    /** The context the platform attached: ids, field errors — whatever makes it actionable. */
+    readonly meta: Record<string, unknown>;
+    /** The OTel trace to quote at support. Absent unless the route sent one. */
+    readonly traceId: string | undefined;
+    /** A clickable link to that trace, when the route sent one. */
+    readonly traceUrl: string | undefined;
+    /** A clickable link to the logs for that trace, when the route sent one. */
+    readonly logsUrl: string | undefined;
+    /** The failure behind the failure, when the route sent the chain. */
+    readonly reasons: CliHandledErrorReason[] | undefined;
+    /** What the user can DO about it, when the platform sent next steps. */
+    readonly suggestions: string[] | undefined;
+    /** The docs page that explains the failure, when the platform sent one. */
+    readonly docUrl: string | undefined;
+    /** The raw response body, verbatim — the escape hatch for anything unmodelled. */
+    readonly body: unknown;
+    /** What the SDK was doing, e.g. `get dataset "abc"`. */
+    readonly operation: string | undefined;
+    /**
+     * Alias of {@link httpStatus}, and the raw body again under the name the
+     * per-service `*ApiError` classes use.
+     *
+     * Not redundancy for its own sake: this class is thrown from the SAME code
+     * path that used to throw `TracesApiError` & friends, so anything that reads
+     * `.status` or `.originalError` off a caught SDK error — including the CLI's
+     * own telemetry reader — keeps working unchanged.
+     */
+    readonly status: number;
+    readonly originalError: unknown;
+    constructor({ handled, body, operation, message, }: {
+        handled: CliHandledError;
+        body: unknown;
+        operation?: string;
+        message: string;
+    });
+}
+/** Narrows any caught value to a {@link LangWatchHandledError}. */
+declare const isLangWatchHandledError: (error: unknown) => error is LangWatchHandledError;
+declare class LangWatchApiError extends Error {
+    readonly httpStatus: number;
+    readonly httpStatusText: string;
+    apiError: string | undefined;
+    body: unknown;
+    constructor(message: string, response: Response);
+    safeParseBody(response: Response): Promise<void>;
+}
+
+/**
+ * Receiver-side verification of a LangWatch webhook delivery.
+ *
+ * Every delivery carries
+ *
+ *   X-LangWatch-Signature: t=<unix seconds>,v1=<hex hmac-sha256>[,v1=<hex>]
+ *
+ * where each `v1` is HMAC-SHA256 over `"<t>.<raw body>"` under one currently
+ * valid signing secret. `v1` REPEATS during a secret rotation, newest first,
+ * which is what lets a receiver swap secrets on its own schedule instead of
+ * dropping deliveries mid-swap.
+ *
+ * That repetition is the reason this helper exists. A hand-rolled parser that
+ * keeps the LAST `v1` it sees, or splits the header into a flat key/value map,
+ * rejects every delivery to a receiver that has already moved to the new
+ * secret: the signature it kept is the one computed from the OLD secret. The
+ * bug only appears during a rotation, which is exactly when a receiver can
+ * least afford to be dropping deliveries.
+ *
+ * The algorithm here is pinned to the sender's by the vectors in
+ * `specs/webhooks/signature-vectors.json`, generated from the server's own
+ * signing code and asserted by the suite next to this file.
+ */
+/** The header a delivery carries its signature in. */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-LangWatch-Signature";
+/**
+ * Identifies one delivery ATTEMPT on the webhook platform's endpoints.
+ *
+ * The natural idempotency key for a receiver: retries of the same batch repeat
+ * it, so a receiver that has already processed this id can acknowledge and
+ * stop rather than applying the batch twice.
+ */
+declare const WEBHOOK_DELIVERY_ID_HEADER = "X-LangWatch-Delivery-Id";
+/**
+ * The same role on automation deliveries (graph alerts and friends), which
+ * group their attempts by the logical fire rather than by the batch.
+ *
+ * Two names because they are two senders: read whichever the delivery carries.
+ */
+declare const WEBHOOK_EVENT_ID_HEADER = "X-LangWatch-Event-Id";
+/**
+ * How far a delivery's timestamp may sit from the receiver's clock, in
+ * seconds. Matches the sender's documented window.
+ */
+declare const WEBHOOK_SIGNATURE_DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Why a delivery was refused. Switch on this rather than on the message: the
+ * message is written for a human reading a log and will change, the code is
+ * the contract.
+ *
+ * The three mean genuinely different things to an operator. `stale_timestamp`
+ * is a clock or a replay and is worth alerting on; `invalid_signature` is a
+ * wrong secret or a tampered body; `malformed_header` is almost always
+ * something other than LangWatch posting to the URL.
+ */
+type WebhookSignatureFailureCode = "malformed_header" | "stale_timestamp" | "invalid_signature";
+/**
+ * A delivery that did not verify.
+ *
+ * One class carrying a `code` rather than three classes, because the SDK and
+ * the platform both ask callers to branch on a stable code instead of on the
+ * error's identity, which does not survive a serialization boundary.
+ */
+declare class WebhookSignatureVerificationError extends Error {
+    readonly code: WebhookSignatureFailureCode;
+    constructor(code: WebhookSignatureFailureCode, message: string);
+}
+interface VerifyWebhookSignatureOptions {
+    /**
+     * The EXACT bytes of the request body, as received.
+     *
+     * Not a parsed object, and not the result of re-serializing one: the digest
+     * is over the bytes the sender hashed, and `JSON.parse` followed by
+     * `JSON.stringify` reorders keys, drops insignificant whitespace and
+     * re-escapes non-ASCII, any of which changes the digest. Read the raw body
+     * before your framework's JSON middleware does.
+     */
+    body: string | Uint8Array;
+    /** The `X-LangWatch-Signature` header value, verbatim. */
+    header: string;
+    /**
+     * The signing secret, or every secret this receiver currently accepts.
+     *
+     * Pass both values during a rotation and the delivery verifies under
+     * either, so there is no window where deliveries are refused.
+     */
+    secret: string | readonly string[];
+    /**
+     * Freshness window in seconds, defaulting to the sender's five minutes.
+     * Tighten it only if your clocks are disciplined.
+     */
+    toleranceSeconds?: number;
+    /**
+     * The current time in unix SECONDS. Defaults to the system clock; pass it
+     * to verify a delivery captured earlier, or from a test.
+     */
+    nowSeconds?: number;
+}
+/**
+ * Verify a webhook delivery, or throw explaining which check failed.
+ *
+ * ```ts
+ * app.post("/langwatch", express.raw({ type: "application/json" }), (req, res) => {
+ *   try {
+ *     verifyWebhookSignature({
+ *       body: req.body, // the raw Buffer, before JSON parsing
+ *       header: req.header("X-LangWatch-Signature") ?? "",
+ *       secret: [process.env.WEBHOOK_SECRET_NEW, process.env.WEBHOOK_SECRET_OLD],
+ *     });
+ *   } catch (error) {
+ *     return res.status(400).send((error as WebhookSignatureVerificationError).code);
+ *   }
+ *   // Trusted from here.
+ * });
+ * ```
+ *
+ * Throws rather than returning false so that a delivery cannot be trusted by
+ * forgetting to check a return value. The thrown
+ * {@link WebhookSignatureVerificationError} carries a
+ * {@link WebhookSignatureFailureCode} saying which check failed.
+ *
+ * Checks run in a fixed order, so a delivery that is both stale and wrongly
+ * signed reports the staleness: a header that did not parse has no
+ * trustworthy timestamp to judge, and a timestamp outside the window makes
+ * the digest moot.
+ *
+ * A missing or empty secret is a configuration mistake rather than a bad
+ * delivery, and raises `TypeError`. Reporting it as a failed verification
+ * would let a receiver that lost its secret quietly refuse every delivery as
+ * if the sender were at fault.
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): void;
 
 declare const logger: {
     ConsoleLogger: typeof ConsoleLogger;
     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 Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, 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 GatewayBudgetList, GatewayBudgetsApiError, GatewayBudgetsApiService, type GetDatasetOptions, type GetPromptOptions, LangWatch, LangWatchApiError, LangWatchHandledError, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type LogOptions, type PaginatedResponse, type Pagination, type RunCallback, type RunContext, type RunOptions, type RunWithResultsOptions, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type UpdateDatasetOptions, type UpdateGatewayBudgetInput, type UpdateVirtualKeyInput, type UploadResponse, type VirtualKey, type VirtualKeyBudgetInput, type VirtualKeyRoutingMode, type VirtualKeyScope, type VirtualKeyScopeType, type VirtualKeySpendSummary, type VirtualKeyWithSecret, VirtualKeysApiError, VirtualKeysApiService, isLangWatchHandledError, logger };
+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 };