@arizeai/phoenix-client 7.5.0 → 7.7.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 prompts, datasets, experiments, spans, sessions, traces, 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, users, and CI-friendly dataset-backed eval tests.
 
 ## Install
 
@@ -37,12 +37,14 @@ That gives the agent version-matched docs plus the exact implementation and gene
 | Import | Purpose |
 |--------|---------|
 | `@arizeai/phoenix-client` | `createClient`, generated OpenAPI types, config helpers |
+| `@arizeai/phoenix-client/projects` | Project listing and retention-policy assignment |
 | `@arizeai/phoenix-client/prompts` | Prompt CRUD plus `toSDK` conversion |
 | `@arizeai/phoenix-client/datasets` | Dataset creation and retrieval |
 | `@arizeai/phoenix-client/experiments` | Experiment execution and lifecycle |
 | `@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 and trace annotations |
+| `@arizeai/phoenix-client/traces` | Project trace retrieval, transfers, and trace annotations |
+| `@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 |
 | `@arizeai/phoenix-client/jest` | Jest entrypoint for dataset-backed eval tests |
@@ -158,10 +160,10 @@ Prefer this layer when:
 
 ## Where To Start
 
-- [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
+- [Projects](./projects), [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
 - [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) — retrieval and maintenance
+- [Spans](./spans), [Sessions](./sessions), [Traces](./traces), [Users](./users) — retrieval and maintenance
 
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
@@ -171,12 +173,14 @@ Prefer this layer when:
     <li><code>src/config.ts</code></li>
     <li><code>src/__generated__/api/v1.ts</code></li>
     <li><code>src/types/core.ts</code></li>
+    <li><code>src/projects/</code></li>
     <li><code>src/prompts/</code></li>
     <li><code>src/datasets/</code></li>
     <li><code>src/experiments/</code></li>
     <li><code>src/spans/</code></li>
     <li><code>src/sessions/</code></li>
     <li><code>src/traces/</code></li>
+    <li><code>src/users/</code></li>
     <li><code>src/vitest/</code></li>
     <li><code>src/jest/</code></li>
     <li><code>src/testing/</code></li>

package/docs/projects.mdx

@@ -0,0 +1,71 @@
+---
+title: "Projects"
+description: "List projects and manage project retention-policy assignments"
+---
+
+The projects module lists Phoenix projects and assigns existing trace retention policies to them.
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li><code>src/projects/getProjects.ts</code></li>
+    <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/types/projects.ts</code></li>
+  </ul>
+</section>
+
+## List Projects
+
+`getProjects` handles cursor pagination automatically. Use `nameContains` for a case-insensitive, server-side substring filter.
+
+```ts
+import { getProjects } from "@arizeai/phoenix-client/projects";
+
+const projects = await getProjects({ nameContains: "support" });
+
+for (const project of projects) {
+  console.log(`${project.name} (${project.id})`);
+}
+```
+
+## Assign A Retention Policy
+
+`setProjectRetentionPolicy` accepts a project name or project GlobalID and the GlobalID of an existing trace retention policy.
+
+```ts
+import { setProjectRetentionPolicy } from "@arizeai/phoenix-client/projects";
+
+const assignment = await setProjectRetentionPolicy({
+  projectName: "support-bot",
+  policyId: "UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=",
+});
+
+console.log(assignment.project_id, assignment.policy_id);
+```
+
+You can select the project with `projectName`, `projectId`, or the shorthand `project`. `projectId` must be the project's GlobalID.
+
+This helper only changes which existing retention policy the project uses. It does not create, read, update, or delete retention policies; policy CRUD is outside the TypeScript client's projects helper.
+
+## Reset To The Default Policy
+
+Pass `null` as `policyId` to remove the explicit assignment and return the project to Phoenix's default retention policy.
+
+```ts
+await setProjectRetentionPolicy({
+  projectId: "UHJvamVjdDox",
+  policyId: null,
+});
+```
+
+Assigning or resetting a retention policy requires an admin when authentication is enabled. Invalid policy GlobalIDs produce a `422` response, while callers without permission receive `403`; both are surfaced as `HttpError` instances by the client.
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/projects/getProjects.ts</code></li>
+    <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/projects/index.ts</code></li>
+    <li><code>src/types/projects.ts</code></li>
+  </ul>
+</section>

package/docs/prompts.mdx

@@ -3,7 +3,7 @@ title: "Prompts"
 description: "Manage prompts with @arizeai/phoenix-client"
 ---
 
-The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, update a prompt's description and metadata, and adapt prompt versions to supported provider SDKs.
+The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, update a prompt's description and metadata, delete a prompt, and adapt prompt versions to supported provider SDKs.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -59,6 +59,23 @@ await updatePrompt({
 
 Requires a Phoenix server on 19.18.0 or later.
 
+## Delete A Prompt
+
+```ts
+import { deletePrompt } from "@arizeai/phoenix-client/prompts";
+
+await deletePrompt({ prompt: { name: "support-response" } });
+
+// Or by prompt id
+await deletePrompt({ prompt: { promptId: "UHJvbXB0OjE=" } });
+```
+
+`prompt` takes the same selector style as `getPrompt`, narrowed to the two selectors that identify a prompt rather than one of its versions: `{ name }` and `{ promptId }`. Passing a version selector — `{ versionId }`, or `{ name, tag }` — rejects instead of falling back to the whole prompt, so a variable holding a version never deletes more than you named.
+
+Deletion cascades: every version of the prompt, along with its version tags and labels, is removed with it, and the deletion cannot be undone. A prompt that does not exist rejects with `Prompt not found: <identifier>`.
+
+Requires a Phoenix server on 13.20.0 or later.
+
 ## Convert To Another SDK
 
 ```ts
@@ -81,6 +98,7 @@ Supported `sdk` targets:
   <h2>Source Map</h2>
   <ul>
     <li><code>src/prompts/createPrompt.ts</code></li>
+    <li><code>src/prompts/deletePrompt.ts</code></li>
     <li><code>src/prompts/getPrompt.ts</code></li>
     <li><code>src/prompts/listPrompts.ts</code></li>
     <li><code>src/prompts/updatePrompt.ts</code></li>

package/docs/traces.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Traces"
-description: "Retrieve traces and annotate them with @arizeai/phoenix-client"
+description: "Retrieve, move, and annotate traces with @arizeai/phoenix-client"
 ---
 
-The traces module provides trace retrieval and trace-level annotation functions.
+The traces module provides trace retrieval, project transfer, and trace-level annotation functions.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -18,6 +18,9 @@ The traces module provides trace retrieval and trace-level annotation functions.
     <li>
       <code>src/traces/logTraceAnnotations.ts</code> for batched annotation writes
     </li>
+    <li>
+      <code>src/traces/transferTraces.ts</code> for moving traces between projects
+    </li>
     <li>
       <code>src/traces/types.ts</code> for the <code>TraceAnnotation</code> type
     </li>
@@ -65,6 +68,28 @@ console.log(result.nextCursor);
 - Set `includeSpans` when you need a trace-centric fetch that also contains span details
 - `project` accepts `{ project }`, `{ projectId }`, or `{ projectName }`
 
+## Move Traces To Another Project
+
+Use `transferTraces` to move one or more traces from their current project to a destination project. This operation **moves rather than copies** the traces: after a successful transfer, they no longer appear in the source project.
+
+All traces in one call must currently belong to the same source project. Each trace identifier can be either an OpenTelemetry trace ID or a Phoenix trace GlobalID, and the destination can be either a project name or project GlobalID.
+
+```ts
+import { transferTraces } from "@arizeai/phoenix-client/traces";
+
+const result = await transferTraces({
+  traceIdentifiers: ["8f3a...", "VHJhY2U6Mg=="],
+  destinationProjectIdentifier: "production",
+});
+
+console.log(`Moved ${result.transferredTraceCount} traces`);
+console.log(`Destination project: ${result.destinationProjectId}`);
+```
+
+The result contains the number of distinct traces moved and the resolved GlobalID of the destination project. Phoenix rejects an empty list, trace or project identifiers that do not resolve, and requests that combine traces from multiple source projects.
+
+`transferTraces` requires Phoenix server 20.4.0 or newer.
+
 ## Annotate a Single Trace
 
 Use `addTraceAnnotation` to attach a label, score, or explanation to one trace. If you supply an `identifier`, Phoenix upserts the annotation when an annotation with that identifier already exists.
@@ -128,6 +153,7 @@ for (const r of results) {
     <li><code>src/traces/getTraces.ts</code></li>
     <li><code>src/traces/addTraceAnnotation.ts</code></li>
     <li><code>src/traces/logTraceAnnotations.ts</code></li>
+    <li><code>src/traces/transferTraces.ts</code></li>
     <li><code>src/traces/types.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
   </ul>

package/docs/users.mdx

@@ -0,0 +1,44 @@
+---
+title: "Users"
+description: "Get the current Phoenix user with @arizeai/phoenix-client"
+---
+
+The users module identifies the user associated with the client's current credentials.
+
+## Get The Current User
+
+```ts
+import { getCurrentUser } from "@arizeai/phoenix-client/users";
+
+const user = await getCurrentUser();
+
+if (user.auth_method === "ANONYMOUS") {
+  console.log("Authentication is disabled");
+} else {
+  console.log(`${user.username} has the ${user.role} role`);
+}
+```
+
+`getCurrentUser()` returns the generated Phoenix API user union. Authenticated deployments return a local, OAuth 2, or LDAP user profile. When authentication is disabled, it returns `{ auth_method: "ANONYMOUS" }`. Invalid credentials reject with an `HttpError` whose `status` is `401`; other authorization failures retain their HTTP status as well.
+
+Pass a client explicitly when you need custom configuration:
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+import { getCurrentUser } from "@arizeai/phoenix-client/users";
+
+const client = createClient({
+  options: { baseUrl: "https://phoenix.example.com" },
+});
+
+const user = await getCurrentUser({ client });
+```
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/users/getCurrentUser.ts</code></li>
+    <li><code>src/users/index.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.5.0",
+  "version": "7.7.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -57,6 +57,10 @@
       "import": "./dist/esm/projects/index.js",
       "require": "./dist/src/projects/index.js"
     },
+    "./users": {
+      "import": "./dist/esm/users/index.js",
+      "require": "./dist/src/users/index.js"
+    },
     "./traces": {
       "import": "./dist/esm/traces/index.js",
       "require": "./dist/src/traces/index.js"
@@ -100,36 +104,36 @@
   },
   "dependencies": {
     "@arizeai/openinference-semantic-conventions": "^2.7.0",
+    "@arizeai/phoenix-config": "0.5.0",
+    "@arizeai/phoenix-otel": "2.2.0",
     "async": "^3.2.6",
     "openapi-fetch": "^0.17.0",
     "tiny-invariant": "^1.3.3",
-    "zod": "^4.4.3",
-    "@arizeai/phoenix-config": "0.5.0",
-    "@arizeai/phoenix-otel": "2.2.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.36",
-    "@ai-sdk/otel": "^1.0.58",
+    "@ai-sdk/openai": "^4.0.46",
+    "@ai-sdk/otel": "^1.0.77",
     "@anthropic-ai/sdk": "^0.111.0",
+    "@arizeai/phoenix-evals": "2.4.0",
+    "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-node": "^2.10.0",
     "@types/async": "^3.2.25",
     "@types/node": "^26.2.0",
-    "ai": "^7.0.58",
+    "ai": "^7.0.77",
     "dotenv": "^17.4.2",
     "jest": "^30.4.2",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
-    "tsx": "^4.23.11",
-    "vitest": "^4.1.10",
-    "@arizeai/phoenix-evals": "2.2.0",
-    "@arizeai/phoenix-testing": "0.0.0"
+    "tsx": "^4.23.12",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",
     "ai": "^7.0.0",
     "jest": ">=27",
-    "openai": "^6.10.0",
+    "openai": "^6.10.0 || ^7.0.0",
     "vitest": ">=1"
   },
   "peerDependenciesMeta": {