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.

8.6 KB
Raw Blame
import { match, P } from 'ts-pattern';
import type {
  WebhookFilter,
  WebhookScope,
} from '../../generated/storage/types.gen';
import { MacroError } from '../utils';
import type { MacroClient } from '../utils/client';
import { hydrateAgentSessionEvent } from './hydrate/agentSession';
import { hydrateCallEvent } from './hydrate/call';
import { hydrateChannelEvent } from './hydrate/channel';
import { hydrateDocumentEvent } from './hydrate/document';
import { hydrateMessageEvent } from './hydrate/message';
import type {
  DeliveryHeaders,
  EventHandler,
  EventMap,
  EventName,
  MacroEvent,
} from './types';
import { verifySignature } from './verify';

type AnyHandler = (event: unknown) => void | Promise<void>;

/** Sent by Macro when validating a newly registered endpoint; acked, never dispatched. */
const VALIDATION_EVENT = 'webhook.validation.test';

/** Options for {@link MacroEvents.listen}. */
export interface ListenOptions {
  /**
   * Event/entity-id filters, identical to persisted webhook `filters`.
   * Defaults to one filter covering every event currently registered with
   * {@link MacroEvents.on}.
   */
  filters?: WebhookFilter[];
  /**
   * Personal or team workspace whose webhook lifecycle events are delivered.
   * Defaults to `'user'`.
   */
  scope?: WebhookScope;
  /** Abort the stream. */
  signal?: AbortSignal;
}

/** Attach the entity handles defined for each webhook event. */
function hydrate(
  client: MacroClient,
  event: MacroEvent,
): EventMap[EventName] | undefined {
  return match(event)
    .with({ event_type: P.string.startsWith('document.') }, (documentEvent) =>
      hydrateDocumentEvent(client, documentEvent),
    )
    .with({ event_type: P.string.startsWith('call.') }, (callEvent) =>
      hydrateCallEvent(client, callEvent),
    )
    .with({ event_type: P.string.startsWith('channel.') }, (channelEvent) =>
      hydrateChannelEvent(client, channelEvent),
    )
    .with({ event_type: P.string.startsWith('message.') }, (messageEvent) =>
      hydrateMessageEvent(client, messageEvent),
    )
    .with(
      { event_type: P.string.startsWith('agent_session.') },
      (agentSessionEvent) =>
        hydrateAgentSessionEvent(client, agentSessionEvent),
    )
    .otherwise(() => undefined);
}

/**
 * Per-instance event receiver. Subscribe with {@link MacroEvents.on}, then
 * either {@link MacroEvents.listen} (SSE, the default) or mount
 * {@link MacroEvents.webhook} at a persisted webhook URL.
 *
 * Obtain via `macro.events` — do not construct directly.
 */
export class MacroEvents {
  private readonly handlers = new Map<EventName, Set<AnyHandler>>();

  constructor(
    private readonly client: MacroClient,
    private readonly secret?: string,
  ) {}

  /**
   * Subscribe to an event across all entities.
   *
   * @returns An unsubscribe function.
   */
  on<E extends EventName>(event: E, handler: EventHandler<E>): () => void {
    const set = this.handlers.get(event) ?? new Set<AnyHandler>();
    set.add(handler as AnyHandler);
    this.handlers.set(event, set);
    return () => set.delete(handler as AnyHandler);
  }

  /**
   * Subscribe to @-mentions of the authenticated caller: `message.mentioned`
   * deliveries whose mentioned entity is this bot (bot auth) or this user
   * (user auth), in channels and in document comments alike.
   *
   * `message.mentioned` deliveries cover every mention the stream's (or
   * webhook's) workspace can access (its `ids` filter holds channel or
   * document ids); picking out "me" happens here, client-side. The caller's
   * identity is resolved lazily (once) on the first delivery.
   *
   * For SSE, register this handler before {@link listen} so the derived
   * filters include `message.mentioned`. For persisted webhooks, register the
   * webhook separately, e.g. `macro.webhooks.create({ filters: [{ events:
   * ['message.mentioned'] }], … })`.
   *
   * @returns An unsubscribe function.
   */
  onSelfMention(handler: EventHandler<'message.mentioned'>): () => void {
    return this.on('message.mentioned', async (event) => {
      // Principals embed emails for users; emails are case-insensitive.
      const mentioned = event.metadata.mentioned.entity_id.toLowerCase();
      if (mentioned !== (await this.client.myPrincipalId()).toLowerCase()) {
        return;
      }
      await handler(event);
    });
  }

