@spaceinvoices/react-ui 0.1.1

package/src/components/dashboard/payment-trend-chart/use-payment-trend.ts

@@ -0,0 +1,92 @@
+/**
+ * Payment trend hook using the entity stats API.
+ * Server-side aggregation by month for accurate trend data.
+ */
+import type { StatsQueryDataItem } from "@spaceinvoices/js-sdk";
+import { useQuery } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { STATS_QUERY_CACHE_KEY } from "../shared/use-stats-query";
+
+export const PAYMENT_TREND_CACHE_KEY = "dashboard-payment-trend";
+
+function getLastMonths(count: number): { months: string[]; startDate: string; endDate: string } {
+  const months: string[] = [];
+  const now = new Date();
+
+  // Start of the month 'count-1' months ago
+  const startDate = new Date(now.getFullYear(), now.getMonth() - (count - 1), 1);
+  // End of current month
+  const endDate = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+
+  for (let i = count - 1; i >= 0; i--) {
+    const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+    months.push(d.toISOString().substring(0, 7));
+  }
+
+  return {
+    months,
+    startDate: startDate.toISOString().substring(0, 10),
+    endDate: endDate.toISOString().substring(0, 10),
+  };
+}
+
+export type PaymentTrendData = { month: string; amount: number }[];
+
+export function usePaymentTrendData(entityId: string | undefined) {
+  const { sdk } = useSDK();
+
+  const { months, startDate, endDate } = getLastMonths(6);
+
+  const query = useQuery({
+    queryKey: [STATS_QUERY_CACHE_KEY, entityId, "payment-trend", startDate, endDate],
+    queryFn: async () => {
+      if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+      return sdk.entityStats.queryEntityStats(
+        {
+          metrics: [{ type: "sum", field: "amount_converted", alias: "amount" }],
+          table: "payments",
+          date_from: startDate,
+          date_to: endDate,
+          group_by: ["month", "currency_code"], // Include currency for display
+          order_by: [{ field: "month", direction: "asc" }],
+        },
+        { entity_id: entityId },
+      );
+    },
+    enabled: !!entityId && !!sdk,
+    staleTime: 30_000,
+    select: (response) => {
+      // Build a map of all months with 0 amount
+      const monthMap: Record<string, number> = {};
+      for (const month of months) {
+        monthMap[month] = 0;
+      }
+
+      // Fill in the actual amounts from the API response
+      // Sum up amounts per month (in case of multiple rows due to currency_code grouping)
+      const data = response.data || [];
+      let currency = "EUR";
+      for (const row of data as StatsQueryDataItem[]) {
+        const month = String(row.month);
+        if (month in monthMap) {
+          monthMap[month] += Number(row.amount) || 0;
+        }
+        // Get currency from first row with data
+        if (row.currency_code && currency === "EUR") {
+          currency = String(row.currency_code);
+        }
+      }
+
+      return {
+        data: months.map((month) => ({ month, amount: monthMap[month] })),
+        currency, // Currency from payment data
+      };
+    },
+  });
+
+  return {
+    data: query.data?.data || [],
+    currency: query.data?.currency || "EUR",
+    isLoading: query.isLoading,
+  };
+}

package/src/components/dashboard/revenue-card.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { AlertTriangle, TrendingDown, TrendingUp } from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/ui/components/ui/card";
+
+export type RevenueCardProps = {
+  title: string;
+  value: number;
+  currency: string;
+  variant?: "default" | "success" | "warning" | "danger";
+  subtitle?: string;
+  locale?: string;
+};
+
+const variantStyles = {
+  default: "",
+  success: "text-green-600 dark:text-green-400",
+  warning: "text-yellow-600 dark:text-yellow-400",
+  danger: "text-red-600 dark:text-red-400",
+};
+
+const variantIcons = {
+  default: null,
+  success: TrendingUp,
+  warning: AlertTriangle,
+  danger: TrendingDown,
+};
+
+export function RevenueCard({ title, value, currency, variant = "default", subtitle, locale }: RevenueCardProps) {
+  const Icon = variantIcons[variant];
+  const formattedValue = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 2,
+  }).format(value);
+
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between pb-2">
+        <CardTitle className="font-medium text-muted-foreground text-sm">{title}</CardTitle>
+        {Icon && <Icon className={`h-4 w-4 ${variantStyles[variant]}`} />}
+      </CardHeader>
+      <CardContent>
+        <div className={`font-bold text-2xl ${variantStyles[variant]}`}>{formattedValue}</div>
+        {subtitle && <p className="mt-1 text-muted-foreground text-xs">{subtitle}</p>}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/dashboard/revenue-trend-chart/index.ts

