@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/node_modules/@metro-labs/xmtp/src/emit-payloads.ts

@@ -0,0 +1,346 @@
+import type { Reaction } from '@xmtp/content-type-reaction';
+import type { Reply } from '@xmtp/content-type-reply';
+import { errMsg } from '@metro-labs/core/log';
+import { transcribeAndEmit } from './transcribe.js';
+import {
+  INBOUND_FETCH_SCHEDULE,
+  saveInlineAttachment,
+  saveRemoteAttachment,
+  type RemoteEntry,
+} from './attachments.js';
+import { reportAttachment } from '@metro-labs/core/stations/train-events';
+import { sentByMe } from './wire.js';
+import { CALL_TYPES, frameActionText, frameFallback, type FrameContent } from './codecs.js';
+import { asFrameAction } from './frames.js';
+
+export interface EnvelopeCtx {
+  accountId: string;
+  msgId: string;
+  line: string;
+  baseId: string;
+}
+
+interface RemoteAtt {
+  url: string;
+  filename?: string;
+  contentDigest?: string;
+  nonce?: Uint8Array;
+  salt?: Uint8Array;
+  secret?: Uint8Array;
+  scheme?: string;
+  contentLength?: number;
+}
+
+interface AttView {
+  kind: string;
+  url: string;
+  name?: string;
+  size?: number;
+  remote: {
+    contentDigest?: string;
+    nonce?: string;
+    salt?: string;
+    secret?: string;
+    scheme?: string;
+  };
+}
+
+const b64 = (u?: Uint8Array): string | undefined =>
+  u ? Buffer.from(u).toString('base64') : undefined;
+
+function remoteAtt(r: RemoteAtt, kind: string): AttView {
+  return {
+    kind,
+    url: r.url,
+    name: r.filename,
+    size: r.contentLength,
+    remote: {
+      contentDigest: r.contentDigest,
+      nonce: b64(r.nonce),
+      salt: b64(r.salt),
+      secret: b64(r.secret),
+      scheme: r.scheme,
+    },
+  };
+}
+
+const IMG_RE = /\.(png|jpg|jpeg|gif|webp|heic)(\?|$)/i;
+const VID_RE = /\.(mp4|mov|webm|m4v)(\?|$)/i;
+
+function attKindFor(r: RemoteAtt): string {
+  const isImg = IMG_RE.test(r.url) || IMG_RE.test(r.filename ?? '');
+  if (isImg) return 'image';
+  const isVid = VID_RE.test(r.url) || VID_RE.test(r.filename ?? '');
+  return isVid ? 'video' : 'file';
+}
+
+function singleAttText(one: AttView): string {
+  if (one.kind === 'video') return `🎥 ${one.name ?? 'video'}`;
+  return `[${one.kind}: ${one.name ?? one.url}]`;
+}
+
+function multiAttText(attachments: AttView[]): string {
+  const total = attachments.length;
+  const imgCount = attachments.filter((a) => a.kind === 'image').length;
+  const vidCount = attachments.filter((a) => a.kind === 'video').length;
+  if (imgCount === total && imgCount > 1) return `📷 ${imgCount} photos`;
+  if (vidCount === total && vidCount > 1) return `🎥 ${vidCount} videos`;
+  const one = attachments[0];
+  if (total === 1 && one) return singleAttText(one);
+  return `📎 ${total} attachments`;
+}
+
+function multiRemotePayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+): Record<string, unknown> {
+  const m = c as { attachments?: RemoteAtt[] };
+  const list = Array.isArray(m.attachments) ? m.attachments : [];
+  const attachments = list.map((r) => remoteAtt(r, attKindFor(r)));
+  return {
+    ...base,
+    text: multiAttText(attachments),
+    payload: { contentType: typeId, attachments },
+  };
+}
+
+function reactionPayload(
+  base: Record<string, unknown>,
+  r: Reaction,
+): Record<string, unknown> {
+  const schemaStr = ((): string | undefined => {
+    const s = (r as { schema?: unknown }).schema;
+    if (typeof s === 'string') return s.toLowerCase();
+    if (s === 3) return 'custom';
+    if (s === 2) return 'shortcode';
+    if (s === 1) return 'unicode';
+    return undefined;
+  })();
+  const actionStr = ((): string | undefined => {
+    const a = (r as { action?: unknown }).action;
+    if (typeof a === 'string') return a.toLowerCase();
+    if (a === 2) return 'removed';
+    if (a === 1) return 'added';
+    return undefined;
+  })();
+  const removed = actionStr === 'removed';
+  return {
+    ...base,
+    text: `[react ${r.content ?? ''}${removed ? ' (removed)' : ''}]`,
+    event: { type: 'react', emoji: r.content, targetId: r.reference },
+    payload: {
+      contentType: 'reaction',
+      reactTo: r.reference,
+      emoji: r.content,
+      content: r.content,
+      schema: schemaStr,
+      action: actionStr,
+      removed,
+      optionIndex: schemaStr === 'custom' ? Number(r.content) : undefined,
+    },
+  };
+}
+
+function replyPayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: Reply,
+): Record<string, unknown> {
+  return {
+    ...base,
+    text:
+      typeof c.content === 'string'
+        ? c.content
+        : `[reply with ${c.contentType?.typeId ?? 'unknown'}]`,
+    event: { type: 'reply', replyTo: c.reference },
+    ...(sentByMe(c.reference) ? { reply_to_self: true } : {}),
+    payload: {
+      contentType: typeId,
+      replyTo: c.reference,
+      replyContentType: c.contentType?.typeId,
+    },
+  };
+}
+
+function attachmentKind(mime: string | undefined): string {
+  if (mime?.startsWith('image/')) return 'image';
+  if (mime?.startsWith('audio/')) return 'audio';
+  if (mime?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+function inlineAttachmentPayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: { filename?: string; mimeType: string; content: Uint8Array },
+  ctx: EnvelopeCtx,
+): Record<string, unknown> {
+  const kind = attachmentKind(c.mimeType);
+  const dataB64 = Buffer.from(c.content).toString('base64');
+  const out = {
+    ...base,
+    text: `[${kind}: ${c.filename ?? 'attachment'}]`,
+    payload: {
+      contentType: typeId,
+      attachments: [{ kind, mime: c.mimeType, name: c.filename, dataB64 }],
+    },
+  };
+  if (kind === 'audio')
+    transcribeAndEmit(
+      c.content,
+      ctx.line,
+      ctx.accountId,
+      ctx.baseId,
+    ).catch((err: unknown) => {
+      process.stderr.write(
+        `xmtp[${ctx.accountId}] voice transcription failed: ${errMsg(err)}\n`,
+      );
+    });
+  reportAttachment(saveInlineAttachment(c, ctx.msgId, 0), { station: 'xmtp', account: ctx.accountId, line: ctx.line, forId: ctx.baseId, index: 0 });
+  return out;
+}
+
+function remoteStaticPayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: RemoteAtt,
+  ctx: EnvelopeCtx,
+): Record<string, unknown> {
+  const kind = IMG_RE.test(c.url) ? 'image' : 'file';
+  reportAttachment(saveRemoteAttachment(c, ctx.msgId, 0, INBOUND_FETCH_SCHEDULE), { station: 'xmtp', account: ctx.accountId, line: ctx.line, forId: ctx.baseId, index: 0 });
+  return {
+    ...base,
+    text: `[${kind}: ${c.filename ?? c.url}]`,
+    payload: { contentType: typeId, attachments: [remoteAtt(c, kind)] },
+  };
+}
+
+function multiRemoteEnvelope(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+  ctx: EnvelopeCtx,
+): Record<string, unknown> {
+  const m = c as { attachments?: RemoteEntry[] };
+  (Array.isArray(m.attachments) ? m.attachments : []).forEach((r, i) => {
+    reportAttachment(saveRemoteAttachment(r, ctx.msgId, i, INBOUND_FETCH_SCHEDULE), { station: 'xmtp', account: ctx.accountId, line: ctx.line, forId: ctx.baseId, index: i });
+  });
+  return multiRemotePayload(base, typeId, c);
+}
+
+function pollPayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+): Record<string, unknown> {
+  const p = c as { question?: string };
+  return {
+    ...base,
+    text: `Poll: ${p.question ?? ''}`,
+    payload: { contentType: typeId, poll: c },
+  };
+}
+
+function labeledPayload(
+  base: Record<string, unknown>,
+  typeId: string,
+  text: string,
+  key: string,
+  c: unknown,
+): Record<string, unknown> {
+  return { ...base, text, payload: { contentType: typeId, [key]: c } };
+}
+
+function attachmentEnvelope(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+  ctx: EnvelopeCtx,
+): Record<string, unknown> | undefined {
+  if (typeId === 'attachment')
+    return inlineAttachmentPayload(
+      base,
+      typeId,
+      c as { filename?: string; mimeType: string; content: Uint8Array },
+      ctx,
+    );
+  if (typeId === 'remoteStaticAttachment')
+    return remoteStaticPayload(base, typeId, c as RemoteAtt, ctx);
+  if (
+    typeId === 'multiRemoteStaticAttachment' ||
+    typeId === 'multiRemoteAttachment'
+  )
+    return multiRemoteEnvelope(base, typeId, c, ctx);
+  return undefined;
+}
+
+function refEnvelope(
+  base: Record<string, unknown>,
+  typeId: string | undefined,
+  c: object,
+): Record<string, unknown> | undefined {
+  if (typeId === 'walletSendCalls')
+    return labeledPayload(
+      base,
+      typeId,
+      'Payment request',
+      'walletSendCalls',
+      c,
+    );
+  if (typeId === 'transactionReference')
+    return labeledPayload(
+      base,
+      typeId,
+      'Transaction',
+      'transactionReference',
+      c,
+    );
+  if (typeId === 'signatureRequest')
+    return labeledPayload(base, typeId, 'Signature request', 'signatureRequest', c);
+  if (typeId === 'signatureReference')
+    return labeledPayload(base, typeId, 'Signature', 'signatureReference', c);
+  return undefined;
+}
+
+function frameEnvelope(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+): Record<string, unknown> | undefined {
+  if (typeId === 'frame') {
+    const f = c as Partial<FrameContent>;
+    const frame: FrameContent = {
+      ...(typeof f.title === 'string' ? { title: f.title } : {}),
+      ...(typeof f.description === 'string' ? { description: f.description } : {}),
+    };
+    return { ...base, text: frameFallback(frame), payload: { contentType: typeId, frame: c } };
+  }
+  const a = typeId === 'frameAction' ? asFrameAction(c) : undefined;
+  if (!a) return undefined;
+  const label = a.label ? ` (tapped "${a.label}")` : '';
+  return {
+    ...base,
+    text: `${frameActionText(a)}${label}`,
+    event: { type: 'reply', replyTo: a.frameId },
+    ...(sentByMe(a.frameId) ? { reply_to_self: true } : {}),
+    payload: { contentType: typeId, frameAction: a, replyTo: a.frameId },
+  };
+}
+
+export function typedEnvelope(
+  base: Record<string, unknown>,
+  typeId: string | undefined,
+  c: object,
+  ctx: EnvelopeCtx,
+): Record<string, unknown> | undefined {
+  if (typeId === 'reaction') return reactionPayload(base, c as Reaction);
+  if (typeId === 'reply') return replyPayload(base, typeId, c as Reply);
+  if (typeId === 'poll') return pollPayload(base, typeId, c);
+  if (typeId !== undefined && CALL_TYPES.has(typeId)) return { ...base, payload: { contentType: typeId, call: c } };
+  return (
+    attachmentEnvelope(base, typeId ?? '', c, ctx) ??
+    refEnvelope(base, typeId, c) ??
+    frameEnvelope(base, typeId ?? '', c)
+  );
+}