  /**
   * Open a live Server-Sent Events stream of matching broker events. This is
   * the default way to receive events — no public URL or signing secret
   * required. Delivery is best-effort: events published before the
   * connection, while disconnected, or dropped for a slow subscriber are
   * missed; there is no replay.
   *
   * Filters default to the event names currently registered with {@link on}.
   * The stream uses those filters for its lifetime; later `.on` / unsubscribe
   * calls do not change what the server sends.
   *
   * @returns A function that closes the stream.
   */
  async listen(opts: ListenOptions = {}): Promise<() => void> {
    const filters = opts.filters ?? this.filtersFromHandlers();
    if (
      filters.length === 0 ||
      filters.every((filter) => filter.events.length === 0)
    ) {
      throw new MacroError(
        'listen() needs filters — pass filters or register handlers with .on() first',
      );
    }

    const controller = new AbortController();
    if (opts.signal) {
      if (opts.signal.aborted) {
        controller.abort();
      } else {
        opts.signal.addEventListener('abort', () => controller.abort(), {
          once: true,
        });
      }
    }

    const { stream } = await this.client.storage.streamEvents({
      query: {
        scope: opts.scope ?? 'user',
        filters: JSON.stringify(filters),
      },
      signal: controller.signal,
    });

    const consume = (async () => {
      try {
        for await (const data of stream) {
          await this.dispatchEvent(data);
        }
      } catch {
        if (controller.signal.aborted) return;
        throw new MacroError('event stream failed');
      }
    })();
    consume.catch(() => {
      // Connection errors are retried by the generated SSE client. A terminal
      // failure after listen() has returned must not become an unhandled
      // rejection; the caller already has `stop`.
    });

    return () => {
      controller.abort();
    };
  }

  /**
   * Feed a raw webhook delivery in: verifies the signature, parses, and
   * dispatches to matching handlers.
   *
   * @throws {MacroError} if no signing secret was configured, or if the
   *   signature is missing or invalid.
   */
  async handle(rawBody: string, headers: DeliveryHeaders): Promise<void> {
    if (!this.secret) {
      throw new MacroError(
        'webhookSecret is required to verify incoming webhook deliveries',
      );
    }
    const ok = await verifySignature({
      secret: this.secret,
      timestamp: headers.timestamp ?? '',
      rawBody,
      signature: headers.signature ?? '',
    });
    if (!ok) throw new MacroError('invalid webhook signature');

    if (headers.event === VALIDATION_EVENT) return;

    await this.dispatchEvent(JSON.parse(rawBody));
  }

  /**
   * A Fetch-style handler to mount at your persisted webhook route.
   *
   * Requires `webhookSecret` (or `MACRO_WEBHOOK_SECRET`).
   *
   * @example
   * app.post('/webhook', macro.events.webhook()); // Hono
   */
  webhook(): (req: Request) => Promise<Response> {
    if (!this.secret) {
      throw new MacroError(
        'webhookSecret is required to verify incoming webhook deliveries',
      );
    }
    return async (req: Request) => {
      await this.handle(await req.text(), {
        event: req.headers.get('x-macro-event') ?? undefined,
        eventId: req.headers.get('x-macro-event-id') ?? undefined,
        timestamp: req.headers.get('x-macro-timestamp') ?? undefined,
        signature: req.headers.get('x-macro-signature') ?? undefined,
      });
      return new Response('ok');
    };
  }

  private filtersFromHandlers(): WebhookFilter[] {
    const events = [...this.handlers.entries()]
      .filter(([, set]) => set.size > 0)
      .map(([name]) => name);
    return events.length > 0 ? [{ events }] : [];
  }

  private async dispatchEvent(data: unknown): Promise<void> {
    const event =
      typeof data === 'string' ? (JSON.parse(data) as unknown) : data;
    if (
      event === null ||
      typeof event !== 'object' ||
      !('event_type' in event)
    ) {
      return;
    }
    const typed = event as MacroEvent;
    const handlers = this.handlers.get(typed.event_type);
    if (!handlers || handlers.size === 0) return;

    const payload = hydrate(this.client, typed);
    if (!payload) return;
    await Promise.all([...handlers].map((handler) => handler(payload)));
  }
}