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.

36.9 KB
Raw Blame
import { analytics } from '@app/lib/analytics';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { toast } from '@core/component/Toast/Toast';
import {
  enableGraphqlSoup,
  isFeatureEnabled,
} from '@core/constant/featureFlags';
import { fireAndForget } from '@core/util/fireAndForget';
import { thrownResultErrorHasCode, throwOnErr } from '@core/util/result';
import { optimisticMutationDispositionOf } from '@graphql-cache/exchange/optimistic';
import {
  entityPropertyFromApi,
  propertyValueToApi,
} from '@property/api/converters';
import { PROPERTY_OPTION_IDS, SYSTEM_PROPERTY_IDS } from '@property/constants';
import type {
  Property,
  PropertyApiValues,
  PropertyDefinitionDomain,
} from '@property/types';
import { isInstantiatedProperty } from '@property/utils';
import { refreshCrmAssociatedSoupQueries } from '@queries/soup/crm-association';
import { ownTouchStamp } from '@queries/soup/normalized-cache/own-touch';
import { DeleteEntityPropertyDocument } from '@service-storage/graphql/generated/graphql';
import { getGraphqlSoupClient } from '@service-storage/graphql-soup';
import { queryOptions, useMutation, useQuery } from '@tanstack/solid-query';
import { type Accessor, batch } from 'solid-js';
import { propertiesServiceClient } from '../../service-clients/service-properties/client';
import type { EntityType } from '../../service-clients/service-properties/generated/schemas/entityType';
import type { PropertyTargetEntityType } from '../../service-clients/service-properties/generated/schemas/propertyTargetEntityType';
import type { SoupProperty } from '../../service-clients/service-storage/generated/schemas/soupProperty';
import type { SoupPropertyValue } from '../../service-clients/service-storage/generated/schemas/soupPropertyValue';
import { queryClient } from '../client';
import {
  getSoupEntityById,
  invalidateSoupEntity,
  optimisticUpdateSoupEntity,
  type SoupTransaction,
} from '../soup/cache';
import { refreshPropertyQueries } from '../soup/property-queries';
import { type MutationCallbacks, withCallbacks } from '../utils';
import {
  type AddEntityPropertyInput,
  type BulkSaveEntityPropertiesInput,
  createGraphqlAddEntityPropertyMutation,
  createGraphqlBulkSaveEntityPropertiesMutation,
  createGraphqlEntityPropertiesQuery,
  type EntityPropertyMutationDisposition,
  refetchGraphqlInitiativeProperties,
} from './graphql/entity';
import { updateGraphqlEntityPropertyOptions } from './graphql/entity-options';
import {
  type BulkUpdateEntityPropertyOptionsParams,
  bulkEntityPropertyOptionsKey,
} from './in-flight-options';
import { propertiesKeys } from './keys';
import {
  type EntityPropertyOptionSelection,
  getEntityPropertyOptionDeltas,
} from './option-deltas';

function toPropertyTargetEntityType(
  entityType: EntityType | PropertyTargetEntityType
): PropertyTargetEntityType {
  if (entityType === 'TASK') return 'DOCUMENT';
  if (entityType === 'CALENDAR_EVENT') {
    // Not a property target yet; surface a real error instead of a bad request.
    throw new Error('calendar events do not support properties');
  }
  if (entityType === 'CONTACT') {
    throw new Error('crm contacts do not support properties');
  }
  return entityType;
}

async function setRestEntityProperty(args: {
  entityType: EntityType | PropertyTargetEntityType;
  entityId: string;
  propertyDefinitionId: string;
  value: ReturnType<typeof propertyValueToApi>;
}): Promise<EntityPropertyMutationDisposition> {
  try {
    await throwOnErr(
      async () =>
        await propertiesServiceClient.setEntityProperty({
          entity_type: toPropertyTargetEntityType(args.entityType),
          entity_id: args.entityId,
          property_id: args.propertyDefinitionId,
          body: { value: args.value },
        })
    );
    return { kind: 'committed' };
  } catch (error) {
    return {
      kind: 'permanently-failed',
      error: error instanceof Error ? error : new Error(String(error)),
    };
  }
}

/**
 * An entity's properties from the properties service, metadata included, so
 * consumers with different `includeMetadata` values share one cache entry and
 * one request.
 */
async function fetchRestEntityProperties(
  entityType: EntityType,
  entityId: string
): Promise<Property[]> {
  const data = await throwOnErr(
    async () =>
      await propertiesServiceClient.getEntityProperties({
        entity_type: toPropertyTargetEntityType(entityType),
        entity_id: entityId,
        query: { include_metadata: true },
      })
  );
  return data.properties.flatMap((property) => {
    try {
      return [entityPropertyFromApi(property)];
    } catch (error) {
      console.warn('Skipping property with unsupported type', error);
      return [];
    }
  });
}

