@arizeai/phoenix-client 7.12.0 → 7.14.0

package/docs/datasets.mdx

@@ -3,7 +3,7 @@ title: "Datasets"
 description: "Create and inspect datasets with @arizeai/phoenix-client"
 ---
 
-Datasets are the foundation for experiment runs. The dataset helpers cover creation (which upserts by name), record inspection, and example appends.
+Datasets are the foundation for experiment runs. The dataset helpers cover creation (which upserts by name), record inspection, example appends, and split management.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -25,14 +25,27 @@ const { datasetId } = await createDataset({
   description: "Support questions with expected answers",
   examples: [
     {
+      id: "order-tracking",
       input: { question: "Where is my order?" },
       output: { answer: "Use the tracking page in your account." },
       metadata: { channel: "chat" },
     },
+    {
+      id: "password-reset",
+      input: { question: "How do I reset my password?" },
+      output: { answer: "Use the forgot password flow." },
+      metadata: { channel: "chat" },
+    },
   ],
 });
 ```
 
+`id` is optional. When you do provide it, give every example its own value:
+example IDs are unique per dataset, so reusing one across examples in the same
+dataset is an error. A stable, unique `id` is what `createDataset()` matches on
+when it upserts, and what you can hand to the split helpers below instead of the
+server-generated `nodeId`. Omit `id` and the server generates one for you.
+
 ## Upsert Or Append
 
 `createDataset()` upserts by name: re-running it with the same name updates the existing dataset to match the examples you pass, and an unchanged upload is a no-op. To keep existing examples and add more, use `appendDatasetExamples()` instead of re-running `createDataset()` with the extra examples.
@@ -48,6 +61,7 @@ const dataset = await createDataset({
   description: "Support questions with expected answers",
   examples: [
     {
+      id: "order-tracking",
       input: { question: "Where is my order?" },
       output: { answer: "Use the tracking page in your account." },
     },
@@ -58,6 +72,7 @@ await appendDatasetExamples({
   dataset,
   examples: [
     {
+      id: "password-reset",
       input: { question: "How do I reset my password?" },
       output: { answer: "Use the forgot password flow." },
     },
@@ -71,6 +86,61 @@ await appendDatasetExamples({
 
 Use `getDataset`, `getDatasetExamples`, and `getDatasetInfo` to inspect datasets after creation.
 
+## Manage Splits On An Existing Dataset
+
+Use `createDatasetSplit`, `updateDatasetSplit`, and `deleteDatasetSplit` to
+manage train, test, validation, or other named subsets after a dataset exists.
+Select the dataset by name or GlobalID. Example membership accepts either the
+user-provided `id` or Phoenix `nodeId` returned by `getDatasetExamples`.
+
+```ts
+import {
+  createDatasetSplit,
+  deleteDatasetSplit,
+  getDatasetExamples,
+  updateDatasetSplit,
+} from "@arizeai/phoenix-client/datasets";
+
+const datasetIdentifier = "support-eval";
+const dataset = { datasetName: datasetIdentifier };
+const { examples } = await getDatasetExamples({
+  dataset,
+});
+const [firstExample, secondExample] = examples;
+if (firstExample == null || secondExample == null) {
+  throw new Error("At least two examples are required to demonstrate split updates");
+}
+
+const testSplit = await createDatasetSplit({
+  dataset,
+  name: "test",
+  description: "Held-out evaluation examples",
+  exampleIds: [firstExample.id],
+});
+
+// Only provided fields change. Adding an existing member or removing a
+// non-member is an idempotent no-op.
+await updateDatasetSplit({
+  dataset,
+  splitId: testSplit.id,
+  description: "Reviewed held-out examples",
+  addExampleIds: [secondExample.id],
+  removeExampleIds: [firstExample.id],
+});
+
+// Deleting a split removes its memberships, not the underlying examples.
+await deleteDatasetSplit({
+  dataset,
+  splitId: testSplit.id,
+});
+```
+
+Split names are unique across the Phoenix instance. Creating or renaming a
+split to an existing name fails with HTTP 409. These helpers require Phoenix
+server 19.20.0 or newer. Servers on 19.20.0 through 20.15.0 resolve membership
+by `nodeId` only — user-provided `id` values are accepted from the release that
+follows 20.15.0, so pass `nodeId` when you target an older server.
+
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
   <ul>
@@ -79,5 +149,8 @@ Use `getDataset`, `getDatasetExamples`, and `getDatasetInfo` to inspect datasets
     <li><code>src/datasets/getDataset.ts</code></li>
     <li><code>src/datasets/getDatasetExamples.ts</code></li>
     <li><code>src/datasets/getDatasetInfo.ts</code></li>
+    <li><code>src/datasets/createDatasetSplit.ts</code></li>
+    <li><code>src/datasets/updateDatasetSplit.ts</code></li>
+    <li><code>src/datasets/deleteDatasetSplit.ts</code></li>
   </ul>
 </section>

package/docs/overview.mdx

@@ -3,7 +3,7 @@ title: "Overview"
 description: "Typed TypeScript client for Phoenix platform APIs"
 ---
 
-`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, users, and CI-friendly dataset-backed eval tests.
+`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, secrets, users, and CI-friendly dataset-backed eval tests.
 
 ## Install
 
@@ -44,6 +44,7 @@ That gives the agent version-matched docs plus the exact implementation and gene
 | `@arizeai/phoenix-client/spans` | Span search, notes, and span/document annotations |
 | `@arizeai/phoenix-client/sessions` | Session listing, retrieval, and session annotations |
 | `@arizeai/phoenix-client/traces` | Project trace retrieval, transfers, and trace annotations |
+| `@arizeai/phoenix-client/secrets` | Atomic secret creation, rotation, and deletion |
 | `@arizeai/phoenix-client/users` | Current authenticated user retrieval |
 | `@arizeai/phoenix-client/vitest` | Vitest entrypoint for dataset-backed eval tests |
 | `@arizeai/phoenix-client/vitest/reporter` | Vitest reporter for Phoenix eval summaries |
@@ -164,6 +165,7 @@ Prefer this layer when:
 - [Annotations](./annotations) — annotation concepts, then [Span](./span-annotations), [Document](./document-annotations), and [Session](./session-annotations) annotations for detailed usage
 - [CI Eval Tests](./ci-evals) — Vitest/Jest eval suites backed by Phoenix datasets and experiments
 - [Spans](./spans), [Sessions](./sessions), [Traces](./traces), [Users](./users) — retrieval and maintenance
+- [Secrets](./secrets) — encrypted provider credential management
 
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
@@ -180,6 +182,7 @@ Prefer this layer when:
     <li><code>src/spans/</code></li>
     <li><code>src/sessions/</code></li>
     <li><code>src/traces/</code></li>
+    <li><code>src/secrets/</code></li>
     <li><code>src/users/</code></li>
     <li><code>src/vitest/</code></li>
     <li><code>src/jest/</code></li>

package/docs/secrets.mdx

@@ -0,0 +1,68 @@
+---
+title: "Secrets"
+description: "Atomically manage encrypted provider credentials with the Phoenix TypeScript client"
+---
+
+Use `upsertOrDeleteSecrets` from the `@arizeai/phoenix-client/secrets` entrypoint to create, rotate, or delete encrypted provider credentials in one atomic request.
+
+<Warning>
+Managing secrets requires an administrator when Phoenix authentication is enabled. Do not log the request batch or retain its values outside your credential store.
+</Warning>
+
+## Create, Update, And Delete Secrets
+
+Each batch entry has a `key` and a required `value`:
+
+- A string value creates or updates the secret.
+- `null` deletes the secret.
+- When a key occurs more than once, its last occurrence wins.
+
+```ts
+import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+
+const result = await upsertOrDeleteSecrets({
+  secrets: [
+    { key: "OPENAI_API_KEY", value: apiKey },
+    { key: "OLD_PROVIDER_API_KEY", value: null },
+  ],
+});
+
+console.log(result.upsertedKeys);
+console.log(result.deletedKeys);
+```
+
+The operation returns only `upsertedKeys` and `deletedKeys`. Submitted secret values are never returned or added to helper error messages.
+
+## Use An Explicit Client
+
+Pass `client` when you need to target a particular Phoenix instance. Otherwise, the helper creates a client from the standard Phoenix environment configuration.
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+
+const client = createClient({
+  options: { baseUrl: "https://phoenix.example.com" },
+});
+
+await upsertOrDeleteSecrets({
+  client,
+  secrets: [{ key: "OPENAI_API_KEY", value: apiKey }],
+});
+```
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/secrets/index.ts</code></li>
+    <li><code>src/secrets/upsertOrDeleteSecrets.ts</code></li>
+    <li><code>src/client.ts</code></li>
+    <li><code>src/__generated__/api/v1.ts</code></li>
+  </ul>
+</section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.12.0",
+  "version": "7.14.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -53,6 +53,10 @@
       "import": "./dist/esm/sessions/index.js",
       "require": "./dist/src/sessions/index.js"
     },