@@ -0,0 +1,4 @@
+export type { RevenueTrendChartData, RevenueTrendChartProps } from "./revenue-trend-chart";
+export { RevenueTrendChart } from "./revenue-trend-chart";
+export type { RevenueTrendData } from "./use-revenue-trend";
+export { REVENUE_TREND_CACHE_KEY, useRevenueTrendData } from "./use-revenue-trend";

package/src/components/dashboard/revenue-trend-chart/locales/sl.ts

@@ -0,0 +1,5 @@
+export default {
+  "Revenue Trend": "Trend prihodkov",
+  "Monthly revenue over the last 6 months": "Mesečni prihodki v zadnjih 6 mesecih",
+  "No data available": "Ni podatkov",
+} as const;

package/src/components/dashboard/revenue-trend-chart/revenue-trend-chart.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from "recharts";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/ui/components/ui/card";
+import { type ChartConfig, ChartContainer, ChartTooltip, ChartTooltipContent } from "@/ui/components/ui/chart";
+import { createTranslation } from "@/ui/lib/translation";
+import { ChartEmptyState } from "../chart-empty-state";
+import { LoadingCard } from "../loading-card";
+import sl from "./locales/sl";
+import { useRevenueTrendData } from "./use-revenue-trend";
+
+const translations = { sl } as const;
+
+export type RevenueTrendChartData = { month: string; revenue: number }[];
+
+type BaseProps = {
+  locale?: string;
+  t?: (key: string) => string;
+  namespace?: string;
+};
+
+type DataProps = BaseProps & {
+  data: RevenueTrendChartData;
+  currency: string;
+  entityId?: never;
+};
+
+type TurnkeyProps = BaseProps & {
+  entityId: string;
+  data?: never;
+  currency?: never;
+};
+
+export type RevenueTrendChartProps = DataProps | TurnkeyProps;
+
+const chartConfig = {
+  revenue: {
+    label: "Revenue",
+    color: "var(--chart-1)",
+  },
+} satisfies ChartConfig;
+
+function formatMonth(month: string, locale?: string): string {
+  const date = new Date(`${month}-01`);
+  return date.toLocaleDateString(locale, { month: "short" });
+}
+
+function formatCurrency(value: number, currency: string, locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  }).format(value);
+}
+
+export function RevenueTrendChart(props: RevenueTrendChartProps) {
+  const { locale, t: externalT, namespace } = props;
+  const t = createTranslation({ t: externalT, namespace, locale, translations });
+
+  // Turnkey mode - fetch own data
+  const hookResult = useRevenueTrendData("entityId" in props ? props.entityId : undefined);
+
+  // Determine data source
+  const data = "entityId" in props ? hookResult.data : props.data;
+  const currency = "entityId" in props ? hookResult.currency : props.currency;
+  const isLoading = "entityId" in props ? hookResult.isLoading : false;
+
+  if (isLoading) {
+    return <LoadingCard className="h-[280px]" />;
+  }
+
+  const hasData = data.some((d) => d.revenue > 0);
+
+  // Placeholder data for empty state
+  const placeholderData =
+    data.length > 0
+      ? data.map((d) => ({ ...d, revenue: 100 }))
+      : [
+          { month: "2024-01", revenue: 80 },
+          { month: "2024-02", revenue: 120 },
+          { month: "2024-03", revenue: 90 },
+          { month: "2024-04", revenue: 140 },
+          { month: "2024-05", revenue: 100 },
+          { month: "2024-06", revenue: 130 },
+        ];
+
+  const chartContent = (
+    <ChartContainer config={chartConfig} className="h-[200px] w-full">
+      <AreaChart data={hasData ? data : placeholderData} margin={{ left: 12, right: 12 }}>
+        <CartesianGrid vertical={false} strokeDasharray="3 3" />
+        <XAxis
+          dataKey="month"
+          tickLine={false}
+          axisLine={false}
+          tickMargin={8}
+          tickFormatter={(m) => formatMonth(m, locale)}
+        />
+        <YAxis
+          tickLine={false}
+          axisLine={false}
+          tickMargin={8}
+          tickFormatter={(value) => formatCurrency(value, currency, locale)}
+          width={80}
+        />
+        <defs>
+          <linearGradient id="fillRevenue" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="5%" stopColor="var(--chart-1)" stopOpacity={0.8} />
+            <stop offset="95%" stopColor="var(--chart-1)" stopOpacity={0.1} />
+          </linearGradient>
+        </defs>
+        <ChartTooltip
+          cursor={false}
+          content={
+            <ChartTooltipContent
+              labelFormatter={(label) => formatMonth(label, locale)}
+              formatter={(value) => formatCurrency(Number(value), currency, locale)}
+            />
+          }
+        />
+        <Area dataKey="revenue" type="monotone" fill="url(#fillRevenue)" stroke="var(--chart-1)" strokeWidth={2} />
+      </AreaChart>
+    </ChartContainer>
+  );
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t("Revenue Trend")}</CardTitle>
+        <CardDescription>{t("Monthly revenue over the last 6 months")}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        {hasData ? chartContent : <ChartEmptyState label={t("No data available")}>{chartContent}</ChartEmptyState>}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/dashboard/revenue-trend-chart/use-revenue-trend.ts