/** Read an entity's current properties through the shared entity query. */
export function fetchEntityProperties(
  entityType: EntityType,
  entityId: string
): Promise<Property[]> {
  return queryClient.fetchQuery({
    queryKey: propertiesKeys.entity({ entityType, entityId }).queryKey,
    queryFn: () => fetchRestEntityProperties(entityType, entityId),
    staleTime: 0,
  });
}

// Cached callbacks outlive the caller; only plain values enter here.
function entityPropertiesQueryOptions(
  entityType: EntityType,
  entityId: string,
  enabled: boolean,
  includeMetadata: boolean
) {
  return queryOptions({
    queryKey: propertiesKeys.entity({ entityType, entityId }).queryKey,
    enabled,
    queryFn: () => fetchRestEntityProperties(entityType, entityId),
    select: (properties: Property[]) =>
      includeMetadata
        ? properties
        : properties.filter((property) => property.isMetadata !== true),
    staleTime: 0,
  });
}

export function useEntityPropertiesQuery(
  entityType: Accessor<EntityType>,
  entityId: Accessor<string>,
  includeMetadata: boolean
) {
  const graphqlSoupFlag = useFeatureFlag(enableGraphqlSoup);

  // Metadata properties are computed by the REST properties endpoint and are
  // not part of the GraphQL Soup property edge. USER is not represented in
  // Soup either. The GraphQL adapter owns those eligibility details.
  const graphqlQuery = createGraphqlEntityPropertiesQuery({
    entityType,
    entityId,
    enabled: () =>
      entityType() === 'INITIATIVE' ||
      (graphqlSoupFlag().enabled && !includeMetadata),
  });

  const usesGraphql = graphqlQuery.isEnabled;

  const restQuery = useQuery(
    () => {
      const id = entityId();
      return entityPropertiesQueryOptions(
        entityType(),
        id,
        !usesGraphql() && id.length > 0,
        includeMetadata
      );
    },
    () => queryClient
  );

  return {
    get data() {
      if (
        entityType() === 'INITIATIVE' &&
        graphqlQuery.result.error?.graphQLErrors.some((error) =>
          ['UNAUTHORIZED', 'FORBIDDEN', 'NOT_FOUND'].includes(
            String(error.extensions.code)
          )
        )
      )
        return [];
      return usesGraphql() ? graphqlQuery.result.data : restQuery.data;
    },
    get error() {
      return usesGraphql() ? graphqlQuery.result.error : restQuery.error;
    },
    get isLoading() {
      return usesGraphql()
        ? graphqlQuery.result.isLoading
        : restQuery.isLoading;
    },
    get isFetching() {
      return usesGraphql()
        ? graphqlQuery.result.isFetching
        : restQuery.isFetching;
    },
    refetch() {
      if (entityId().length === 0) return Promise.resolve(undefined);
      return usesGraphql() ? graphqlQuery.refetch() : restQuery.refetch();
    },
  };
}

async function invalidatePropertiesForEntity(
  entityType: EntityType | PropertyTargetEntityType,
  entityId: string
) {
  const invalidate = queryClient.invalidateQueries({
    queryKey: propertiesKeys.entity({ entityType, entityId }).queryKey,
  });
  if (entityType !== 'INITIATIVE') {
    await invalidate;
    return;
  }
  // Attaching/removing a property changes the initiative's property link list,
  // which cannot be inferred from the returned property record alone.
  await Promise.all([invalidate, refetchGraphqlInitiativeProperties(entityId)]);
}

function getPropertyDefinitionId(
  property: Property | PropertyDefinitionDomain
): string {
  return isInstantiatedProperty(property)
    ? property.propertyDefinitionId
    : property.id;
}

