@go-avro/avro-js 0.0.44 → 0.0.46

package/dist/client/QueryClient.d.ts

@@ -517,6 +517,11 @@ declare module '../client/QueryClient' {
         }>>;
     }
 }
+export type ListQueryMatch = 'match' | 'nomatch' | 'unknown';
+export declare function matchesEventsListQuery(queryKey: readonly unknown[], item: any): ListQueryMatch;
+export declare function matchesBillsListQuery(queryKey: readonly unknown[], item: any): ListQueryMatch;
+export declare function matchesJobsListQuery(queryKey: readonly unknown[], item: any): ListQueryMatch;
+export declare function matchesRoutesListQuery(queryKey: readonly unknown[], _item: any): ListQueryMatch;
 export declare class AvroQueryClient {
     protected config: Required<AvroQueryClientConfig>;
     readonly socket: Socket;
@@ -618,23 +623,13 @@ export declare class AvroQueryClient {
     getAuthState(): AuthState;
     getAuthStateAsync(): Promise<AuthState>;
     getQueryClient(): QueryClient;
-    /**
-     * Fetch an entity from the API, optionally construct it, and surgically
-     * update all matching React-Query caches (individual + list + infinite).
-     *
-     * Shared by socket handlers and mutation `onSuccess` callbacks so the
-     * sender gets an immediate cache sync and everyone else gets the socket
-     * update — both use the identical code path.
-     *
-     * @returns The fetched (and optionally constructed) item, or `undefined`
-     *          for deletes / entities without a fetchPath.
-     */
     _syncEntity(queryClient: QueryClient, params: {
         action: 'create' | 'update' | 'delete';
         entityKey: string;
         id: string;
         fetchPath?: string;
         construct?: (raw: any) => any;
+        matchesQuery?: (queryKey: readonly unknown[], item: any) => ListQueryMatch;
     }): Promise<any>;
     useLogout(): ReturnType<typeof useMutation<void, StandardError, CancelToken | undefined>>;
     fetchJobs(body?: {

package/dist/client/QueryClient.js

@@ -7,6 +7,91 @@ import { StandardError } from '../types/error';
 function isBulkEvent(c) {
     return 'invalidateKeys' in c;
 }
+export function matchesEventsListQuery(queryKey, item) {
+    if (queryKey.length < 11)
+        return 'match';
+    if (!item)
+        return 'match';
+    const knownIds = queryKey[3];
+    const unknownIds = queryKey[4];
+    const query = queryKey[5];
+    const includeUnbilled = queryKey[6];
+    const includeBilled = queryKey[7];
+    const includePaid = queryKey[8];
+    const filterJobId = queryKey[9];
+    if (knownIds && knownIds.length > 0 && !knownIds.includes(item.id))
+        return 'nomatch';
+    if (unknownIds && unknownIds.length > 0 && unknownIds.includes(item.id))
+        return 'nomatch';
+    if (filterJobId && item.job_id !== filterJobId)
+        return 'nomatch';
+    const status = item.status;
+    if (status !== undefined) {
+        const isPaid = status === 'PAID' || status === 'PREPAID' || status === 'EXTERNALLY_PAID';
+        const isBilled = status === 'BILLED' || status === 'EXTERNALLY_BILLED';
+        const isUnbilled = !isPaid && !isBilled;
+        if (includePaid === false && isPaid)
+            return 'nomatch';
+        if (includeBilled === false && isBilled)
+            return 'nomatch';
+        if (includeUnbilled === false && isUnbilled)
+            return 'nomatch';
+    }
+    if (query && query.length > 0)
+        return 'unknown';
+    return 'match';
+}
+export function matchesBillsListQuery(queryKey, item) {
+    if (queryKey.length < 6)
+        return 'match';
+    if (!item)
+        return 'match';
+    const query = queryKey[2];
+    const knownIds = queryKey[3];
+    const unknownIds = queryKey[4];
+    const paidFilter = queryKey[5];
+    if (knownIds && knownIds.length > 0 && !knownIds.includes(item.id))
+        return 'nomatch';
+    if (unknownIds && unknownIds.length > 0 && unknownIds.includes(item.id))
+        return 'nomatch';
+    const status = item.status;
+    if (paidFilter !== undefined && status !== undefined) {
+        const isPaid = status === 'PAID' || status === 'MANUALLY_PAID';
+        if (paidFilter === true && !isPaid)
+            return 'nomatch';
+        if (paidFilter === false && isPaid)
+            return 'nomatch';
+    }
+    if (query && query.length > 0)
+        return 'unknown';
+    return 'match';
+}
+export function matchesJobsListQuery(queryKey, item) {
+    if (queryKey[0] !== 'infinite')
+        return 'match';
+    if (queryKey.length < 6)
+        return 'match';
+    if (!item)
+        return 'match';
+    const query = queryKey[4];
+    const routeId = queryKey[5];
+    if (routeId && routeId.length > 0) {
+        const routes = item.routes ?? [];
+        if (!routes.some((r) => r?.route_id === routeId))
+            return 'nomatch';
+    }
+    if (query && query.length > 0)
+        return 'unknown';
+    return 'match';
+}
+export function matchesRoutesListQuery(queryKey, _item) {
+    if (queryKey.length < 5)
+        return 'match';
+    const query = queryKey[3];
+    if (query && query.length > 0)
+        return 'unknown';
+    return 'match';
+}
 /**
  * Maps socket event names to cache-update strategies.
  *
@@ -38,12 +123,14 @@ const SOCKET_EVENT_CONFIG = {
         action: 'create',
         fetchPath: (id) => `/job/${id}`,
         construct: (d) => new Job(d),
+        matchesQuery: matchesJobsListQuery,
     },
     update_job: {
         entityKey: 'jobs',
         action: 'update',
         fetchPath: (id) => `/job/${id}`,
         construct: (d) => new Job(d),
+        matchesQuery: matchesJobsListQuery,
     },
     delete_job: { entityKey: 'jobs', action: 'delete', fetchPath: null },
     update_jobs: { invalidateKeys: [['jobs'], ['infinite', 'jobs']] },
@@ -54,12 +141,14 @@ const SOCKET_EVENT_CONFIG = {
         action: 'create',
         fetchPath: (id) => `/route/${id}`,
         construct: (d) => new Route(d),
+        matchesQuery: matchesRoutesListQuery,
     },
     update_route: {
         entityKey: 'routes',
         action: 'update',
         fetchPath: (id) => `/route/${id}`,
         construct: (d) => new Route(d),
+        matchesQuery: matchesRoutesListQuery,
     },
     delete_route: { entityKey: 'routes', action: 'delete', fetchPath: null },
     // ── Events (also refetch parent job — overdueness, last_event, etc.) ──
@@ -68,12 +157,14 @@ const SOCKET_EVENT_CONFIG = {
         action: 'create',
         fetchPath: (id) => `/event/${id}`,
         construct: (d) => new _Event(d),
+        matchesQuery: matchesEventsListQuery,
         relatedRefetch: [
             {
                 entityKey: 'jobs',
                 idField: 'job_id',
                 fetchPath: (id) => `/job/${id}`,
                 construct: (d) => new Job(d),
+                matchesQuery: matchesJobsListQuery,
             },
         ],
     },
@@ -82,12 +173,14 @@ const SOCKET_EVENT_CONFIG = {
         action: 'update',
         fetchPath: (id) => `/event/${id}`,
         construct: (d) => new _Event(d),
+        matchesQuery: matchesEventsListQuery,
         relatedRefetch: [
             {
                 entityKey: 'jobs',
                 idField: 'job_id',
                 fetchPath: (id) => `/job/${id}`,
                 construct: (d) => new Job(d),
+                matchesQuery: matchesJobsListQuery,
             },
         ],
     },
@@ -101,6 +194,7 @@ const SOCKET_EVENT_CONFIG = {
                 idField: 'job_id',
                 fetchPath: (id) => `/job/${id}`,
                 construct: (d) => new Job(d),
+                matchesQuery: matchesJobsListQuery,
             },
         ],
     },
@@ -115,6 +209,7 @@ const SOCKET_EVENT_CONFIG = {
         entityKey: 'bills',
         action: 'create',
         fetchPath: (id) => `/bill/${id}`,
+        matchesQuery: matchesBillsListQuery,
     },
     delete_bill: { entityKey: 'bills', action: 'delete', fetchPath: null },
     update_bills: { invalidateKeys: [['bills']] },
@@ -348,10 +443,10 @@ export class AvroQueryClient {
                         id,
                         fetchPath: fetchPath ? fetchPath(id) : undefined,
                         construct: config.construct,
+                        matchesQuery: config.matchesQuery,
                     });
                     // Invalidate any additional keys (e.g. companies → /company/list)
                     alsoInvalidate?.forEach((k) => queryClient.invalidateQueries({ queryKey: k }));
-                    // Refetch & patch related entities (e.g. event → parent job)
                     if (relatedRefetch) {
                         for (const related of relatedRefetch) {
                             const relatedId = data?.[related.idField] ?? fetchedItem?.[related.idField];
@@ -363,6 +458,7 @@ export class AvroQueryClient {
                                 id: relatedId,
                                 fetchPath: related.fetchPath(relatedId),
                                 construct: related.construct,
+                                matchesQuery: related.matchesQuery,
                             });
                         }
                     }
@@ -615,22 +711,10 @@ export class AvroQueryClient {
     getQueryClient() {
         return useQueryClient();
     }
-    /**
-     * Fetch an entity from the API, optionally construct it, and surgically
-     * update all matching React-Query caches (individual + list + infinite).
-     *
-     * Shared by socket handlers and mutation `onSuccess` callbacks so the
-     * sender gets an immediate cache sync and everyone else gets the socket
-     * update — both use the identical code path.
-     *
-     * @returns The fetched (and optionally constructed) item, or `undefined`
-     *          for deletes / entities without a fetchPath.
-     */
     async _syncEntity(queryClient, params) {
-        const { action, entityKey, id, fetchPath, construct } = params;
+        const { action, entityKey, id, fetchPath, construct, matchesQuery } = params;
         const predicate = (q) => matchesEntityKey(q, entityKey);
         const invalidate = () => queryClient.invalidateQueries({ predicate });
-        // ─── DELETE ─────────────────────────────────────────
         if (action === 'delete') {
             queryClient.removeQueries({ queryKey: [entityKey, id], exact: true });
             queryClient.setQueriesData({ predicate }, (old) => {
@@ -649,7 +733,6 @@ export class AvroQueryClient {
             });
             return undefined;
         }
-        // ─── CREATE / UPDATE ────────────────────────────────
         if (!fetchPath) {
             invalidate();
             return undefined;
@@ -662,42 +745,60 @@ export class AvroQueryClient {
             });
             const item = construct ? construct(raw) : raw;
             queryClient.setQueryData([entityKey, id], item);
-            if (action === 'create') {
-                queryClient.setQueriesData({ predicate }, (old) => {
-                    if (!old)
-                        return old;
-                    if (old.pages && Array.isArray(old.pages)) {
-                        if (old.pages.some((p) => p.some((x) => x?.id === id)))
+            const matchingQueries = queryClient.getQueryCache().findAll({ predicate });
+            for (const query of matchingQueries) {
+                const queryKey = query.queryKey;
+                if (queryKey.length === 2 && queryKey[0] === entityKey)
+                    continue;
+                const verdict = matchesQuery
+                    ? matchesQuery(queryKey, item)
+                    : 'match';
+                if (verdict === 'unknown') {
+                    queryClient.invalidateQueries({ queryKey, exact: true });
+                    continue;
+                }
+                if (action === 'create') {
+                    if (verdict === 'nomatch')
+                        continue;
+                    queryClient.setQueryData(queryKey, (old) => {
+                        if (!old)
                             return old;
-                        return {
-                            ...old,
-                            pages: [[item, ...(old.pages[0] || [])], ...old.pages.slice(1)],
-                        };
-                    }
-                    if (Array.isArray(old)) {
-                        if (old.some((x) => x?.id === id))
+                        if (old.pages && Array.isArray(old.pages)) {
+                            if (old.pages.some((p) => p.some((x) => x?.id === id)))
+                                return old;
+                            return {
+                                ...old,
+                                pages: [[item, ...(old.pages[0] || [])], ...old.pages.slice(1)],
+                            };
+                        }
+                        if (Array.isArray(old)) {
+                            if (old.some((x) => x?.id === id))
+                                return old;
+                            return [...old, item];
+                        }
+                        return old;
+                    });
+                }
+                else {
+                    queryClient.setQueryData(queryKey, (old) => {
+                        if (!old)
                             return old;
-                        return [...old, item];
-                    }
-                    return old;
-                });
-            }
-            else {
-                // UPDATE — replace in every active list / infinite-query cache
-                queryClient.setQueriesData({ predicate }, (old) => {
-                    if (!old)
+                        if (old.pages && Array.isArray(old.pages)) {
+                            return {
+                                ...old,
+                                pages: old.pages.map((page) => verdict === 'match'
+                                    ? page.map((x) => (x?.id === id ? item : x))
+                                    : page.filter((x) => x?.id !== id)),
+                            };
+                        }
+                        if (Array.isArray(old)) {
+                            return verdict === 'match'
+                                ? old.map((x) => (x?.id === id ? item : x))
+                                : old.filter((x) => x?.id !== id);
+                        }
                         return old;
-                    if (old.pages && Array.isArray(old.pages)) {
-                        return {
-                            ...old,
-                            pages: old.pages.map((page) => page.map((x) => (x?.id === id ? item : x))),
-                        };
-                    }
-                    if (Array.isArray(old)) {
-                        return old.map((x) => (x?.id === id ? item : x));
-                    }
-                    return old;
-                });
+                    });
+                }
             }
             return item;
         }

package/dist/client/hooks/events.js

@@ -1,10 +1,9 @@
 import { useInfiniteQuery, useQuery, useMutation } from '@tanstack/react-query';
-import { AvroQueryClient } from '../../client/QueryClient';
+import { AvroQueryClient, matchesEventsListQuery } from '../../client/QueryClient';
 import { _Event, Job, LineItemStatus } from '../../types/api';
-/** Predicate that matches all 'jobs' queries (list and individual, but NOT 'infinite'). */
 const isJobsQuery = (q) => q.queryKey[0] === 'jobs';
-/** Predicate that matches all 'events' queries (list and individual). */
 const isEventsQuery = (q) => q.queryKey[0] === 'events';
+const isEventsQueryFor = (item) => (q) => q.queryKey[0] === 'events' && matchesEventsListQuery(q.queryKey, item) === 'match';
 AvroQueryClient.prototype.useGetEvents = function (body) {
     const queryClient = this.getQueryClient();
     const result = useInfiniteQuery({
@@ -102,8 +101,7 @@ AvroQueryClient.prototype.useCreateEvent = function () {
                     return old;
                 });
             }
-            // Add optimistic event to all active events queries
-            queryClient.setQueriesData({ predicate: isEventsQuery, type: 'active' }, (oldData) => {
+            queryClient.setQueriesData({ predicate: isEventsQueryFor(optimisticEvent), type: 'active' }, (oldData) => {
                 if (!oldData)
                     return oldData;
                 if (oldData.pages) {

package/dist/types/api/Job.d.ts

@@ -35,6 +35,21 @@ export declare class Job {
     getOverdueLabel: () => string;
     getStatus(): "PENDING_CUSTOMER" | "PENDING_COMPANY" | "ACTIVE" | "ARCHIVED" | "DRAFT" | "PENDING_PAYMENT" | "PENDING_ACTIVATION";
     getStatusLabel(): "Active" | "Draft" | "Archived" | "Pending Activation" | "Customer Approval" | "Company Approval" | "Awaiting Payment";
+    /**
+     * Returns the sum of `service` (in seconds) for the tasks attached to a
+     * given routeJob. Use this to compute predicted completion time:
+     * `routeJob.getPredictedArrival() + job.getServiceDuration(routeJob)`.
+     */
+    getServiceDuration: (routeJob: RouteJob) => number;
+    /**
+     * Returns the most relevant event for the job in its current state:
+     * the active `current_event` if one exists, otherwise the
+     * `last_completed_event`. Falls back to `null`.
+     *
+     * Most callers historically used `last_completed_event ?? current_event`
+     * which inverted the precedence — prefer the live event over a stale one.
+     */
+    getRouteEvent: () => _Event | null;
     portionDone: (route: Route) => number;
     isDone: (route: Route) => boolean;
 }

package/dist/types/api/Job.js

@@ -21,6 +21,27 @@ export class Job {
             }, activeTasks[0]);
             return mostOverdueTask.getOverdueLabel?.() ?? 'N/A';
         };
+        /**
+         * Returns the sum of `service` (in seconds) for the tasks attached to a
+         * given routeJob. Use this to compute predicted completion time:
+         * `routeJob.getPredictedArrival() + job.getServiceDuration(routeJob)`.
+         */
+        this.getServiceDuration = (routeJob) => {
+            return routeJob.tasks
+                .map((tid) => this.tasks.find((t) => t.id === tid)?.service ?? 0)
+                .reduce((a, b) => a + b, 0);
+        };
+        /**
+         * Returns the most relevant event for the job in its current state:
+         * the active `current_event` if one exists, otherwise the
+         * `last_completed_event`. Falls back to `null`.
+         *
+         * Most callers historically used `last_completed_event ?? current_event`
+         * which inverted the precedence — prefer the live event over a stale one.
+         */
+        this.getRouteEvent = () => {
+            return this.current_event ?? this.last_completed_event ?? null;
+        };
         this.portionDone = (route) => {
             if (!this.tasks || this.tasks.length === 0) {
                 return 0;

package/dist/types/api/Route.d.ts

@@ -1,4 +1,5 @@
 import { RouteJob } from '../../types/api/RouteJob';
+import type { Job } from '../../types/api/Job';
 export declare const FrequencyType: {
     readonly ONCE: "ONCE";
     readonly DAILY: "DAILY";
@@ -33,4 +34,16 @@ export declare class Route {
     constructor(init?: Partial<Route>);
     getNextOccurrences: (count?: number) => (Date | null)[];
     getNextOccurrence: (after?: Date) => Date | null;
+    /**
+     * Computes how far ahead/behind schedule the route is, in seconds, based on
+     * stops that have already been completed. Positive = behind schedule,
+     * negative = ahead of schedule.
+     *
+     * The offset is taken from the most recently completed stop (largest
+     * `time_ended`), not the last stop in route order. This is what consumers
+     * want: "given the latest completed work, how off-schedule are we?".
+     *
+     * Returns `null` if no stop in this route has a usable completion event.
+     */
+    getScheduleOffset: (jobs: Job[]) => number | null;
 }

package/dist/types/api/Route.js

@@ -43,6 +43,38 @@ export class Route {
             }
             return next_occurrence;
         };
+        /**
+         * Computes how far ahead/behind schedule the route is, in seconds, based on
+         * stops that have already been completed. Positive = behind schedule,
+         * negative = ahead of schedule.
+         *
+         * The offset is taken from the most recently completed stop (largest
+         * `time_ended`), not the last stop in route order. This is what consumers
+         * want: "given the latest completed work, how off-schedule are we?".
+         *
+         * Returns `null` if no stop in this route has a usable completion event.
+         */
+        this.getScheduleOffset = (jobs) => {
+            let latestEnd = -Infinity;
+            let offset = null;
+            for (const rj of this.jobs) {
+                const job = jobs.find((j) => j.id === rj.job_id);
+                if (!job || !job.isDone(this))
+                    continue;
+                // Offset semantics specifically want a *completed* event, not an
+                // in-progress one. Use last_completed_event directly rather than
+                // getRouteEvent() (which prefers current_event for display).
+                const actualEnd = job.last_completed_event?.time_ended;
+                if (typeof actualEnd !== 'number' || actualEnd <= 0)
+                    continue;
+                if (actualEnd <= latestEnd)
+                    continue;
+                const predictedCompletion = rj.getPredictedArrival() + job.getServiceDuration(rj);
+                latestEnd = actualEnd;
+                offset = actualEnd - predictedCompletion;
+            }
+            return offset;
+        };
         Object.assign(this, init);
         if (init?.jobs) {
             this.jobs = init.jobs.map((j) => new RouteJob(j));

package/dist/types/api/RouteJob.d.ts

@@ -12,4 +12,11 @@ declare module '../../types/api/RouteJob' {
 }
 export declare class RouteJob {
     constructor(init?: Partial<RouteJob>);
+    /**
+     * Returns the arrival time the UI should show for this stop:
+     * `scheduled_arrival_time` if set (>= 0), otherwise the optimizer's
+     * `estimated_arrival_time`. The sentinel value -1 means "no manual
+     * schedule, fall back to the optimizer estimate".
+     */
+    getPredictedArrival: () => number;
 }

package/dist/types/api/RouteJob.js

@@ -1,5 +1,16 @@
 export class RouteJob {
     constructor(init) {
+        /**
+         * Returns the arrival time the UI should show for this stop:
+         * `scheduled_arrival_time` if set (>= 0), otherwise the optimizer's
+         * `estimated_arrival_time`. The sentinel value -1 means "no manual
+         * schedule, fall back to the optimizer estimate".
+         */
+        this.getPredictedArrival = () => {
+            return this.scheduled_arrival_time === -1
+                ? this.estimated_arrival_time
+                : this.scheduled_arrival_time;
+        };
         Object.assign(this, init);
     }
 }

package/dist/types/api/Task.js

@@ -102,12 +102,15 @@ export class Task {
             if (!this.status || this.status !== TaskStatus.ACTIVE) {
                 return true;
             }
-            if (this.frequency > 0) {
-                return (this.last_completed_event?.time_ended ?? 0) > route.start_time;
-            }
-            else {
-                return this.last_completed_event?.time_ended ? true : false;
-            }
+            // Cutoff: midnight (local time) of the day route.start_time falls on.
+            // Counts work completed at any point during the route's day (including
+            // an early-start autostart that finishes a few minutes before
+            // route.start_time) while still rejecting stale events from previous
+            // occurrences. Applies to both recurring and one-shot tasks.
+            const routeDay = new Date(route.start_time * 1000);
+            routeDay.setHours(0, 0, 0, 0);
+            const cutoff = Math.floor(routeDay.getTime() / 1000);
+            return (this.last_completed_event?.time_ended ?? 0) >= cutoff;
         };
         Object.assign(this, init);
         if (init?.prepayments) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-avro/avro-js",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "JS client for Avro backend integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",