@@ -0,0 +1,93 @@
+/**
+ * Revenue trend hook using the entity stats API.
+ * Server-side aggregation by month for accurate trend data.
+ */
+import type { StatsQueryDataItem } from "@spaceinvoices/js-sdk";
+import { useQuery } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { STATS_QUERY_CACHE_KEY } from "../shared/use-stats-query";
+
+export const REVENUE_TREND_CACHE_KEY = "dashboard-revenue-trend";
+
+function getLastMonths(count: number): { months: string[]; startDate: string; endDate: string } {
+  const months: string[] = [];
+  const now = new Date();
+
+  // Start of the month 'count-1' months ago
+  const startDate = new Date(now.getFullYear(), now.getMonth() - (count - 1), 1);
+  // End of current month
+  const endDate = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+
+  for (let i = count - 1; i >= 0; i--) {
+    const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+    months.push(d.toISOString().substring(0, 7));
+  }
+
+  return {
+    months,
+    startDate: startDate.toISOString().substring(0, 10),
+    endDate: endDate.toISOString().substring(0, 10),
+  };
+}
+
+export type RevenueTrendData = { month: string; revenue: number }[];
+
+export function useRevenueTrendData(entityId: string | undefined) {
+  const { sdk } = useSDK();
+
+  const { months, startDate, endDate } = getLastMonths(6);
+
+  const query = useQuery({
+    queryKey: [STATS_QUERY_CACHE_KEY, entityId, "revenue-trend", startDate, endDate],
+    queryFn: async () => {
+      if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+      return sdk.entityStats.queryEntityStats(
+        {
+          metrics: [{ type: "sum", field: "total_with_tax_converted", alias: "revenue" }],
+          table: "invoices",
+          date_from: startDate,
+          date_to: endDate,
+          filters: { is_draft: false, voided_at: null },
+          group_by: ["month", "quote_currency"], // Include currency for display
+          order_by: [{ field: "month", direction: "asc" }],
+        },
+        { entity_id: entityId },
+      );
+    },
+    enabled: !!entityId && !!sdk,
+    staleTime: 30_000,
+    select: (response) => {
+      // Build a map of all months with 0 revenue
+      const monthMap: Record<string, number> = {};
+      for (const month of months) {
+        monthMap[month] = 0;
+      }
+
+      // Fill in the actual revenue from the API response
+      // Sum up revenues per month (in case of multiple rows due to quote_currency grouping)
+      const data = response.data || [];
+      let currency = "EUR";
+      for (const row of data as StatsQueryDataItem[]) {
+        const month = String(row.month);
+        if (month in monthMap) {
+          monthMap[month] += Number(row.revenue) || 0;
+        }
+        // Get currency from first row with data
+        if (row.quote_currency && currency === "EUR") {
+          currency = String(row.quote_currency);
+        }
+      }
+
+      return {
+        data: months.map((month) => ({ month, revenue: monthMap[month] })),
+        currency, // Currency from document data
+      };
+    },
+  });
+
+  return {
+    data: query.data?.data || [],
+    currency: query.data?.currency || "EUR",
+    isLoading: query.isLoading,
+  };
+}