function optimisticUpdateSoupEntityProperties(
  entityId: string,
  updates: {
    property: Property | PropertyDefinitionDomain;
    value: SoupPropertyValue;
  }[]
): SoupTransaction | undefined {
  const current = getSoupEntityById(entityId);
  if (!current) {
    // A miss here means the write silently lost its optimism. Expected on the
    // GraphQL transport, whose rows live in the normalized cache instead and
    // carry their own optimistic write.
    if (!isFeatureEnabled(enableGraphqlSoup)) {
      console.warn(
        'no soup cache entry for entity; skipping optimistic property update',
        entityId
      );
    }
    return undefined;
  }
  // channel / foreign entity / channel thread rows are property-less; call
  // records carry properties (tags) and are handled like documents.
  if (
    current.tag === 'channel' ||
    current.tag === 'foreignEntity' ||
    current.tag === 'channelThread' ||
    current.tag === 'calendarEvent' ||
    !current.data.properties
  ) {
    return undefined;
  }

  const nextProperties = [...current.data.properties];
  for (const { property, value } of updates) {
    const propertyDefinitionId = getPropertyDefinitionId(property);
    const index = nextProperties.findIndex(
      (prop) => prop.definition.id === propertyDefinitionId
    );
    const existingProp = nextProperties[index];
    const nextProp: SoupProperty = existingProp
      ? {
          ...existingProp,
          definition: {
            ...existingProp.definition,
            // HACK (seamus): we need to change something other than value in
            // order to get normy to update the cache. Changing
            // definition.updated_at is INCORRECT, but it's currently harmless.
            updated_at: new Date().toISOString(),
          },
          value,
        }
      : buildSoupProperty(property, value);

    if (index === -1) nextProperties.push(nextProp);
    else nextProperties[index] = nextProp;
  }

  return optimisticUpdateSoupEntity({
    tag: current.tag,
    data: {
      ...current.data,
      properties: nextProperties,
    },
    frecency_score: current.frecency_score,
    // A property change is a PropertyChanged activity, i.e. a touch
    // (own-touch.ts).
    touched_at: ownTouchStamp(entityId),
  });
}

function optimisticUpdateSoupEntityProperty(
  entityId: string,
  property: Property | PropertyDefinitionDomain,
  value: SoupPropertyValue
): SoupTransaction | undefined {
  return optimisticUpdateSoupEntityProperties(entityId, [{ property, value }]);
}

function buildSoupProperty(
  property: Property | PropertyDefinitionDomain,
  value: SoupPropertyValue
): SoupProperty {
  const now = new Date().toISOString();
  const instantiated = isInstantiatedProperty(property);
  return {
    id: instantiated ? property.propertyId : property.id,
    definition: {
      id: getPropertyDefinitionId(property),
      display_name: property.displayName,
      data_type: property.valueType,
      is_metadata: instantiated
        ? (property.isMetadata ?? false)
        : property.isMetadata,
      is_multi_select: property.isMultiSelect,
      is_system: instantiated
        ? (property.isSystemProperty ?? false)
        : property.isSystem,
      owner: property.owner,
      specific_entity_type: property.specificEntityType ?? null,
      created_at: now,
      updated_at: now,
    },
    value,
  };
}

/**
 * Converts PropertyApiValues to the SoupProperty value format for optimistic updates.
 */
function apiValuesToSoupPropertyValue(
  apiValues: PropertyApiValues
): SoupPropertyValue {
  switch (apiValues.valueType) {
    case 'STRING':
      return apiValues.value != null
        ? { type: 'String', value: apiValues.value }
        : null;
    case 'NUMBER':
      return apiValues.value != null
        ? { type: 'Number', value: apiValues.value }
        : null;
    case 'BOOLEAN':
      return apiValues.value != null
        ? { type: 'Boolean', value: apiValues.value }
        : null;
    case 'DATE':
      return apiValues.value != null
        ? { type: 'Date', value: apiValues.value.toISOString() }
        : null;
    case 'SELECT_STRING':
    case 'SELECT_NUMBER':
      return apiValues.values != null && apiValues.values.length > 0
        ? { type: 'SelectOption', value: apiValues.values }
        : null;
    case 'ENTITY':
      return apiValues.refs != null && apiValues.refs.length > 0
        ? { type: 'EntityReference', value: apiValues.refs }
        : null;
    case 'LINK':
      return apiValues.values != null && apiValues.values.length > 0
        ? { type: 'Link', value: apiValues.values }
        : null;
    default:
      return null;
  }
}

type DeleteEntityPropertyParams = {
  entityPropertyId: string;
  entityType: EntityType;
  entityId: string;
};

