langsmith 0.8.7 → 0.8.9

package/dist/client.js

@@ -8,7 +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 { _MIN_BACKEND_VERSION } from "./utils/constants.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";
@@ -123,9 +123,13 @@ function _formatFeedbackScore(score) {
     }
     return score;
 }
-export function _checkBackendVersion(version, minVersion = _MIN_BACKEND_VERSION) {
+export function _checkBackendVersion(backendVersion, minVersion) {
+    if (!backendVersion) {
+        // /info was unreachable (or skipped): nothing to compare against.
+        return;
+    }
     const parse = (v) => v.split(".").map((s) => parseInt(s, 10));
-    const [maj, min, pat] = parse(version);
+    const [maj, min, pat] = parse(backendVersion);
     const [rMaj, rMin, rPat] = parse(minVersion);
     if (isNaN(maj) ||
         isNaN(min) ||
@@ -133,13 +137,16 @@ export function _checkBackendVersion(version, minVersion = _MIN_BACKEND_VERSION)
         isNaN(rMaj) ||
         isNaN(rMin) ||
         isNaN(rPat)) {
-        console.warn(`[LANGSMITH]: Could not parse backend version ${JSON.stringify(version)} for compatibility check.`);
+        console.warn(`[LANGSMITH]: Could not parse backend version ${JSON.stringify(backendVersion)} for compatibility check.`);
         return;
     }
     if (maj < rMaj ||
         (maj === rMaj && min < rMin) ||
         (maj === rMaj && min === rMin && pat < rPat)) {
-        console.warn(`[LANGSMITH]: Backend version ${JSON.stringify(version)} is older than the minimum version required by this SDK (${JSON.stringify(minVersion)}). Some features may not work as expected.`);
+        console.warn(`[LANGSMITH]: Backend version ${JSON.stringify(backendVersion)} is older than ` +
+            `the minimum version required by this SDK (${JSON.stringify(minVersion)}). ` +
+            "Some features may not work as expected. See " +
+            "https://docs.langchain.com/langsmith/smithdb-sdk-migration");
     }
 }
 export const DEFAULT_UNCOMPRESSED_BATCH_SIZE_LIMIT_BYTES = 24 * 1024 * 1024;
@@ -148,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", {
@@ -566,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,
@@ -609,11 +695,11 @@ export class Client {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "_stainlessVersionChecked", {
+        Object.defineProperty(this, "_stainlessVersionsChecked", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: false
+            value: new Set()
         });
         Object.defineProperty(this, "manualFlushMode", {
             enumerable: true,
@@ -777,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") {
@@ -813,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();
@@ -886,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) {
@@ -907,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).
@@ -916,24 +1071,47 @@ export class Client {
         return this._customHeaders;
     }
     set headers(value) {
+        assertValidHeaders(value);
         this._customHeaders = value ?? {};
     }
     _getOpenAPIBaseUrl() {
-        return this.apiUrl.endsWith("/v1") ? this.apiUrl.slice(0, -3) : this.apiUrl;
+        const url = this.apiUrl.replace(/\/$/, "");
+        for (const suffix of ["/api/v1", "/api"]) {
+            if (url.endsWith(suffix))
+                return url.slice(0, -suffix.length);
+        }
+        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) {
@@ -942,35 +1120,42 @@ export class Client {
         return needsV1Prefix ? `/v1/platform/${path}` : `/platform/${path}`;
     }
     get evaluators() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.onlineEvaluators;
     }
     get runs() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.runs;
     }
     /** Access the v2 sandboxes resource (registries, snapshots, boxes). */
     get sandboxes() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.sandboxes;
     }
     /** Access the v2 datasets resource (experimentRuns, etc.). */
     get datasets() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.datasets;
     }
+    /** Access the annotation queues resource (runs, items). */
+    get annotationQueues() {
+        // The items endpoints landed in backend 0.16.14; the rest are older.
+        this._checkStainlessVersion("0.16.14");
+        return this.openAPIClient.annotationQueues;
+    }
     /** Access the threads resource (query, stats, listTraces). */
     get threads() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.threads;
     }
     /** Access the traces resource (query, listRuns). */
     get traces() {
-        this._checkStainlessVersion();
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.traces;
     }
     /** Access the public shared-run resource. */
     get public() {
+        this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.public;
     }
     async processInputs(inputs) {
@@ -1459,15 +1644,13 @@ export class Client {
         }
         return json;
     }
-    _checkStainlessVersion() {
-        if (this._stainlessVersionChecked)
+    _checkStainlessVersion(minVersion) {
+        if (this._stainlessVersionsChecked.has(minVersion))
             return;
-        this._stainlessVersionChecked = true;
+        this._stainlessVersionsChecked.add(minVersion);
         this._ensureServerInfo()
             .then((serverInfo) => {
-            if (serverInfo?.version) {
-                _checkBackendVersion(serverInfo.version);
-            }
+            _checkBackendVersion(serverInfo?.version, minVersion);
         })
             .catch(() => {
             // _ensureServerInfo handles and logs its own errors
@@ -1498,6 +1681,20 @@ export class Client {
         const serverInfo = await this._ensureServerInfo();
         return serverInfo.instance_flags?.sdb_query_enabled === true;
     }
+    /**
+     * Throw on SmithDB-only deployments, warn elsewhere. Call only when run-level
+     * feedback has no sessionId.
+     */
+    async _checkFeedbackSessionId() {
+        const docs = "https://docs.langchain.com/langsmith/smithdb-sdk-migration#feedback-create";
+        const serverInfo = await this._ensureServerInfo();
+        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}`);
+        }
+        warnOnce(`Creating feedback for a run without sessionId is deprecated and will ` +
+            `stop working in a future release. See ${docs}`);
+    }
     async _getSettings() {
         if (!this.settings) {
             this.settings = this._get("/settings");
@@ -2016,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) {
@@ -2024,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) {
@@ -2046,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`);
             }
@@ -2058,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,
@@ -2091,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.
@@ -2172,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) {
@@ -2305,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");
@@ -2314,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,
@@ -2323,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");
@@ -2473,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(),
@@ -2497,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`, {
@@ -2510,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`, {
@@ -2528,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,
         });
@@ -3592,13 +3857,19 @@ export class Client {
             return res;
         });
     }
-    async createFeedback(runId, key, { score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, }) {
+    async createFeedback(runIdOrParams, keyArg, optionsArg) {
+        const { runId = null, key, score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, } = typeof runIdOrParams === "object" && runIdOrParams !== null
+            ? runIdOrParams
+            : { runId: runIdOrParams, key: keyArg, ...optionsArg };
         if (!runId && !projectId) {
             throw new Error("One of runId or projectId must be provided");
         }
         if (runId && projectId) {
             throw new Error("Only one of runId or projectId can be provided");
         }
+        if (runId && sessionId === undefined) {
+            await this._checkFeedbackSessionId();
+        }
         const feedback_source = {
             type: feedbackSourceType ?? "api",
             metadata: sourceInfo ?? {},
@@ -4111,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.
@@ -4143,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 = [];