@arizeai/phoenix-client 7.6.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/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.6.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"
@@ -129,7 +133,7 @@
     "@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": {

package/src/__generated__/api/v1.ts

@@ -9987,7 +9987,7 @@ export interface operations {
                 order?: "asc" | "desc";
                 /** @description Maximum number of traces to return */
                 limit?: number;
-                /** @description Pagination cursor (Trace GlobalID) */
+                /** @description Pagination cursor returned by a previous request */
                 cursor?: string | null;
                 /** @description If true, include full span details for each trace. This significantly increases response size and query latency, especially with large page sizes. Prefer fetching spans lazily for individual traces when possible. */
                 include_spans?: boolean;

package/src/constants/serverRequirements.ts

@@ -98,6 +98,13 @@ export const LIST_PROJECT_TRACES: RouteRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const TRANSFER_TRACES: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/traces/transfer",
+  minServerVersion: [20, 4, 0],
+};
+
 export const GET_SPANS_BY_ATTRIBUTE: ParameterRequirement = {
   kind: "parameter",
   parameterName: "attribute",
@@ -227,6 +234,7 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_FILTERS,
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
+  TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
   ADD_TRACE_NOTE_IDENTIFIER,
   ADD_SPAN_NOTE_IDENTIFIER,

package/src/projects/index.ts

@@ -1 +1,2 @@
 export * from "./getProjects";
+export * from "./setProjectRetentionPolicy";

package/src/projects/setProjectRetentionPolicy.ts

@@ -0,0 +1,80 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+
+/**
+ * The retention-policy assignment returned for a project.
+ */
+export type ProjectRetentionPolicyAssignment =
+  components["schemas"]["ProjectRetentionPolicyData"];
+
+/**
+ * Parameters for assigning or resetting a project's retention policy.
+ */
+export type SetProjectRetentionPolicyParams = ClientFn &
+  ProjectIdentifier & {
+    /**
+     * The GlobalID of an existing trace retention policy, or `null` to reset
+     * the project to the default policy.
+     */
+    policyId: string | null;
+  };
+
+/**
+ * Assign an existing trace retention policy to a project, or reset the project
+ * to the default policy.
+ *
+ * This helper only changes the project's assignment. It does not create,
+ * retrieve, update, or delete retention policies.
+ *
+ * @param params - The project and policy assignment.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.policyId - An existing policy GlobalID, or `null` to reset.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The project's resulting retention-policy assignment.
+ *
+ * @example
+ * ```ts
+ * import { setProjectRetentionPolicy } from "@arizeai/phoenix-client/projects";
+ *
+ * await setProjectRetentionPolicy({
+ *   projectName: "support-bot",
+ *   policyId: "UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=",
+ * });
+ *
+ * await setProjectRetentionPolicy({
+ *   projectId: "UHJvamVjdDox",
+ *   policyId: null,
+ * });
+ * ```
+ */
+export async function setProjectRetentionPolicy(
+  params: SetProjectRetentionPolicyParams
+): Promise<ProjectRetentionPolicyAssignment> {
+  const client = params.client ?? createClient();
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const { data, error } = await client.PATCH(
+    "/v1/projects/{project_identifier}/retention",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+      },
+      body: {
+        policy_id: params.policyId,
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to set project retention policy");
+  return data.data;
+}

package/src/traces/getTraces.ts

@@ -22,7 +22,7 @@ export interface GetTracesParams extends ClientFn {
   order?: "asc" | "desc";
   /** Maximum number of traces to return */
   limit?: number;
-  /** Pagination cursor (Trace GlobalID) */
+  /** Pagination cursor */
   cursor?: string | null;
   /** If true, include full span details for each trace */
   includeSpans?: boolean;

package/src/traces/index.ts

@@ -2,4 +2,5 @@ export * from "./addTraceAnnotation";
 export * from "./addTraceNote";
 export * from "./getTraces";
 export * from "./logTraceAnnotations";
+export * from "./transferTraces";
 export type { TraceAnnotation } from "./types";

package/src/traces/transferTraces.ts

@@ -0,0 +1,89 @@
+import { createClient } from "../client";
+import { TRANSFER_TRACES } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for moving traces to another project.
+ */
+export interface TransferTracesParams extends ClientFn {
+  /**
+   * Trace GlobalIDs or OpenTelemetry trace IDs to move. All traces must
+   * currently belong to the same source project.
+   */
+  traceIdentifiers: string[];
+  /**
+   * The destination project name or GlobalID.
+   */
+  destinationProjectIdentifier: string;
+}
+
+/**
+ * The result of moving traces to another project.
+ */
+export interface TransferTracesResult {
+  /** The number of distinct traces moved. */
+  transferredTraceCount: number;
+  /** The destination project's GlobalID. */
+  destinationProjectId: string;
+}
+
+/**
+ * Move traces from one project to another.
+ *
+ * This operation re-parents the traces; it does not copy them. After the move,
+ * the traces no longer appear in their original project. Every trace must
+ * currently belong to the same source project.
+ *
+ * @param params - The parameters for moving traces.
+ * @param params.traceIdentifiers - Trace GlobalIDs or OpenTelemetry trace IDs to move.
+ * @param params.destinationProjectIdentifier - The destination project name or GlobalID.
+ * @returns The number of traces moved and the destination project's GlobalID.
+ * @throws {RangeError} If no trace identifiers are provided.
+ * @throws {HttpError} If a trace or destination project is missing, the traces
+ * belong to multiple source projects, or the transfer otherwise fails.
+ *
+ * @requires Phoenix server >= 20.4.0
+ *
+ * @example
+ * ```ts
+ * import { transferTraces } from "@arizeai/phoenix-client/traces";
+ *
+ * const result = await transferTraces({
+ *   traceIdentifiers: ["8f3a...", "VHJhY2U6Mg=="],
+ *   destinationProjectIdentifier: "production",
+ * });
+ *
+ * console.log(result.transferredTraceCount);
+ * console.log(result.destinationProjectId);
+ * ```
+ */
+export async function transferTraces({
+  client: _client,
+  traceIdentifiers,
+  destinationProjectIdentifier,
+}: TransferTracesParams): Promise<TransferTracesResult> {
+  if (traceIdentifiers.length === 0) {
+    throw new RangeError("At least one trace identifier is required");
+  }
+
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: TRANSFER_TRACES });
+
+  const { data, error } = await client.POST("/v1/traces/transfer", {
+    body: {
+      trace_identifiers: traceIdentifiers,
+      destination_project_identifier: destinationProjectIdentifier,
+    },
+  });
+
+  if (error) throw error;
+  if (!data?.data) {
+    throw new Error("Failed to transfer traces: no data returned");
+  }
+
+  return {
+    transferredTraceCount: data.data.transferred_trace_count,
+    destinationProjectId: data.data.destination_project_id,
+  };
+}

package/src/users/getCurrentUser.ts

@@ -0,0 +1,39 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+
+/** The user profile returned for the current Phoenix client credentials. */
+export type CurrentUser =
+  components["schemas"]["GetViewerResponseBody"]["data"];
+
+/**
+ * Get the currently authenticated user.
+ *
+ * When authentication is disabled, Phoenix returns an anonymous user with
+ * `auth_method: "ANONYMOUS"`.
+ *
+ * @param params - The parameters for fetching the current user.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The current user's generated API profile shape.
+ * @throws {HttpError} If the request is not authenticated or is forbidden.
+ *
+ * @example
+ * ```ts
+ * import { getCurrentUser } from "@arizeai/phoenix-client/users";
+ *
+ * const user = await getCurrentUser();
+ * console.log(user.auth_method);
+ * ```
+ */
+export async function getCurrentUser({
+  client: _client,
+}: ClientFn = {}): Promise<CurrentUser> {
+  const client = _client ?? createClient();
+  const { data, error } = await client.GET("/v1/user");
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to get current user");
+  return data.data;
+}

package/src/users/index.ts

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