+    "./secrets": {
+      "import": "./dist/esm/secrets/index.js",
+      "require": "./dist/src/secrets/index.js"
+    },
     "./projects": {
       "import": "./dist/esm/projects/index.js",
       "require": "./dist/src/projects/index.js"
@@ -115,7 +119,7 @@
     "@ai-sdk/openai": "^4.0.71",
     "@ai-sdk/otel": "^1.0.107",
     "@anthropic-ai/sdk": "^0.111.0",
-    "@arizeai/phoenix-evals": "2.5.0",
+    "@arizeai/phoenix-evals": "2.6.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-node": "^2.11.0",

package/src/__generated__/api/v1.ts

@@ -2679,7 +2679,7 @@ export interface components {
             };
             /**
              * Example Ids
-             * @description Optional dataset example IDs (GlobalIDs) to seed the split with. Each example must belong to this dataset. Omit to create an empty split.
+             * @description Optional dataset example identifiers (GlobalIDs or user-provided IDs) to seed the split with. Each example must belong to this dataset. Omit to create an empty split.
              */
             example_ids?: string[];
         };
@@ -6716,12 +6716,12 @@ export interface components {
             } | null;
             /**
              * Add Example Ids
-             * @description Dataset example IDs (GlobalIDs) to add to the split. Each example must belong to this dataset. Adding an example already in the split is a no-op.
+             * @description Dataset example identifiers (GlobalIDs or user-provided IDs) to add to the split. Each example must belong to this dataset. Adding an example already in the split is a no-op.
              */
             add_example_ids?: string[];
             /**
              * Remove Example Ids
-             * @description Dataset example IDs (GlobalIDs) to remove from the split.
+             * @description Dataset example identifiers (GlobalIDs or user-provided IDs) to remove from the split.
              */
             remove_example_ids?: string[];
         };

