Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

19.8 KB
Raw Blame
import { ENABLE_DOCUMENT_MENTION_NOTIFICATIONS } from '@core/constant/featureFlags';
import type { Entity } from '@core/types';
import { fireAndForget } from '@core/util/fireAndForget';
import { muteItemForRef } from '@entity/utils/notification';
import { createSocketEffect } from '@macro-inc/collaboration/websocket';
import { updateSoupForNotification } from '@queries/notification/notification-soup';
import {
  useMuteItemMutation,
  useUnmuteItemMutation,
} from '@queries/notification/unsubscribes';
import {
  optimisticInsertNotification,
  type UserNotificationsQuery,
  useMarkNotificationsAsDoneMutation,
  useMarkNotificationsAsSeenMutation,
  useUserNotificationsQuery,
} from '@queries/notification/user-notifications';
import type { ConnectionGatewayWebsocket } from '@service-connection/websocket';
import type {
  ConnGatewayNotificationPayload,
  NotifEvent,
  UserUnsubscribe,
} from '@service-notification/generated/schemas';
import { mapGraphqlNotification } from '@service-storage/graphql-soup';
import { subscribeToGraphqlNotificationPatches } from '@service-storage/graphql-soup-websocket';
import { createLazyMemo } from '@solid-primitives/memo';
import type { UseQueryResult } from '@tanstack/solid-query';
import {
  type Accessor,
  batch,
  createEffect,
  createMemo,
  createRoot,
  createSignal,
  onCleanup,
  untrack,
} from 'solid-js';
import { createStore } from 'solid-js/store';
import { fromZodError } from 'zod-validation-error';
import { nextNotificationState } from './notification-state';
import { createMutedEntitiesQuery } from './queries/muted-entities-query';
import {
  type CompositeEntity,
  compositeEntity,
  notificationEntity,
  type UnifiedNotification,
  unifiedNotificationSchema,
} from './types';

export const CHANNEL_EVENT_TYPES = [
  'channel_mention',
  'channel_message_send',
  'channel_message_reaction',
  'channel_message_reply',
  'document_mention',
] as const;

type NotificationsByEntity = Record<CompositeEntity, UnifiedNotification[]>;

type UnsubscribeFn = () => void;
type SubscribeFn = (newNotification: UnifiedNotification) => void;

export type NotificationSource = {
  readonly notificationsByEntity: Accessor<NotificationsByEntity>;
  readonly notifications: Accessor<UnifiedNotification[]>;
  readonly mutedEntities: Accessor<UserUnsubscribe[]>;
  readonly isLoading: Accessor<boolean>;

  readonly _notificationsQuery: UserNotificationsQuery;

  readonly _mutedEntitiesQuery: UseQueryResult<UserUnsubscribe[], Error>;

  /** Mark a single notification as done */
  markAsDone: (notification: UnifiedNotification) => Promise<void>;

  /** Mark a single notification as read */
  markAsRead: (notification: UnifiedNotification) => Promise<void>;

  /** Bulk mark notifications as done */
  bulkMarkAsDone: (notifications: UnifiedNotification[]) => Promise<void>;

  /** Bulk mark notifications as read */
  bulkMarkAsRead: (notifications: UnifiedNotification[]) => Promise<void>;

  /** unsubscribe from entity notifications */
  muteEntity: (entity: Entity) => Promise<void>;

  /** subscribe to entity notifications */
  unmuteEntity: (entity: Entity) => Promise<void>;

  /** Apply local seen/done intent to a GraphQL edge without replacing its data. */
  withLocalOverrides?: (
    notification: UnifiedNotification
  ) => UnifiedNotification;

  /** Apply local intent to an unread witness without fetching full metadata. */
  withLocalState?: (
    notification: Pick<UnifiedNotification, 'id' | 'state'>
  ) => UnifiedNotification['state'];

  /** subscribe to new notifications */
  subscribe: (subscribe: SubscribeFn) => UnsubscribeFn;
};

const NOTIFICATION_EVENT_TYPE = 'notification';

const QUERY_LIMIT = 500;

