@teincfood/core 0.10.13 → 0.10.15

package/dist/adapters/services.d.ts

@@ -87,8 +87,14 @@ export declare const dashboardService: {
     fetchSellerDashboard: (_businessId: string) => Promise<unknown>;
 };
 export declare const analyticsService: {
-    fetchSellerAnalytics: (_businessId: string, _period?: string) => Promise<unknown>;
-    fetchRevenueSummary: (_businessId: string, _period?: string) => Promise<unknown>;
+    fetchSellerAnalytics: (_businessId: string, _period?: string, _range?: {
+        date_from?: string;
+        date_to?: string;
+    }) => Promise<unknown>;
+    fetchRevenueSummary: (_businessId: string, _period?: string, _range?: {
+        date_from?: string;
+        date_to?: string;
+    }) => Promise<unknown>;
 };
 export declare const placesService: {
     searchPlaces: (_query: string, _lat?: number, _lng?: number) => Promise<PlaceSuggestion[]>;

package/dist/adapters/services.js

@@ -172,10 +172,10 @@ export const dashboardService = {
 };
 // analytics.service — seller analytics + revenue (hosts inject axios impls)
 export const analyticsService = {
-    fetchSellerAnalytics: async (_businessId, _period) => {
+    fetchSellerAnalytics: async (_businessId, _period, _range) => {
         notImpl("analyticsService.fetchSellerAnalytics");
     },
-    fetchRevenueSummary: async (_businessId, _period) => {
+    fetchRevenueSummary: async (_businessId, _period, _range) => {
         notImpl("analyticsService.fetchRevenueSummary");
     },
 };

package/dist/hooks/analytics.hooks.d.ts

@@ -3,13 +3,19 @@
  * Offline-first: local SQLite aggregates serve instantly; the network
  * refreshes silently when online.
  */
+export type AnalyticsPeriod = "today" | "this_week" | "this_month" | "this_year" | "custom";
+/** Inclusive UTC day bounds used by the custom range filter. */
+export interface AnalyticsRange {
+    date_from?: string;
+    date_to?: string;
+}
 export declare const SELLER_ANALYTICS_KEYS: {
     all: readonly ["seller-analytics"];
-    analytics: (businessId?: string, period?: string) => readonly ["seller-analytics", string | undefined, string | undefined];
+    analytics: (businessId?: string, period?: AnalyticsPeriod, range?: AnalyticsRange) => readonly ["seller-analytics", string | undefined, AnalyticsPeriod | undefined, string | null, string | null];
 };
 export declare const REVENUE_KEYS: {
     all: readonly ["revenue-summary"];
-    summary: (businessId?: string, period?: string) => readonly ["revenue-summary", string | undefined, string | undefined];
+    summary: (businessId?: string, period?: AnalyticsPeriod, range?: AnalyticsRange) => readonly ["revenue-summary", string | undefined, AnalyticsPeriod | undefined, string | null, string | null];
 };
 interface LocalOrderRow {
     status: string;
@@ -31,24 +37,21 @@ interface LocalOrderRow {
 interface AggregateOptions {
     forRevenueSummary: boolean;
 }
-/**
- * Backend-shaped aggregates computed from local SQLite rows (offline).
- * Field names mirror orders.ex get_seller_analytics / get_revenue_summary
- * exactly so screens render identically online and offline.
- */
 /**
  * Filter local rows to the same period boundaries as the backend
- * (`period_start_datetime/1`):
+ * (`period_bounds/2`):
  *   - today      = current UTC day
  *   - this_week  = Monday 00:00 UTC → now (backend uses ISO weekday)
  *   - this_month = 1st of the current UTC month → now
+ *   - this_year  = 1 January of the current UTC year → now
+ *   - custom     = inclusive `date_from` → `date_to` (YYYY-MM-DD)
  *
  * Exported so the period boundaries can be regression-tested with a fixed
  * clock instead of depending on the day the suite runs.
  */
-export declare function filterByPeriod(orders: LocalOrderRow[], period: "today" | "this_week" | "this_month", now?: Date): LocalOrderRow[];
-export declare function aggregateLocal(orders: LocalOrderRow[], period: "today" | "this_week" | "this_month", opts: AggregateOptions): {
-    period: "this_month" | "this_week" | "today";
+export declare function filterByPeriod(orders: LocalOrderRow[], period: AnalyticsPeriod, now?: Date, range?: AnalyticsRange): LocalOrderRow[];
+export declare function aggregateLocal(orders: LocalOrderRow[], period: AnalyticsPeriod, opts: AggregateOptions, range?: AnalyticsRange): {
+    period: AnalyticsPeriod;
     total_revenue_minor: number;
     total_orders: number;
     average_order_value_minor: number;
@@ -77,7 +80,7 @@ export declare function aggregateLocal(orders: LocalOrderRow[], period: "today"
     by_payment_method?: undefined;
     by_order_type?: undefined;
     by_day?: undefined;
-    period: "this_month" | "this_week" | "today";
+    period: AnalyticsPeriod;
     total_revenue_minor: number;
     total_orders: number;
     average_order_value_minor: number;
@@ -98,6 +101,14 @@ export declare function aggregateLocal(orders: LocalOrderRow[], period: "today"
     }[];
     offline: boolean;
 };
-export declare function useSellerAnalyticsQuery(period?: "today" | "this_week" | "this_month", enabled?: boolean): import("@tanstack/react-query").UseQueryResult<unknown, Error>;
-export declare function useRevenueSummaryQuery(period?: "today" | "this_week" | "this_month", enabled?: boolean): import("@tanstack/react-query").UseQueryResult<unknown, Error>;
+interface AnalyticsPayload {
+    total_orders?: number;
+    [key: string]: unknown;
+}
+interface AnalyticsResponse {
+    data?: AnalyticsPayload;
+    [key: string]: unknown;
+}
+export declare function useSellerAnalyticsQuery(period?: AnalyticsPeriod, enabled?: boolean, range?: AnalyticsRange): import("@tanstack/react-query").UseQueryResult<AnalyticsResponse, Error>;
+export declare function useRevenueSummaryQuery(period?: AnalyticsPeriod, enabled?: boolean, range?: AnalyticsRange): import("@tanstack/react-query").UseQueryResult<AnalyticsResponse, Error>;
 export {};

package/dist/hooks/analytics.hooks.js

@@ -3,45 +3,66 @@
  * Offline-first: local SQLite aggregates serve instantly; the network
  * refreshes silently when online.
  */
-import { useQuery } from "@tanstack/react-query";
-import { useSyncExternalStore } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useSyncExternalStore } from "react";
 import { getActiveBusiness, subscribeBusiness } from "../adapters/business";
 import { analyticsService } from "../adapters/services";
 import { listLocalOrders } from "../domain/orders/service";
+import { pullRemoteOrders } from "../sync/sync-jobs.service";
+import { syncLogger } from "../utils/sync-logger";
 import { useIsEffectivelyOnline } from "./use-infinite-list";
 export const SELLER_ANALYTICS_KEYS = {
     all: ["seller-analytics"],
-    analytics: (businessId, period) => [...SELLER_ANALYTICS_KEYS.all, businessId, period],
+    analytics: (businessId, period, range) => [
+        ...SELLER_ANALYTICS_KEYS.all,
+        businessId,
+        period,
+        range?.date_from ?? null,
+        range?.date_to ?? null,
+    ],
 };
 export const REVENUE_KEYS = {
     all: ["revenue-summary"],
-    summary: (businessId, period) => [...REVENUE_KEYS.all, businessId, period],
+    summary: (businessId, period, range) => [
+        ...REVENUE_KEYS.all,
+        businessId,
+        period,
+        range?.date_from ?? null,
+        range?.date_to ?? null,
+    ],
 };
 function useBusinessId() {
     const id = useSyncExternalStore(subscribeBusiness, () => getActiveBusiness()?.id ?? null, () => null);
     return id ?? undefined;
 }
 const OFFLINE_FIRST = { retry: false, networkMode: "offlineFirst" };
-/**
- * Backend-shaped aggregates computed from local SQLite rows (offline).
- * Field names mirror orders.ex get_seller_analytics / get_revenue_summary
- * exactly so screens render identically online and offline.
- */
 /**
  * Filter local rows to the same period boundaries as the backend
- * (`period_start_datetime/1`):
+ * (`period_bounds/2`):
  *   - today      = current UTC day
  *   - this_week  = Monday 00:00 UTC → now (backend uses ISO weekday)
  *   - this_month = 1st of the current UTC month → now
+ *   - this_year  = 1 January of the current UTC year → now
+ *   - custom     = inclusive `date_from` → `date_to` (YYYY-MM-DD)
  *
  * Exported so the period boundaries can be regression-tested with a fixed
  * clock instead of depending on the day the suite runs.
  */
-export function filterByPeriod(orders, period, now = new Date()) {
+export function filterByPeriod(orders, period, now = new Date(), range) {
     const todayStr = now.toISOString().slice(0, 10);
     if (period === "today") {
         return orders.filter((o) => (o.inserted_at ?? "").slice(0, 10) === todayStr);
     }
+    if (period === "custom") {
+        const from = range?.date_from;
+        const to = range?.date_to;
+        if (!from || !to)
+            return [];
+        return orders.filter((o) => {
+            const d = (o.inserted_at ?? "").slice(0, 10);
+            return d >= from && d <= to;
+        });
+    }
     let startStr;
     if (period === "this_week") {
         // `getUTCDay()` is 0 for Sunday; shift so Monday is the first day.
@@ -51,6 +72,9 @@ export function filterByPeriod(orders, period, now = new Date()) {
         startOfWeek.setUTCDate(todayUtc.getUTCDate() - daysSinceMonday);
         startStr = startOfWeek.toISOString().slice(0, 10);
     }
+    else if (period === "this_year") {
+        startStr = `${todayStr.slice(0, 4)}-01-01`;
+    }
     else {
         startStr = `${todayStr.slice(0, 7)}-01`;
     }
@@ -59,8 +83,8 @@ export function filterByPeriod(orders, period, now = new Date()) {
         return d >= startStr && d <= todayStr;
     });
 }
-export function aggregateLocal(orders, period, opts) {
-    const filtered = filterByPeriod(orders, period);
+export function aggregateLocal(orders, period, opts, range) {
+    const filtered = filterByPeriod(orders, period, new Date(), range);
     // Backend parity (orders.ex get_business_analytics / get_revenue_summary):
     // revenue-eligible = all EXCEPT cancelled. Cancelled orders must never
     // inflate revenue, counts, breakdowns, or top items — online and offline.
@@ -68,7 +92,9 @@ export function aggregateLocal(orders, period, opts) {
     const total_revenue_minor = revenueOrders.reduce((s, o) => s + (o.total_minor ?? 0), 0);
     const total_orders = revenueOrders.length;
     // Backend uses div (truncation) — mirror, don't round.
-    const average_order_value_minor = total_orders ? Math.floor(total_revenue_minor / total_orders) : 0;
+    const average_order_value_minor = total_orders
+        ? Math.floor(total_revenue_minor / total_orders)
+        : 0;
     const byMethod = new Map();
     const byType = new Map();
     const byDay = new Map();
@@ -98,7 +124,9 @@ export function aggregateLocal(orders, period, opts) {
             itemRev.set(name, (itemRev.get(name) ?? 0) + rev);
         }
     }
-    const pct = (v) => (total_revenue_minor > 0 ? Math.round((v / total_revenue_minor) * 1000) / 10 : 0);
+    const pct = (v) => total_revenue_minor > 0
+        ? Math.round((v / total_revenue_minor) * 1000) / 10
+        : 0;
     // Backend orders_by_status counts over ALL period orders (not revenue-only).
     const orders_by_status = {
         delivered: filtered.filter((o) => o.status === "delivered").length,
@@ -112,7 +140,11 @@ export function aggregateLocal(orders, period, opts) {
             total_orders,
             average_order_value_minor,
             by_payment_method: [...byMethod.entries()]
-                .map(([method, v]) => ({ method, ...v, percentage: pct(v.revenue_minor) }))
+                .map(([method, v]) => ({
+                method,
+                ...v,
+                percentage: pct(v.revenue_minor),
+            }))
                 .sort((a, b) => b.revenue_minor - a.revenue_minor),
             by_order_type: [...byType.entries()]
                 .map(([type, v]) => ({ type, ...v }))
@@ -130,7 +162,11 @@ export function aggregateLocal(orders, period, opts) {
         average_order_value_minor,
         total_refunds_minor: 0,
         top_items: [...itemQty.entries()]
-            .map(([name, quantity]) => ({ name, quantity, revenue_minor: itemRev.get(name) ?? 0 }))
+            .map(([name, quantity]) => ({
+            name,
+            quantity,
+            revenue_minor: itemRev.get(name) ?? 0,
+        }))
             .sort((a, b) => b.revenue_minor - a.revenue_minor)
             .slice(0, 10),
         orders_by_status,
@@ -142,69 +178,145 @@ export function aggregateLocal(orders, period, opts) {
 }
 async function localOrders(businessId) {
     const { data } = await listLocalOrders(businessId, {}, 1, 500);
-    return (data ?? []);
+    return data ?? [];
+}
+function hasCustomRange(period, range) {
+    return (period !== "custom" || Boolean(range?.date_from && range?.date_to));
 }
-export function useSellerAnalyticsQuery(period = "today", enabled = true) {
+const ORDER_PULL_COOLDOWN_MS = 15000;
+const lastOrderPullAt = new Map();
+/**
+ * Refresh the local order read model in the background. Analytics renders
+ * from SQLite immediately; this pull is what makes a freshly opened screen
+ * converge with the server without blocking the first paint.
+ */
+async function syncOrdersForAnalytics(businessId, queryClient) {
+    const now = Date.now();
+    const last = lastOrderPullAt.get(businessId) ?? 0;
+    if (now - last < ORDER_PULL_COOLDOWN_MS)
+        return;
+    lastOrderPullAt.set(businessId, now);
+    try {
+        await pullRemoteOrders(businessId);
+        await Promise.all([
+            queryClient.invalidateQueries({ queryKey: SELLER_ANALYTICS_KEYS.all }),
+            queryClient.invalidateQueries({ queryKey: REVENUE_KEYS.all }),
+        ]);
+    }
+    catch (error) {
+        syncLogger.debug("Analytics", "background order sync failed", {
+            businessId,
+            err: String(error),
+        });
+    }
+}
+/**
+ * Keep local data when it knows about more orders than the server snapshot
+ * (e.g. an offline order still in the outbox). Otherwise the server snapshot
+ * wins because it may include older history the device has never pulled.
+ */
+function preferRemote(current, remote) {
+    const localOrders = current?.data?.total_orders ?? 0;
+    const remoteOrders = remote.data?.total_orders ?? 0;
+    return remoteOrders >= localOrders ? remote : (current ?? remote);
+}
+async function buildLocalAnalytics(businessId, period, range) {
+    try {
+        return {
+            data: aggregateLocal(await localOrders(businessId), period, { forRevenueSummary: false }, range),
+        };
+    }
+    catch {
+        return {
+            data: aggregateLocal([], period, { forRevenueSummary: false }, range),
+        };
+    }
+}
+async function buildLocalRevenue(businessId, period, range) {
+    try {
+        return {
+            data: aggregateLocal(await localOrders(businessId), period, { forRevenueSummary: true }, range),
+        };
+    }
+    catch {
+        return {
+            data: aggregateLocal([], period, { forRevenueSummary: true }, range),
+        };
+    }
+}
+export function useSellerAnalyticsQuery(period = "today", enabled = true, range) {
     const businessId = useBusinessId();
     const online = useIsEffectivelyOnline();
+    const queryClient = useQueryClient();
+    const customReady = hasCustomRange(period, range);
+    const queryKey = SELLER_ANALYTICS_KEYS.analytics(businessId ?? "", period, range);
+    const active = enabled && Boolean(businessId) && customReady;
+    // Local-first: read SQLite on every query run. The network is a background
+    // refresh only, so opening the screen never waits on the server.
+    useEffect(() => {
+        if (!active || !online || !businessId)
+            return;
+        void syncOrdersForAnalytics(businessId, queryClient);
+    }, [active, online, businessId, queryClient]);
     return useQuery({
-        queryKey: SELLER_ANALYTICS_KEYS.analytics(businessId ?? "", period),
+        queryKey,
         queryFn: async () => {
-            if (!online) {
-                try {
-                    return { data: aggregateLocal(await localOrders(businessId), period, { forRevenueSummary: false }) };
-                }
-                catch {
-                    return { data: aggregateLocal([], period, { forRevenueSummary: false }) };
-                }
-            }
-            try {
-                // The backend applies the period filter itself. An empty
-                // `revenue_by_day` is a valid result (e.g. no orders today) and must
-                // not be replaced with local rows — doing that hid real backend data.
-                return await analyticsService.fetchSellerAnalytics(businessId, period);
-            }
-            catch {
-                return {
-                    data: aggregateLocal(await localOrders(businessId), period, {
-                        forRevenueSummary: false,
-                    }),
-                };
+            const local = await buildLocalAnalytics(businessId, period, range);
+            if (online && businessId) {
+                // Do not await. Once the server snapshot arrives, merge it into the
+                // cache only when it is at least as complete as the local model.
+                void analyticsService
+                    .fetchSellerAnalytics(businessId, period, range)
+                    .then((remote) => {
+                    const remoteResponse = remote;
+                    const current = queryClient.getQueryData(queryKey);
+                    queryClient.setQueryData(queryKey, preferRemote(current, remoteResponse));
+                })
+                    .catch((error) => {
+                    syncLogger.debug("Analytics", "background analytics refresh failed", {
+                        businessId,
+                        err: String(error),
+                    });
+                });
             }
+            return local;
         },
-        enabled: enabled && Boolean(businessId),
+        enabled: active,
         staleTime: 30000,
         ...OFFLINE_FIRST,
     });
 }
-export function useRevenueSummaryQuery(period = "today", enabled = true) {
+export function useRevenueSummaryQuery(period = "today", enabled = true, range) {
     const businessId = useBusinessId();
     const online = useIsEffectivelyOnline();
+    const queryClient = useQueryClient();
+    const customReady = hasCustomRange(period, range);
+    const queryKey = REVENUE_KEYS.summary(businessId ?? "", period, range);
+    const active = enabled && Boolean(businessId) && customReady;
+    useEffect(() => {
+        if (!active || !online || !businessId)
+            return;
+        void syncOrdersForAnalytics(businessId, queryClient);
+    }, [active, online, businessId, queryClient]);
     return useQuery({
-        queryKey: REVENUE_KEYS.summary(businessId ?? "", period),
+        queryKey,
         queryFn: async () => {
-            if (!online) {
-                try {
-                    return { data: aggregateLocal(await localOrders(businessId), period, { forRevenueSummary: true }) };
-                }
-                catch {
-                    return { data: aggregateLocal([], period, { forRevenueSummary: true }) };
-                }
-            }
-            try {
-                // Same contract as analytics: trust the backend period filter and
-                // only fall back to SQLite when the request itself fails.
-                return await analyticsService.fetchRevenueSummary(businessId, period);
-            }
-            catch {
-                return {
-                    data: aggregateLocal(await localOrders(businessId), period, {
-                        forRevenueSummary: true,
-                    }),
-                };
+            const local = await buildLocalRevenue(businessId, period, range);
+            if (online && businessId) {
+                void analyticsService
+                    .fetchRevenueSummary(businessId, period, range)
+                    .then((remote) => {
+                    const remoteResponse = remote;
+                    const current = queryClient.getQueryData(queryKey);
+                    queryClient.setQueryData(queryKey, preferRemote(current, remoteResponse));
+                })
+                    .catch((error) => {
+                    syncLogger.debug("Analytics", "background revenue refresh failed", { businessId, err: String(error) });
+                });
             }
+            return local;
         },
-        enabled: enabled && Boolean(businessId),
+        enabled: active,
         staleTime: 30000,
         ...OFFLINE_FIRST,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teincfood/core",
-  "version": "0.10.13",
+  "version": "0.10.15",
   "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",