export function useDeleteEntityPropertyMutation(
  callbacks?: MutationCallbacks<void, Error, DeleteEntityPropertyParams>
) {
  return useMutation(() => ({
    mutationFn: async (vars: DeleteEntityPropertyParams) => {
      if (
        vars.entityType === 'INITIATIVE' ||
        (isFeatureEnabled(enableGraphqlSoup) &&
          vars.entityType !== 'USER' &&
          vars.entityType !== 'CALENDAR_EVENT')
      ) {
        const result = await getGraphqlSoupClient()
          .mutation(DeleteEntityPropertyDocument, {
            entityType: toPropertyTargetEntityType(vars.entityType),
            entityId: vars.entityId,
            entityPropertyId: vars.entityPropertyId,
          })
          .toPromise();
        const disposition = optimisticMutationDispositionOf(result);
        if (disposition?.kind === 'queued') return;
        if (disposition?.kind === 'permanently-failed') throw disposition.error;
        if (result.error) throw result.error;
        if (!result.data) throw new Error('Property removal returned no data');
        return;
      }
      await throwOnErr(
        async () =>
          await propertiesServiceClient.deleteEntityProperty({
            entity_property_id: vars.entityPropertyId,
          })
      );
    },
    ...withCallbacks<void, Error, DeleteEntityPropertyParams>(
      {
        onSuccess: (_data, variables) => {
          // The removed row may have been a Companies or Contacts value.
          fireAndForget(refreshCrmAssociatedSoupQueries(), 'entity-properties');
          invalidateSoupEntity(variables.entityId);
          // Deletion carries an assignment ID, not its definition; refresh property-dependent lists.
          fireAndForget(refreshPropertyQueries(), 'entity-properties');
          return invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          );
        },
        onError(error, variables) {
          console.error('Failed to delete property', error);
          toast.failure('Failed to delete property');
          return invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          );
        },
      },
      callbacks
    ),
  }));
}

type AddEntityPropertyParams = AddEntityPropertyInput;

function useRestAddEntityPropertyMutation(
  callbacks?: MutationCallbacks<void, Error, AddEntityPropertyParams>
) {
  return useMutation(() => ({
    mutationFn: async (vars: AddEntityPropertyParams) => {
      const disposition = await setRestEntityProperty({
        entityType: vars.entityType,
        entityId: vars.entityId,
        propertyDefinitionId: vars.propertyDefinitionId,
        value: null,
      });
      if (disposition.kind === 'permanently-failed') {
        throw disposition.error;
      }
    },
    ...withCallbacks<void, Error, AddEntityPropertyParams>(
      {
        onSuccess: (_data, variables) =>
          invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          ),
        onError(error, variables) {
          console.error('Failed to add property', error);
          toast.failure('Failed to add property');
          return invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          );
        },
      },
      callbacks
    ),
  }));
}

/** Transport-neutral mutation interface for property attachments. */
export type AddEntityPropertyMutation = {
  readonly isPending: boolean;
  readonly error: Error | null;
  mutate(variables: AddEntityPropertyParams): void;
  mutateAsync(variables: AddEntityPropertyParams): Promise<void>;
};

/** Adds a property through GraphQL or the REST fallback. */
export function useAddEntityPropertyMutation(
  callbacks?: MutationCallbacks<void, Error, AddEntityPropertyParams>
): AddEntityPropertyMutation {
  const restMutation = useRestAddEntityPropertyMutation(callbacks);
  const graphqlMutation = createGraphqlAddEntityPropertyMutation<unknown>({
    onMutate: (variables) =>
      callbacks?.onMutate?.(variables, undefined as never),
    onSuccess: async (variables, context) => {
      await invalidatePropertiesForEntity(
        variables.entityType,
        variables.entityId
      );
      await callbacks?.onSuccess?.(
        undefined,
        variables,
        context,
        undefined as never
      );
    },
    onError: async (error, variables, context) => {
      console.error('Failed to add property', error);
      toast.failure('Failed to add property');
      await invalidatePropertiesForEntity(
        variables.entityType,
        variables.entityId
      );
      await callbacks?.onError?.(error, variables, context, undefined as never);
    },
    onSettled: async (error, variables, context) => {
      await callbacks?.onSettled?.(
        undefined,
        error,
        variables,
        context,
        undefined as never
      );
    },
  });

  return {
    get isPending() {
      return graphqlMutation.isPending || restMutation.isPending;
    },
    get error() {
      return graphqlMutation.error ?? restMutation.error ?? null;
    },
    mutate(variables) {
      if (
        variables.entityType === 'INITIATIVE' ||
        isFeatureEnabled(enableGraphqlSoup)
      ) {
        graphqlMutation.mutate(variables);
      } else {
        restMutation.mutate(variables);
      }
    },
    async mutateAsync(variables) {
      if (
        variables.entityType === 'INITIATIVE' ||
        isFeatureEnabled(enableGraphqlSoup)
      ) {
        const result = await graphqlMutation.mutateAsync(variables);
        if (result.error) throw result.error;
      } else {
        await restMutation.mutateAsync(variables);
      }
    },
  };
}

