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.

21.2 KB
Raw Blame
import { createUrqlMutation } from '@app/lib/urql-solid/create-urql-mutation';
import { createUrqlQuery } from '@app/lib/urql-solid/create-urql-query';
import type { UrqlMutationExecutor } from '@app/lib/urql-solid/types';
import { soupPropertyToProperty } from '@entity/extractors-property/property-helpers';
import {
  executeOptimisticMutation,
  optimisticMutationDispositionOf,
} from '@graphql-cache/index';
import { propertyValueToApi } from '@property/api/converters';
import type {
  Property,
  PropertyApiValues,
  PropertyDefinitionDomain,
} from '@property/types';
import { withProjectStatusOptions } from '@property/utils/select-options';
import { isInstantiatedProperty } from '@property/utils/typeGuards';
import type { EntityReference } from '@service-properties/generated/schemas/entityReference';
import type { EntityType } from '@service-properties/generated/schemas/entityType';
import type { PropertyTargetEntityType } from '@service-properties/generated/schemas/propertyTargetEntityType';
import type { SetPropertyValue } from '@service-properties/generated/schemas/setPropertyValue';
import type { SoupProperty } from '@service-storage/generated/schemas/soupProperty';
import {
  EntityPropertiesDocument,
  type EntityPropertiesQuery,
  type EntityPropertiesQueryVariables,
  type GraphqlEntityReferenceInput,
  type GraphqlPropertyTargetEntityType,
  type GraphqlSetPropertyValue,
  SetEntityPropertyDocument,
  type SetEntityPropertyMutation,
  type SetEntityPropertyMutationVariables,
  type SoupEntityInput,
} from '@service-storage/graphql/generated/graphql';
import {
  getGraphqlCacheHost,
  getGraphqlSoupClient,
  mapGraphqlProperties,
} from '@service-storage/graphql-soup';
import { CombinedError, type OperationResult } from '@urql/core';
import { type Accessor, createMemo } from 'solid-js';
import { match } from 'ts-pattern';
import { v5 as uuidv5 } from 'uuid';
import {
  type buildOptimisticGroupedPropertyUpdates,
  createGroupedPropertyPreparation,
  groupedPropertyKeys,
  type PrepareGroupedPropertyUpdates,
} from '../../soup/grouped/graphql-optimistic';
import { buildOptimisticSetEntityProperty } from '../graphql-optimistic';
import { buildPropertyAssignmentLinks } from './assignment-links';
import { observePropertyMutationSettlements } from './mutation-settlements';

/** Builds the input used to load one entity's properties. */
export function buildEntityPropertiesInput(
  entityType: EntityType,
  entityId: string
): SoupEntityInput | undefined {
  const soupEntityType = match(entityType)
    .returnType<SoupEntityInput['entityType'] | undefined>()
    .with('DOCUMENT', 'TASK', () => 'DOCUMENT')
    .with('PROJECT', () => 'PROJECT')
    .with('CHAT', () => 'CHAT')
    .with('THREAD', () => 'EMAIL_THREAD')
    .with('CHANNEL', () => 'CHANNEL')
    .with('CALL_RECORD', () => 'CALL')
    .with('COMPANY', () => 'CRM_COMPANY')
    .with('CALENDAR_EVENT', () => 'CALENDAR_EVENT')
    .with('INITIATIVE', () => 'INITIATIVE')
    .with('DATABASE_ROW', () => 'DATABASE_ROW')
    // Users and CRM contacts carry no Soup properties.
    .with('USER', 'CONTACT', () => undefined)
    .exhaustive(() => undefined);
  return soupEntityType && { entityType: soupEntityType, entityId };
}

type GraphqlEntityPropertiesQueryOptions = {
  entityType: Accessor<EntityType>;
  entityId: Accessor<string>;
  enabled: Accessor<boolean>;
};

