refactor(analytics): accept legacy "JSON"/"ARROW" format aliases

Widen AnalyticsFormat to also include the pre-rename "JSON" and "ARROW"
spellings, both marked @deprecated with a JSDoc note describing the
removal condition (no consumer on appkit/appkit-ui < 0.33.0). Add a
normalizeAnalyticsFormat helper and call it at the analytics route
handler entry point so all downstream code (cache key, format
branching, formatParameters) continues to operate on the canonical
"JSON_ARRAY" | "ARROW_STREAM" values.

InferResultByFormat is widened to also match "ARROW" so callers
passing the legacy spelling still get TypedArrowTable<...> inferred.

This lifts the breaking-change carve-out from the rename, so callers
of useAnalyticsQuery({ format: "JSON" | "ARROW" }) keep working with
only an IDE deprecation hint.

Signed-off-by: James Broadhead <jamesbroadhead@gmail.com>

Author: jamesbroadhead

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

@@ -4,8 +4,20 @@ import type { Table } from "apache-arrow";
 // Data Format Types
 // ============================================================================
 
-/** Supported response formats for analytics queries */
-export type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
+/**
+ * Supported response formats for analytics queries.
+ *
+ * "JSON" and "ARROW" are legacy aliases kept for backwards compatibility
+ * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on
+ * a pre-0.33.0 version.
+ */
+export type AnalyticsFormat =
+  | "JSON_ARRAY"
+  | "ARROW_STREAM"
+  /** @deprecated Use "JSON_ARRAY". Safe to remove once no consumer is on appkit-ui < 0.33.0. */
+  | "JSON"
+  /** @deprecated Use "ARROW_STREAM". Safe to remove once no consumer is on appkit-ui < 0.33.0. */
+  | "ARROW";
 
 /**
  * Typed Arrow Table - preserves row type information for type inference.
@@ -120,7 +132,9 @@ export type InferResultByFormat<
   T,
   K,
   F extends AnalyticsFormat,
-> = F extends "ARROW_STREAM" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
+> = F extends "ARROW_STREAM" | "ARROW"
+  ? TypedArrowTable<InferRowType<K>>
+  : InferResult<T, K>;
 
 /**
  * Infers parameters type from QueryRegistry[K]["parameters"]

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

@@ -24,6 +24,7 @@ import type { PluginManifest } from "../../registry";
 import { queryDefaults } from "./defaults";
 import manifest from "./manifest.json";
 import { QueryProcessor } from "./query";
+import { normalizeAnalyticsFormat } from "./types";
 import type {
   AnalyticsQueryResponse,
   IAnalyticsConfig,
@@ -128,7 +129,9 @@ export class AnalyticsPlugin extends Plugin implements ToolProvider {
     res: express.Response,
   ): Promise<void> {
     const { query_key } = req.params;
-    const { parameters, format = "JSON_ARRAY" } = req.body as IAnalyticsQueryRequest;
+    const { parameters, format: rawFormat = "JSON_ARRAY" } =
+      req.body as IAnalyticsQueryRequest;
+    const format = normalizeAnalyticsFormat(rawFormat);
 
     // Request-scoped logging with WideEvent tracking
     logger.debug(req, "Executing query: %s (format=%s)", query_key, format);

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

@@ -4,7 +4,38 @@ export interface IAnalyticsConfig extends BasePluginConfig {
   timeout?: number;
 }
 
-export type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
+/**
+ * Supported response formats for analytics queries.
+ *
+ * "JSON" and "ARROW" are legacy aliases kept for backwards compatibility
+ * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on
+ * a pre-0.33.0 version. The route handler normalizes them to their
+ * canonical equivalents before any downstream code reads the value.
+ */
+export type AnalyticsFormat =
+  | "JSON_ARRAY"
+  | "ARROW_STREAM"
+  /** @deprecated Use "JSON_ARRAY". Safe to remove once no consumer is on appkit < 0.33.0. */
+  | "JSON"
+  /** @deprecated Use "ARROW_STREAM". Safe to remove once no consumer is on appkit < 0.33.0. */
+  | "ARROW";
+
+/** Canonical (post-normalization) analytics format values. */
+export type CanonicalAnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
+
+/**
+ * Map a (possibly legacy) AnalyticsFormat to its canonical form.
+ * Legacy values come from appkit/appkit-ui < 0.33.0 and can be removed
+ * along with the deprecated aliases once no such consumer remains.
+ */
+export function normalizeAnalyticsFormat(
+  f: AnalyticsFormat,
+): CanonicalAnalyticsFormat {
+  if (f === "JSON") return "JSON_ARRAY";
+  if (f === "ARROW") return "ARROW_STREAM";
+  return f;
+}
+
 export interface IAnalyticsQueryRequest {
   parameters?: Record<string, any>;
   format?: AnalyticsFormat;