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.

13.7 KB
Raw Blame
import type {
  EmailRecipient,
  SendEmail,
  SendEmailResponse,
} from '../../../generated/agent-reviews';
import type {
  ApiDraftContactInfo,
  GetMessageResponses,
  MessageOperationResponse,
  ResolveMessageOperationRequest,
  TransferDraftRequest,
  TransferDraftResponse,
} from '../../../generated/email/types.gen';
import { unwrap } from '../../utils';
import type { MacroClient } from '../../utils/client';
import type { Document } from '../documents/document';
import { MacroEntity } from '../entity';
import { EmailAttachment } from './attachment';
import type { Label } from './label';
import { Link } from './link';
import { EmailThread } from './thread';

/** The API's representation of an email message (`ParsedMessage`). */
export type EmailMessageData = GetMessageResponses[200];

/** Options for sending a fresh email message. */
export interface SendEmailOptions {
  /** Recipients. */
  to: ApiDraftContactInfo[];
  /** Cc recipients. */
  cc?: ApiDraftContactInfo[];
  /** Bcc recipients. */
  bcc?: ApiDraftContactInfo[];
  /** Subject line. */
  subject: string;
  /** Plain-text body. */
  bodyText: string;
}

// The HTTP schema is opaque: the server serializes the Rust tool response,
// whose TypeScript contract is generated from the same Rust type.
function sendEmailResponse(response: unknown): SendEmailResponse {
  return response as SendEmailResponse;
}

/** An email the user has approved in conversation, for `email.sendConfirmed`. */
export interface ConfirmedEmailOptions {
  /** Recipients. */
  to: EmailRecipient[];
  /** Cc recipients. */
  cc?: EmailRecipient[];
  /** Bcc recipients. */
  bcc?: EmailRecipient[];
  /** Subject line. */
  subject: string;
  /** The body, written as Markdown; it is rendered to HTML on send. */
  body: string;
  /**
   * The connected inbox to send from. Omit it unless you know which inbox is
   * right: a reply then goes out from the inbox that received the message it
   * answers, and a new email from the user's primary inbox.
   */
  from?: Link;
  /** The message this answers; the email is then sent as a reply in its thread. */
  replyingTo?: EmailMessage;
  /**
   * Macro documents to attach as files: uploaded files (PDFs, images,
   * spreadsheets, Word documents) the user can view, 18 MB together. An
   * editor-native document has no file; link to it in the body instead.
   */
  attachments?: Document[];
  /** `false` leaves the inbox signature off this one email; omit for the inbox's default. */
  includeSignature?: boolean;
  /**
   * The user's own reply approving this specific email, quoted verbatim, such
   * as their "yes, send it" after you wrote the email out for them. Never the
   * request that asked you to write it, and never your own words.
   */
  userConfirmation: string;
}

/** A forward the user has approved, for `EmailMessage.forwardDraft` and `forwardConfirmed`. */
export interface ForwardEmailOptions {
  /** Recipients. */
  to: EmailRecipient[];
  /** Cc recipients. */
  cc?: EmailRecipient[];
  /** Bcc recipients. */
  bcc?: EmailRecipient[];
  /** A note above the forwarded message, written as Markdown. */
  body?: string;
  /** The connected inbox to send from; defaults to the inbox holding the message. */
  from?: Link;
  /** `false` leaves the inbox signature off this one email; omit for the inbox's default. */
  includeSignature?: boolean;
}

/** The first line of a forwarded message, as the web composer writes it. */
const FORWARDED_MESSAGE_HEADER = '---------- Forwarded message ----------';