/** Creates the live urql query for one Soup-backed entity's properties. */
export function createGraphqlEntityPropertiesQuery(
  options: GraphqlEntityPropertiesQueryOptions
) {
  const input = createMemo(() => {
    const entityId = options.entityId();
    if (!options.enabled() || entityId.length === 0) return undefined;
    return buildEntityPropertiesInput(options.entityType(), entityId);
  });

  const result = createUrqlQuery<
    EntityPropertiesQuery,
    EntityPropertiesQueryVariables,
    Property[]
  >(() => {
    const currentInput = input();
    const entityId = options.entityId();

    return {
      query: EntityPropertiesDocument,
      client: getGraphqlSoupClient(),
      variables: { input: currentInput! },
      enabled: currentInput !== undefined,
      requestPolicy: 'cache-and-network',
      keepPreviousData: false,
      select: (data) =>
        (mapGraphqlEntityProperties(data, entityId) ?? []).flatMap(
          (property) => {
            try {
              const mapped = soupPropertyToProperty(property);
              return mapped.isMetadata === true
                ? []
                : [
                    options.entityType() === 'INITIATIVE'
                      ? withProjectStatusOptions(mapped)
                      : mapped,
                  ];
            } catch (error) {
              console.warn(
                'Skipping GraphQL property with unsupported type',
                error
              );
              return [];
            }
          }
        ),
    };
  });

  return {
    result,
    isEnabled: () => input() !== undefined,
    refetch: () => result.refetch({ requestPolicy: 'network-only' }),
  };
}

/** Re-read the native property relation, including newly attached values. */
export async function refetchGraphqlInitiativeProperties(
  initiativeId: string
): Promise<void> {
  await getGraphqlSoupClient()
    .query(
      EntityPropertiesDocument,
      { input: buildEntityPropertiesInput('INITIATIVE', initiativeId)! },
      { requestPolicy: 'network-only' }
    )
    .toPromise();
}

export type GraphqlEntityPropertyMutationInput =
  | {
      kind: 'save';
      entityType: EntityType | PropertyTargetEntityType;
      entityId: string;
      property: Property | PropertyDefinitionDomain;
      apiValues: PropertyApiValues;
    }
  | {
      kind: 'add';
      entityType: EntityType | PropertyTargetEntityType;
      entityId: string;
      propertyDefinitionId: string;
    };

export type EntityPropertyMutationDisposition =
  | {
      kind: 'committed';
      property?: SetEntityPropertyMutation['setEntityProperty'];
    }
  | { kind: 'queued'; transactionId: string }
  | { kind: 'permanently-failed'; error: Error };

type SetEntityPropertyArgs = {
  entityType: GraphqlPropertyTargetEntityType;
  entityId: string;
  propertyDefinitionId: string;
  value: SetPropertyValue | null;
  optimisticProperty?: ReturnType<typeof buildOptimisticSetEntityProperty>;
  optimisticCache?: Awaited<
    ReturnType<typeof buildOptimisticGroupedPropertyUpdates>
  >;
};

function toGraphqlEntityReference(
  reference: EntityReference
): GraphqlEntityReferenceInput {
  return {
    entityId: reference.entity_id,
    entityType: reference.entity_type,
    specificMessageId: reference.specific_message_id ?? null,
  };
}

export function toGraphqlSetPropertyValue(
  value: SetPropertyValue | null
): GraphqlSetPropertyValue | null {
  if (value === null) return null;
  return match(value)
    .with({ type: 'boolean' }, (v) => ({ boolean: v.value }))
    .with({ type: 'date' }, (v) => ({ date: v.value }))
    .with({ type: 'date_range' }, (v) => ({ dateRange: v.value }))
    .with({ type: 'number' }, (v) => ({ number: v.value }))
    .with({ type: 'string' }, (v) => ({ string: v.value }))
    .with({ type: 'select_option' }, (v) => ({ selectOption: v.option_id }))
    .with({ type: 'multi_select_option' }, (v) => ({
      multiSelectOption: v.option_ids,
    }))
    .with({ type: 'entity_reference' }, (v) => ({
      entityReference: toGraphqlEntityReference(v.reference),
    }))
    .with({ type: 'multi_entity_reference' }, (v) => ({
      multiEntityReference: v.references.map(toGraphqlEntityReference),
    }))
    .with({ type: 'link' }, (v) => ({ link: v.url }))
    .with({ type: 'multi_link' }, (v) => ({ multiLink: v.urls }))
    .exhaustive(() => {
      throw new Error(`Unsupported property value type: ${value.type}`);
    });
}