// Persistent overrides for the `done` flag that survive cache writes.
// In-flight infinite-query page fetches can land after an optimistic cache
// flip and overwrite it with stale server data; this map keeps the UI
// consistent regardless of what the cache says.
type DoneOverride = { done: boolean; reopened: boolean };
const [doneOverrides, setDoneOverrides] = createRoot(() =>
  createSignal<ReadonlyMap<string, DoneOverride>>(new Map())
);

export function setDoneOverride(
  ids: readonly string[],
  done: boolean | undefined
) {
  if (ids.length === 0)
    return Object.assign(() => undefined, { release: () => {} });
  const previous = untrack(
    () => new Map(ids.map((id) => [id, doneOverrides().get(id)]))
  );
  const applied = new Map<string, DoneOverride | undefined>();
  setDoneOverrides((prev) => {
    const next = new Map(prev);
    for (const id of ids) {
      if (done === undefined) next.delete(id);
      else
        next.set(id, {
          done,
          reopened:
            !done &&
            (prev.get(id)?.done === true || prev.get(id)?.reopened === true),
        });
      applied.set(id, next.get(id));
    }
    return next;
  });
  // A failed older mutation must not undo a newer local action.
  const finish = (restorePrevious: boolean) =>
    setDoneOverrides((current) => {
      const next = new Map(current);
      for (const id of ids) {
        if (current.get(id) !== applied.get(id)) continue;
        const before = restorePrevious ? previous.get(id) : undefined;
        if (before === undefined) next.delete(id);
        else next.set(id, before);
      }
      return next;
    });
  return Object.assign(() => finish(true), {
    // A partially committed reversal needs authoritative state, not a guessed
    // all-or-nothing rollback. Only release this operation's own contribution.
    release: () => finish(false),
  });
}

// Client-asserted seen state, the `doneOverrides` twin for `viewed_at`. Seen
// is monotone (there is no unsee API), so once a mark is initiated no fetch
// snapshot may present the notification as unread: a full refetch reads its
// pages over several seconds and a page read before the mark's POST commits
// resurrects pre-write state when it lands. Entries are removed on mutation
// failure (that rollback is deliberate). REST-only overrides can be pruned
// once the feed confirms the seen state at a quiet moment; GraphQL Soup edges
// can still hold older snapshots independently of that feed.
type SeenOverride = { viewedAt: string; token: symbol };
const [seenOverrides, setSeenOverrides] = createRoot(() =>
  createStore<Record<string, SeenOverride | undefined>>({})
);

function setSeenOverride(ids: readonly string[], viewedAt: string | undefined) {
  if (ids.length === 0) return () => undefined;
  const token = Symbol();
  const previous = untrack(
    () =>
      new Map(
        ids.map((id) => {
          const entry = seenOverrides[id];
          return [id, entry ? { ...entry } : undefined] as const;
        })
      )
  );
  batch(() => {
    for (const id of ids)
      setSeenOverrides(
        id,
        viewedAt === undefined ? undefined : { viewedAt, token }
      );
  });
  return () =>
    batch(() => {
      for (const id of ids) {
        if (seenOverrides[id]?.token === token)
          setSeenOverrides(id, previous.get(id));
      }
    });
}

/** Applies local intent to a bounded state-only witness without loading the feed. */
function notificationStateWithLocalOverrides(
  notification: Pick<UnifiedNotification, 'id' | 'state'>
): UnifiedNotification['state'] {
  const override = doneOverrides().get(notification.id);
  const state = override?.done
    ? 'done'
    : override?.reopened
      ? 'seen'
      : override
        ? nextNotificationState(notification.state, 'MARK_UNDONE')
        : notification.state;
  return state === 'unseen' && seenOverrides[notification.id] ? 'seen' : state;
}

function withNotificationOverrides(
  notification: UnifiedNotification
): UnifiedNotification {
  const doneOverride = doneOverrides().get(notification.id);
  if (notification.state !== 'unseen' && doneOverride === undefined) {
    return notification;
  }
  return {
    ...notification,
    get state() {
      return notificationStateWithLocalOverrides(notification);
    },
    // Only the affected id's seen state is a dependency of this row.
    get viewed_at() {
      if (notification.viewed_at) return notification.viewed_at;
      return seenOverrides[notification.id]?.viewedAt ?? notification.viewed_at;
    },
  };
}

