@teincfood/core 0.7.9 → 0.8.0

package/dist/hooks/rider.hooks.js

@@ -0,0 +1,373 @@
+/**
+ * Rider hooks — single source for both apps (previously verbatim copies).
+ * Reads serve cache instantly; network refreshes silently when online.
+ */
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { riderService } from "../adapters/services";
+import { notifySuccess, notifyError } from "../adapters/notify";
+import { assertOnlineFor } from "../sync/online-gates";
+import { extractApiErrorMessage } from "../utils/error";
+import { useInfiniteList, useIsEffectivelyOnline } from "./use-infinite-list";
+// No SQLite rider mirror — the persisted query cache is the offline source.
+// Reads never fire while unreachable; the OfflineBanner marks not-live.
+function useOnline() {
+    return useIsEffectivelyOnline();
+}
+// Query keys
+export const RIDER_KEYS = {
+    all: ["rider"],
+    profile: () => [...RIDER_KEYS.all, "profile"],
+    metrics: () => [...RIDER_KEYS.all, "metrics"],
+    activeDelivery: () => [...RIDER_KEYS.all, "active-delivery"],
+    deliveries: () => [...RIDER_KEYS.all, "deliveries"],
+    deliveryDetail: (id) => [...RIDER_KEYS.all, "delivery", id],
+    earnings: () => [...RIDER_KEYS.all, "earnings"],
+    earningsBreakdown: () => [...RIDER_KEYS.all, "earnings-breakdown"],
+    earningsSummary: (period) => [...RIDER_KEYS.all, "earnings-summary", period],
+    transactions: () => [...RIDER_KEYS.all, "transactions"],
+    statistics: () => [...RIDER_KEYS.all, "statistics"],
+    vehicleInfo: () => [...RIDER_KEYS.all, "vehicle"],
+    deliveryZones: () => [...RIDER_KEYS.all, "zones"],
+    navigationSettings: () => [...RIDER_KEYS.all, "navigation"],
+    navigationApps: () => [...RIDER_KEYS.all, "navigation-apps"],
+};
+// ─── Available Orders ───
+export function useAvailableOrdersQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: [...RIDER_KEYS.all, "available-orders"],
+        queryFn: async () => {
+            const res = (await riderService.fetchAvailableOrders());
+            return res.data;
+        },
+        enabled: enabled && online,
+        staleTime: 15000,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useClaimOrderMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (orderId) => riderService.acceptDelivery(orderId),
+        onSuccess: () => {
+            notifySuccess("Interest claimed! You'll be notified when ready.");
+            queryClient.invalidateQueries({ queryKey: [...RIDER_KEYS.all, "available-orders"] });
+        },
+        onError: (error) => {
+            notifyError(extractApiErrorMessage(error));
+        },
+    });
+}
+export function useSelfAssignMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (orderId) => riderService.selfAssignDelivery(orderId),
+        onSuccess: () => {
+            notifySuccess("Delivery assigned! Confirm handover with the restaurant.");
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveries() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.activeDelivery() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.metrics() });
+        },
+        onError: (error) => {
+            notifyError(extractApiErrorMessage(error));
+        },
+    });
+}
+// ─── Metrics & Dashboard Hooks ───
+export function useRiderProfileQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.profile(),
+        queryFn: async () => {
+            const res = (await riderService.fetchRiderProfile());
+            return res.data;
+        },
+        enabled: enabled && online,
+        staleTime: 30000,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useRiderMetricsQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.metrics(),
+        queryFn: async () => {
+            const res = (await riderService.fetchRiderDashboard());
+            return res.data;
+        },
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useActiveDeliveryQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.activeDelivery(),
+        queryFn: async () => {
+            const res = (await riderService.fetchActiveDelivery());
+            return res.data;
+        },
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+// ─── Deliveries Hooks ───
+export function useRiderDeliveriesQuery(enabled = true, filters) {
+    const online = useOnline();
+    return useInfiniteList({
+        key: [...RIDER_KEYS.deliveries(), filters],
+        enabled: enabled && online,
+        pageSize: 20,
+        onlineFetch: async (page, pageSize) => {
+            const res = (await riderService.fetchRiderDeliveries(page, pageSize, filters));
+            return res;
+        },
+    });
+}
+export function useRiderDeliveryDetailQuery(deliveryId, enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.deliveryDetail(deliveryId),
+        queryFn: () => riderService.fetchDeliveryDetail(deliveryId),
+        enabled: enabled && Boolean(deliveryId) && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useUpdateDeliveryStatusMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: ({ deliveryId, action }) => {
+            // Delivery state transitions require online (single source).
+            assertOnlineFor("order:create", { order_type: "delivery" });
+            const actions = {
+                "in-transit": riderService.markDeliveryInTransit,
+                arrived: riderService.markDeliveryArrived,
+                delivered: riderService.markDeliveryDelivered,
+                failed: riderService.markDeliveryFailed,
+                returned: riderService.markDeliveryReturned,
+                "confirm-pickup": riderService.confirmDeliveryPickup,
+                "confirm-handover": riderService.confirmDeliveryHandover,
+            };
+            const fn = actions[action];
+            if (!fn)
+                return Promise.reject(new Error(`Unknown action: ${action}`));
+            return fn(deliveryId);
+        },
+        onSuccess: (_, { deliveryId }) => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveries() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveryDetail(deliveryId) });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.activeDelivery() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.metrics() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.earnings() });
+        },
+    });
+}
+export function useAcceptDeliveryMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (orderId) => riderService.selfAssignDelivery(orderId),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: [...RIDER_KEYS.all, "available-orders"] });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveries() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.activeDelivery() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.metrics() });
+        },
+    });
+}
+// ─── Earnings Hooks ───
+export function useRiderEarningsQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.earnings(),
+        queryFn: () => riderService.fetchRiderEarnings(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useEarningsBreakdownQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.earningsBreakdown(),
+        queryFn: () => riderService.fetchEarningsBreakdown(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useRiderEarningsSummaryQuery(period, enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.earningsSummary(period),
+        queryFn: () => riderService.fetchRiderEarningsSummary(period),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useRiderWalletHistoryQuery(enabled = true) {
+    const online = useOnline();
+    return useInfiniteList({
+        key: RIDER_KEYS.transactions(),
+        enabled: enabled && online,
+        pageSize: 20,
+        onlineFetch: async (page, pageSize) => {
+            const res = (await riderService.fetchWalletHistory(page, pageSize));
+            return { data: res.data.entries, pagination: res.pagination };
+        },
+    });
+}
+export function useRequestPayoutMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (_amount) => Promise.reject(new Error("Payout not implemented on backend")),
+        onError: () => { },
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.earnings() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.transactions() });
+        },
+    });
+}
+// ─── Statistics Hooks ───
+export function useRiderStatisticsQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.statistics(),
+        queryFn: () => riderService.fetchRiderStatistics(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+// ─── Vehicle Info Hooks ───
+export function useVehicleInfoQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.vehicleInfo(),
+        queryFn: () => riderService.fetchVehicleInfo(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useCreateVehicleMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (vehicleInfo) => riderService.createVehicle(vehicleInfo),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.vehicleInfo() });
+        },
+        onError: (error) => {
+            try {
+                console.debug("[useCreateVehicleMutation] error", error);
+            }
+            catch { }
+        },
+    });
+}
+// ─── Delivery Zones Hooks ───
+export function useDeliveryZonesQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.deliveryZones(),
+        queryFn: () => riderService.fetchDeliveryZones(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useUpdateDeliveryZonesMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (zones) => riderService.updateDeliveryZones(zones),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveryZones() });
+        },
+    });
+}
+export function useToggleDeliveryZoneMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: ({ zoneId, enabled }) => riderService.toggleDeliveryZone(zoneId, enabled),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.deliveryZones() });
+        },
+    });
+}
+// ─── Navigation Settings Hooks ───
+export function useNavigationSettingsQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.navigationSettings(),
+        queryFn: () => riderService.fetchNavigationSettings(),
+        enabled: enabled && online,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+export function useUpdateNavigationSettingsMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (settings) => riderService.updateNavigationSettings(settings),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.navigationSettings() });
+        },
+    });
+}
+// ─── Online Status Hooks ───
+export function useUpdateOnlineStatusMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (isOnline) => riderService.updateOnlineStatus(isOnline),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.profile() });
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.metrics() });
+        },
+        onError: (error) => {
+            try {
+                console.debug("[useUpdateOnlineStatus] error", error);
+            }
+            catch { }
+            notifyError(extractApiErrorMessage(error));
+        },
+    });
+}
+// ─── Navigation Apps Hooks ───
+export function useNavigationAppsQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: RIDER_KEYS.navigationApps(),
+        queryFn: () => riderService.fetchNavigationApps(),
+        enabled: enabled && online,
+        staleTime: Infinity,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+// ─── Vehicle Types Hooks ───
+export function useVehicleTypesQuery(enabled = true) {
+    const online = useOnline();
+    return useQuery({
+        queryKey: [...RIDER_KEYS.all, "vehicle-types"],
+        queryFn: () => riderService.fetchVehicleTypes(),
+        enabled: enabled && online,
+        staleTime: Infinity,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+}
+// ─── Toggle Online Status ───
+export function useToggleOnlineMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (isOnline) => riderService.updateRiderProfile({ is_online: isOnline }),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: RIDER_KEYS.profile() });
+        },
+    });
+}

