refactor: rename AnalyticsFormat to API enum names (JSON_ARRAY, ARROW_STREAM)

packages/appkit-ui/src/react/hooks/__tests__/use-chart-data.test.ts

@@ -89,7 +89,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
@@ -110,7 +110,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
@@ -132,7 +132,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         { limit: 1000 },
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
@@ -157,7 +157,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.objectContaining({ startDate: "2025-01-01" }),
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
@@ -179,7 +179,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.anything(),
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
@@ -201,7 +201,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.anything(),
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
@@ -223,7 +223,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         { limit: 100 },
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
@@ -243,7 +243,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
   });

packages/appkit-ui/src/react/hooks/types.ts

@@ -5,7 +5,7 @@ import type { Table } from "apache-arrow";
 // ============================================================================
 
 /** Supported response formats for analytics queries */
-export type AnalyticsFormat = "JSON" | "ARROW";
+export type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
 
 /**
  * Typed Arrow Table - preserves row type information for type inference.
@@ -32,8 +32,8 @@ export interface TypedArrowTable<
 // ============================================================================
 
 /** Options for configuring an analytics SSE query */
-export interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON"> {
-  /** Response format - "JSON" returns typed arrays, "ARROW" returns TypedArrowTable */
+export interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON_ARRAY"> {
+  /** Response format - "JSON_ARRAY" returns typed arrays, "ARROW_STREAM" returns TypedArrowTable */
   format?: F;
 
   /** Maximum size of serialized parameters in bytes */
@@ -120,7 +120,7 @@ export type InferResultByFormat<
   T,
   K,
   F extends AnalyticsFormat,
-> = F extends "ARROW" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
+> = F extends "ARROW_STREAM" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
 
 /**
  * Infers parameters type from QueryRegistry[K]["parameters"]

packages/appkit-ui/src/react/hooks/use-analytics-query.ts

@@ -27,8 +27,8 @@ function getArrowStreamUrl(id: string) {
  * Integration hook between client and analytics plugin.
  *
  * The return type is automatically inferred based on the format:
- * - `format: "JSON"` (default): Returns typed array from QueryRegistry
- * - `format: "ARROW"`: Returns TypedArrowTable with row type preserved
+ * - `format: "JSON_ARRAY"` (default): Returns typed array from QueryRegistry
+ * - `format: "ARROW_STREAM"`: Returns TypedArrowTable with row type preserved
  *
  * Note: User context execution is determined by query file naming:
  * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)
@@ -47,20 +47,20 @@ function getArrowStreamUrl(id: string) {
  *
  * @example Arrow format
  * ```typescript
- * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW" });
+ * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
  * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null
  * ```
  */
 export function useAnalyticsQuery<
   T = unknown,
   K extends QueryKey = QueryKey,
-  F extends AnalyticsFormat = "JSON",
+  F extends AnalyticsFormat = "JSON_ARRAY",
 >(
   queryKey: K,
   parameters?: InferParams<K> | null,
   options: UseAnalyticsQueryOptions<F> = {} as UseAnalyticsQueryOptions<F>,
 ): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>> {
-  const format = options?.format ?? "JSON";
+  const format = options?.format ?? "JSON_ARRAY";
   const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;
   const autoStart = options?.autoStart ?? true;
 

packages/appkit-ui/src/react/hooks/use-chart-data.ts

@@ -50,32 +50,32 @@ export interface UseChartDataResult {
 function resolveFormat(
   format: DataFormat,
   parameters?: Record<string, unknown>,
-): "JSON" | "ARROW" {
+): "JSON_ARRAY" | "ARROW_STREAM" {
   // Explicit format selection
-  if (format === "json") return "JSON";
-  if (format === "arrow") return "ARROW";
+  if (format === "json") return "JSON_ARRAY";
+  if (format === "arrow") return "ARROW_STREAM";
 
   // Auto-selection heuristics
   if (format === "auto") {
     // Check for explicit hint in parameters
-    if (parameters?._preferArrow === true) return "ARROW";
-    if (parameters?._preferJson === true) return "JSON";
+    if (parameters?._preferArrow === true) return "ARROW_STREAM";
+    if (parameters?._preferJson === true) return "JSON_ARRAY";
 
     // Check limit parameter as data size hint
     const limit = parameters?.limit;
     if (typeof limit === "number" && limit > ARROW_THRESHOLD) {
-      return "ARROW";
+      return "ARROW_STREAM";
     }
 
     // Check for date range queries (often large)
     if (parameters?.startDate && parameters?.endDate) {
-      return "ARROW";
+      return "ARROW_STREAM";
     }
 
-    return "JSON";
+    return "JSON_ARRAY";
   }
 
-  return "JSON";
+  return "JSON_ARRAY";
 }
 
 // ============================================================================
@@ -110,7 +110,7 @@ export function useChartData(options: UseChartDataOptions): UseChartDataResult {
     [format, parameters],
   );
 
-  const isArrowFormat = resolvedFormat === "ARROW";
+  const isArrowFormat = resolvedFormat === "ARROW_STREAM";
 
   // Fetch data using the analytics query hook
   const {

packages/appkit/src/plugins/analytics/analytics.ts

@@ -115,7 +115,7 @@ export class AnalyticsPlugin extends Plugin {
     res: express.Response,
   ): Promise<void> {
     const { query_key } = req.params;
-    const { parameters, format = "JSON" } = req.body as IAnalyticsQueryRequest;
+    const { parameters, format = "JSON_ARRAY" } = req.body as IAnalyticsQueryRequest;
 
     // Request-scoped logging with WideEvent tracking
     logger.debug(req, "Executing query: %s (format=%s)", query_key, format);
@@ -151,7 +151,7 @@ export class AnalyticsPlugin extends Plugin {
     const executorKey = isAsUser ? this.resolveUserId(req) : "global";
 
     const queryParameters =
-      format === "ARROW"
+      format === "ARROW_STREAM"
         ? {
             formatParameters: {
               disposition: "EXTERNAL_LINKS",

packages/appkit/src/plugins/analytics/types.ts

@@ -4,7 +4,7 @@ export interface IAnalyticsConfig extends BasePluginConfig {
   timeout?: number;
 }
 
-export type AnalyticsFormat = "JSON" | "ARROW";
+export type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
 export interface IAnalyticsQueryRequest {
   parameters?: Record<string, any>;
   format?: AnalyticsFormat;