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.

3.3 KB
Raw Blame
import type { SimpleMention } from '../generated/storage/types.gen';

export type { SimpleMention };

/** The two things a mentionable entity contributes to a message. */
export interface MentionPart {
  /** The `<m-*>` tag written into the message content. */
  tag: string;
  /** The parallel entry the backend uses for notifications and permissions. */
  mention: SimpleMention;
}

/** Anything that can be dropped into a {@link msg} template as a mention. */
export interface Mentionable {
  toMention(): MentionPart;
}

/** What may be interpolated into a {@link msg} template: a mention, or plain text. */
export type Interpolation = Mentionable | string | number;

/** A composed message body: content with embedded tags, and the matching mentions. */
export interface RichMessage {
  content: string;
  mentions: SimpleMention[];
}

const TAG_JSON_ESCAPES: Record<string, string> = {
  '<': '\\u003c',
  '>': '\\u003e',
  '&': '\\u0026',
};

/**
 * Serialize a mention node to its `<tag>{json}</tag>` wire form. Readers take
 * everything up to the first closing tag, so `<`, `>` and `&` in the JSON are
 * written as `\u` escapes: a document named `</m-document-mention>` would
 * otherwise end the tag early. Decoding the JSON restores the original text.
 */
export function wrapXml(tag: string, data: unknown): string {
  const json = JSON.stringify(data).replace(
    /[<>&]/g,
    (char) => TAG_JSON_ESCAPES[char] ?? char,
  );
  return `<${tag}>${json}</${tag}>`;
}

function isMentionable(value: Interpolation): value is Mentionable {
  return (
    typeof value === 'object' &&
    value !== null &&
    typeof value.toMention === 'function'
  );
}

/** The `@here` group mention. */
export const here: Mentionable = {
  toMention: () => ({
    tag: wrapXml('m-group-mention', { groupAlias: 'here' }),
    mention: { entity_type: 'group', entity_id: 'here' },
  }),
};

/**
 * Compose a rich message. Interpolate mentions (a {@link User}, {@link Document},
 * {@link here}, …) or plain strings. Each mention writes its `<m-*>` tag into the
 * content *and* adds itself to `mentions[]`, so the two can never drift; strings
 * are inserted as-is, so markdown like `**bold**` passes through untouched.
 *
 * @example
 * channel.send(msg`Hey ${user}, see ${doc}. cc ${here}`);
 * channel.send(msg`Status: ${status} — see ${doc}`);
 */
export function msg(
  strings: TemplateStringsArray,
  ...values: Interpolation[]
): RichMessage {
  let content = '';
  const mentions: SimpleMention[] = [];

  for (const [i, string] of strings.entries()) {
    content += string;

    const value = values[i];
    if (value === undefined) continue;
    if (isMentionable(value)) {
      const part = value.toMention();
      content += part.tag;
      mentions.push(part.mention);
    } else {
      content += String(value);
    }
  }

  return { content, mentions: dedupe(mentions) };
}

function dedupe(mentions: SimpleMention[]): SimpleMention[] {
  const seen = new Set<string>();
  return mentions.filter((m) => {
    const key = `${m.entity_type}:${m.entity_id}`;
    if (seen.has(key)) return false;
    seen.add(key);
    return true;
  });
}

/** Normalize a plain string or a {@link RichMessage} to the wire shape. */
export function toBody(body: string | RichMessage): RichMessage {
  return typeof body === 'string' ? { content: body, mentions: [] } : body;
}