package/dist/hooks/use-infinite-list.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Shared infinite-list primitive — the ONLY pagination implementation.
+ *
+ * Offline-first: SQLite/offline fetch serves instantly; the network fetch
+ * refreshes silently when effectively online and falls back to offline on
+ * error. Network is sync transport, never a render delay.
+ *
+ * Canonical pagination shape matches the backend (pagination.ex):
+ * { page, page_size, total_entries, total_pages }.
+ */
+export declare function useIsEffectivelyOnline(): boolean;
+export interface ListPage<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        page_size: number;
+        total_pages: number;
+        total_entries?: number;
+    };
+}
+export interface InfiniteListOptions<T> {
+    key: readonly unknown[];
+    enabled?: boolean;
+    pageSize?: number;
+    staleTime?: number;
+    /**
+     * Always-available local fetch (SQLite). Serves instantly offline.
+     * Omit when there is no local source — offline then preserves stale
+     * cache (query errors, data stays) instead of serving empty.
+     */
+    offlineFetch?: (page: number, pageSize: number) => Promise<ListPage<T>>;
+    /** Network refresh. Failure falls back to offlineFetch, else stale cache. */
+    onlineFetch?: (page: number, pageSize: number) => Promise<ListPage<T>>;
+}
+export declare function nextPageParam(lastPage: unknown): number | undefined;
+export declare function flattenPages<T>(pages: Array<{
+    data: T[];
+}>): T[];
+export declare function useInfiniteList<T>(options: InfiniteListOptions<T>): {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: 'error';
+    data: T[] | undefined;
+} | {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: 'pending';
+    data: T[] | undefined;
+} | {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: 'pending';
+    data: T[] | undefined;
+} | {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    status: 'success';
+    data: T[] | undefined;
+} | {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchNextPageError: boolean;
+    isFetchingNextPage: boolean;
+    isFetchPreviousPageError: boolean;
+    isFetchingPreviousPage: boolean;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: 'error';
+    data: T[] | undefined;
+} | {
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<T>, unknown>, Error>>;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isFetchNextPageError: false;
+    isFetchPreviousPageError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: 'success';
+    data: T[] | undefined;
+};