/** Maps a REST property target type onto its GraphQL enum. */
export function toGraphqlPropertyTargetEntityType(
  entityType: EntityType | PropertyTargetEntityType
): GraphqlPropertyTargetEntityType {
  if (entityType === 'TASK') return 'DOCUMENT';
  if (entityType === 'CALENDAR_EVENT') {
    throw new Error('calendar events do not support properties');
  }
  if (entityType === 'CONTACT') {
    throw new Error('crm contacts do not support properties');
  }
  return entityType;
}

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

async function prepareMutationArgs(
  input: GraphqlEntityPropertyMutationInput,
  prepareGrouped?: PrepareGroupedPropertyUpdates
): Promise<SetEntityPropertyArgs> {
  if (input.kind === 'add') {
    return {
      entityType: toGraphqlPropertyTargetEntityType(input.entityType),
      entityId: input.entityId,
      propertyDefinitionId: input.propertyDefinitionId,
      value: null,
    };
  }

  const entityType = toGraphqlPropertyTargetEntityType(input.entityType);
  const propertyDefinitionId = getPropertyDefinitionId(input.property);
  const optimisticProperty = buildOptimisticSetEntityProperty(
    input.property,
    input.apiValues,
    { entityType, entityId: input.entityId }
  );
  const optimisticCache: NonNullable<SetEntityPropertyArgs['optimisticCache']> =
    {
      updates: [],
      revalidations: [],
    };
  const host = getGraphqlCacheHost();
  if (host) {
    try {
      if (optimisticProperty) {
        optimisticCache.updates = buildPropertyAssignmentLinks(
          entityType,
          input.entityId,
          optimisticProperty.id,
          propertyDefinitionId
        );
        // Recover a missing/evicted parent after commit (including offline replay)
        // without ever discovering or refetching unrelated cached pages.
        const targetInput = buildEntityPropertiesInput(
          entityType,
          input.entityId
        );
        if (targetInput) {
          optimisticCache.revalidations.push({
            document: EntityPropertiesDocument,
            variables: { input: targetInput },
            onlyOnLinkFailure: true,
          });
        }
      }
      const oldGroupKeys = groupedPropertyKeys(input.property);
      const newGroupKeys = groupedPropertyKeys(input.apiValues);
      const dateChange =
        input.apiValues.valueType === 'DATE'
          ? {
              from:
                'value' in input.property &&
                input.property.value instanceof Date
                  ? input.property.value
                  : null,
              to: input.apiValues.value,
            }
          : undefined;
      const grouped = await (
        prepareGrouped ?? createGroupedPropertyPreparation(host)
      )({
        entityId: input.entityId,
        propertyDefinitionId,
        oldGroupKeys: oldGroupKeys ?? [],
        newGroupKeys: newGroupKeys ?? [],
        ...(dateChange && { dateChange }),
        revalidateOnly:
          oldGroupKeys === undefined || newGroupKeys === undefined,
      });
      // Link the assignment before moving its owning row between groups.
      optimisticCache.updates.push(...grouped.updates);
      optimisticCache.revalidations.push(...grouped.revalidations);
    } catch (error) {
      console.warn('Failed to build property Soup optimism', error);
    }
  }

  return {
    entityType: toGraphqlPropertyTargetEntityType(input.entityType),
    entityId: input.entityId,
    propertyDefinitionId: getPropertyDefinitionId(input.property),
    value: propertyValueToApi(input.apiValues, input.property.isMultiSelect),
    optimisticProperty,
    optimisticCache,
  };
}

function mutationDisposition(
  result: OperationResult<
    SetEntityPropertyMutation,
    SetEntityPropertyMutationVariables
  >
): EntityPropertyMutationDisposition {
  const disposition = optimisticMutationDispositionOf(result);
  if (disposition?.kind === 'queued') return disposition;
  if (disposition?.kind === 'permanently-failed') return disposition;
  if (disposition?.kind === 'committed') {
    return {
      kind: 'committed',
      property: disposition.data.setEntityProperty,
    };
  }
  if (result.error) {
    return { kind: 'permanently-failed', error: result.error };
  }
  if (!result.data) {
    return {
      kind: 'permanently-failed',
      error: new Error('setEntityProperty mutation returned no data'),
    };
  }
  return { kind: 'committed', property: result.data.setEntityProperty };
}

const ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE =
  '1697e6bc-0d9a-4dd2-bc3f-bd33bcb6f607';