/** Escape text so Markdown renders it literally. */
function literalMarkdown(text: string): string {
  return text.replace(/[\\`*_{}[\]<>()#+\-.!|~]/g, '\\$&');
}

/** A sent email: the message and the thread it belongs to. */
export interface SentEmail {
  /** The sent message. */
  message: EmailMessage;
  /** The thread the message belongs to. */
  thread: EmailThread;
}

/**
 * A message in an email thread. A thin handle keyed by message id; the
 * record loads lazily on first field access.
 */
export class EmailMessage extends MacroEntity<EmailMessageData> {
  protected async fetch(): Promise<EmailMessageData> {
    return unwrap(
      await this.client.email.getMessage({ path: { id: this.id } }),
    );
  }

  /** A handle to a message by id. Fields load on first access. */
  static byId(client: MacroClient, id: string): EmailMessage {
    return new EmailMessage(client, id);
  }

  /** Build a message from an already-fetched record (pre-seeded, no fetch). */
  static from(client: MacroClient, data: EmailMessageData): EmailMessage {
    return new EmailMessage(client, data.db_id, data);
  }

  /**
   * Send a new plain-text email; an agent's program is refused (403) and
   * sends through a review or {@link EmailMessage.sendConfirmed} instead.
   * Returns a handle when the API reports the created message's id.
   */
  static async send(
    client: MacroClient,
    opts: SendEmailOptions,
  ): Promise<EmailMessage | undefined> {
    const { message } = unwrap(
      await client.email.sendMessage({
        body: {
          message: {
            to: opts.to,
            cc: opts.cc ?? null,
            bcc: opts.bcc ?? null,
            subject: opts.subject,
            body_text: opts.bodyText,
          },
        },
      }),
    );
    return message.db_id ? EmailMessage.byId(client, message.db_id) : undefined;
  }

  /** Send an email the user approved in conversation, quoting their approval; see `EmailNamespace.sendConfirmed`. */
  static async sendConfirmed(
    client: MacroClient,
    opts: ConfirmedEmailOptions,
  ): Promise<SentEmail> {
    const email: SendEmail = {
      subject: opts.subject,
      body: opts.body,
      to: opts.to,
      cc: opts.cc,
      bcc: opts.bcc,
      from: opts.from ? await opts.from.emailAddress() : undefined,
      replyingToId: opts.replyingTo?.id,
      includeSignature: opts.includeSignature,
      attachments: opts.attachments?.map((document) => ({
        documentId: document.id,
      })),
    };
    return EmailMessage.sendReviewedDraft(client, email, opts.userConfirmation);
  }

  /** @internal Run the SendConfirmedEmail tool with a SendEmail draft and its approval. */
  private static async sendReviewedDraft(
    client: MacroClient,
    email: SendEmail,
    userConfirmation: string,
  ): Promise<SentEmail> {
    const response = sendEmailResponse(
      unwrap(
        await client.cognition.sendConfirmedEmail({
          body: { ...email, userConfirmation },
        }),
      ),
    );
    if (typeof response === 'string' || !response.sent)
      throw new Error('The confirmed send did not report a sent message');
    return {
      message: EmailMessage.byId(client, response.sent.message_id),
      thread: EmailThread.byId(client, response.sent.thread_id),
    };
  }

  /** The files attached to this message, from its thread's first 100 messages. */
  async attachments(): Promise<EmailAttachment[]> {
    const { thread_db_id } = await this.detail.get();
    const { thread } = unwrap(
      await this.client.email.getThread({
        path: { thread_id: thread_db_id },
        query: { limit: 100 },
      }),
    );
    const message = thread.messages.find((m) => m.db_id === this.id);
    if (!message)
      throw new Error(
        `Message ${this.id} is not among its thread's first 100 messages`,
      );
    return message.attachments.map((a) => EmailAttachment.from(this.client, a));
  }

  /**
   * This message as a forward: a SendEmail draft with the note, the quoted
   * message under the forwarded-message header, and its attachments as
   * Macro documents. Pass it to `execution.reviews.create({kind: 'email'})`
   * in a session; in a thread, use {@link forwardConfirmed}.
   */
  async forwardDraft(opts: ForwardEmailOptions): Promise<SendEmail> {
    const [message, attachments] = await Promise.all([
      this.detail.get(),
      this.attachments(),
    ]);
    const documents = await Promise.all(
      attachments.map((attachment) => attachment.toDocument()),
    );
    const inbox = opts.from ?? Link.byId(this.client, message.link_id);
    const subject = message.subject ?? '';
    const people = (contacts: EmailMessageData['to']) =>
      contacts
        .map((contact) => `${contact.name ?? contact.email} <${contact.email}>`)
        .join(', ');
    const header = [
      FORWARDED_MESSAGE_HEADER,
      `From: ${message.from ? people([message.from]) : ''}`,
      `Date: ${message.internal_date_ts ? new Date(message.internal_date_ts).toUTCString() : ''}`,
      `Subject: ${subject}`,
      ...(message.to.length > 0 ? [`To: ${people(message.to)}`] : []),
      ...(message.cc.length > 0 ? [`Cc: ${people(message.cc)}`] : []),
    ];
    const quoted = (message.body_parsed ?? '')
      .split('\n')
      .filter((line) => line.trim() !== '')
      .map((line) => `> ${literalMarkdown(line)}`)
      .join('\n>\n');
    return {
      subject: /^fwd?:/i.test(subject) ? subject : `Fwd: ${subject}`,
      body: [
        ...(opts.body ? [opts.body] : []),
        header.map(literalMarkdown).join('\n\n'),
        quoted,
      ]
        .filter((part) => part !== '')
        .join('\n\n'),
      to: opts.to,
      cc: opts.cc,
      bcc: opts.bcc,
      from: await inbox.emailAddress(),
      includeSignature: opts.includeSignature,
      attachments: documents.map((document) => ({ documentId: document.id })),
    };
  }

  /**
   * Forward this message, with its attachments, only after the user replied approving the forward, quoting that reply in `userConfirmation`.
   *
   * For a prompt from a channel or document thread: write the forward out
   * (recipients and note), ask whether to send it, and call this in a later
   * turn on the user's approving reply. In the agent session view, present
   * `forwardDraft` as a review instead. The forward is a new email that
   * quotes this message and carries its attachments; it takes effect at once
   * and is never retried.
   */
  async forwardConfirmed(
    opts: ForwardEmailOptions & { userConfirmation: string },
  ): Promise<SentEmail> {
    return EmailMessage.sendReviewedDraft(
      this.client,
      await this.forwardDraft(opts),
      opts.userConfirmation,
    );
  }

  /** The message's subject line. */
  readonly subject = this.field('subject');

  /** The sender. */
  readonly from = this.field('from');

  /** The To recipients. */
  readonly to = this.field('to');

  /** The Cc recipients. */
  readonly cc = this.field('cc');

  /** The Bcc recipients. */
  readonly bcc = this.field('bcc');

  /** The parsed message body, as the API returns it. */
  readonly body = this.field('body_parsed');

  /** The provider-internal date of the message. */
  readonly sentAt = this.field('internal_date_ts');

  /** Labels on this message. */
  readonly labels = this.field('labels');

  /** The inbox (email link) this message belongs to. */
  readonly link = this.mappedField('link_id', (id) =>
    Link.byId(this.client, id),
  );

  /** Read the draft's durable send, upload, or conflict status without retrying it. */
  async operationStatus(): Promise<MessageOperationResponse> {
    return unwrap(
      await this.client.email.messageOperationStatus({ path: { id: this.id } }),
    );
  }

  /** Resolve the displayed operation revision after the user chooses an action.
   * Retrying an uncertain send requires explicit duplicate-risk acceptance. */
  async resolveOperation(
    request: ResolveMessageOperationRequest,
  ): Promise<void> {
    await this.mutate((c) =>
      c.email.resolveMessageOperation({ path: { id: this.id }, body: request }),
    );
  }

  /** Verify an uploaded attachment using the draft generation captured when its upload began. */
  async completeDraftAttachment(
    attachmentId: string,
    draftGeneration = 0,
  ): Promise<void> {
    const link = await this.link();
    await this.mutate((c) =>
      c.email.completeDraftAttachment({
        path: { id: this.id, attachment_id: attachmentId },
        query: { draft_generation: draftGeneration },
        headers: { 'X-Email-Link-Id': link.id },
      }),
    );
  }

  /** Move a draft to another inbox using a caller-persisted operation UUID.
   * Continue editing the returned message_id; the original identity is retired.
   * On an interrupted response, use email.recoverDraftTransfer(operation_id). */
  async transferDraft(
    request: TransferDraftRequest,
  ): Promise<TransferDraftResponse> {
    const draft = await this.detail.get();
    return this.mutate((c) =>
      c.email.transferDraft({
        path: { id: this.id },
        body: {
          ...request,
          draft_generation:
            request.draft_generation ?? draft.draft_generation ?? 0,
        },
        headers: { 'X-Email-Link-Id': draft.link_id },
      }),
    );
  }

  /** Add a label to this message. */
  async addLabel(label: Label): Promise<void> {
    await this.mutate((c) =>
      c.email.addRemoveLabel({
        body: {
          label_id: label.id,
          message_ids: [this.id],
          value: true,
        },
      }),
    );
  }

  /** Remove a label from this message. */
  async removeLabel(label: Label): Promise<void> {
    await this.mutate((c) =>
      c.email.addRemoveLabel({
        body: {
          label_id: label.id,
          message_ids: [this.id],
          value: false,
        },
      }),
    );
  }

  /** The thread this message belongs to. */
  async thread(): Promise<EmailThread> {
    return EmailThread.byId(
      this.client,
      (await this.detail.get()).thread_db_id,
    );
  }

  /**
   * The message's original source, exactly as Gmail or Outlook holds it, as
   * `message/rfc822` bytes for an `.eml` file. Drafts and messages still on
   * their way have no source yet and fail with a 404.
   */
  async downloadEml(): Promise<Blob> {
    return unwrap(
      await this.client.email.getMessageEml({
        path: { id: this.id },
        parseAs: 'blob',
      }),
    );
  }
}