type EntityPropertyOptionParams = {
  entityId: string;
  entityType: EntityType | PropertyTargetEntityType;
  property: Property | PropertyDefinitionDomain;
  optionId: string;
  /**
   * Full option-id array to show optimistically (current value ± optionId). The
   * server applies the single-option delta atomically under a row lock; this
   * array only drives the local cache so the UI updates instantly.
   */
  optimisticOptionIds: string[];
};

type EntityPropertyOptionContext = {
  soupTxn?: SoupTransaction;
};

function entityPropertyOptionCallbacks(
  failureMessage: string,
  callbacks?: MutationCallbacks<
    void,
    Error,
    EntityPropertyOptionParams,
    EntityPropertyOptionContext
  >
) {
  return withCallbacks<
    void,
    Error,
    EntityPropertyOptionParams,
    EntityPropertyOptionContext
  >(
    {
      onMutate: (vars): EntityPropertyOptionContext => {
        const value: SoupPropertyValue =
          vars.optimisticOptionIds.length > 0
            ? { type: 'SelectOption', value: vars.optimisticOptionIds }
            : null;
        const soupTxn = optimisticUpdateSoupEntityProperty(
          vars.entityId,
          vars.property,
          value
        );
        return { soupTxn };
      },
      onSuccess: (_data, variables) => {
        invalidateSoupEntity(variables.entityId);
        fireAndForget(
          refreshPropertyQueries(getPropertyDefinitionId(variables.property)),
          'entity-properties'
        );
        return invalidatePropertiesForEntity(
          variables.entityType,
          variables.entityId
        );
      },
      onError: (error, variables, context) => {
        context?.soupTxn?.rollback();
        invalidateSoupEntity(variables.entityId);
        console.error(failureMessage, error);
        toast.failure(failureMessage);
        return invalidatePropertiesForEntity(
          variables.entityType,
          variables.entityId
        );
      },
    },
    callbacks
  );
}

/**
 * Adds a single option to a multi-select value via the atomic delta endpoint.
 * Unlike the full-value save, concurrent edits to the same value merge instead
 * of clobbering each other.
 */
export function useAddEntityPropertyOptionMutation(
  callbacks?: MutationCallbacks<
    void,
    Error,
    EntityPropertyOptionParams,
    EntityPropertyOptionContext
  >
) {
  return useMutation(() => ({
    mutationFn: async (vars: EntityPropertyOptionParams) => {
      if (vars.entityType === 'INITIATIVE') {
        await updateGraphqlEntityPropertyOptions({
          entityType: vars.entityType,
          entityId: vars.entityId,
          properties: [
            {
              property: vars.property,
              currentOptionIds: vars.optimisticOptionIds.filter(
                (id) => id !== vars.optionId
              ),
              nextOptionIds: vars.optimisticOptionIds,
            },
          ],
        });
        return;
      }
      await throwOnErr(
        async () =>
          await propertiesServiceClient.addEntityPropertyOption({
            entity_type: toPropertyTargetEntityType(vars.entityType),
            entity_id: vars.entityId,
            property_id: getPropertyDefinitionId(vars.property),
            option_id: vars.optionId,
          })
      );
    },
    ...entityPropertyOptionCallbacks('Failed to add tag', callbacks),
  }));
}

/**
 * Removes a single option from a multi-select value via the atomic delta
 * endpoint. A no-op server-side if the option is already gone.
 */
export function useRemoveEntityPropertyOptionMutation(
  callbacks?: MutationCallbacks<
    void,
    Error,
    EntityPropertyOptionParams,
    EntityPropertyOptionContext
  >
) {
  return useMutation(() => ({
    mutationFn: async (vars: EntityPropertyOptionParams) => {
      if (vars.entityType === 'INITIATIVE') {
        await updateGraphqlEntityPropertyOptions({
          entityType: vars.entityType,
          entityId: vars.entityId,
          properties: [
            {
              property: vars.property,
              currentOptionIds: [...vars.optimisticOptionIds, vars.optionId],
              nextOptionIds: vars.optimisticOptionIds,
            },
          ],
        });
        return;
      }
      await throwOnErr(
        async () =>
          await propertiesServiceClient.removeEntityPropertyOption({
            entity_type: toPropertyTargetEntityType(vars.entityType),
            entity_id: vars.entityId,
            property_id: getPropertyDefinitionId(vars.property),
            option_id: vars.optionId,
          })
      );
    },
    ...entityPropertyOptionCallbacks('Failed to remove tag', callbacks),
  }));
}

type BulkUpdateEntityPropertyOptionsContext = {
  soupTxn?: SoupTransaction;
};