package/runtime/node_modules/@metro-labs/xmtp/src/emit.ts

@@ -0,0 +1,68 @@
+import type { Conversation, DecodedMessage } from '@xmtp/node-sdk';
+import { lineOf } from './accounts.js';
+import { selfUri } from '@metro-labs/core/stations/train-events';
+import { emit, mintId } from '@metro-labs/core/stations/station-runtime';
+import { rememberSent, rememberUid } from './wire.js';
+import { typedEnvelope, type EnvelopeCtx } from './emit-payloads.js';
+import type { StructuredEvent } from '@metro-labs/core/events';
+
+export function envelope(
+  accountId: string,
+  msg: DecodedMessage,
+  conv: Conversation,
+): Record<string, unknown> {
+  const typeId = msg.contentType?.typeId;
+  const c = msg.content;
+  const line = lineOf(accountId, conv.id);
+  const base = {
+    id: mintId(),
+    ts: msg.sentAt.toISOString(),
+    station: 'xmtp',
+    line,
+    from: `metro://xmtp/${accountId}/user/${msg.senderInboxId}`,
+    message_id: msg.id,
+    is_private: 'peerInboxId' in conv,
+  };
+  rememberUid(base.id, msg.id);
+  if (typeof c === 'string')
+    return { ...base, text: c, payload: { contentType: typeId } };
+  if (c && typeof c === 'object') {
+    const ctx: EnvelopeCtx = {
+      accountId,
+      msgId: msg.id,
+      line,
+      baseId: base.id,
+    };
+    const out = typedEnvelope(base, typeId, c, ctx);
+    if (out) return out;
+  }
+  return {
+    ...base,
+    text: `[${typeId ?? 'unknown'} payload]`,
+    payload: { contentType: typeId },
+  };
+}
+
+export function emitOutbound(
+  accountId: string,
+  line: string,
+  messageId: string,
+  text: string,
+  event?: StructuredEvent,
+): void {
+  const uid = mintId();
+  rememberUid(uid, messageId);
+  rememberSent(messageId);
+  emit({
+    id: uid,
+    ts: new Date().toISOString(),
+    station: 'xmtp',
+    line,
+    from: selfUri(),
+    to: line,
+    message_id: messageId,
+    text,
+    ...(event ? { event } : {}),
+    payload: { account: accountId },
+  });
+}

