@arizeai/phoenix-client 6.4.0 → 6.5.1

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/types/spans.ts

@@ -0,0 +1,12 @@
+import type { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
+
+/**
+ * Status codes for spans.
+ */
+export type SpanStatusCode = "OK" | "ERROR" | "UNSET";
+
+/**
+ * Span kind filter value. Accepts well-known OpenInference span kinds
+ * as well as arbitrary strings for forward-compatibility.
+ */
+export type SpanKindFilter = OpenInferenceSpanKind | (string & {});

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.`
+    );
+  }
+}