langsmith 0.8.8 → 0.8.9

package/dist/_openapi_client/resources/threads.d.ts

@@ -4,8 +4,9 @@ import { ItemsCursorGetPagination, type ItemsCursorGetPaginationParams, ItemsCur
 import { RequestOptions } from '../internal/request-options.js';
 export declare class Threads extends APIResource {
     /**
-     * **Alpha:** The request and response contract may change; Retrieve all traces
-     * belonging to a specific thread within a project.
+     * Retrieve all traces belonging to a specific thread within a project.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -20,9 +21,10 @@ export declare class Threads extends APIResource {
      */
     listTraces(threadID: string, query: ThreadListTracesParams, options?: RequestOptions): PagePromise<ThreadTracesItemsCursorGetPagination, ThreadTrace>;
     /**
-     * **Alpha:** The request and response contract may change; Query threads within a
-     * project (session), with cursor-based pagination. Returns threads matching the
-     * given time range and optional filter.
+     * Query threads within a project (session), with cursor-based pagination. Returns
+     * threads matching the given time range and optional filter.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -34,9 +36,10 @@ export declare class Threads extends APIResource {
      */
     query(body: ThreadQueryParams, options?: RequestOptions): PagePromise<ThreadsItemsCursorPostPagination, Thread>;
     /**
-     * **Alpha:** The request and response contract may change; Compute aggregate stats
-     * for a single thread (turn count, latency percentiles, token/cost sums, and
-     * detail breakdowns) within a project.
+     * Compute aggregate stats for a single thread (turn count, latency percentiles,
+     * token/cost sums, and detail breakdowns) within a project.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts

package/dist/_openapi_client/resources/threads.js

@@ -5,8 +5,9 @@ import { ItemsCursorGetPagination, ItemsCursorPostPagination, } from '../core/pa
 import { path } from '../internal/utils/path.js';
 export class Threads extends APIResource {
     /**
-     * **Alpha:** The request and response contract may change; Retrieve all traces
-     * belonging to a specific thread within a project.
+     * Retrieve all traces belonging to a specific thread within a project.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -23,9 +24,10 @@ export class Threads extends APIResource {
         return this._client.getAPIList(path `/api/v2/threads/${threadID}/traces`, (ItemsCursorGetPagination), { query, ...options });
     }
     /**
-     * **Alpha:** The request and response contract may change; Query threads within a
-     * project (session), with cursor-based pagination. Returns threads matching the
-     * given time range and optional filter.
+     * Query threads within a project (session), with cursor-based pagination. Returns
+     * threads matching the given time range and optional filter.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -43,9 +45,10 @@ export class Threads extends APIResource {
         });
     }
     /**
-     * **Alpha:** The request and response contract may change; Compute aggregate stats
-     * for a single thread (turn count, latency percentiles, token/cost sums, and
-     * detail breakdowns) within a project.
+     * Compute aggregate stats for a single thread (turn count, latency percentiles,
+     * token/cost sums, and detail breakdowns) within a project.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts

package/dist/_openapi_client/resources/traces.cjs

@@ -9,9 +9,10 @@ const headers_js_1 = require("../internal/headers.cjs");
 const path_js_1 = require("../internal/utils/path.cjs");
 class Traces extends resource_js_1.APIResource {
     /**
-     * **Alpha:** The request and response contract may change; Returns runs for a
-     * trace ID within min/max start time. Optional `filter`; repeatable `selects` to
-     * select fields to return.
+     * Returns runs for a trace ID within min/max start time. Optional `filter`;
+     * repeatable `selects` to select fields to return.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -42,6 +43,8 @@ class Traces extends resource_js_1.APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
+     *
      * @example
      * ```ts
      * // Automatically fetches more pages as needed.

package/dist/_openapi_client/resources/traces.d.ts

@@ -5,9 +5,10 @@ import { ItemsCursorPostPagination, type ItemsCursorPostPaginationParams, PagePr
 import { RequestOptions } from '../internal/request-options.js';
 export declare class Traces extends APIResource {
     /**
-     * **Alpha:** The request and response contract may change; Returns runs for a
-     * trace ID within min/max start time. Optional `filter`; repeatable `selects` to
-     * select fields to return.
+     * Returns runs for a trace ID within min/max start time. Optional `filter`;
+     * repeatable `selects` to select fields to return.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -31,6 +32,8 @@ export declare class Traces extends APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
+     *
      * @example
      * ```ts
      * // Automatically fetches more pages as needed.

package/dist/_openapi_client/resources/traces.js

@@ -6,9 +6,10 @@ import { buildHeaders } from '../internal/headers.js';
 import { path } from '../internal/utils/path.js';
 export class Traces extends APIResource {
     /**
-     * **Alpha:** The request and response contract may change; Returns runs for a
-     * trace ID within min/max start time. Optional `filter`; repeatable `selects` to
-     * select fields to return.
+     * Returns runs for a trace ID within min/max start time. Optional `filter`;
+     * repeatable `selects` to select fields to return.
+     *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
      *
      * @example
      * ```ts
@@ -39,6 +40,8 @@ export class Traces extends APIResource {
      * Supports filters (`trace_filter`, `tree_filter`), cursor pagination (`cursor`),
      * and field projection (`selects`).
      *
+     * Self-hosted deployments require LangSmith `v0.16` or later.
+     *
      * @example
      * ```ts
      * // Automatically fetches more pages as needed.

package/dist/client.cjs

@@ -46,6 +46,7 @@ const index_js_1 = require("./index.cjs");
 const index_js_2 = require("./_openapi_client/index.cjs");
 const _uuid_js_1 = require("./utils/_uuid.cjs");
 const warn_js_1 = require("./utils/warn.cjs");
+const v2_migration_js_1 = require("./utils/v2_migration.cjs");
 const prompts_js_1 = require("./utils/prompts.cjs");
 const error_js_1 = require("./utils/error.cjs");
 const index_js_3 = require("./utils/prompt_cache/index.cjs");
@@ -192,6 +193,72 @@ exports.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;
+}
 class AutoBatchQueue {
     constructor(maxSizeBytes) {
         Object.defineProperty(this, "items", {
@@ -611,13 +678,26 @@ 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,
@@ -822,8 +902,15 @@ 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 = (0, env_js_1.resolveTracingMode)(config.tracingMode);
         if (this._tracingMode === "otel") {
@@ -858,8 +945,6 @@ class Client {
             // Use the global singleton instance
             this._promptCache = index_js_3.promptCacheSingleton;
         }
-        // Initialize custom headers
-        this._customHeaders = config.headers ?? {};
     }
     static getDefaultClientConfig() {
         const profileConfig = (0, profiles_js_1.loadProfileClientConfig)();
@@ -931,11 +1016,46 @@ 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/${index_js_1.__version__}`,
-            ...this._customHeaders,
+            ...this._callerHeaders,
         };
         // Required headers that should not be overridden
         if (this.apiKey !== undefined) {
@@ -952,6 +1072,35 @@ 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).
@@ -961,6 +1110,7 @@ class Client {
         return this._customHeaders;
     }
     set headers(value) {
+        assertValidHeaders(value);
         this._customHeaders = value ?? {};
     }
     _getOpenAPIBaseUrl() {
@@ -971,19 +1121,36 @@ 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 index_js_2.Langsmith({
-            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) {
@@ -1560,7 +1727,7 @@ 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 ((0, v2_migration_js_1.getQueryBackend)(serverInfo.instance_flags) === v2_migration_js_1.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}`);
         }
@@ -2085,7 +2252,22 @@ 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 }) {
+        (0, warn_js_1.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 }) {
         (0, _uuid_js_1.assertUuid)(runId);
         let run = _normalizeRunTimestamps(await this._get(`/runs/${runId}`));
         if (loadChildRuns) {
@@ -2093,7 +2275,11 @@ 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, }) {
+        (0, warn_js_1.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) {
@@ -2115,7 +2301,9 @@ 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`);
             }
@@ -2127,7 +2315,7 @@ 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,
@@ -2160,6 +2348,7 @@ 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.
@@ -2241,6 +2430,20 @@ class Client {
      * });
      */
     async *listRuns(props) {
+        (0, warn_js_1.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) {
@@ -2374,7 +2577,11 @@ 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) {
+        (0, warn_js_1.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");
@@ -2383,7 +2590,9 @@ 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,
@@ -2392,7 +2601,11 @@ 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) {
+        (0, warn_js_1.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");
@@ -2542,7 +2755,11 @@ 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 } = {}) {
+        (0, warn_js_1.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(),
@@ -2566,7 +2783,11 @@ 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) {
+        (0, warn_js_1.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" });
         (0, _uuid_js_1.assertUuid)(runId);
         await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2579,7 +2800,14 @@ 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) {
+        (0, warn_js_1.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",
+        });
         (0, _uuid_js_1.assertUuid)(runId);
         const response = await this.caller.call(async () => {
             const res = await this._fetch(`${this.apiUrl}/runs/${runId}/share`, {
@@ -2597,7 +2825,14 @@ 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, } = {}) {
+        (0, warn_js_1.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,
         });
@@ -4186,8 +4421,9 @@ 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.
@@ -4218,6 +4454,12 @@ class Client {
             }));
         }
         else {
+            (0, warn_js_1.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) => (0, _uuid_js_1.assertUuid)(id, `runs[${i}]`).toString()));
         }