/** Stable coalescing UUID for one absolute entity-property value slot. */
export function entityPropertyOptimisticMutationUuid(args: {
  entityType: GraphqlPropertyTargetEntityType;
  entityId: string;
  propertyDefinitionId: string;
}): string {
  return uuidv5(
    JSON.stringify([
      'setEntityProperty',
      args.entityType,
      args.entityId,
      args.propertyDefinitionId,
    ]),
    ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE
  );
}

type EntityPropertyExecution = Parameters<
  UrqlMutationExecutor<
    SetEntityPropertyMutation,
    SetEntityPropertyMutationVariables,
    GraphqlEntityPropertyMutationInput
  >
>[0];

async function executeGraphqlEntityPropertyMutation(
  { client, mutation, input, context }: EntityPropertyExecution,
  onEnqueued?: () => void,
  prepareGrouped?: PrepareGroupedPropertyUpdates
) {
  const args = await prepareMutationArgs(input, prepareGrouped);
  const variables: SetEntityPropertyMutationVariables = {
    input: {
      entityType: args.entityType,
      entityId: args.entityId,
      propertyDefinitionId: args.propertyDefinitionId,
      value: toGraphqlSetPropertyValue(args.value),
    },
  };

  const mutationResult = await (args.optimisticProperty
    ? executeOptimisticMutation(
        client,
        mutation,
        variables,
        { setEntityProperty: args.optimisticProperty },
        {
          ...args.optimisticCache,
          uuid: entityPropertyOptimisticMutationUuid(args),
          onEnqueued,
        }
      ).toPromise()
    : client.mutation(mutation, variables, context).toPromise());
  const disposition = mutationDisposition(mutationResult);
  if (
    disposition.kind === 'queued' &&
    mutationResult.data == null &&
    args.optimisticProperty
  ) {
    return {
      ...mutationResult,
      data: { setEntityProperty: args.optimisticProperty },
      error: undefined,
    };
  }
  if (disposition.kind !== 'permanently-failed' || mutationResult.error) {
    return mutationResult;
  }
  return {
    ...mutationResult,
    error:
      disposition.error instanceof CombinedError
        ? disposition.error
        : new CombinedError({ networkError: disposition.error }),
  };
}

export type AddEntityPropertyInput = {
  entityType: EntityType | PropertyTargetEntityType;
  entityId: string;
  propertyDefinitionId: string;
};

type GraphqlAddMutationOptions<Context> = {
  onMutate?: (input: AddEntityPropertyInput) => Context | Promise<Context>;
  onSuccess?: (
    input: AddEntityPropertyInput,
    context: Context | undefined
  ) => void | Promise<void>;
  onError?: (
    error: Error,
    input: AddEntityPropertyInput,
    context: Context | undefined
  ) => void | Promise<void>;
  onSettled?: (
    error: Error | null,
    input: AddEntityPropertyInput,
    context: Context | undefined
  ) => void | Promise<void>;
};

/** Creates the callback-driven urql mutation for property attachments. */
export function createGraphqlAddEntityPropertyMutation<Context = void>(
  options: GraphqlAddMutationOptions<Context> = {}
) {
  return createUrqlMutation<
    SetEntityPropertyMutation,
    SetEntityPropertyMutationVariables,
    AddEntityPropertyInput,
    Context
  >(() => ({
    mutation: SetEntityPropertyDocument,
    client: getGraphqlSoupClient(),
    execute: ({ client, mutation, input, context }) =>
      executeGraphqlEntityPropertyMutation({
        client,
        mutation,
        input: { kind: 'add', ...input },
        context,
      }),
    onMutate: options.onMutate,
    onSuccess: (_data, input, context) => options.onSuccess?.(input, context),
    onError: (error, input, context) =>
      options.onError?.(error, input, context),
    onSettled: (_data, error, input, context) =>
      options.onSettled?.(error, input, context),
  }));
}

export type BulkSaveEntityPropertiesInput = {
  properties: Array<{
    entityType: EntityType | PropertyTargetEntityType;
    entityId: string;
    property: Property | PropertyDefinitionDomain;
    apiValues: PropertyApiValues;
  }>;
};