package/runtime/node_modules/@metro-labs/xmtp/src/frames.ts

@@ -0,0 +1,190 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import type { FrameActionContent, FrameContent } from './codecs.js';
+
+export const FRAME_MAX_CHARS = 64 * 1024;
+export const FRAME_MAX_SCREENS = 50;
+const MAX_SCREEN_ID = 120;
+const FRAME_OPEN = 'frame.open';
+const MAX_TITLE = 200;
+const MAX_DESCRIPTION = 1000;
+const MAX_SOURCE_URL = 2048;
+const SUMMARY_SCAN = 80;
+const TEXT_TYPES = new Set(['Text', 'Caption', 'Markdown']);
+
+type Node = Record<string, unknown>;
+
+export const isNode = (v: unknown): v is Node =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export const bad = (message: string): TrainError => new TrainError('INVALID_ARGS', message);
+
+function plain(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  return value
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/^\s*(?:#{1,6}|>)\s*/gm, '')
+    .replace(/[*_`~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function childrenOf(node: Node): Node[] {
+  const c = node.children;
+  if (Array.isArray(c)) return c.filter(isNode);
+  return isNode(c) ? [c] : [];
+}
+
+export function frameSummary(widget: Node): { title?: string; description?: string } {
+  const titles: string[] = [];
+  const texts: string[] = [];
+  const stack: Node[] = [widget];
+  for (let seen = 0; stack.length > 0 && seen < SUMMARY_SCAN; seen += 1) {
+    const node = stack.pop();
+    if (!node) break;
+    const value = plain(node.value);
+    if (node.type === 'Title' && value) titles.push(value);
+    if (typeof node.type === 'string' && TEXT_TYPES.has(node.type) && value) texts.push(value);
+    stack.push(...childrenOf(node).reverse());
+  }
+  const title = titles[0] ?? texts[0];
+  return { title, description: texts.find((t) => t !== title) };
+}
+
+function clip(value: unknown, max: number, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw bad(`frame ${name} must be a string`);
+  const out = value.trim().slice(0, max);
+  return out === '' ? undefined : out;
+}
+
+export function parseJson(raw: unknown, name: string): unknown {
+  if (typeof raw !== 'string') return raw;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw bad(`${name} is not valid JSON`);
+  }
+}
+
+function checkSize(value: unknown, name: string): void {
+  const chars = JSON.stringify(value).length;
+  if (chars > FRAME_MAX_CHARS) throw bad(`${name} is ${chars} characters; the limit is ${FRAME_MAX_CHARS}`);
+}
+
+function parseWidget(raw: unknown, name = 'frame widget'): Node {
+  const widget = parseJson(raw, name);
+  if (!isNode(widget) || typeof widget.type !== 'string' || widget.type === '')
+    throw bad(`${name} must be a ChatKit widget object with a \`type\` (Card, ListView or Basic)`);
+  checkSize(widget, name);
+  return widget;
+}
+
+function parseScreen(id: string, raw: unknown): { screen: Node; widget: Node } {
+  const name = `frame screen "${id}"`;
+  const given = parseJson(raw, name);
+  if (!isNode(given) || given.type !== undefined || given.widget === undefined) {
+    const widget = parseWidget(given, name);
+    return { screen: widget, widget };
+  }
+  const widget = parseWidget(given.widget, `${name} widget`);
+  const title = clip(given.title, MAX_TITLE, `screen "${id}" title`);
+  return { screen: title ? { title, widget } : { widget }, widget };
+}
+
+function openTargets(root: unknown): string[] {
+  const targets: string[] = [];
+  const stack: unknown[] = [root];
+  while (stack.length > 0) {
+    const value = stack.pop();
+    if (Array.isArray(value)) stack.push(...(value as unknown[]));
+    else if (isNode(value)) {
+      if (value.type === FRAME_OPEN)
+        targets.push(isNode(value.payload) && typeof value.payload.screen === 'string' ? value.payload.screen : '');
+      stack.push(...Object.values(value));
+    }
+  }
+  return targets;
+}
+
+function screenIds(screens: Node): string[] {
+  const ids = Object.keys(screens);
+  if (ids.length === 0 || ids.length > FRAME_MAX_SCREENS)
+    throw bad(`frame screens must hold 1 to ${FRAME_MAX_SCREENS} screens, not ${ids.length}`);
+  const badId = ids.find((id) => id === '' || id.length > MAX_SCREEN_ID);
+  if (badId !== undefined) throw bad(`frame screen ids must be 1 to ${MAX_SCREEN_ID} characters`);
+  return ids;
+}
+
+function checkLinks(screens: Node, ids: string[], start: unknown): void {
+  if (typeof start !== 'string' || !ids.includes(start))
+    throw bad(`frame start is required with screens and must be one of their ids: ${ids.slice(0, 10).join(', ')}`);
+  const lost = openTargets(screens).find((target) => !ids.includes(target));
+  if (lost !== undefined)
+    throw bad(`frame.open goes to screen "${lost}", which is not in screens (${ids.slice(0, 10).join(', ')})`);
+}
+
+interface FrameBody {
+  content: Pick<FrameContent, 'widget' | 'screens' | 'start'>;
+  first: Node;
+}
+
+function parseScreens(raw: unknown, start: unknown): FrameBody {
+  const given = parseJson(raw, 'frame screens');
+  if (!isNode(given))
+    throw bad('frame screens must be an object of screen id to widget: {"home": {…}, "story": {"title": "…", "widget": {…}}}');
+  const ids = screenIds(given);
+  const parsed = ids.map((id) => [id, parseScreen(id, given[id])] as const);
+  const screens: Node = Object.fromEntries(parsed.map(([id, p]) => [id, p.screen]));
+  checkSize(screens, 'frame screens');
+  checkLinks(screens, ids, start);
+  const first = parsed.find(([id]) => id === start)?.[1];
+  if (!first || typeof start !== 'string') throw bad('frame start must name a screen');
+  return { content: { screens, start }, first: first.widget };
+}
+
+function frameBody(args: Node): FrameBody {
+  if (args.screens === undefined) {
+    const widget = parseWidget(args.widget);
+    return { content: { widget }, first: widget };
+  }
+  if (args.widget !== undefined) throw bad('frame takes `widget` or `screens`, not both');
+  return parseScreens(args.screens, args.start);
+}
+
+function sourcePart(raw: unknown): Pick<FrameContent, 'source'> {
+  if (raw === undefined) return {};
+  const url = isNode(raw) && typeof raw.url === 'string' ? raw.url.trim() : '';
+  if (url.length > MAX_SOURCE_URL)
+    throw bad(`frame source url is ${url.length} characters; the limit is ${MAX_SOURCE_URL}`);
+  if (!URL.canParse(url) || new URL(url).protocol !== 'https:')
+    throw bad('frame source must be {"url": "https://…"}, the node that serves this widget');
+  return { source: { url } };
+}
+
+export function buildFrameContent(raw: unknown): { frame: FrameContent; title: string } {
+  const args = parseJson(raw, 'frame');
+  if (!isNode(args))
+    throw bad('frame must be an object: {widget, title?, description?} or {screens, start, title?, description?}');
+  const body = frameBody(args);
+  const derived = frameSummary(body.first);
+  const title = clip(args.title, MAX_TITLE, 'title') ?? derived.title?.slice(0, MAX_TITLE);
+  const description = clip(args.description, MAX_DESCRIPTION, 'description') ?? derived.description?.slice(0, MAX_DESCRIPTION);
+  const frame: FrameContent = {
+    ...(title ? { title } : {}),
+    ...(description && description !== title ? { description } : {}),
+    ...body.content,
+    ...sourcePart(args.source),
+  };
+  return { frame, title: title ?? 'Frame' };
+}
+
+export function asFrameAction(c: object): FrameActionContent | undefined {
+  const v = c as Partial<FrameActionContent>;
+  if (typeof v.frameId !== 'string' || !isNode(v.action) || typeof v.action.type !== 'string') return undefined;
+  const payload = isNode(v.action.payload) ? v.action.payload : undefined;
+  return {
+    frameId: v.frameId,
+    action: payload ? { type: v.action.type, payload } : { type: v.action.type },
+    ...(typeof v.label === 'string' && v.label ? { label: v.label } : {}),
+  };
+}

package/runtime/node_modules/@metro-labs/xmtp/src/group-members.ts

@@ -0,0 +1,34 @@
+import type {
+  MemberOutcome,
+  MemberOutcomeStatus,
+} from '@metro-labs/core/stations/types';
+
+type Args = Record<string, unknown>;
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+function strList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.length > 0) as string[];
+}
+
+export function splitMembers(args: Args): {
+  addrs: string[];
+  inboxes: string[];
+} {
+  const addrs = new Set(strList(args.addresses));
+  const inboxes = new Set(strList(args.inboxIds));
+  for (const m of strList(args.members)) {
+    if (ADDRESS_RE.test(m)) addrs.add(m);
+    else inboxes.add(m);
+  }
+  return { addrs: [...addrs], inboxes: [...inboxes] };
+}
+
+export function memberOutcomes(
+  addrs: string[],
+  inboxes: string[],
+  status: MemberOutcomeStatus,
+): MemberOutcome[] {
+  return [...addrs, ...inboxes].map((id) => ({ id, status }));
+}

