feat(js): Add method to list dataset versions

js/src/client.ts

@@ -7,6 +7,7 @@ import {
   Dataset,
   DatasetDiffInfo,
   DatasetShareSchema,
+  DatasetVersion,
   Example,
   ExampleCreate,
   ExampleUpdate,
@@ -1836,6 +1837,98 @@ export class Client implements LangSmithTracingClientInterface {
     return dataset as Dataset;
   }
 
+  /**
+   * Lists the versions of a dataset.
+   *
+   * @param {Object} params - The parameters for listing dataset versions.
+   * @param {string} params.datasetId - The ID of the dataset.
+   * @param {string} [params.search] - Optional search query to filter dataset versions.
+   * @param {string} [params.example] - Optional example query to filter dataset versions.
+   * @param {number} [params.limit=100] - The maximum number of dataset versions to return.
+   * @param {number} [params.offset=0] - The offset for pagination.
+   * @returns {Promise<DatasetVersion[]>} A promise that resolves to an array of dataset versions.
+   * @throws {Error} Throws an error if the datasetId is not a valid UUID.
+   */
+  public async listDatasetVersions({
+    datasetId,
+    search,
+    example,
+    limit = 100,
+    offset = 0,
+  }: {
+    datasetId: string;
+    search?: string;
+    example?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<DatasetVersion[]> {
+    assertUuid(datasetId);
+    const params = new URLSearchParams({
+      limit: limit.toString(),
+      offset: offset.toString(),
+    });
+    if (search !== undefined) {
+      params.append("search", search);
+    }
+    if (example !== undefined) {
+      params.append("example", example);
+    }
+    const response = await this.caller.call(
+      _getFetchImplementation(),
+      `${this.apiUrl}/datasets/${datasetId}/versions?${params.toString()}`,
+      {
+        method: "GET",
+        headers: this.headers,
+        signal: AbortSignal.timeout(this.timeout_ms),
+        ...this.fetchOptions,
+      }
+    );
+    const datasetVersions = await response.json();
+    return datasetVersions as DatasetVersion[];
+  }
+
+  /**
+   * Updates the version of a dataset.
+   *
+   * @param {string} dataSetId - The ID of the dataset to update.
+   * @param {Object} options - The options for updating the dataset version.
+   * @param {string} options.asOf - The timestamp of the dataset version.
+   * @param {string} options.tag - The tag of the dataset version.
+   * @returns {Promise<DatasetVersion>} - A promise that resolves to the updated dataset version.
+   * @throws {Error} - Throws an error if the update fails.
+   */
+  public async updateDatasetVersion(
+    dataSetId: string,
+    {
+      asOf,
+      tag,
+    }: {
+      asOf: string;
+      tag: string;
+    }
+  ): Promise<DatasetVersion> {
+    assertUuid(dataSetId);
+    const endpoint = `${this.apiUrl}/datasets/${dataSetId}/tags`;
+    const body: RecordStringAny = {
+      as_of: asOf,
+      tag,
+    };
+    const response = await this.caller.call(
+      _getFetchImplementation(),
+      endpoint,
+      {
+        method: "PUT",
+        headers: { ...this.headers, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeout_ms),
+        ...this.fetchOptions,
+      }
+    );
+    await raiseForStatus(response, "update dataset version");
+    const result = await response.json();
+    return result as DatasetVersion;
+  }
+
   /**
    * Get shared examples.
    *

js/src/schemas.ts

@@ -349,6 +349,11 @@ export interface DatasetShareSchema {
   url: string;
 }
 
+export interface DatasetVersion {
+  tags?: string[];
+  as_of: string;
+}
+
 export interface FeedbackSourceBase {
   type: string;
   metadata?: KVMap;