langsmith 0.8.8 → 0.8.9

package/dist/client.d.ts

@@ -501,8 +501,11 @@ export declare class Client implements LangSmithTracingClientInterface {
     private autoBatchAggregationDelayMs;
     private batchSizeBytesLimit?;
     private batchSizeLimit?;
+    /** `config.fetchOptions` without its `headers`, which are merged separately. */
     private fetchOptions;
-    private openAPIClient;
+    private _fetchOptionsHeaders;
+    private _openAPIClient?;
+    private _openAPIClientSignature?;
     private settings;
     private blockOnRootRunFinalization;
     private traceBatchConcurrency;
@@ -555,7 +558,33 @@ export declare class Client implements LangSmithTracingClientInterface {
     constructor(config?: ClientConfig);
     static getDefaultClientConfig(): DefaultClientConfig;
     getHostUrl(): string;
+    /**
+     * The headers this client sets from its own config, which a caller-supplied
+     * header must not replace.
+     *
+     * Only what the client *actually* supplies: passing an explicit `Authorization`
+     * or `x-api-key` header with no configured credential is a supported way to
+     * authenticate (see `hasExplicitAuthHeader`), so those must survive.
+     */
+    private get _sdkControlledHeaders();
+    /**
+     * Headers supplied by the caller, through either `config.headers` or
+     * `config.fetchOptions.headers`, with the ones this SDK sets removed.
+     *
+     * `_customHeaders` is normalized here rather than at assignment because it is
+     * public and mutable: `get headers` hands back the caller's own object, so its
+     * contents can change (and can become malformed) at any point.
+     */
+    private get _callerHeaders();
     private get _mergedHeaders();
+    /**
+     * The auth options and caller headers to build the generated client with.
+     *
+     * The generated client applies `defaultHeaders` *after* its own auth headers,
+     * so the ones this SDK sets are already dropped from `_callerHeaders` to keep
+     * the precedence of `_mergedHeaders`, where required headers win.
+     */
+    private get _openAPIAuth();
     /**
      * Get or set custom headers for the client.
      * Custom headers are merged with default headers (User-Agent, x-api-key, x-tenant-id).
@@ -564,6 +593,17 @@ export declare class Client implements LangSmithTracingClientInterface {
     get headers(): Record<string, string>;
     set headers(value: Record<string, string> | undefined);
     private _getOpenAPIBaseUrl;
+    /**
+     * The generated OpenAPI client, rebuilt whenever its auth or headers change.
+     *
+     * The generated client captures `defaultHeaders` and `apiKey` when it is
+     * built, while the handwritten paths recompute `_mergedHeaders` per request.
+     * Rebuilding on change keeps the two halves from diverging when the inputs
+     * move underneath us — a caller mutating the object returned by
+     * `get headers`, or a profile whose auth header only becomes available after
+     * its token is refreshed.
+     */
+    private get openAPIClient();
     private _newOpenAPIClient;
     private _getPlatformEndpointPath;
     get evaluators(): Evaluators;
@@ -687,9 +727,11 @@ export declare class Client implements LangSmithTracingClientInterface {
         apiUrl?: string;
         workspaceId?: string;
     }): Promise<void>;
+    /** @deprecated Use `client.runs.retrieve()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide. Will be removed after Jan 31, 2027. */
     readRun(runId: string, { loadChildRuns }?: {
         loadChildRuns: boolean;
     }): Promise<Run>;
+    /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
     getRunUrl({ runId, run, projectOpts, }: {
         runId?: string;
         run?: Run;
@@ -698,6 +740,7 @@ export declare class Client implements LangSmithTracingClientInterface {
     private _loadChildRuns;
     /**
      * List runs from the LangSmith server.
+     * @deprecated Use `client.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide. Will be removed after Jan 31, 2027.
      * @param projectId - The ID of the project to filter by.
      * @param projectName - The name of the project to filter by.
      * @param parentRunId - The ID of the parent run to filter by.
@@ -780,7 +823,9 @@ export declare class Client implements LangSmithTracingClientInterface {
      */
     listRuns(props: ListRunsParams): AsyncIterable<Run>;
     listGroupRuns(props: GroupRunsParams): AsyncIterable<Thread>;
+    /** @deprecated Use `client.threads.listTraces()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide. Will be removed after Jan 31, 2027. */
     readThread(props: ReadThreadParams): AsyncIterable<Run>;
+    /** @deprecated Use `client.threads.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide. Will be removed after Jan 31, 2027. */
     listThreads(props: ListThreadsParams): Promise<ListThreadsItem[]>;
     getRunStats({ id, trace, parentRun, runType, projectNames, projectIds, referenceExampleIds, startTime, endTime, error, query, filter, traceFilter, treeFilter, isRoot, dataSourceType, }: {
         id?: string[];
@@ -800,11 +845,15 @@ export declare class Client implements LangSmithTracingClientInterface {
         isRoot?: boolean;
         dataSourceType?: string;
     }): Promise<any>;
+    /** @deprecated Use `client.runs.share.create()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     shareRun(runId: string, { shareId }?: {
         shareId?: string;
     }): Promise<string>;
+    /** @deprecated Use `client.runs.share.delete()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     unshareRun(runId: string): Promise<void>;
+    /** @deprecated Use `client.runs.retrieve({ selects: ["SHARE_URL"] })` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     readRunSharedLink(runId: string): Promise<string | undefined>;
+    /** @deprecated Use `client.public.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     listSharedRuns(shareToken: string, { runIds, }?: {
         runIds?: string[];
     }): Promise<Run[]>;
@@ -1196,8 +1245,9 @@ export declare class Client implements LangSmithTracingClientInterface {
      * - `RunKey[]` (preferred): each entry carries the run's full lookup key, so
      *   it can be located directly without a scan. Required for workspaces served
      *   by SmithDB; routes to `POST /runs/by-key`.
-     * - `string[]`: a plain list of run IDs. This path will be deprecated in a
-     *   future release; prefer the key form. Routes to `POST /runs`.
+     * - `string[]`: a plain list of run IDs. **Deprecated**: this path will be
+     *   removed after Jan 31, 2027; prefer the key form. Routes to `POST /runs`.
+     *   See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs.
      *
      * If every element is a string (or the list is empty) it is treated as run
      * IDs; otherwise the list is treated as `RunKey` objects.

package/dist/client.js

@@ -8,6 +8,7 @@ import { __version__ } from "./index.js";
 import { Langsmith as OpenAPILangsmith } from "./_openapi_client/index.js";
 import { assertUuid } from "./utils/_uuid.js";
 import { warnOnce } from "./utils/warn.js";
+import { getQueryBackend, QueryBackend } from "./utils/v2_migration.js";
 import { parseHubIdentifier } from "./utils/prompts.js";
 import { raiseForStatus, isLangSmithNotFoundError, isLangSmithConflictError, } from "./utils/error.js";
 import { promptCacheSingleton, } from "./utils/prompt_cache/index.js";
@@ -154,6 +155,72 @@ export const DEFAULT_MAX_SIZE_BYTES = 1024 * 1024 * 1024; // 1GB
 const SERVER_INFO_REQUEST_TIMEOUT_MS = 10000;
 /** Maximum number of operations to batch in a single request. */
 const DEFAULT_BATCH_SIZE_LIMIT = 100;
+/**
+ * Reject header names or values that could alter a request's framing.
+ *
+ * `Headers` does this for us, and does it the same way `fetch` will.
+ */
+function assertValidHeader(name, value) {
+    new Headers({ [name]: value });
+}
+/** Reject a malformed header up front, before it can reach a request. */
+function assertValidHeaders(headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        assertValidHeader(name, value);
+    }
+}
+/**
+ * Fold a `HeadersInit` into a plain object so it can be spread.
+ *
+ * Names are matched case-insensitively with the last value winning, keeping the
+ * first spelling seen. A plain object would instead keep both spellings, which
+ * `Headers` later joins into a `"first, second"` list rather than an override.
+ * Every name and value is validated on the way through.
+ */
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    const entries = headers instanceof Headers
+        ? [...headers.entries()]
+        : Array.isArray(headers)
+            ? headers.map(([name, value]) => [name, value])
+            : Object.entries(headers);
+    const normalized = {};
+    const nameByLower = new Map();
+    for (const [name, value] of entries) {
+        assertValidHeader(name, value);
+        const lowerName = name.toLowerCase();
+        const existingName = nameByLower.get(lowerName);
+        if (existingName === undefined) {
+            nameByLower.set(lowerName, name);
+            normalized[name] = value;
+        }
+        else {
+            normalized[existingName] = value;
+        }
+    }
+    return normalized;
+}
+/**
+ * Merge the caller's two header channels, then drop the `reserved` names.
+ *
+ * `overrides` wins, matched case-insensitively so a header supplied through both
+ * channels is overridden rather than turned into a `"first, second"` list.
+ */
+function mergeCallerHeaders(base, overrides, reserved) {
+    const merged = { ...base };
+    const nameByLower = new Map(Object.keys(merged).map((name) => [name.toLowerCase(), name]));
+    for (const [name, value] of Object.entries(overrides)) {
+        const lowerName = name.toLowerCase();
+        merged[nameByLower.get(lowerName) ?? name] = value;
+    }
+    for (const name of Object.keys(merged)) {
+        if (reserved.has(name.toLowerCase())) {
+            delete merged[name];
+        }
+    }
+    return merged;
+}
 export class AutoBatchQueue {
     constructor(maxSizeBytes) {
         Object.defineProperty(this, "items", {
@@ -572,13 +639,26 @@ export class Client {
             writable: true,
             value: void 0
         });
+        /** `config.fetchOptions` without its `headers`, which are merged separately. */
         Object.defineProperty(this, "fetchOptions", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "openAPIClient", {
+        Object.defineProperty(this, "_fetchOptionsHeaders", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "_openAPIClient", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_openAPIClientSignature", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -783,8 +863,15 @@ export class Client {
             config.blockOnRootRunFinalization ?? this.blockOnRootRunFinalization;
         this.batchSizeBytesLimit = config.batchSizeBytesLimit;
         this.batchSizeLimit = config.batchSizeLimit;
-        this.fetchOptions = config.fetchOptions || {};
-        this.openAPIClient = this._newOpenAPIClient();
+        const { headers: fetchOptionsHeaders, ...fetchOptions } = config.fetchOptions || {};
+        this.fetchOptions = fetchOptions;
+        // Kept apart from `fetchOptions` so they can be merged *under* the required
+        // headers instead of replacing the whole set at each call site.
+        this._fetchOptionsHeaders = normalizeHeaders(fetchOptionsHeaders);
+        // Validated eagerly so malformed input fails at construction, but stored
+        // as given: `get headers` hands this object back to the caller.
+        assertValidHeaders(config.headers);
+        this._customHeaders = config.headers ?? {};
         this.manualFlushMode = config.manualFlushMode ?? this.manualFlushMode;
         this._tracingMode = resolveTracingMode(config.tracingMode);
         if (this._tracingMode === "otel") {
@@ -819,8 +906,6 @@ export class Client {
             // Use the global singleton instance
             this._promptCache = promptCacheSingleton;
         }
-        // Initialize custom headers
-        this._customHeaders = config.headers ?? {};
     }
     static getDefaultClientConfig() {
         const profileConfig = loadProfileClientConfig();
@@ -892,11 +977,46 @@ export class Client {
             return this.webUrl;
         }
     }
+    /**
+     * The headers this client sets from its own config, which a caller-supplied
+     * header must not replace.
+     *
+     * Only what the client *actually* supplies: passing an explicit `Authorization`
+     * or `x-api-key` header with no configured credential is a supported way to
+     * authenticate (see `hasExplicitAuthHeader`), so those must survive.
+     */
+    get _sdkControlledHeaders() {
+        const names = new Set();
+        if (this.apiKey !== undefined) {
+            names.add("x-api-key");
+        }
+        else {
+            const profileAuthHeader = this.profileAuth?.currentAuthHeader();
+            if (profileAuthHeader) {
+                names.add(profileAuthHeader.name.toLowerCase());
+            }
+        }
+        if (this.workspaceId) {
+            names.add("x-tenant-id");
+        }
+        return names;
+    }
+    /**
+     * Headers supplied by the caller, through either `config.headers` or
+     * `config.fetchOptions.headers`, with the ones this SDK sets removed.
+     *
+     * `_customHeaders` is normalized here rather than at assignment because it is
+     * public and mutable: `get headers` hands back the caller's own object, so its
+     * contents can change (and can become malformed) at any point.
+     */
+    get _callerHeaders() {
+        return mergeCallerHeaders(normalizeHeaders(this._customHeaders), this._fetchOptionsHeaders, this._sdkControlledHeaders);
+    }
     get _mergedHeaders() {
-        // Start with custom headers so they don't override required headers
+        // Start with caller-supplied headers so they don't override required headers
         const headers = {
             "User-Agent": `langsmith-js/${__version__}`,
-            ...this._customHeaders,
+            ...this._callerHeaders,
         };
         // Required headers that should not be overridden
         if (this.apiKey !== undefined) {
@@ -913,6 +1033,35 @@ export class Client {
         }
         return headers;
     }
+    /**
+     * The auth options and caller headers to build the generated client with.
+     *
+     * The generated client applies `defaultHeaders` *after* its own auth headers,
+     * so the ones this SDK sets are already dropped from `_callerHeaders` to keep
+     * the precedence of `_mergedHeaders`, where required headers win.
+     */
+    get _openAPIAuth() {
+        const headers = { ...this._callerHeaders };
+        // A caller may authenticate by supplying `x-api-key` themselves. The
+        // generated client rejects that as a header (its `validateHeaders` requires
+        // its own `apiKey` to be set), so hand it over as the `apiKey` option and
+        // drop the header to avoid sending the same value twice.
+        const callerApiKeyName = Object.keys(headers).find((name) => name.toLowerCase() === "x-api-key");
+        let apiKey = this.apiKey;
+        if (apiKey === undefined && callerApiKeyName !== undefined) {
+            apiKey = headers[callerApiKeyName] ?? undefined;
+            delete headers[callerApiKeyName];
+        }
+        if (apiKey === undefined && this.workspaceId === undefined) {
+            // Let the wrapped `fetch` supply auth (profile auth, an explicit
+            // `Authorization` header, or none at all).
+            headers["X-API-Key"] = null;
+        }
+        return {
+            apiKey,
+            defaultHeaders: Object.keys(headers).length > 0 ? headers : undefined,
+        };
+    }
     /**
      * Get or set custom headers for the client.
      * Custom headers are merged with default headers (User-Agent, x-api-key, x-tenant-id).
@@ -922,6 +1071,7 @@ export class Client {
         return this._customHeaders;
     }
     set headers(value) {
+        assertValidHeaders(value);
         this._customHeaders = value ?? {};
     }
     _getOpenAPIBaseUrl() {
@@ -932,19 +1082,36 @@ export class Client {
         }
         return url;
     }
-    _newOpenAPIClient() {
-        const defaultHeaders = this.apiKey === undefined && this.workspaceId === undefined
-            ? { "X-API-Key": null }
-            : undefined;
-        const { method: _method, headers: _headers, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
+    /**
+     * The generated OpenAPI client, rebuilt whenever its auth or headers change.
+     *
+     * The generated client captures `defaultHeaders` and `apiKey` when it is
+     * built, while the handwritten paths recompute `_mergedHeaders` per request.
+     * Rebuilding on change keeps the two halves from diverging when the inputs
+     * move underneath us — a caller mutating the object returned by
+     * `get headers`, or a profile whose auth header only becomes available after
+     * its token is refreshed.
+     */
+    get openAPIClient() {
+        const auth = this._openAPIAuth;
+        const signature = JSON.stringify([auth.apiKey, auth.defaultHeaders]);
+        if (this._openAPIClient === undefined ||
+            this._openAPIClientSignature !== signature) {
+            this._openAPIClientSignature = signature;
+            this._openAPIClient = this._newOpenAPIClient(auth);
+        }
+        return this._openAPIClient;
+    }
+    _newOpenAPIClient(auth = this._openAPIAuth) {
+        const { method: _method, body: _body, signal: _signal, ...openAPIFetchOptions } = this.fetchOptions;
         return new OpenAPILangsmith({
-            apiKey: this.apiKey,
+            apiKey: auth.apiKey,
             tenantID: this.workspaceId,
             baseURL: this._getOpenAPIBaseUrl(),
             timeout: this.timeout_ms,
             fetch: this._fetch,
             fetchOptions: openAPIFetchOptions,
-            defaultHeaders,
+            defaultHeaders: auth.defaultHeaders,
         });
     }
     _getPlatformEndpointPath(path) {
@@ -1521,7 +1688,7 @@ export class Client {
     async _checkFeedbackSessionId() {
         const docs = "https://docs.langchain.com/langsmith/smithdb-sdk-migration#feedback-create";
         const serverInfo = await this._ensureServerInfo();
-        if (serverInfo.instance_flags?.ch_query_enabled === false) {
+        if (getQueryBackend(serverInfo.instance_flags) === QueryBackend.SMITHDB_ONLY) {
             throw new Error(`sessionId must be provided when creating feedback for a run: this ` +
                 `deployment cannot locate the run without it. See ${docs}`);
         }
@@ -2046,7 +2213,22 @@ export class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide. Will be removed after Jan 31, 2027. */
     async readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
+        warnOnce("readRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.retrieve() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-retrieve for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_RUN" });
+        return this._readRun(runId, { loadChildRuns });
+    }
+    /**
+     * Fetch a run without emitting the `readRun()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async _readRun(runId, { loadChildRuns } = { loadChildRuns: false }) {
         assertUuid(runId);
         let run = _normalizeRunTimestamps(await this._get(`/runs/${runId}`));
         if (loadChildRuns) {
@@ -2054,7 +2236,11 @@ export class Client {
         }
         return run;
     }
+    /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
     async getRunUrl({ runId, run, projectOpts, }) {
+        warnOnce("getRunUrl() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.getURL() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
             let sessionId;
             if (run.session_id) {
@@ -2076,7 +2262,9 @@ export class Client {
             return `${this.getHostUrl()}/o/${tenantId}/projects/p/${sessionId}/r/${run.id}?poll=true`;
         }
         else if (runId !== undefined) {
-            const run_ = await this.readRun(runId);
+            // Via _readRun() rather than readRun() so callers don't also get a
+            // readRun deprecation warning for a method they never called.
+            const run_ = await this._readRun(runId);
             if (!run_.app_path) {
                 throw new Error(`Run ${runId} has no app_path`);
             }
@@ -2088,7 +2276,7 @@ export class Client {
         }
     }
     async _loadChildRuns(run) {
-        const childRuns = await toArray(this.listRuns({
+        const childRuns = await toArray(this._listRuns({
             isRoot: false,
             projectId: run.session_id,
             traceId: run.trace_id,
@@ -2121,6 +2309,7 @@ export class Client {
     }
     /**
      * List runs from the LangSmith server.
+     * @deprecated Use `client.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide. Will be removed after Jan 31, 2027.
      * @param projectId - The ID of the project to filter by.
      * @param projectName - The name of the project to filter by.
      * @param parentRunId - The ID of the parent run to filter by.
@@ -2202,6 +2391,20 @@ export class Client {
      * });
      */
     async *listRuns(props) {
+        warnOnce("listRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_RUNS" });
+        yield* this._listRuns(props);
+    }
+    /**
+     * List runs without emitting the `listRuns()` deprecation warning.
+     *
+     * Internal callers use this so that a supported method doesn't warn about a
+     * deprecated one the caller never invoked.
+     *
+     * @internal
+     */
+    async *_listRuns(props) {
         const { projectId, projectName, parentRunId, traceId, referenceExampleId, startTime, executionOrder, isRoot, runType, error, id, query, filter, traceFilter, treeFilter, limit, select, order, } = props;
         let projectIds = [];
         if (projectId) {
@@ -2335,7 +2538,11 @@ export class Client {
             }
         }
     }
+    /** @deprecated Use `client.threads.listTraces()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide. Will be removed after Jan 31, 2027. */
     async *readThread(props) {
+        warnOnce("readThread() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.listTraces() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-list-traces for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_READ_THREAD" });
         const { threadId, projectId, projectName, isRoot = true, limit, filter: userFilter, order = "asc", } = props;
         if (!projectId && !projectName) {
             throw new Error("threadId requires projectId or projectName");
@@ -2344,7 +2551,9 @@ export class Client {
         const combinedFilter = userFilter
             ? `and(${threadFilter}, ${userFilter})`
             : threadFilter;
-        yield* this.listRuns({
+        // Via _listRuns() rather than listRuns(): readThread() already warned, and it
+        // points at threads.listTraces() rather than listRuns()'s runs.query().
+        yield* this._listRuns({
             projectId: projectId ?? undefined,
             projectName: projectName ?? undefined,
             isRoot,
@@ -2353,7 +2562,11 @@ export class Client {
             order,
         });
     }
+    /** @deprecated Use `client.threads.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide. Will be removed after Jan 31, 2027. */
     async listThreads(props) {
+        warnOnce("listThreads() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.threads.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#threads-query for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_LIST_THREADS" });
         const { projectId, projectName, limit, offset = 0, filter, startTime, isRoot = true, } = props;
         if (!projectId && !projectName) {
             throw new Error("Either projectId or projectName must be provided");
@@ -2503,7 +2716,11 @@ export class Client {
         const result = await response.json();
         return result;
     }
+    /** @deprecated Use `client.runs.share.create()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async shareRun(runId, { shareId } = {}) {
+        warnOnce("shareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.create() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_SHARE_RUN" });
         const data = {
             run_id: runId,
             share_token: shareId || uuid.v4(),
@@ -2527,7 +2744,11 @@ export class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.runs.share.delete()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async unshareRun(runId) {
+        warnOnce("unshareRun() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.runs.share.delete() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_UNSHARE_RUN" });
         assertUuid(runId);
         await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2540,7 +2761,14 @@ export class Client {
             return res;
         });
     }
+    /** @deprecated Use `client.runs.retrieve({ selects: ["SHARE_URL"] })` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async readRunSharedLink(runId) {
+        warnOnce("readRunSharedLink() is deprecated and will be removed after Jan 31, 2027. " +
+            'Use client.runs.retrieve({ selects: ["SHARE_URL"] }) instead. ' +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_READ_RUN_SHARED_LINK",
+        });
         assertUuid(runId);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2558,7 +2786,14 @@ export class Client {
         }
         return `${this.getHostUrl()}/public/${result["share_token"]}/r`;
     }
+    /** @deprecated Use `client.public.runs.query()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide. Will be removed after Jan 31, 2027. */
     async listSharedRuns(shareToken, { runIds, } = {}) {
+        warnOnce("listSharedRuns() is deprecated and will be removed after Jan 31, 2027. " +
+            "Use client.public.runs.query() instead. " +
+            "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#share-and-read-public-runs for the migration guide.", {
+            type: "DeprecationWarning",
+            code: "LANGSMITH_DEPRECATED_LIST_SHARED_RUNS",
+        });
         const queryParams = new URLSearchParams({
             share_token: shareToken,
         });
@@ -4147,8 +4382,9 @@ export class Client {
      * - `RunKey[]` (preferred): each entry carries the run's full lookup key, so
      *   it can be located directly without a scan. Required for workspaces served
      *   by SmithDB; routes to `POST /runs/by-key`.
-     * - `string[]`: a plain list of run IDs. This path will be deprecated in a
-     *   future release; prefer the key form. Routes to `POST /runs`.
+     * - `string[]`: a plain list of run IDs. **Deprecated**: this path will be
+     *   removed after Jan 31, 2027; prefer the key form. Routes to `POST /runs`.
+     *   See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs.
      *
      * If every element is a string (or the list is empty) it is treated as run
      * IDs; otherwise the list is treated as `RunKey` objects.
@@ -4179,6 +4415,12 @@ export class Client {
             }));
         }
         else {
+            warnOnce("Passing run IDs as strings to addRunsToAnnotationQueue() is deprecated and will be removed after Jan 31, 2027. " +
+                "Use RunKey[] instead. " +
+                "See https://docs.langchain.com/langsmith/smithdb-sdk-migration#annotation-queues-add-runs for the migration guide.", {
+                type: "DeprecationWarning",
+                code: "LANGSMITH_DEPRECATED_ADD_RUNS_STRING_IDS",
+            });
             url = base;
             body = JSON.stringify(runs.map((id, i) => assertUuid(id, `runs[${i}]`).toString()));
         }

package/dist/evaluation/evaluate_comparative.cjs

@@ -24,10 +24,13 @@ async function loadTracesForExperiment(client, project, options) {
     const isRoot = options.loadNested ? undefined : true;
     const runs = (await client._supportsSDBQuery())
         ? await (0, v2_migration_js_1.loadTracesV2)(client, project, { isRoot })
-        : await client.listRuns({
-            projectId: project.id,
-            executionOrder: options.loadNested ? undefined : 1,
-        });
+        : // Via _listRuns() rather than listRuns(): evaluate() is supported, so
+            // callers have nothing to migrate; how it loads traces is an
+            // implementation detail.
+            await client._listRuns({
+                projectId: project.id,
+                executionOrder: options.loadNested ? undefined : 1,
+            });
     const treeMap = {};
     const runIdMap = {};
     const results = [];

package/dist/evaluation/evaluate_comparative.js

@@ -17,10 +17,13 @@ export async function loadTracesForExperiment(client, project, options) {
     const isRoot = options.loadNested ? undefined : true;
     const runs = (await client._supportsSDBQuery())
         ? await loadTracesV2(client, project, { isRoot })
-        : await client.listRuns({
-            projectId: project.id,
-            executionOrder: options.loadNested ? undefined : 1,
-        });
+        : // Via _listRuns() rather than listRuns(): evaluate() is supported, so
+            // callers have nothing to migrate; how it loads traces is an
+            // implementation detail.
+            await client._listRuns({
+                projectId: project.id,
+                executionOrder: options.loadNested ? undefined : 1,
+            });
     const treeMap = {};
     const runIdMap = {};
     const results = [];

package/dist/index.cjs

@@ -35,6 +35,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.8.8";
+exports.__version__ = "0.8.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.j
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.8.8";
+export declare const __version__ = "0.8.9";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -7,6 +7,6 @@ export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.8.8";
+export const __version__ = "0.8.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";