type GraphqlBulkMutationOptions<Context> = {
  onMutate?: (
    input: BulkSaveEntityPropertiesInput
  ) => Context | Promise<Context>;
  onCommitted?: (
    item: BulkSaveEntityPropertiesInput['properties'][number],
    disposition: Extract<
      EntityPropertyMutationDisposition,
      { kind: 'committed' }
    >
  ) => void | Promise<void>;
  onSuccess?: (
    input: BulkSaveEntityPropertiesInput,
    context: Context | undefined
  ) => void | Promise<void>;
  onError?: (
    error: Error,
    input: BulkSaveEntityPropertiesInput,
    context: Context | undefined
  ) => void | Promise<void>;
  onSettled?: (
    error: Error | null,
    input: BulkSaveEntityPropertiesInput,
    context: Context | undefined
  ) => void | Promise<void>;
};

/**
 * Enqueues every optimistic layer before waiting for HTTP, but keeps the bulk
 * lifecycle pending until queued saves commit or permanently fail. Replayed
 * saves retain their submission payload; settlement events carry no response.
 */
export function createGraphqlBulkSaveEntityPropertiesMutation<Context = void>(
  options: GraphqlBulkMutationOptions<Context> = {}
) {
  return createUrqlMutation<
    SetEntityPropertyMutation,
    SetEntityPropertyMutationVariables,
    BulkSaveEntityPropertiesInput,
    Context
  >(() => ({
    mutation: SetEntityPropertyDocument,
    client: getGraphqlSoupClient(),
    execute: async ({ client, mutation, input, context }) => {
      let latestResult:
        | OperationResult<
            SetEntityPropertyMutation,
            SetEntityPropertyMutationVariables
          >
        | undefined;
      let permanentError: Error | undefined;

      const pending = [];
      const host = getGraphqlCacheHost();
      const prepareGrouped = host
        ? createGroupedPropertyPreparation(host)
        : undefined;
      const settlements = observePropertyMutationSettlements(host);
      try {
        for (const item of input.properties) {
          let acknowledge!: () => void;
          const enqueued = new Promise<void>((resolve) => {
            acknowledge = resolve;
          });
          async function submitSave() {
            try {
              const result = await executeGraphqlEntityPropertyMutation(
                {
                  client,
                  mutation,
                  input: { kind: 'save', ...item },
                  context,
                },
                acknowledge,
                prepareGrouped
              );
              acknowledge();
              const disposition = mutationDisposition(result);
              if (disposition.kind === 'queued') {
                await settlements.waitForCommit(disposition.transactionId);
                await options.onCommitted?.(item, { kind: 'committed' });
              } else if (disposition.kind === 'committed') {
                await options.onCommitted?.(item, disposition);
              }
              return { kind: 'result' as const, result };
            } catch (error) {
              return {
                kind: 'error' as const,
                error:
                  error instanceof Error ? error : new Error(String(error)),
              };
            } finally {
              // Plain clients and failed preparation have no cache acknowledgement.
              acknowledge();
            }
          }
          pending.push(submitSave());
          // Preserve layer ordering for relation recipes, not HTTP completion.
          await enqueued;
        }
        for (const settled of await Promise.all(pending)) {
          if (settled.kind === 'error') {
            permanentError ??= settled.error;
            continue;
          }
          latestResult = settled.result;
          const disposition = mutationDisposition(latestResult);
          if (disposition.kind === 'permanently-failed') {
            permanentError ??= disposition.error;
          }
        }
      } finally {
        settlements.dispose();
      }

      if (!latestResult && permanentError) throw permanentError;
      if (!latestResult) {
        throw new Error(
          'bulk property mutation requires at least one property'
        );
      }
      if (!permanentError) return latestResult;

      return {
        ...latestResult,
        error:
          permanentError instanceof CombinedError
            ? permanentError
            : new CombinedError({ networkError: permanentError }),
      };
    },
    onMutate: options.onMutate,
    onSuccess: (_data, input, context) => options.onSuccess?.(input, context),
    onError: (error, input, context) =>
      options.onError?.(error, input, context),
    onSettled: (_data, error, input, context) =>
      options.onSettled?.(error, input, context),
  }));
}

/** Maps one entity's GraphQL query result to the shared Soup property shape. */
export function mapGraphqlEntityProperties(
  data: EntityPropertiesQuery | undefined,
  entityId: string
): SoupProperty[] | undefined {
  const entity = data?.user?.soupEntity;
  if (entity === undefined) return undefined;
  return mapGraphqlProperties(entity?.id === entityId ? entity.properties : []);
}