package/src/constants/serverRequirements.ts

@@ -147,6 +147,27 @@ export const DATASET_UPLOAD_EXAMPLE_IDS: ParameterRequirement = {
   minServerVersion: [15, 0, 0],
 };
 
+export const CREATE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/datasets/{dataset_identifier}/splits",
+  minServerVersion: [19, 20, 0],
+};
+
+export const UPDATE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "PATCH",
+  path: "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+  minServerVersion: [19, 20, 0],
+};
+
+export const DELETE_DATASET_SPLIT: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+  minServerVersion: [19, 20, 0],
+};
+
 export const ADD_TRACE_NOTE_IDENTIFIER: ParameterRequirement = {
   kind: "parameter",
   parameterName: "identifier",
@@ -265,6 +286,9 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   LIST_SESSIONS_FILTER_EXPRESSION,
   TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
+  CREATE_DATASET_SPLIT,
+  UPDATE_DATASET_SPLIT,
+  DELETE_DATASET_SPLIT,
   ADD_TRACE_NOTE_IDENTIFIER,
   ADD_SPAN_NOTE_IDENTIFIER,
   ADD_SESSION_NOTE_IDENTIFIER,

package/src/datasets/createDatasetSplit.ts

@@ -0,0 +1,80 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { CREATE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier, DatasetSplit } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+type CreateDatasetSplitRequestBody =
+  components["schemas"]["CreateDatasetSplitRequestBody"];
+type CreateDatasetSplitResponseBody =
+  components["schemas"]["CreateDatasetSplitResponseBody"];
+
+/** Parameters for creating a dataset split. */
+export interface CreateDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** A unique name for the split. */
+  name: CreateDatasetSplitRequestBody["name"];
+  /** An optional description of the split. */
+  description?: CreateDatasetSplitRequestBody["description"];
+  /** An optional hex color for the split. */
+  color?: CreateDatasetSplitRequestBody["color"];
+  /** Arbitrary JSON metadata for the split. */
+  metadata?: CreateDatasetSplitRequestBody["metadata"];
+  /** Dataset example GlobalIDs or user-provided IDs with which to seed the split. */
+  exampleIds?: CreateDatasetSplitRequestBody["example_ids"];
+}
+
+/**
+ * Create a split on an existing dataset.
+ *
+ * @param params - The split to create.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.name - A unique name for the split.
+ * @param params.description - An optional description of the split.
+ * @param params.color - An optional hex color for the split.
+ * @param params.metadata - Arbitrary JSON metadata for the split.
+ * @param params.exampleIds - Dataset example GlobalIDs or user-provided IDs with which to seed the split.
+ * @returns The created dataset split.
+ * @throws {HttpError} If the dataset or an example does not exist, the name is
+ * already in use, or the request is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function createDatasetSplit({
+  client: _client,
+  dataset,
+  name,
+  description,
+  color,
+  metadata,
+  exampleIds,
+}: CreateDatasetSplitParams): Promise<DatasetSplit> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: CREATE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  const body: CreateDatasetSplitRequestBody = {
+    name,
+    ...(description !== undefined ? { description } : {}),
+    ...(color !== undefined ? { color } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    ...(exampleIds !== undefined ? { example_ids: exampleIds } : {}),
+  };
+  const response = await client.POST(
+    "/v1/datasets/{dataset_identifier}/splits",
+    {
+      params: { path: { dataset_identifier: datasetIdentifier } },
+      body,
+    }
+  );
+  const responseBody: CreateDatasetSplitResponseBody | undefined =
+    response.data;
+  invariant(responseBody?.data, "Failed to create dataset split");
+  return responseBody.data;
+}

package/src/datasets/deleteDatasetSplit.ts

@@ -0,0 +1,46 @@
+import { createClient } from "../client";
+import { DELETE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+/** Parameters for deleting a dataset split. */
+export interface DeleteDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** The dataset split GlobalID. */
+  splitId: string;
+}
+
+/**
+ * Delete a dataset split and its memberships without deleting its examples.
+ *
+ * @param params - The split to delete.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.splitId - The dataset split GlobalID.
+ * @returns A promise that resolves once the split is deleted.
+ * @throws {HttpError} If the dataset or split does not exist, or the split ID
+ * is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function deleteDatasetSplit({
+  client: _client,
+  dataset,
+  splitId,
+}: DeleteDatasetSplitParams): Promise<void> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: DELETE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  await client.DELETE("/v1/datasets/{dataset_identifier}/splits/{split_id}", {
+    params: {
+      path: {
+        dataset_identifier: datasetIdentifier,
+        split_id: splitId,
+      },
+    },
+  });
+}

package/src/datasets/index.ts

@@ -1,5 +1,9 @@
 export * from "./createDataset";
+export * from "./createDatasetSplit";
+export * from "./deleteDatasetSplit";
 export * from "./getDataset";
 export * from "./getDatasetExamples";
 export * from "./appendDatasetExamples";
 export * from "./getDatasetInfo";
+export * from "./updateDatasetSplit";
+export type { DatasetIdentifier, DatasetSplit } from "../types/datasets";

package/src/datasets/resolveDatasetIdentifier.ts

@@ -0,0 +1,6 @@
+import type { DatasetIdentifier } from "../types/datasets";
+
+/** Resolve a typed dataset selector to the REST path identifier. */
+export function resolveDatasetIdentifier(dataset: DatasetIdentifier): string {
+  return "datasetName" in dataset ? dataset.datasetName : dataset.datasetId;
+}