package/src/components/dashboard/shared/index.ts

@@ -0,0 +1,5 @@
+export type { RevenueData } from "./use-revenue-data";
+export { REVENUE_DATA_CACHE_KEY, useRevenueData } from "./use-revenue-data";
+export type { StatsCountsData } from "./use-stats-counts";
+export { STATS_COUNTS_CACHE_KEY, useStatsCountsData } from "./use-stats-counts";
+export { STATS_QUERY_CACHE_KEY, useStatsQuery } from "./use-stats-query";

package/src/components/dashboard/shared/use-revenue-data.ts

@@ -0,0 +1,160 @@
+/**
+ * Revenue data hook using the entity stats API.
+ * Server-side aggregation for accurate calculations.
+ */
+import type { StatsQueryDataItem } from "@spaceinvoices/js-sdk";
+import { useQueries } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { STATS_QUERY_CACHE_KEY } from "./use-stats-query";
+
+export const REVENUE_DATA_CACHE_KEY = "dashboard-revenue-data";
+
+function getMonthDateRange() {
+  const now = new Date();
+  const firstDay = new Date(now.getFullYear(), now.getMonth(), 1);
+  const lastDay = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+  return {
+    from: firstDay.toISOString().split("T")[0],
+    to: lastDay.toISOString().split("T")[0],
+  };
+}
+
+function getYearDateRange() {
+  const year = new Date().getFullYear();
+  return {
+    from: `${year}-01-01`,
+    to: `${year}-12-31`,
+  };
+}
+
+export type RevenueData = {
+  thisMonth: number;
+  thisYear: number;
+  outstanding: number;
+  overdue: number;
+  overdueCount: number;
+  currency: string;
+};
+
+export function useRevenueData(entityId: string | undefined) {
+  const { sdk } = useSDK();
+  const monthRange = getMonthDateRange();
+  const yearRange = getYearDateRange();
+
+  const queries = useQueries({
+    queries: [
+      // This month revenue (using converted amounts for multi-currency support)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "revenue-this-month", monthRange.from],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [{ type: "sum", field: "total_with_tax_converted", alias: "revenue" }],
+              table: "invoices",
+              date_from: monthRange.from,
+              date_to: monthRange.to,
+              filters: { is_draft: false, voided_at: null },
+              group_by: ["quote_currency"], // Get the currency for display
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // This year revenue (using converted amounts for multi-currency support)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "revenue-this-year", yearRange.from],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [{ type: "sum", field: "total_with_tax_converted", alias: "revenue" }],
+              table: "invoices",
+              date_from: yearRange.from,
+              date_to: yearRange.to,
+              filters: { is_draft: false, voided_at: null },
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Outstanding (unpaid, not voided)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "outstanding"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [{ type: "sum", field: "total_due", alias: "outstanding" }],
+              table: "invoices",
+              filters: { is_draft: false, voided_at: null, paid_in_full: false },
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Overdue (past due date, unpaid)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "overdue"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [
+                { type: "sum", field: "total_due", alias: "overdue" },
+                { type: "count", alias: "count" },
+              ],
+              table: "invoices",
+              filters: { is_draft: false, voided_at: null, paid_in_full: false },
+              group_by: ["overdue_bucket"],
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+    ],
+  });
+
+  const [thisMonthQuery, thisYearQuery, outstandingQuery, overdueQuery] = queries;
+
+  // Extract this month revenue and currency (may have multiple rows if grouped by quote_currency)
+  const thisMonthData = thisMonthQuery.data?.data || [];
+  const thisMonthRevenue = thisMonthData.reduce(
+    (sum: number, row: StatsQueryDataItem) => sum + (Number(row.revenue) || 0),
+    0,
+  );
+  // Get currency from first row with data
+  const currency = (thisMonthData[0]?.quote_currency as string) || "EUR";
+
+  // Extract overdue data (buckets other than "current")
+  const overdueData = overdueQuery.data?.data || [];
+  const overdueBuckets = overdueData.filter((row: StatsQueryDataItem) => row.overdue_bucket !== "current");
+  const totalOverdue = overdueBuckets.reduce(
+    (sum: number, row: StatsQueryDataItem) => sum + (Number(row.overdue) || 0),
+    0,
+  );
+  const overdueCount = overdueBuckets.reduce(
+    (sum: number, row: StatsQueryDataItem) => sum + (Number(row.count) || 0),
+    0,
+  );
+
+  return {
+    data: {
+      thisMonth: thisMonthRevenue,
+      thisYear: Number(thisYearQuery.data?.data?.[0]?.revenue) || 0,
+      outstanding: Number(outstandingQuery.data?.data?.[0]?.outstanding) || 0,
+      overdue: totalOverdue,
+      overdueCount,
+      currency, // Currency from document data
+    } as RevenueData,
+    isLoading: queries.some((q) => q.isLoading),
+  };
+}