type BulkUpdateEntityPropertyOptionsResult = {
  selections: EntityPropertyOptionSelection[];
  transport: 'graphql' | 'rest';
};

/**
 * Persists a complete multi-select selection across one or more properties in a
 * single transactional request, then reconciles the soup cache from the final
 * option ids the server returns (which may differ from the optimistic value if a
 * concurrent edit merged in). The optimistic soup update is atomic and rolls
 * back as a whole on failure. Commits for the same entity are serialized via a
 * mutation scope, so concurrent edits can't interleave and corrupt optimistic
 * state.
 */
export function useBulkUpdateEntityPropertyOptionsMutation(
  entityId: string,
  callbacks?: MutationCallbacks<
    BulkUpdateEntityPropertyOptionsResult,
    Error,
    BulkUpdateEntityPropertyOptionsParams,
    BulkUpdateEntityPropertyOptionsContext
  >
) {
  return useMutation(() => ({
    mutationKey: bulkEntityPropertyOptionsKey(entityId),
    scope: { id: `entity-property-options:${entityId}` },
    mutationFn: async (
      variables: BulkUpdateEntityPropertyOptionsParams
    ): Promise<BulkUpdateEntityPropertyOptionsResult> => {
      // The transport swaps, the mutation shell does not: the per-entity scope
      // that serializes commits and the in-flight overlay both read this
      // mutation's state, whichever cache the selection lands in.
      if (
        variables.entityType === 'INITIATIVE' ||
        isFeatureEnabled(enableGraphqlSoup)
      ) {
        return {
          selections: await updateGraphqlEntityPropertyOptions(variables),
          transport: 'graphql',
        };
      }
      const response = await throwOnErr(async () =>
        propertiesServiceClient.bulkUpdateEntityPropertyOptions({
          entity_type: toPropertyTargetEntityType(variables.entityType),
          entity_id: variables.entityId,
          body: {
            properties: variables.properties.map((update) => {
              const deltas = getEntityPropertyOptionDeltas(
                update.currentOptionIds,
                update.nextOptionIds
              );
              return {
                property_id: getPropertyDefinitionId(update.property),
                add_option_ids: deltas.addOptionIds,
                remove_option_ids: deltas.removeOptionIds,
              };
            }),
          },
        })
      );
      return {
        selections: response.properties.map((property) => ({
          propertyDefinitionId: property.property_id,
          optionIds: property.option_ids,
        })),
        transport: 'rest',
      };
    },
    ...withCallbacks<
      BulkUpdateEntityPropertyOptionsResult,
      Error,
      BulkUpdateEntityPropertyOptionsParams,
      BulkUpdateEntityPropertyOptionsContext
    >(
      {
        onMutate: (variables) => {
          const soupTxn = optimisticUpdateSoupEntityProperties(
            variables.entityId,
            variables.properties.map((update) => ({
              property: update.property,
              value:
                update.nextOptionIds.length > 0
                  ? { type: 'SelectOption', value: update.nextOptionIds }
                  : null,
            }))
          );
          return { soupTxn };
        },
        onSuccess: ({ selections, transport }, variables) => {
          const propertyByDefinitionId = new Map(
            variables.properties.map((update) => [
              getPropertyDefinitionId(update.property),
              update.property,
            ])
          );
          optimisticUpdateSoupEntityProperties(
            variables.entityId,
            selections.flatMap((selection) => {
              const property = propertyByDefinitionId.get(
                selection.propertyDefinitionId
              );
              if (!property) return [];
              return [
                {
                  property,
                  value:
                    selection.optionIds.length > 0
                      ? {
                          type: 'SelectOption' as const,
                          value: selection.optionIds,
                        }
                      : null,
                },
              ];
            })
          );
          invalidateSoupEntity(variables.entityId);
          for (const selection of selections) {
            fireAndForget(
              refreshPropertyQueries(selection.propertyDefinitionId, {
                includeOptionFilters: true,
                unmaintainedOnly: transport === 'graphql',
              }),
              'entity-properties'
            );
          }
          return invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          );
        },
        onError: (error, variables, context) => {
          context?.soupTxn?.rollback();
          invalidateSoupEntity(variables.entityId);
          console.error('Failed to update tags', error);
          toast.failure(
            thrownResultErrorHasCode(error, 'FORBIDDEN')
              ? 'Edit permissions are required to update tags'
              : 'Failed to update tags'
          );
          return invalidatePropertiesForEntity(
            variables.entityType,
            variables.entityId
          );
        },
      },
      callbacks
    ),
  }));
}

