@arizeai/phoenix-client 6.5.1 → 6.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.5.1",
+  "version": "6.5.3",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -47,6 +47,10 @@
       "import": "./dist/esm/sessions/index.js",
       "require": "./dist/src/sessions/index.js"
     },
+    "./traces": {
+      "import": "./dist/esm/traces/index.js",
+      "require": "./dist/src/traces/index.js"
+    },
     "./experiments": {
       "import": "./dist/esm/experiments/index.js",
       "require": "./dist/src/experiments/index.js"
@@ -71,8 +75,8 @@
     "openapi-fetch": "^0.12.5",
     "tiny-invariant": "^1.3.3",
     "zod": "^4.0.14",
-    "@arizeai/phoenix-config": "0.1.1",
-    "@arizeai/phoenix-otel": "0.4.2"
+    "@arizeai/phoenix-otel": "0.4.2",
+    "@arizeai/phoenix-config": "0.1.2"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.29",

package/src/__generated__/api/v1.ts

@@ -889,6 +889,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/user": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get the authenticated user
+         * @description Returns the profile of the currently authenticated user. When authentication is disabled, returns an anonymous user representation.
+         */
+        get: operations["getViewer"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/users": {
         parameters: {
             query?: never;
@@ -998,6 +1018,14 @@ export interface components {
              */
             explanation?: string | null;
         };
+        /** AnonymousUser */
+        AnonymousUser: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            auth_method: "ANONYMOUS";
+        };
         /** CategoricalAnnotationConfig */
         CategoricalAnnotationConfig: {
             /** Name */
@@ -1593,6 +1621,11 @@ export interface components {
             /** Next Cursor */
             next_cursor: string | null;
         };
+        /** GetViewerResponseBody */
+        GetViewerResponseBody: {
+            /** Data */
+            data: components["schemas"]["LocalUser"] | components["schemas"]["OAuth2User"] | components["schemas"]["LDAPUser"] | components["schemas"]["AnonymousUser"];
+        };
         /** HTTPValidationError */
         HTTPValidationError: {
             /** Detail */
@@ -6383,6 +6416,44 @@ export interface operations {
             };
         };
     };
+    getViewer: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The authenticated user's profile. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetViewerResponseBody"];
+                };
+            };
+            /** @description User not found. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
     getUsers: {
         parameters: {
             query?: {

package/src/constants/serverRequirements.ts

@@ -69,6 +69,13 @@ export const GET_SPANS_FILTERS: ParameterRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const LIST_PROJECT_TRACES: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/projects/{project_identifier}/traces",
+  minServerVersion: [13, 15, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -83,4 +90,5 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ANNOTATE_SESSIONS,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
+  LIST_PROJECT_TRACES,
 ] as const;

package/src/traces/getTraces.ts

@@ -0,0 +1,156 @@
+import type { operations } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { LIST_PROJECT_TRACES } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for getting traces from a project.
+ */
+export interface GetTracesParams extends ClientFn {
+  /** The project to get traces from */
+  project: ProjectIdentifier;
+  /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
+  startTime?: Date | string | null;
+  /** Exclusive upper bound time. Must be a valid ISO 8601 string or Date object. */
+  endTime?: Date | string | null;
+  /** Sort field */
+  sort?: "start_time" | "latency_ms";
+  /** Sort direction */
+  order?: "asc" | "desc";
+  /** Maximum number of traces to return */
+  limit?: number;
+  /** Pagination cursor (Trace GlobalID) */
+  cursor?: string | null;
+  /** If true, include full span details for each trace */
+  includeSpans?: boolean;
+  /** Filter traces by session identifier(s) (session_id strings or GlobalIDs) */
+  sessionId?: string | string[] | null;
+}
+
+export type GetTracesResponse =
+  operations["listProjectTraces"]["responses"]["200"];
+
+export type GetTracesResult = {
+  traces: GetTracesResponse["content"]["application/json"]["data"];
+  nextCursor: GetTracesResponse["content"]["application/json"]["next_cursor"];
+};
+
+/**
+ * Get traces from a project with filtering and sorting options.
+ *
+ * This method fetches traces from a project with support for time range filtering,
+ * sorting, session filtering, and cursor-based pagination.
+ *
+ * @requires Phoenix server >= 13.15.0
+ *
+ * @param params - The parameters to get traces
+ * @returns A paginated response containing traces and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get recent traces from a project
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   limit: 50,
+ * });
+ *
+ * // Get traces in a time range with spans included
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   startTime: new Date("2024-01-01"),
+ *   endTime: new Date("2024-01-02"),
+ *   includeSpans: true,
+ * });
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getTraces({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     cursor,
+ *     limit: 100,
+ *   });
+ *   result.traces.forEach(trace => {
+ *     console.log(`Trace: ${trace.trace_id}`);
+ *   });
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export async function getTraces({
+  client: _client,
+  project,
+  cursor,
+  limit = 100,
+  startTime,
+  endTime,
+  sort,
+  order,
+  includeSpans,
+  sessionId,
+}: GetTracesParams): Promise<GetTracesResult> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: LIST_PROJECT_TRACES });
+  const projectIdentifier = resolveProjectIdentifier(project);
+
+  const params: NonNullable<
+    operations["listProjectTraces"]["parameters"]["query"]
+  > = {
+    limit,
+  };
+
+  if (cursor) {
+    params.cursor = cursor;
+  }
+
+  if (startTime) {
+    params.start_time =
+      startTime instanceof Date ? startTime.toISOString() : startTime;
+  }
+
+  if (endTime) {
+    params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
+  }
+
+  if (sort) {
+    params.sort = sort;
+  }
+
+  if (order) {
+    params.order = order;
+  }
+
+  if (includeSpans) {
+    params.include_spans = true;
+  }
+
+  if (sessionId) {
+    params.session_identifier = Array.isArray(sessionId)
+      ? sessionId
+      : [sessionId];
+  }
+
+  const { data, error } = await client.GET(
+    "/v1/projects/{project_identifier}/traces",
+    {
+      params: {
+        path: {
+          project_identifier: projectIdentifier,
+        },
+        query: params,
+      },
+    }
+  );
+
+  if (error) throw error;
+  return {
+    traces: data?.data ?? [],
+    nextCursor: data?.next_cursor ?? null,
+  };
+}

package/src/traces/index.ts

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