@arizeai/phoenix-client 7.12.0 → 7.13.0

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.13.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/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,
+  };
+}