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.

7.7 KB
Raw Blame
import type {
  BulkUpdateEntityPropertyOptionsResponse,
  EntityPropertyWithDefinition,
  PropertyTargetEntityType as PropertyEntityType,
  PropertyTargetReference,
  SetPropertyValue,
} from '../../generated/properties/types.gen';
import type { FavoriteEntityRef } from '../../generated/storage/types.gen';
import { Lazy, unwrap } from '../utils';
import type { MacroClient } from '../utils/client';
import type { PropertyDefinition } from './properties/property-definition';
import type { PropertyOption } from './properties/property-option';

/** How the entity-addressed APIs (favorites) identify an entity's type. */
export type MacroEntityType = FavoriteEntityRef['entityType'];

/** An entity that can be added to and removed from the user's favorites. */
export interface Favoritable {
  favorite(): Promise<this>;
  unfavorite(): Promise<this>;
}

/** A favoritable entity that also carries user-defined properties. */
export interface Propertied extends Favoritable {
  properties(opts?: {
    includeMetadata?: boolean;
  }): Promise<EntityPropertyWithDefinition[]>;
  setProperty(
    property: PropertyDefinition,
    value?: SetPropertyValue,
  ): Promise<void>;
  deleteProperty(assignment: EntityPropertyWithDefinition): Promise<void>;
}

/** A delta to apply to one multi-select property. */
export interface PropertyOptionDelta {
  /** The multi-select property definition to update. */
  property: PropertyDefinition;
  /** Options to add to the property's current selection. */
  add?: PropertyOption[];
  /** Options to remove from the property's current selection. */
  remove?: PropertyOption[];
}

/** `null` folded into `undefined`, so optional API fields read naturally. */
type Normalized<V> = null extends V
  ? NonNullable<V> | undefined
  : undefined extends V
    ? NonNullable<V> | undefined
    : V;

/**
 * Base for entity handles: a free-to-construct `(client, id)` pair whose
 * detail record loads lazily on first field access and is dropped after any
 * mutation. Subclasses implement {@link fetch} and build their surface from
 * {@link field} and {@link mutate}.
 */
export abstract class MacroEntity<Detail> {
  protected readonly detail: Lazy<Detail>;

  protected constructor(
    protected readonly client: MacroClient,
    public readonly id: string,
    seed?: Detail,
  ) {
    this.detail = new Lazy(() => this.fetch(), seed);
  }

  /** Load the detail record backing {@link field} accessors. */
  protected abstract fetch(): Promise<Detail>;

  /** A lazy accessor for one detail field, `null` normalized to `undefined`. */
  protected field<K extends keyof Detail>(
    key: K,
  ): () => Promise<Normalized<Detail[K]>> {
    return async () =>
      ((await this.detail.get())[key] ?? undefined) as Normalized<Detail[K]>;
  }

  /**
   * Like {@link field}, but maps the raw value through `map` before returning.
   * Used to expose an id field as a handle to the entity it references, e.g.
   * `this.mappedField('owner', (id) => User.byId(this.client, id))`.
   */
  protected mappedField<K extends keyof Detail, T>(
    key: K,
    map: (value: Normalized<Detail[K]>) => T,
  ): () => Promise<T> {
    return async () =>
      map(
        ((await this.detail.get())[key] ?? undefined) as Normalized<Detail[K]>,
      );
  }

  toJSON(): { id: string; detail?: Detail } {
    const detail = this.detail.peek();
    return detail === undefined ? { id: this.id } : { id: this.id, detail };
  }

  /** Run a write, unwrap it, and drop the cached detail so reads refetch. */
  protected async mutate<TData>(
    fn: (client: MacroClient) => Promise<{
      data?: TData;
      error?: unknown;
      response?: Response;
    }>,
  ): Promise<TData> {
    const out = unwrap(await fn(this.client));
    this.detail.clear();
    return out;
  }
}

/** An entity the favorites API can address, and so can be (un)favorited. */
export abstract class FavoritableEntity<Detail>
  extends MacroEntity<Detail>
  implements Favoritable
{
  /** How the entity-addressed APIs (favorites) identify this entity's type. */
  abstract readonly entityType: MacroEntityType;

  /** Read the caller's effective permission on this entity. */
  async permission() {
    return unwrap(
      await this.client.storage.getEntityPermission({
        path: { entity_type: this.entityType, entity_id: this.id },
      }),
    );
  }

  /**
   * Add this entity to the user's favorites. Returns this handle for chaining.
   * Plain unwrap: favoriting alters the user's favorites collection, not this
   * entity's own detail, so there's nothing cached to invalidate.
   */
  async favorite(): Promise<this> {
    unwrap(
      await this.client.storage.addFavorite({
        body: { entityId: this.id, entityType: this.entityType },
      }),
    );
    return this;
  }

  /** Remove this entity from the user's favorites. Returns this handle for chaining. */
  async unfavorite(): Promise<this> {
    unwrap(
      await this.client.storage.removeFavoriteByEntity({
        path: {
          entity_type: this.entityType,
          entity_id: this.id,
        },
      }),
    );
    return this;
  }
}

/** A favoritable entity that also carries user-defined properties. */
export abstract class PropertiedEntity<Detail>
  extends FavoritableEntity<Detail>
  implements Propertied
{
  /**
   * This entity's type in the properties service, which names types
   * differently from {@link entityType} (e.g. `THREAD` for `email_thread`).
   */
  protected abstract readonly propertyEntityType: PropertyEntityType;

  /** This entity's reference for bulk property operations. */
  propertyReference(): PropertyTargetReference {
    return { entity_type: this.propertyEntityType, entity_id: this.id };
  }

  /** The properties set on this entity, each with its definition, value, and options. */
  async properties(opts?: {
    includeMetadata?: boolean;
  }): Promise<EntityPropertyWithDefinition[]> {
    const { properties } = unwrap(
      await this.client.properties.getEntityProperties({
        path: {
          entity_type: this.propertyEntityType,
          entity_id: this.id,
        },
        query:
          opts?.includeMetadata !== undefined
            ? { include_metadata: opts.includeMetadata }
            : undefined,
      }),
    );
    return properties;
  }

  /**
   * Set a property value on this entity, or attach the property without a
   * value when `value` is omitted.
   */
  async setProperty(
    property: PropertyDefinition,
    value?: SetPropertyValue,
  ): Promise<void> {
    unwrap(
      await this.client.properties.setEntityProperty({
        path: {
          ...this.propertyReference(),
          property_id: property.id,
        },
        body: { value: value ?? null },
      }),
    );
  }

  /** Apply multi-select option deltas atomically across this entity's properties. */
  async updatePropertyOptions(
    changes: PropertyOptionDelta[],
  ): Promise<BulkUpdateEntityPropertyOptionsResponse> {
    return unwrap(
      await this.client.properties.bulkUpdateEntityPropertyOptions({
        path: this.propertyReference(),
        body: {
          properties: changes.map((change) => ({
            property_id: change.property.id,
            ...(change.add
              ? { add_option_ids: change.add.map((option) => option.id) }
              : {}),
            ...(change.remove
              ? { remove_option_ids: change.remove.map((option) => option.id) }
              : {}),
          })),
        },
      }),
    );
  }

  /** Remove a property from this entity, given its {@link properties} entry. */
  async deleteProperty(
    assignment: EntityPropertyWithDefinition,
  ): Promise<void> {
    unwrap(
      await this.client.properties.deleteEntityProperty({
        path: { entity_property_id: assignment.property.id },
      }),
    );
  }
}