package/src/components/dashboard/shared/use-stats-counts.ts

@@ -0,0 +1,89 @@
+/**
+ * Stats counts hook using the entity stats API.
+ * Server-side counting for accurate totals.
+ */
+import { useQueries } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { STATS_QUERY_CACHE_KEY } from "./use-stats-query";
+
+export const STATS_COUNTS_CACHE_KEY = "dashboard-stats-counts";
+
+export type StatsCountsData = {
+  invoices: number;
+  estimates: number;
+  customers: number;
+  items: number;
+};
+
+export function useStatsCountsData(entityId: string | undefined) {
+  const { sdk } = useSDK();
+
+  const queries = useQueries({
+    queries: [
+      // Invoices count
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "count-invoices"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            { metrics: [{ type: "count", alias: "total" }], table: "invoices" },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Estimates count
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "count-estimates"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            { metrics: [{ type: "count", alias: "total" }], table: "estimates" },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Customers count
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "count-customers"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            { metrics: [{ type: "count", alias: "total" }], table: "customers" },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Items count
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "count-items"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            { metrics: [{ type: "count", alias: "total" }], table: "items" },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+    ],
+  });
+
+  const [invoicesQuery, estimatesQuery, customersQuery, itemsQuery] = queries;
+
+  return {
+    data: {
+      invoices: Number(invoicesQuery.data?.data?.[0]?.total) || 0,
+      estimates: Number(estimatesQuery.data?.data?.[0]?.total) || 0,
+      customers: Number(customersQuery.data?.data?.[0]?.total) || 0,
+      items: Number(itemsQuery.data?.data?.[0]?.total) || 0,
+    } as StatsCountsData,
+    isLoading: queries.some((q) => q.isLoading),
+  };
+}

package/src/components/dashboard/shared/use-stats-query.ts

@@ -0,0 +1,38 @@
+/**
+ * Base hook for stats queries using the entity stats API.
+ * Provides server-side aggregation instead of client-side calculation.
+ */
+import type { StatsQueryRequest, StatsQueryResponse } from "@spaceinvoices/js-sdk";
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+
+export const STATS_QUERY_CACHE_KEY = "entity-stats-query";
+
+export type StatsQueryOptions<TData = StatsQueryResponse> = Omit<
+  UseQueryOptions<StatsQueryResponse, Error, TData>,
+  "queryKey" | "queryFn"
+>;
+
+/**
+ * Generic hook for executing stats queries.
+ * Use this as a base for specific stats hooks.
+ */
+export function useStatsQuery<TData = StatsQueryResponse>(
+  entityId: string | undefined,
+  query: StatsQueryRequest,
+  options?: StatsQueryOptions<TData>,
+) {
+  const { sdk } = useSDK();
+
+  return useQuery({
+    queryKey: [STATS_QUERY_CACHE_KEY, entityId, query],
+    queryFn: async () => {
+      if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+      // SDK's wrapMethod already unwraps success response and throws on error
+      return await sdk.entityStats.queryEntityStats(query, { entity_id: entityId });
+    },
+    enabled: !!entityId && !!sdk,
+    staleTime: 30_000, // 30 seconds
+    ...options,
+  });
+}