package/dist/hooks/use-infinite-list.js

@@ -0,0 +1,58 @@
+/**
+ * Shared infinite-list primitive — the ONLY pagination implementation.
+ *
+ * Offline-first: SQLite/offline fetch serves instantly; the network fetch
+ * refreshes silently when effectively online and falls back to offline on
+ * error. Network is sync transport, never a render delay.
+ *
+ * Canonical pagination shape matches the backend (pagination.ex):
+ * { page, page_size, total_entries, total_pages }.
+ */
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useSyncExternalStore } from "react";
+import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
+import { DEFAULT_PAGE_SIZE } from "../utils/constants";
+export function useIsEffectivelyOnline() {
+    const s = useSyncExternalStore(subscribeConnectivity, getConnectivityState, getConnectivityState);
+    return s.isOnline && s.isCloudReachable !== "unreachable";
+}
+export function nextPageParam(lastPage) {
+    const p = lastPage?.pagination;
+    return p && p.page < p.total_pages ? p.page + 1 : undefined;
+}
+export function flattenPages(pages) {
+    return pages.flatMap((p) => p.data ?? []);
+}
+export function useInfiniteList(options) {
+    const online = useIsEffectivelyOnline();
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const enabled = options.enabled ?? true;
+    const query = useInfiniteQuery({
+        queryKey: [...options.key],
+        queryFn: async ({ pageParam = 1 }) => {
+            const page = pageParam;
+            if (online && options.onlineFetch) {
+                try {
+                    return await options.onlineFetch(page, pageSize);
+                }
+                catch {
+                    // Network refresh failed — local source, else preserve stale cache.
+                    if (options.offlineFetch)
+                        return options.offlineFetch(page, pageSize);
+                    throw new Error("Offline — showing cached data");
+                }
+            }
+            if (options.offlineFetch)
+                return options.offlineFetch(page, pageSize);
+            throw new Error("Offline — showing cached data");
+        },
+        initialPageParam: 1,
+        getNextPageParam: nextPageParam,
+        enabled,
+        staleTime: options.staleTime ?? 30000,
+        retry: false,
+        networkMode: "offlineFirst",
+    });
+    const data = query.data ? flattenPages(query.data.pages) : undefined;
+    return { ...query, data };
+}