/**
 * Task system property ids → the `property` name reported on `update_entity`.
 * Non-task properties (custom properties, tags, ...) are not tracked here.
 */
const TRACKED_TASK_PROPERTIES: Record<string, string> = {
  [SYSTEM_PROPERTY_IDS.STATUS]: 'status',
  [SYSTEM_PROPERTY_IDS.PRIORITY]: 'priority',
  [SYSTEM_PROPERTY_IDS.ASSIGNEES]: 'assignees',
  [SYSTEM_PROPERTY_IDS.DUE_DATE]: 'due_date',
};

/**
 * Emits a generic `update_entity` event for a saved task system property.
 * Gated on the property being one of the task system properties, so saves on
 * other entities/properties never fire. Call only on save success.
 */
function trackTaskPropertySave(
  entityId: string,
  propertyId: string,
  apiValues: PropertyApiValues
) {
  const property = TRACKED_TASK_PROPERTIES[propertyId];
  if (!property) return;

  const detail: Record<string, unknown> = {};
  if (property === 'status') {
    const newStatus =
      apiValues.valueType === 'SELECT_STRING'
        ? (apiValues.values?.[0] ?? undefined)
        : undefined;
    if (!newStatus) return;
    detail.newStatus = newStatus;
    detail.completed = newStatus === PROPERTY_OPTION_IDS.STATUS.COMPLETED;
  } else if (property === 'priority') {
    detail.newPriority =
      apiValues.valueType === 'SELECT_STRING'
        ? (apiValues.values?.[0] ?? undefined)
        : undefined;
  } else if (property === 'assignees') {
    detail.assigneeCount =
      apiValues.valueType === 'ENTITY' ? (apiValues.refs?.length ?? 0) : 0;
  } else if (property === 'due_date') {
    detail.hasDueDate =
      apiValues.valueType === 'DATE' && apiValues.value != null;
  }

  analytics.track('update_entity', {
    entityType: 'task',
    entityId,
    property,
    source: 'property_editor',
    ...detail,
  });
}

type BulkSaveEntityPropertiesParams = BulkSaveEntityPropertiesInput;

type BulkSaveEntityPropertiesContext = {
  /** Index-aligned with `variables.properties`. */
  soupTxns: Array<SoupTransaction | undefined>;
};

type BulkSaveEntityPropertiesResult = {
  /** Index-aligned with the submitted properties. */
  dispositions: EntityPropertyMutationDisposition[];
};

class BulkSaveEntityPropertiesError extends Error {
  constructor(readonly result: BulkSaveEntityPropertiesResult) {
    super('One or more properties permanently failed to save');
    this.name = 'BulkSaveEntityPropertiesError';
  }
}

/** Properties whose values decide which items a CRM record lists. */
const CRM_ASSOCIATION_PROPERTY_IDS: readonly string[] = [
  SYSTEM_PROPERTY_IDS.COMPANIES,
  SYSTEM_PROPERTY_IDS.CONTACTS,
];

function invalidatePropertySaveCaches(
  item: BulkSaveEntityPropertiesParams['properties'][number]
): void {
  fireAndForget(
    invalidatePropertiesForEntity(item.entityType, item.entityId),
    'entity-properties'
  );
  invalidateSoupEntity(item.entityId);
  fireAndForget(
    refreshPropertyQueries(getPropertyDefinitionId(item.property)),
    'entity-properties'
  );
  // CRM record lists resolve membership on the server, not from these rows.
  if (
    CRM_ASSOCIATION_PROPERTY_IDS.includes(
      getPropertyDefinitionId(item.property)
    )
  ) {
    fireAndForget(refreshCrmAssociatedSoupQueries(), 'entity-properties');
  }
}

function handleCommittedPropertySave(
  item: BulkSaveEntityPropertiesParams['properties'][number],
  disposition: EntityPropertyMutationDisposition
): void {
  if (disposition.kind !== 'committed') return;

  trackTaskPropertySave(
    item.entityId,
    getPropertyDefinitionId(item.property),
    item.apiValues
  );
}

function reportBulkPropertySaveFailure(error: Error): void {
  console.error('Failed to bulk save properties', error);
  toast.failure('Failed to save properties');
}

function rollbackBulkSoupTransactions(
  context: BulkSaveEntityPropertiesContext | undefined
): void {
  if (!context?.soupTxns.length) return;
  batch(() => {
    for (let i = context.soupTxns.length - 1; i >= 0; i--) {
      context.soupTxns[i]?.rollback();
    }
  });
}