export function createNotificationSource(
  ws: ConnectionGatewayWebsocket,
  onNotification?: (notification: UnifiedNotification) => void,
  enabled: Accessor<boolean> = () => true
): NotificationSource {
  const subscriptions: Set<SubscribeFn> = new Set();

  const notificationsQuery = useUserNotificationsQuery(
    () => ({ limit: QUERY_LIMIT }),
    () => ({ enabled: enabled() })
  );
  const usesGraphql = () => notificationsQuery.transport === 'graphql';
  const mutedEntitiesQuery = createMutedEntitiesQuery(
    { limit: QUERY_LIMIT },
    enabled
  );
  // Read the current query rather than retaining a second copy across sessions.
  const mutedEntities = createMemo(() => {
    if (!enabled() || mutedEntitiesQuery.isPending) return [];
    return mutedEntitiesQuery.data ?? [];
  });
  const muteItem = useMuteItemMutation();
  const unmuteItem = useUnmuteItemMutation();

  const markNotificationsAsSeenMutation = useMarkNotificationsAsSeenMutation();
  const markNotificationsAsDoneMutation = useMarkNotificationsAsDoneMutation();

  // Gate on data presence, not isSuccess: a failed or cancelled background
  // refetch flips status to error while the cached pages remain, and blanking
  // every unread surface over a transient refetch is worse than showing the
  // cached state.
  // A shell that only needs mute state, local overrides, or realtime callbacks
  // must not instantiate the full GraphQL notification feed at startup.
  const notifications = createLazyMemo(() => {
    if (!enabled() || notificationsQuery.isLoading) return [];
    const raw = notificationsQuery.data;
    if (!raw) return [];
    return raw.map(withNotificationOverrides);
  });

  // Only the REST feed owns all notification readers. In GraphQL mode an id
  // leaving (or being confirmed by) this feed says nothing about still-mounted
  // Soup edges. Keep their intent until explicitly cleared, replaced, or rolled
  // back rather than letting pagination resurrect stale edge state.
  createEffect(() => {
    if (!enabled() || usesGraphql()) return;
    const raw = notificationsQuery.data;
    if (!raw) return;
    const presentIds = new Set(raw.map((n) => n.id));
    const overrides = doneOverrides();
    if (overrides.size === 0) return;
    const toPrune: string[] = [];
    for (const id of overrides.keys()) {
      if (!presentIds.has(id)) toPrune.push(id);
    }
    if (toPrune.length > 0) setDoneOverride(toPrune, undefined);
  });

  // Prune seen overrides once they stop being load-bearing: the id left the
  // cache, or the cache row itself is seen at a quiet moment. Quiet matters —
  // while a mark is in flight the seen cache row is the optimistic write, and
  // a fetch that is still running may hold a pre-write snapshot that will
  // land later; in both cases the override must survive.
  createEffect(() => {
    if (!enabled() || usesGraphql()) return;
    const raw = notificationsQuery.data;
    if (!raw) return;
    const seenIds = Object.keys(seenOverrides);
    if (seenIds.length === 0) return;
    const quiet =
      !notificationsQuery.isFetching &&
      !markNotificationsAsSeenMutation.isPending;
    const byId = new Map(raw.map((n) => [n.id, n]));
    const toPrune: string[] = [];
    for (const id of seenIds) {
      const row = byId.get(id);
      if (!row || (row.state !== 'unseen' && quiet)) toPrune.push(id);
    }
    if (toPrune.length > 0) setSeenOverride(toPrune, undefined);
  });

  const notificationsByEntity = createLazyMemo(() => {
    const data = notifications();
    const grouped: NotificationsByEntity = {};

    for (const notification of data) {
      const composite = compositeEntity(notificationEntity(notification));
      grouped[composite] ??= [];
      grouped[composite].push(notification);
    }

    return grouped;
  });

  createEffect(() => {
    // TODO(dev-rb/notifications): Remove this legacy eager pagination when the
    // REST notification source is retired. GraphQL consumers should use Soup
    // notification edges or dedicated notification queries instead.
    if (!enabled() || usesGraphql()) return;
    if (!notificationsQuery.data) return;
    // A failed page keeps the loaded pages and the next cursor, so fetching
    // again here would repeat the failed request in a tight loop (for example,
    // a 401 after the session expired). The next successful fetch clears the
    // error and resumes pagination.
    if (notificationsQuery.error) return;
    if (notificationsQuery.hasNextPage && !notificationsQuery.isFetching) {
      fireAndForget(notificationsQuery.fetchNextPage(), 'notifications');
    }
  });

  const isLoading = () => {
    return (
      enabled() &&
      (notificationsQuery.isLoading || mutedEntitiesQuery.isLoading)
    );
  };

  // TODO(dev-rb/notifications): Verify whether document-mention suppression is
  // still required, and remove this source-based cleanup when it is not.
  if (!ENABLE_DOCUMENT_MENTION_NOTIFICATIONS) {
    const discardDocumentMentions = async (notificationIds: string[]) => {
      try {
        await markNotificationsAsDoneMutation.mutateAsync({ notificationIds });
      } catch (error) {
        console.error(
          'Failed to discard document mention notifications',
          error
        );
      }
    };
    createEffect(() => {
      // This flag defaults off in production. Cleanup may observe an activated
      // feed, but must not become the reader that wakes it during startup.
      if (!enabled() || !notificationsQuery.isStarted) return;
      const toDiscard = notifications().filter(
        (n) =>
          n.notification_event_type === 'document_mention' && n.state !== 'done'
      );
      if (toDiscard.length === 0) return;
      fireAndForget(
        discardDocumentMentions(toDiscard.map((n) => n.id)),
        'notifications'
      );
    });
  }

  const dispatchIncomingNotification = (
    notification: UnifiedNotification
  ): void => {
    onNotification?.(notification);
    subscriptions.forEach((subscribe) => subscribe(notification));
  };

  let graphqlRefetchScheduled = false;
  let graphqlRefetchInFlight = false;
  let graphqlRefetchPending = false;
  let graphqlSubscriptionDisposed = false;

  const runGraphqlNotificationRefetch = async (): Promise<void> => {
    if (!enabled() || graphqlSubscriptionDisposed || graphqlRefetchInFlight)
      return;
    graphqlRefetchInFlight = true;
    try {
      do {
        graphqlRefetchPending = false;
        try {
          await notificationsQuery.refetch();
        } catch (error) {
          console.warn(
            'Failed to refresh notifications after GraphQL patch',
            error
          );
        }
      } while (graphqlRefetchPending && !graphqlSubscriptionDisposed);
    } finally {
      graphqlRefetchInFlight = false;
    }
  };

  const scheduleGraphqlNotificationRefetch = (): void => {
    // Still dispatch new-notification callbacks below. The first actual feed
    // reader will fetch current data; a patch must not wake an unused feed.
    if (!enabled() || !notificationsQuery.isStarted) return;
    graphqlRefetchPending = true;
    if (graphqlRefetchScheduled || graphqlRefetchInFlight) return;
    graphqlRefetchScheduled = true;
    queueMicrotask(() => {
      graphqlRefetchScheduled = false;
      fireAndForget(runGraphqlNotificationRefetch(), 'notifications');
    });
  };

  const unsubscribeFromGraphql = subscribeToGraphqlNotificationPatches(
    (patch) => {
      if (!enabled() || !usesGraphql()) return;
      scheduleGraphqlNotificationRefetch();
      if (patch.__typename !== 'GraphqlNewNotification') return;
      const notification = mapGraphqlNotification(patch.notification);
      updateSoupForNotification(notification);
      dispatchIncomingNotification(notification);
    }
  );
  onCleanup(() => {
    graphqlSubscriptionDisposed = true;
    unsubscribeFromGraphql();
  });

  const mapWebsocketNotification = (
    raw: ConnGatewayNotificationPayload
  ): UnifiedNotification => {
    return {
      ...raw,
      id: raw.notification_id,
      notification_metadata: raw.notification_metadata as NotifEvent,
    };
  };

  createSocketEffect(ws, (wsData) => {
    if (
      !enabled() ||
      wsData.type !== NOTIFICATION_EVENT_TYPE ||
      usesGraphql()
    ) {
      return;
    }
    let parsedNotification: UnifiedNotification;
    try {
      const raw = JSON.parse(wsData.data) as ConnGatewayNotificationPayload;
      const unsafeMapped = mapWebsocketNotification(raw);
      // Metadata fallback must never admit a missing or invalid lifecycle state.
      if (!['unseen', 'seen', 'done'].includes(unsafeMapped.state)) {
        throw new Error('Invalid notification state');
      }
      const parseResult = unifiedNotificationSchema.safeParse(unsafeMapped);
      if (!parseResult.success) {
        console.warn(
          'Failed to parse notification',
          wsData.data,
          fromZodError(parseResult.error)
        );
        parsedNotification = unsafeMapped;
      } else {
        parsedNotification = parseResult.data;
      }
    } catch (e) {
      console.error('Failed to parse notification', wsData.data, e);
      return;
    }
    // Apply optimistic Soup writes before callbacks start list revalidation;
    // otherwise those writes cancel the refetch triggered by this delivery.
    if (notificationsQuery.transport === 'rest') {
      optimisticInsertNotification(parsedNotification);
    }
    dispatchIncomingNotification(parsedNotification);
  });

  // Skip empty batches: entity-level read markers fire on mount regardless
  // of whether the entity has notifications, and an empty batch would still
  // POST a no-op mutation.
  const bulkMarkAsDone = async (notifications: UnifiedNotification[]) => {
    if (!enabled() || notifications.length === 0) return;
    const ids = notifications.map((n) => n.id);
    const rollback = setDoneOverride(ids, true);
    try {
      await markNotificationsAsDoneMutation.mutateAsync({
        notificationIds: ids,
      });
    } catch (err) {
      rollback();
      throw err;
    }
  };

  const bulkMarkAsRead = async (notifications: UnifiedNotification[]) => {
    if (!enabled() || notifications.length === 0) return;
    const ids = notifications.map((n) => n.id);
    const rollback = setSeenOverride(ids, new Date().toISOString());
    try {
      await markNotificationsAsSeenMutation.mutateAsync({
        notificationIds: ids,
      });
    } catch (err) {
      rollback();
      throw err;
    }
  };

  const markAsDone = async (notification: UnifiedNotification) => {
    await bulkMarkAsDone([notification]);
  };

  const markAsRead = async (notification: UnifiedNotification) => {
    await bulkMarkAsRead([notification]);
  };

  // Canonicalize the type where we know how to; otherwise pass it through so
  // legacy callers keep working unchanged.
  const toMuteItem = (entity: Entity): UserUnsubscribe =>
    muteItemForRef(entity) ?? { item_id: entity.id, item_type: entity.type };

  const muteEntity = async (entity: Entity) => {
    if (!enabled()) return;
    await muteItem.mutateAsync(toMuteItem(entity));
  };

  const unmuteEntity = async (entity: Entity) => {
    if (!enabled()) return;
    await unmuteItem.mutateAsync(toMuteItem(entity));
  };

  const subscribe = (subscribeFn: SubscribeFn) => {
    subscriptions.add(subscribeFn);
    return () => {
      subscriptions.delete(subscribeFn);
    };
  };

  return {
    notificationsByEntity,
    notifications,
    mutedEntities,
    isLoading,
    _notificationsQuery: notificationsQuery,
    _mutedEntitiesQuery: mutedEntitiesQuery,
    markAsDone,
    markAsRead,
    bulkMarkAsRead,
    bulkMarkAsDone,
    muteEntity,
    unmuteEntity,
    subscribe,
    get withLocalOverrides() {
      return usesGraphql() ? withNotificationOverrides : undefined;
    },
    get withLocalState() {
      return usesGraphql() ? notificationStateWithLocalOverrides : undefined;
    },
  };
}