@arizeai/phoenix-client 6.3.0 → 6.5.0

package/src/sessions/listSessions.ts

@@ -2,10 +2,12 @@ import invariant from "tiny-invariant";
 
 import type { components } from "../__generated__/api/v1";
 import { createClient } from "../client";
+import { LIST_PROJECT_SESSIONS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { ProjectIdentifier } from "../types/projects";
 import { resolveProjectIdentifier } from "../types/projects";
 import type { Session } from "../types/sessions";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import { toSession } from "./sessionUtils";
 
 export type ListSessionsParams = ClientFn & ProjectIdentifier;
@@ -17,6 +19,8 @@ const DEFAULT_PAGE_SIZE = 100;
 /**
  * List all sessions for a project with automatic pagination handling.
  *
+ * @requires Phoenix server >= 13.5.0
+ *
  * @example
  * ```ts
  * import { listSessions } from "@arizeai/phoenix-client/sessions";
@@ -34,6 +38,7 @@ export async function listSessions(
   params: ListSessionsParams
 ): Promise<Session[]> {
   const client = params.client || createClient();
+  await ensureServerCapability({ client, requirement: LIST_PROJECT_SESSIONS });
   const projectIdentifier = resolveProjectIdentifier(params);
 
   const sessions: Session[] = [];

package/src/sessions/logSessionAnnotations.ts

@@ -1,5 +1,7 @@
 import { createClient } from "../client";
+import { ANNOTATE_SESSIONS } from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
 import type { SessionAnnotation } from "./types";
 import { toSessionAnnotationData } from "./types";
 
@@ -28,6 +30,8 @@ export interface LogSessionAnnotationsParams extends ClientFn {
  * @param params - The parameters to log session annotations
  * @returns The IDs of the created or updated annotations
  *
+ * @requires Phoenix server >= 12.0.0
+ *
  * @example
  * ```ts
  * const results = await logSessionAnnotations({
@@ -60,6 +64,7 @@ export async function logSessionAnnotations({
   sync = false,
 }: LogSessionAnnotationsParams): Promise<{ id: string }[]> {
   const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ANNOTATE_SESSIONS });
 
   const { data, error } = await client.POST("/v1/session_annotations", {
     params: {

package/src/spans/getSpans.ts

@@ -1,8 +1,10 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
+import { GET_SPANS_TRACE_IDS } 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 to get spans from a project using auto-generated types
@@ -44,6 +46,8 @@ export type GetSpansResult = {
  * @param params - The parameters to search for spans
  * @returns A paginated response containing spans and optional next cursor
  *
+ * @requires Phoenix server >= 13.9.0 when filtering by `traceIds`
+ *
  * @example
  * ```ts
  * // Get recent spans from a project
@@ -101,6 +105,9 @@ export async function getSpans({
   parentId,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
+  if (traceIds) {
+    await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
+  }
   const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {

package/src/types/semver.ts

@@ -0,0 +1,2 @@
+/** A semantic version triple: [major, minor, patch]. */
+export type SemanticVersion = [number, number, number];

package/src/types/serverRequirements.ts

@@ -0,0 +1,42 @@
+/**
+ * Server capability requirements.
+ *
+ * A "capability" represents a specific server-side feature — such as an HTTP
+ * route or query parameter — that is gated behind a minimum Phoenix server
+ * version.  Each {@link CapabilityRequirement} declares *what* the capability
+ * is and *which* server version first introduced it.
+ *
+ * The client checks these requirements at call time via
+ * {@link ensureServerCapability} so that callers get a clear, actionable error
+ * instead of an opaque 404 or 400 from an older server.
+ */
+
+import type { SemanticVersion } from "./semver";
+
+export interface RouteRequirement {
+  kind: "route";
+  /** HTTP method (e.g. "GET", "POST", "DELETE"). */
+  method: string;
+  /** URL path template (e.g. "/v1/sessions/{session_id}"). */
+  path: string;
+  /** Minimum Phoenix server version as [major, minor, patch]. */
+  minServerVersion: SemanticVersion;
+  /** Optional human-readable description override. */
+  description?: string;
+}
+
+export interface ParameterRequirement {
+  kind: "parameter";
+  /** Name of the query/path/header parameter. */
+  parameterName: string;
+  /** Location of the parameter (e.g. "query", "path", "header"). */
+  parameterLocation: string;
+  /** The route this parameter belongs to (e.g. "GET /v1/projects/{id}/spans"). */
+  route: string;
+  /** Minimum Phoenix server version as [major, minor, patch]. */
+  minServerVersion: SemanticVersion;
+  /** Optional human-readable description override. */
+  description?: string;
+}
+
+export type CapabilityRequirement = RouteRequirement | ParameterRequirement;

package/src/utils/semverUtils.ts

@@ -0,0 +1,66 @@
+/**
+ * Lightweight semantic version utilities.
+ */
+
+import type { SemanticVersion } from "../types/semver";
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a semver-like version string (e.g. "13.14.0") into a triple.
+ * Returns `null` if the string is not a valid version.
+ */
+export function parseSemanticVersion(raw: string): SemanticVersion | null {
+  const parts = raw.trim().split(".");
+  if (parts.length < 3) return null;
+  const major = parseInt(parts[0]!, 10);
+  const minor = parseInt(parts[1]!, 10);
+  const patch = parseInt(parts[2]!, 10);
+  if (
+    Number.isNaN(major) ||
+    Number.isNaN(minor) ||
+    Number.isNaN(patch) ||
+    major < 0 ||
+    minor < 0 ||
+    patch < 0
+  ) {
+    return null;
+  }
+  return [major, minor, patch];
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a `SemanticVersion` as a `"major.minor.patch"` string.
+ */
+export function formatVersion(version: SemanticVersion): string {
+  return `${version[0]}.${version[1]}.${version[2]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` if `version` is greater than or equal to `minVersion`.
+ */
+export function satisfiesMinVersion({
+  version,
+  minVersion,
+}: {
+  version: SemanticVersion;
+  minVersion: SemanticVersion;
+}): boolean {
+  const [serverVersionMajor, serverVersionMinor, serverVersionPatch] = version;
+  const [minVersionMajor, minVersionMinor, minVersionPatch] = minVersion;
+  if (serverVersionMajor !== minVersionMajor)
+    return serverVersionMajor > minVersionMajor;
+  if (serverVersionMinor !== minVersionMinor)
+    return serverVersionMinor > minVersionMinor;
+  return serverVersionPatch >= minVersionPatch;
+}

package/src/utils/serverVersionUtils.ts

@@ -0,0 +1,79 @@
+/**
+ * Phoenix server version utilities.
+ *
+ * Provides guards for capabilities that require a minimum Phoenix **server**
+ * version.  The server version is detected from the
+ * `x-phoenix-server-version` response header or by calling
+ * `GET /arize_phoenix_version`.
+ *
+ * ## Capability guard pattern
+ *
+ * Each server-side feature that was introduced after the initial release is
+ * represented by a {@link CapabilityRequirement} constant (defined in
+ * `constants/serverRequirements`).  Before calling such a feature, the client
+ * passes the requirement to {@link ensureServerCapability}, which compares the
+ * connected server's version against the requirement's minimum version and
+ * throws a descriptive error when the server is too old.  This lets callers
+ * see *exactly* which feature is unavailable and which version they need,
+ * rather than receiving an opaque HTTP 404 or 400 response.
+ */
+
+import type { PhoenixClient } from "../client";
+import type { CapabilityRequirement } from "../types/serverRequirements";
+import { formatVersion, satisfiesMinVersion } from "./semverUtils";
+
+// ---------------------------------------------------------------------------
+// Capability label
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a human-readable label from a structured capability requirement.
+ * Uses `description` if provided, otherwise auto-derives from metadata.
+ */
+export function capabilityLabel(req: CapabilityRequirement): string {
+  if (req.description) return req.description;
+  switch (req.kind) {
+    case "route":
+      return `The ${req.method} ${req.path} route`;
+    case "parameter":
+      return `The '${req.parameterName}' ${req.parameterLocation} parameter on ${req.route}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Check the **Phoenix server version** before allowing a capability to proceed.
+ *
+ * Throws if the connected Phoenix server is older than the minimum version
+ * required by the given capability. Also throws if the server version cannot
+ * be determined — this typically means the server is too old to report its
+ * version at all and is therefore incompatible with this client.
+ *
+ * @example
+ * ```ts
+ * import { ensureServerCapability } from "../utils/serverVersionUtils";
+ * import { GET_SESSION } from "../constants/serverRequirements";
+ *
+ * await ensureServerCapability({ client, requirement: GET_SESSION });
+ * ```
+ */
+export async function ensureServerCapability({
+  client,
+  requirement,
+}: {
+  client: PhoenixClient;
+  requirement: CapabilityRequirement;
+}): Promise<void> {
+  const version = await client.getServerVersion();
+  if (
+    !satisfiesMinVersion({ version, minVersion: requirement.minServerVersion })
+  ) {
+    throw new Error(
+      `${capabilityLabel(requirement)} requires Phoenix server >= ${formatVersion(requirement.minServerVersion)}, ` +
+        `but connected to server ${formatVersion(version)}. Please upgrade your Phoenix server.`
+    );
+  }
+}