package/src/datasets/updateDatasetSplit.ts

@@ -0,0 +1,99 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { UPDATE_DATASET_SPLIT } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { DatasetIdentifier, DatasetSplit } from "../types/datasets";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+import { resolveDatasetIdentifier } from "./resolveDatasetIdentifier";
+
+type UpdateDatasetSplitRequestBody =
+  components["schemas"]["UpdateDatasetSplitRequestBody"];
+type UpdateDatasetSplitResponseBody =
+  components["schemas"]["UpdateDatasetSplitResponseBody"];
+
+/** Parameters for partially updating a dataset split. */
+export interface UpdateDatasetSplitParams extends ClientFn {
+  /** The dataset, selected by name or GlobalID. */
+  dataset: DatasetIdentifier;
+  /** The dataset split GlobalID. */
+  splitId: string;
+  /** A new unique name for the split. */
+  name?: UpdateDatasetSplitRequestBody["name"];
+  /** A new description, or null to clear it. */
+  description?: UpdateDatasetSplitRequestBody["description"];
+  /** A new hex color for the split. */
+  color?: UpdateDatasetSplitRequestBody["color"];
+  /** JSON metadata that replaces the existing metadata. */
+  metadata?: UpdateDatasetSplitRequestBody["metadata"];
+  /** Dataset example GlobalIDs or user-provided IDs to add. Existing memberships are no-ops. */
+  addExampleIds?: UpdateDatasetSplitRequestBody["add_example_ids"];
+  /** Dataset example GlobalIDs or user-provided IDs to remove. Missing memberships are no-ops. */
+  removeExampleIds?: UpdateDatasetSplitRequestBody["remove_example_ids"];
+}
+
+/**
+ * Partially update a dataset split and/or its example membership.
+ *
+ * Only provided fields change. Membership additions and removals are
+ * idempotent; if an example appears in both arrays, removal wins.
+ *
+ * @param params - The split fields and memberships to update.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.dataset - The dataset, selected by name or GlobalID.
+ * @param params.splitId - The dataset split GlobalID.
+ * @param params.name - A new unique name for the split.
+ * @param params.description - A new description, or null to clear it.
+ * @param params.color - A new hex color for the split.
+ * @param params.metadata - JSON metadata that replaces the existing metadata.
+ * @param params.addExampleIds - Dataset example GlobalIDs or user-provided IDs to add.
+ * @param params.removeExampleIds - Dataset example GlobalIDs or user-provided IDs to remove.
+ * @returns The updated dataset split.
+ * @throws {HttpError} If the dataset, split, or an example does not exist, the
+ * name is already in use, or the request is invalid.
+ *
+ * @requires Phoenix server >= 19.20.0
+ */
+export async function updateDatasetSplit({
+  client: _client,
+  dataset,
+  splitId,
+  name,
+  description,
+  color,
+  metadata,
+  addExampleIds,
+  removeExampleIds,
+}: UpdateDatasetSplitParams): Promise<DatasetSplit> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: UPDATE_DATASET_SPLIT });
+  const datasetIdentifier = resolveDatasetIdentifier(dataset);
+
+  const body: UpdateDatasetSplitRequestBody = {
+    ...(name !== undefined ? { name } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(color !== undefined ? { color } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+    ...(addExampleIds !== undefined ? { add_example_ids: addExampleIds } : {}),
+    ...(removeExampleIds !== undefined
+      ? { remove_example_ids: removeExampleIds }
+      : {}),
+  };
+  const response = await client.PATCH(
+    "/v1/datasets/{dataset_identifier}/splits/{split_id}",
+    {
+      params: {
+        path: {
+          dataset_identifier: datasetIdentifier,
+          split_id: splitId,
+        },
+      },
+      body,
+    }
+  );
+  const responseBody: UpdateDatasetSplitResponseBody | undefined =
+    response.data;
+  invariant(responseBody?.data, "Failed to update dataset split");
+  return responseBody.data;
+}

package/src/secrets/index.ts

@@ -0,0 +1 @@
+export * from "./upsertOrDeleteSecrets";

package/src/secrets/upsertOrDeleteSecrets.ts

@@ -0,0 +1,87 @@
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+
+/**
+ * A secret to create, update, or delete.
+ */
+export interface SecretInput {
+  /** The environment-style key used to identify the secret. */
+  key: string;
+  /** A value to create or update, or `null` to delete the key. */
+  value: string | null;
+}
+
+/**
+ * Parameters for atomically updating secrets.
+ */
+export interface UpsertOrDeleteSecretsParams extends ClientFn {
+  /**
+   * Ordered secret updates. When a key occurs more than once, the server
+   * applies only its last occurrence.
+   */
+  secrets: SecretInput[];
+}
+
+/**
+ * The names of the keys changed by a secrets update.
+ *
+ * Secret values are intentionally excluded.
+ */
+export interface UpsertOrDeleteSecretsResult {
+  /** Keys that were created or updated. */
+  upsertedKeys: string[];
+  /** Keys that were deleted. */
+  deletedKeys: string[];
+}
+
+/**
+ * Atomically create, update, or delete a batch of Phoenix secrets.
+ *
+ * A non-null value creates or updates a secret, while `null` deletes it.
+ * Duplicate keys use the last occurrence in the batch. The result contains
+ * key names only; submitted values are never returned or logged.
+ *
+ * @param params - The secrets update.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.secrets - Ordered key/value-or-null updates.
+ * @returns The names of the keys that were upserted and deleted.
+ *
+ * @example
+ * ```ts
+ * import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+ *
+ * const apiKey = process.env.OPENAI_API_KEY;
+ * if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+ *
+ * const result = await upsertOrDeleteSecrets({
+ *   secrets: [
+ *     { key: "OPENAI_API_KEY", value: apiKey },
+ *     { key: "OLD_PROVIDER_API_KEY", value: null },
+ *   ],
+ * });
+ * ```
+ */
+export async function upsertOrDeleteSecrets({
+  client: _client,
+  secrets,
+}: UpsertOrDeleteSecretsParams): Promise<UpsertOrDeleteSecretsResult> {
+  const client = _client ?? createClient();
+  const { data, error } = await client.PUT("/v1/secrets", {
+    body: { secrets },
+  });
+
+  // Do not include the server error payload here: validation responses can be
+  // influenced by submitted data, which must never enter helper error text.
+  if (error) {
+    throw new Error("Failed to upsert or delete secrets");
+  }
+
+  if (!data?.data) {
+    throw new Error("Failed to upsert or delete secrets: no data returned");
+  }
+
+  return {
+    upsertedKeys: data.data.upserted_keys,
+    deletedKeys: data.data.deleted_keys,
+  };
+}

package/src/types/datasets.ts

@@ -1,13 +1,18 @@
+import type { components } from "../__generated__/api/v1";
 import type { Node } from "./core";
 
+/** A named subset of examples in a dataset. */
+export type DatasetSplit = components["schemas"]["DatasetSplit"];
+
 type DatasetSelectorBase = { versionId?: string; splits?: string[] };
 
+/** A dataset identified by either its GlobalID or name. */
+export type DatasetIdentifier = { datasetId: string } | { datasetName: string };
+
 /**
  * A dataset can be identified by its datasetId, datasetName, or datasetVersionId
  */
-export type DatasetSelector =
-  | (DatasetSelectorBase & { datasetId: string })
-  | (DatasetSelectorBase & { datasetName: string });
+export type DatasetSelector = DatasetSelectorBase & DatasetIdentifier;
 
 /**
  * Overview information about a dataset