function useRestBulkSaveEntityPropertiesMutation(
  callbacks?: MutationCallbacks<
    void,
    Error,
    BulkSaveEntityPropertiesParams,
    BulkSaveEntityPropertiesContext
  >
) {
  return useMutation(() => ({
    mutationFn: async (vars: BulkSaveEntityPropertiesParams): Promise<void> => {
      const dispositions = await Promise.all(
        vars.properties.map(async (item) => {
          const disposition = await setRestEntityProperty({
            entityType: item.entityType,
            entityId: item.entityId,
            propertyDefinitionId: getPropertyDefinitionId(item.property),
            value: propertyValueToApi(
              item.apiValues,
              item.property.isMultiSelect
            ),
          });
          handleCommittedPropertySave(item, disposition);
          return disposition;
        })
      );
      const result = { dispositions };
      if (
        dispositions.some(
          (disposition) => disposition.kind === 'permanently-failed'
        )
      ) {
        throw new BulkSaveEntityPropertiesError(result);
      }
    },
    ...withCallbacks<
      void,
      Error,
      BulkSaveEntityPropertiesParams,
      BulkSaveEntityPropertiesContext
    >(
      {
        onMutate: (
          vars: BulkSaveEntityPropertiesParams
        ): BulkSaveEntityPropertiesContext => ({
          soupTxns: batch(() =>
            vars.properties.map((item) =>
              optimisticUpdateSoupEntityProperty(
                item.entityId,
                item.property,
                apiValuesToSoupPropertyValue(item.apiValues)
              )
            )
          ),
        }),
        onError: (error, _variables, context) => {
          rollbackBulkSoupTransactions(context);
          reportBulkPropertySaveFailure(error);
        },
        onSettled: (_data, _error, variables) => {
          batch(() => {
            for (const item of variables.properties) {
              invalidatePropertySaveCaches(item);
            }
          });
        },
      },
      callbacks
    ),
  }));
}

/** Transport-neutral mutation interface exposed to property consumers. */
export type BulkSaveEntityPropertiesMutation = {
  readonly isPending: boolean;
  readonly error: Error | null;
  mutate(variables: BulkSaveEntityPropertiesParams): void;
  mutateAsync(variables: BulkSaveEntityPropertiesParams): Promise<void>;
};

/** Saves entity properties through GraphQL or the REST fallback. */
export function useBulkSaveEntityPropertiesMutation(
  callbacks?: MutationCallbacks<
    void,
    Error,
    BulkSaveEntityPropertiesParams,
    BulkSaveEntityPropertiesContext
  >
): BulkSaveEntityPropertiesMutation {
  const restMutation = useRestBulkSaveEntityPropertiesMutation(callbacks);
  const graphqlMutation =
    createGraphqlBulkSaveEntityPropertiesMutation<BulkSaveEntityPropertiesContext>(
      {
        onMutate: async (variables) =>
          (await callbacks?.onMutate?.(variables, undefined as never)) ?? {
            soupTxns: [],
          },
        onCommitted: handleCommittedPropertySave,
        onSuccess: async (variables, context) => {
          await callbacks?.onSuccess?.(
            undefined,
            variables,
            context ?? { soupTxns: [] },
            undefined as never
          );
        },
        onError: async (error, variables, context) => {
          reportBulkPropertySaveFailure(error);
          await callbacks?.onError?.(
            error,
            variables,
            context ?? { soupTxns: [] },
            undefined as never
          );
        },
        onSettled: async (error, variables, context) => {
          batch(() => {
            for (const item of variables.properties) {
              invalidatePropertySaveCaches(item);
            }
          });
          await callbacks?.onSettled?.(
            undefined,
            error,
            variables,
            context ?? { soupTxns: [] },
            undefined as never
          );
        },
      }
    );

  return {
    get isPending() {
      return graphqlMutation.isPending || restMutation.isPending;
    },
    get error() {
      return graphqlMutation.error ?? restMutation.error ?? null;
    },
    mutate(variables) {
      if (
        variables.properties.some((item) => item.entityType === 'INITIATIVE') ||
        isFeatureEnabled(enableGraphqlSoup)
      ) {
        graphqlMutation.mutate(variables);
      } else {
        restMutation.mutate(variables);
      }
    },
    async mutateAsync(variables) {
      if (
        variables.properties.some((item) => item.entityType === 'INITIATIVE') ||
        isFeatureEnabled(enableGraphqlSoup)
      ) {
        const result = await graphqlMutation.mutateAsync(variables);
        if (result.error) throw result.error;
      } else {
        await restMutation.mutateAsync(variables);
      }
    },
  };
}