package/runtime/node_modules/@metro-labs/xmtp/src/group.ts

@@ -0,0 +1,56 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import type { GroupResult } from '@metro-labs/core/stations/types';
+import { accountForCall, convOf, lineOf } from './accounts.js';
+import {
+  applyMemberOp,
+  createGroupWithMembers,
+  warmGroupName,
+} from './conv-helpers.js';
+import { memberOutcomes, splitMembers } from './group-members.js';
+
+type Args = Record<string, unknown>;
+
+export async function groupCreate(args: Args): Promise<GroupResult> {
+  const name = typeof args.name === 'string' ? args.name : '';
+  if (!name) throw new TrainError('INVALID_ARGS', 'groupCreate requires a `name`');
+  const acct = accountForCall(args);
+  const { addrs, inboxes } = splitMembers(args);
+  const group = await createGroupWithMembers(acct, addrs, inboxes, {
+    groupName: name,
+  });
+  warmGroupName(group.id, name);
+  return {
+    capability: { supported: true },
+    line: lineOf(acct.cfg.id, group.id),
+    id: group.id,
+    name,
+    members: memberOutcomes(addrs, inboxes, 'added'),
+  };
+}
+
+async function memberOp(
+  args: Args,
+  mode: 'add' | 'remove',
+  verb: string,
+): Promise<GroupResult> {
+  const line = typeof args.line === 'string' ? args.line : '';
+  if (!line) throw new TrainError('INVALID_ARGS', `${verb} requires a \`line\``);
+  const { addrs, inboxes } = splitMembers(args);
+  if (!addrs.length && !inboxes.length)
+    throw new TrainError('INVALID_ARGS', `${verb} requires members`);
+  const { conv } = await convOf(line);
+  if (!conv) throw new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+  await applyMemberOp(conv, addrs, inboxes, mode);
+  return {
+    capability: { supported: true },
+    line,
+    id: conv.id,
+    members: memberOutcomes(addrs, inboxes, mode === 'add' ? 'added' : 'removed'),
+  };
+}
+
+export const groupAddMembers = (args: Args): Promise<GroupResult> =>
+  memberOp(args, 'add', 'groupAddMembers');
+
+export const groupRemoveMembers = (args: Args): Promise<GroupResult> =>
+  memberOp(args, 'remove', 'groupRemoveMembers');