@arizeai/phoenix-client 6.0.0 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/sessions/getSession.ts

@@ -0,0 +1,44 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type GetSessionParams = ClientFn & {
+  /**
+   * The session identifier: either a GlobalID or user-provided session_id string.
+   */
+  sessionId: string;
+};
+
+/**
+ * Fetch a single session by its GlobalID or user-provided session_id string.
+ *
+ * @example
+ * ```ts
+ * import { getSession } from "@arizeai/phoenix-client/sessions";
+ *
+ * const session = await getSession({ sessionId: "my-session-id" });
+ * console.log(session.traces.length);
+ * ```
+ */
+export async function getSession({
+  client: _client,
+  sessionId,
+}: GetSessionParams): Promise<Session> {
+  const client = _client || createClient();
+  const { data, error } = await client.GET(
+    "/v1/sessions/{session_identifier}",
+    {
+      params: {
+        path: {
+          session_identifier: sessionId,
+        },
+      },
+    }
+  );
+  if (error) throw error;
+  invariant(data?.data, "Failed to get session");
+  return toSession(data.data);
+}

package/src/sessions/index.ts

@@ -1,2 +1,4 @@
 export * from "./addSessionAnnotation";
+export * from "./getSession";
+export * from "./listSessions";
 export * from "./logSessionAnnotations";

package/src/sessions/listSessions.ts

@@ -0,0 +1,64 @@
+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";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type ListSessionsParams = ClientFn & ProjectIdentifier;
+
+type SessionsResponse = components["schemas"]["GetSessionsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List all sessions for a project with automatic pagination handling.
+ *
+ * @example
+ * ```ts
+ * import { listSessions } from "@arizeai/phoenix-client/sessions";
+ *
+ * const sessions = await listSessions({
+ *   project: "my-project",
+ * });
+ *
+ * for (const session of sessions) {
+ *   console.log(`Session: ${session.sessionId}, Traces: ${session.traces.length}`);
+ * }
+ * ```
+ */
+export async function listSessions(
+  params: ListSessionsParams
+): Promise<Session[]> {
+  const client = params.client || createClient();
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const sessions: Session[] = [];
+  let cursor: string | null | undefined = null;
+
+  do {
+    const response: { data?: SessionsResponse; error?: unknown } =
+      await client.GET("/v1/projects/{project_identifier}/sessions", {
+        params: {
+          path: {
+            project_identifier: projectIdentifier,
+          },
+          query: {
+            cursor,
+            limit: DEFAULT_PAGE_SIZE,
+          },
+        },
+      });
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list sessions");
+
+    cursor = response.data.next_cursor ?? null;
+    sessions.push(...response.data.data.map(toSession));
+  } while (cursor != null);
+
+  return sessions;
+}

package/src/sessions/sessionUtils.ts

@@ -0,0 +1,23 @@
+import type { components } from "../__generated__/api/v1";
+import type { Session } from "../types/sessions";
+
+type SessionData = components["schemas"]["SessionData"];
+
+/**
+ * Convert an API SessionData response to a user-facing Session object.
+ */
+export function toSession(data: SessionData): Session {
+  return {
+    id: data.id,
+    sessionId: data.session_id,
+    projectId: data.project_id,
+    startTime: data.start_time,
+    endTime: data.end_time,
+    traces: data.traces.map((trace) => ({
+      id: trace.id,
+      traceId: trace.trace_id,
+      startTime: trace.start_time,
+      endTime: trace.end_time,
+    })),
+  };
+}

package/src/spans/getSpanAnnotations.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get span annotations from a project using auto-generated types
  */
 export interface GetSpanAnnotationsParams extends ClientFn {
   /** The project to get span annotations from */
-  project: ProjectSelector;
+  project: ProjectIdentifier;
   /** One or more span IDs to fetch annotations for */
   spanIds: string[];
   /** Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
@@ -89,8 +90,7 @@ export async function getSpanAnnotations({
   limit = 100,
 }: GetSpanAnnotationsParams): Promise<GetSpanAnnotationsResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<
     operations["listSpanAnnotationsBySpanIds"]["parameters"]["query"]

package/src/spans/getSpans.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get spans from a project using auto-generated types
  */
 export interface GetSpansParams extends ClientFn {
   /** The project to get spans from */
-  project: ProjectSelector;
+  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. */
@@ -87,8 +88,7 @@ export async function getSpans({
   endTime,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
     limit,

package/src/types/projects.ts

@@ -1,5 +1,22 @@
 /**
- * A project can be identified by its projectId or projectName
- * In the case of a projectName, the name must be url encodable
+ * Identifies a project. Accepts any of:
+ * - `project` — a project ID or name (the server accepts either)
+ * - `projectId` — an explicit project ID
+ * - `projectName` — an explicit project name
  */
-export type ProjectSelector = { projectId: string } | { projectName: string };
+export type ProjectIdentifier =
+  | { project: string }
+  | { projectId: string }
+  | { projectName: string };
+
+/**
+ * Resolves a {@link ProjectIdentifier} union to a plain string
+ * suitable for the REST `project_identifier` path parameter.
+ */
+export function resolveProjectIdentifier(
+  identifier: ProjectIdentifier
+): string {
+  if ("project" in identifier) return identifier.project;
+  if ("projectId" in identifier) return identifier.projectId;
+  return identifier.projectName;
+}

package/src/types/sessions.ts

@@ -0,0 +1,29 @@
+import type { Node } from "./core";
+
+/**
+ * A trace that belongs to a session.
+ */
+export interface SessionTrace extends Node {
+  /** The unique trace identifier (e.g. OpenTelemetry trace ID) */
+  traceId: string;
+  /** ISO 8601 timestamp of when the trace started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the trace ended */
+  endTime: string;
+}
+
+/**
+ * A session representing a group of related traces (e.g. a multi-turn conversation).
+ */
+export interface Session extends Node {
+  /** The user-provided session identifier */
+  sessionId: string;
+  /** The ID of the project this session belongs to */
+  projectId: string;
+  /** ISO 8601 timestamp of when the first trace in the session started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the last trace in the session ended */
+  endTime: string;
+  /** The traces that belong to this session */
+  traces: SessionTrace[];
+}