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

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

@@ -0,0 +1,130 @@
+import { IdentifierKind, type DecodedMessage } from '@xmtp/node-sdk';
+import { accountForCall, convOf, lineOf, type Account } from './accounts.js';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { resolveMsgId } from './wire.js';
+import { serializeTrainError, TrainError } from '@metro-labs/core/train-error';
+import {
+  buildGroupInfo,
+  buildMemberList,
+} from './conv-helpers.js';
+import { closeGroup } from './actions-close.js';
+import {
+  groupAddMembers,
+  groupCreate,
+  groupRemoveMembers,
+} from './group.js';
+import { updateChannelMeta } from './actions-meta.js';
+import { deletedByRequests, isDeleteRequest, superAdminCheck } from './delete-requests.js';
+import { isCallSignal } from './codecs.js';
+import { syncConversation } from './network.js';
+import { readAttachments } from './read-attachments.js';
+
+type Args = Record<string, unknown>;
+type Handler = (id: string, args: Args) => Promise<void>;
+
+async function newDm(id: string, args: Args): Promise<void> {
+  const { address } = args as { address: string };
+  const acct = accountForCall(args);
+  const dm = await acct.client.conversations.createDmWithIdentifier({
+    identifier: address,
+    identifierKind: IdentifierKind.Ethereum,
+  });
+  respond(id, {
+    result: {
+      line: lineOf(acct.cfg.id, dm.id),
+      id: dm.id,
+      account: acct.cfg.id,
+    },
+  });
+}
+
+function upTo<T extends { id: string }>(all: T[], before: string | undefined): T[] {
+  if (!before) return all;
+  const target = resolveMsgId(before);
+  const at = all.findIndex((m) => m.id === target);
+  if (at < 0) throw new TrainError('NOT_FOUND', `message ${before} is not in this conversation`);
+  return all.slice(0, at);
+}
+
+function textOf(m: DecodedMessage): string {
+  try {
+    const cc: unknown = m.content;
+    return typeof cc === 'string' ? cc : `[${m.contentType?.typeId ?? 'unknown'}]`;
+  } catch {
+    return `[${m.contentType?.typeId ?? 'unknown'}]`;
+  }
+}
+
+const DELETED = { text: '[deletedMessage]', contentType: 'deletedMessage' };
+
+function messageOf(acct: Account, m: DecodedMessage, deleted: Set<string>): Record<string, unknown> {
+  return {
+    id: m.id,
+    ts: new Date(Number(m.sentAtNs / 1_000_000n)).toISOString(),
+    from: `metro://xmtp/${acct.cfg.id}/user/${m.senderInboxId}`,
+    ...(m.senderInboxId === acct.inboxId ? { self: true } : {}),
+    ...(deleted.has(m.id) ? DELETED : { text: textOf(m), contentType: m.contentType?.typeId ?? 'unknown' }),
+  };
+}
+
+async function read(id: string, args: Args): Promise<void> {
+  const { line, limit, before, messageId } = args as { line: string; limit?: number; before?: string; messageId?: string };
+  const { acct, conv } = await convOf(line);
+  if (!conv)
+    throw new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+  await syncConversation(acct.client, conv);
+  const all = await conv.messages();
+  if (messageId) {
+    const target = resolveMsgId(messageId);
+    const message = acct.client.conversations.getMessageById(target);
+    if (message?.conversationId !== conv.id || isDeleteRequest(message) || isCallSignal(message))
+      throw new TrainError('NOT_FOUND', `message ${messageId} is not in this conversation`);
+    const deleted = deletedByRequests([...all, message], superAdminCheck(conv));
+    try {
+      const attachments = deleted.has(message.id) ? [] : await readAttachments(message);
+      respond(id, { result: { line, account: acct.cfg.id, message: { ...messageOf(acct, message, deleted), attachments } } });
+    } catch (error) {
+      respond(id, serializeTrainError(error));
+    }
+    return;
+  }
+  const lim = Math.min(Math.max(1, limit ?? 20), 200);
+  const deleted = deletedByRequests(all, superAdminCheck(conv));
+  const slice = upTo(all.filter((m) => !isDeleteRequest(m) && !isCallSignal(m)), before).slice(-lim);
+  const messages = slice.map((m) => messageOf(acct, m, deleted));
+  respond(id, { result: { line, count: messages.length, messages } });
+}
+
+async function groupInfo(id: string, args: Args): Promise<void> {
+  const { line } = args as { line: string };
+  const { acct, conv } = await convOf(line);
+  if (!conv)
+    throw new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+  respond(id, { result: await buildGroupInfo(line, acct, conv) });
+}
+
+async function listMembers(id: string, args: Args): Promise<void> {
+  const { line } = args as { line: string };
+  const { conv } = await convOf(line);
+  if (!conv)
+    throw new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+  respond(id, { result: await buildMemberList(conv) });
+}
+
+export const convHandlers: Record<string, Handler> = {
+  newDm,
+  updateChannelMeta,
+  closeGroup,
+  read,
+  groupInfo,
+  listMembers,
+  groupCreate: async (id, args) => {
+    respond(id, { result: await groupCreate(args) });
+  },
+  groupAddMembers: async (id, args) => {
+    respond(id, { result: await groupAddMembers(args) });
+  },
+  groupRemoveMembers: async (id, args) => {
+    respond(id, { result: await groupRemoveMembers(args) });
+  },
+};

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

@@ -0,0 +1,151 @@
+import { accountForCall, convOf, lineOf, parseLine } from './accounts.js';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { ethIdentifiers, warmGroupName } from './conv-helpers.js';
+import { mergeAppData, normalizeAssigned, readAppDataObject, type GroupLike } from './labels.js';
+import { TrainError } from '@metro-labs/core/train-error';
+import { syncConversation } from './network.js';
+
+type Args = Record<string, unknown>;
+
+function resolveLine(args: Args, verb: string): string {
+  const line = (args as { line?: string }).line;
+  if (line) return line;
+  const groupId = (args as { groupId?: string }).groupId;
+  if (groupId) {
+    const acct = accountForCall(args);
+    return lineOf(acct.cfg.id, groupId);
+  }
+  throw new TrainError(
+    'INVALID_ARGS',
+    `${verb} requires \`line\` or \`groupId\``,
+  );
+}
+
+async function applyNameAndDescription(
+  group: GroupLike,
+  name: string | undefined,
+  description: string | undefined,
+): Promise<void> {
+  if (
+    typeof name === 'string' &&
+    name &&
+    typeof group.updateName === 'function'
+  ) {
+    await group.updateName(name);
+    warmGroupName(group.id, name);
+  }
+  if (
+    typeof description === 'string' &&
+    typeof group.updateDescription === 'function'
+  ) {
+    await group.updateDescription(description);
+  }
+}
+
+async function applyMergedAppData(
+  group: GroupLike & { updateAppData: (s: string) => Promise<void> },
+  appData: Record<string, unknown> | undefined,
+): Promise<Record<string, unknown>> {
+  if (appData && typeof appData === 'object' && !Array.isArray(appData)) {
+    const res = mergeAppData(group.appData, appData);
+    await group.updateAppData(res.blob);
+    return res.merged;
+  }
+  return readAppDataObject(group.appData);
+}
+
+async function applyChannelMeta(
+  args: {
+    line: string;
+    name?: string;
+    description?: string;
+    appData?: Record<string, unknown>;
+  },
+  verb: string,
+): Promise<Record<string, unknown>> {
+  const { line, name, description, appData } = args;
+  const { acct, conv } = await convOf(line);
+  if (!conv)
+    throw new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+  const group = conv as unknown as GroupLike;
+  if (typeof group.updateAppData !== 'function') {
+    throw new TrainError(
+      'INVALID_ARGS',
+      `${verb} target is not a group (no updateAppData)`,
+    );
+  }
+  await syncConversation(acct.client, conv);
+  if (appData) mergeAppData(group.appData, appData);
+  else readAppDataObject(group.appData);
+  if (appData && Object.hasOwn(appData, 'assigned')) {
+    const assigned = normalizeAssigned(appData.assigned);
+    const inboxIds = await Promise.all(
+      ethIdentifiers(assigned).map((identifier) => acct.client.fetchInboxIdByIdentifier(identifier)),
+    );
+    const members = new Set((await conv.members()).map((member) => member.inboxId));
+    if (inboxIds.some((inboxId) => !inboxId || !members.has(inboxId))) {
+      throw new TrainError('INVALID_ARGS', 'Assignees must be current channel members');
+    }
+  }
+
+  await applyNameAndDescription(group, name, description);
+  const merged = await applyMergedAppData(
+    group as GroupLike & { updateAppData: (s: string) => Promise<void> },
+    appData,
+  );
+
+  return {
+    line,
+    id: group.id,
+    account: acct.cfg.id,
+    ...(typeof name === 'string' && name ? { name } : {}),
+    ...metaFields(merged),
+    appData: merged,
+  };
+}
+
+function metaFields(merged: Record<string, unknown>): {
+  labels: string[];
+  category: string | undefined;
+  status: string | undefined;
+  priority: string | undefined;
+  github: string | undefined;
+  preview: string | undefined;
+  assigned: unknown;
+} {
+  return {
+    labels: Array.isArray(merged.labels) ? (merged.labels as string[]) : [],
+    category: typeof merged.category === 'string' ? merged.category : undefined,
+    status: typeof merged.status === 'string' ? merged.status : undefined,
+    priority: typeof merged.priority === 'string' ? merged.priority : undefined,
+    github: typeof merged.github === 'string' ? merged.github : undefined,
+    preview: typeof merged.preview === 'string' ? merged.preview : undefined,
+    assigned: Object.hasOwn(merged, 'assigned') ? merged.assigned : [],
+  };
+}
+
+const metadataWrites = new Map<string, Promise<Record<string, unknown>>>();
+
+export async function updateChannelMeta(id: string, args: Args): Promise<void> {
+  const line = resolveLine(args, 'updateChannelMeta');
+  const parsed = parseLine(line);
+  if (!parsed) throw new TrainError('INVALID_ARGS', `bad xmtp line: ${line}`);
+  const key = lineOf(parsed.accountId, parsed.convId);
+  const { name, description, appData } = args as {
+    name?: string;
+    description?: string;
+    appData?: Record<string, unknown>;
+  };
+  if (name !== undefined && typeof name !== 'string') {
+    throw new TrainError('INVALID_ARGS', 'name must be a string');
+  }
+  const task = () => applyChannelMeta({ line, name, description, appData }, 'updateChannelMeta');
+  const previous = metadataWrites.get(key);
+  const pending = previous ? previous.then(task, task) : task();
+  metadataWrites.set(key, pending);
+  try {
+    respond(id, { result: await pending });
+  } finally {
+    if (metadataWrites.get(key) === pending) metadataWrites.delete(key);
+  }
+}

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

@@ -0,0 +1,266 @@
+import {
+  GroupMessageKind,
+  ReactionAction,
+  ReactionSchema,
+  type Conversation,
+} from '@xmtp/node-sdk';
+import type { Reply } from '@xmtp/node-bindings';
+import {
+  AttachmentCodec,
+  type Attachment,
+} from '@xmtp/content-type-remote-attachment';
+import type { EncodedContent } from '@xmtp/content-type-primitives';
+import { convOf, type Account } from './accounts.js';
+import { resolveMsgId } from './wire.js';
+import { emitOutbound } from './emit.js';
+import { CallSignalCodec, FrameCodec, PollCodec, buildPollContent, encodeDeleteMessage } from './codecs.js';
+import { buildFrameContent } from './frames.js';
+import { buildWalletContent } from './wallet.js';
+import { network } from './network.js';
+import { callLeftovers } from './call-leftovers.js';
+import { convHandlers } from './actions-conv.js';
+import { messagingAliases } from '@metro-labs/core/stations/messaging-normalize';
+import { TrainError } from '@metro-labs/core/train-error';
+import { claimNameAction, nameAction, setProfile } from './profile.js';
+import { profileAction } from './sender.js';
+import { resolveSenderAction } from './resolve.js';
+import { listChannels } from './channels.js';
+import { makeStation, respond, type CallMsg } from '@metro-labs/core/stations/station-runtime';
+
+type Args = Record<string, unknown>;
+
+const noConv = (line: string): TrainError =>
+  new TrainError('NOT_FOUND', `conversation not found for ${line}`);
+const badArgs = (message: string): TrainError =>
+  new TrainError('INVALID_ARGS', message);
+
+function framePart(raw: unknown): { encoded: EncodedContent; summary: string } {
+  const built = buildFrameContent(raw);
+  return { encoded: new FrameCodec().encode(built.frame), summary: `Frame: ${built.title}` };
+}
+
+async function send(id: string, args: Args): Promise<void> {
+  const { line, text } = args as { line: string; text: string };
+  const parts = [
+    ...(args.frame === undefined ? [] : [framePart(args.frame)]),
+    ...(args.wallet === undefined ? [] : [buildWalletContent(args.wallet)]),
+  ];
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  let messageId: string | undefined;
+  if (text || parts.length === 0) {
+    messageId = await conv.sendText(text);
+    emitOutbound(acct.cfg.id, line, messageId, text);
+  }
+  for (const part of parts) {
+    messageId = await conv.send(part.encoded);
+    emitOutbound(acct.cfg.id, line, messageId, part.summary);
+  }
+  respond(id, { result: { messageId } });
+}
+
+async function ask(id: string, args: Args): Promise<void> {
+  const { line } = args as { line: string };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const mintedId = crypto.randomUUID();
+  const { poll, title } = buildPollContent(args, mintedId);
+  const sentId = await conv.send(new PollCodec().encode(poll));
+  emitOutbound(acct.cfg.id, line, sentId, `📊 Poll: ${title}`);
+  respond(id, { result: { messageId: sentId, pollId: mintedId } });
+}
+
+async function referenceInboxOf(conv: Conversation, xmtpMsgId: string): Promise<string> {
+  const recent = await conv.messages({ limit: 200, direction: 1 });
+  const inbox = recent.find((m) => m.id === xmtpMsgId)?.senderInboxId;
+  if (!inbox)
+    throw new TrainError('NOT_FOUND', `could not resolve referenceInboxId for ${xmtpMsgId}`);
+  return inbox;
+}
+
+async function react(id: string, args: Args): Promise<void> {
+  const { line, messageId, emoji, action: reactAction } = args as {
+    line: string;
+    messageId: string;
+    emoji: string;
+    action?: 'added' | 'removed';
+  };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const xmtpMsgId = resolveMsgId(messageId);
+  const removed = reactAction === 'removed';
+  const sentId = await conv.sendReaction({
+    reference: xmtpMsgId,
+    referenceInboxId: await referenceInboxOf(conv, xmtpMsgId),
+    action: removed ? ReactionAction.Removed : ReactionAction.Added,
+    content: emoji,
+    schema: ReactionSchema.Unicode,
+  });
+  emitOutbound(
+    acct.cfg.id,
+    line,
+    sentId,
+    `[react ${emoji}${removed ? ' (removed)' : ''}]`,
+    { type: 'react', emoji, targetId: xmtpMsgId },
+  );
+  respond(id, { result: { messageId: sentId } });
+}
+
+async function reply(id: string, args: Args): Promise<void> {
+  const { line, replyTo, text } = args as {
+    line: string;
+    replyTo: string;
+    text: string;
+  };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const { encodeText } = await import('@xmtp/node-bindings');
+  const xmtpReplyTo = resolveMsgId(replyTo);
+  const sentId = await conv.sendReply({
+    reference: xmtpReplyTo,
+    content: encodeText(text),
+    contentType: {
+      authorityId: 'xmtp.org',
+      typeId: 'text',
+      versionMajor: 1,
+      versionMinor: 0,
+    },
+  } as unknown as Reply);
+  emitOutbound(acct.cfg.id, line, sentId, text, {
+    type: 'reply',
+    replyTo: xmtpReplyTo,
+  });
+  respond(id, { result: { messageId: sentId } });
+}
+
+const UNDELETABLE = new Set(['deleteMessage', 'deletedMessage']);
+
+function assertDeletable(acct: Account, conv: Conversation, messageId: string): void {
+  const msg = acct.client.conversations.getMessageById(messageId);
+  if (msg?.conversationId !== conv.id)
+    throw new TrainError('NOT_FOUND', `message ${messageId} is not in this conversation`);
+  if (msg.senderInboxId !== acct.inboxId)
+    throw badArgs(`message ${messageId} was not sent by this account; only your own messages can be deleted`);
+  if (msg.kind !== GroupMessageKind.Application || UNDELETABLE.has(msg.contentType?.typeId ?? ''))
+    throw badArgs(`message ${messageId} cannot be deleted`);
+}
+
+async function remove(id: string, args: Args): Promise<void> {
+  const { line, messageId } = args as { line: string; messageId: string };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const target = resolveMsgId(messageId);
+  assertDeletable(acct, conv, target);
+  const sentId = await conv.send(encodeDeleteMessage(target), { shouldPush: false });
+  respond(id, { result: { messageId: sentId } });
+}
+
+async function callSignal(id: string, args: Args): Promise<void> {
+  const { line, signal } = args as { line: string; signal?: unknown };
+  if (typeof signal !== 'object' || signal === null) throw badArgs('callSignal requires a signal object');
+  const { conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const messageId = await conv.send(new CallSignalCodec().encode(signal as Record<string, unknown>), { shouldPush: false });
+  respond(id, { result: { messageId } });
+}
+
+async function sendAttachment(id: string, args: Args): Promise<void> {
+  const { line, name, mime, dataB64 } = args as {
+    line: string;
+    name: string;
+    mime: string;
+    dataB64: string;
+  };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const sentId = await conv.sendAttachment({
+    filename: name,
+    mimeType: mime,
+    content: new Uint8Array(Buffer.from(dataB64, 'base64')),
+  });
+  emitOutbound(acct.cfg.id, line, sentId, `[${mime.split('/')[0]}: ${name}]`);
+  respond(id, { result: { messageId: sentId } });
+}
+
+const IMG_MIME_BY_EXT: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+};
+
+function imageMime(path: string): string {
+  const ext = path.toLowerCase().split('.').pop() ?? '';
+  return IMG_MIME_BY_EXT[ext] ?? 'image/png';
+}
+
+function imageFilename(path: string): string {
+  const baseName = path.split('/').pop();
+  return baseName != null && baseName !== '' ? baseName : 'image.png';
+}
+
+async function sendImage(id: string, args: Args): Promise<void> {
+  const { line, path } = args as { line: string; path?: string };
+  if (!path) throw badArgs('sendImage requires path');
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const { readFileSync } = await import('node:fs');
+  const mime = imageMime(path);
+  const fname = imageFilename(path);
+  const attachment: Attachment = {
+    filename: fname,
+    mimeType: mime,
+    data: new Uint8Array(readFileSync(path)),
+  };
+  const sentId = await conv.send(new AttachmentCodec().encode(attachment));
+  emitOutbound(acct.cfg.id, line, sentId, `[${mime.split('/')[0]}: ${fname}]`);
+  respond(id, { result: { messageId: sentId } });
+}
+
+async function accountsAction(id: string): Promise<void> {
+  const { accounts } = await import('./accounts.js');
+  respond(id, {
+    result: {
+      accounts: [...accounts.values()].map((a) => ({
+        id: a.cfg.id,
+        handle: a.address,
+        url: `https://stage.box/#/${a.address}`,
+        address: a.address,
+        inboxId: a.inboxId,
+        smart: a.smart !== null,
+      })),
+    },
+  });
+}
+
+const handlers: Record<string, (id: string, args: Args) => Promise<void>> = {
+  accounts: (id) => accountsAction(id),
+  listChannels,
+  set_profile: setProfile,
+  claim_name: claimNameAction,
+  name: nameAction,
+  profile: profileAction,
+  resolve_sender: resolveSenderAction,
+  send,
+  ask,
+  react,
+  reply,
+  delete: remove,
+  callSignal,
+  callLeftovers: (id) => callLeftovers(id),
+  sendAttachment,
+  sendImage,
+  ...convHandlers,
+};
+
+export type { CallMsg };
+
+export const handleCall = makeStation({
+  handlers: Object.fromEntries(Object.entries(handlers).map(([action, handler]) => [
+    action,
+    action === 'accounts' || action === 'callLeftovers' || action === 'listChannels'
+      ? handler
+      : (id: string, args: Args) => network.run(() => handler(id, args)),
+  ])),
+  normalize: messagingAliases({ action: 'removed' }),
+});

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

@@ -0,0 +1,150 @@
+import {
+  AttachmentCodec,
+  RemoteAttachmentCodec,
+  ContentTypeAttachment,
+} from '@xmtp/content-type-remote-attachment';
+import {
+  saveBufferToCache,
+  assertAttachmentSize,
+} from '@metro-labs/core/stations/attachments';
+import type { SavedAttachment } from '@metro-labs/core/stations/attachments';
+import { errMsg } from '@metro-labs/core/log';
+
+export type { SavedAttachment };
+
+interface FetchSchedule {
+  delaysMs: readonly number[];
+  requestTimeoutMs: number;
+}
+
+const READ_SCHEDULE: FetchSchedule = { delaysMs: [400, 800], requestTimeoutMs: 18_000 };
+export const INBOUND_FETCH_SCHEDULE: FetchSchedule = {
+  delaysMs: [
+    2_000, 4_000, 8_000, 15_000, 30_000, 30_000,
+    60_000, 60_000, 60_000, 60_000, 60_000, 60_000,
+  ],
+  requestTimeoutMs: 120_000,
+};
+export const REMOTE_FETCH_ATTEMPTS = READ_SCHEDULE.delaysMs.length + 1;
+const SWARM_GATEWAY = 'https://download.gateway.ethswarm.org/bzz/';
+const SWARM_BZZ_URL = /^https:\/\/[^/]+\/bzz\/([0-9a-f]{64}(?:[0-9a-f]{64})?)\/?$/i;
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+const attachmentCodec = new AttachmentCodec();
+const loadRegistry = {
+  codecFor: (ct: { typeId?: string }) =>
+    ct.typeId === ContentTypeAttachment.typeId ? attachmentCodec : undefined,
+};
+
+export interface RemoteEntry {
+  url: string;
+  filename?: string;
+  contentDigest?: string;
+  nonce?: Uint8Array;
+  salt?: Uint8Array;
+  secret?: Uint8Array;
+  scheme?: string;
+  contentLength?: number;
+}
+
+export async function saveInlineAttachment(
+  a: { filename?: string; mimeType?: string; content: Uint8Array },
+  messageId: string,
+  index = 0,
+): Promise<SavedAttachment> {
+  return saveBufferToCache(a.content, messageId, index, {
+    mime: a.mimeType,
+    name: a.filename,
+  });
+}
+
+function toRemoteDescriptor(r: RemoteEntry): {
+  url: string;
+  contentDigest: string;
+  salt: Uint8Array;
+  nonce: Uint8Array;
+  secret: Uint8Array;
+  scheme: string;
+  contentLength: number;
+  filename: string;
+} {
+  return {
+    url: r.url,
+    contentDigest: r.contentDigest ?? '',
+    salt: r.salt ?? new Uint8Array(),
+    nonce: r.nonce ?? new Uint8Array(),
+    secret: r.secret ?? new Uint8Array(),
+    scheme: r.scheme ?? 'https://',
+    contentLength: r.contentLength ?? 0,
+    filename: r.filename ?? '',
+  };
+}
+
+interface DecodedAttachment {
+  filename?: string;
+  mimeType?: string;
+  data: Uint8Array;
+}
+
+function remoteUrl(url: string): string {
+  const ref = SWARM_BZZ_URL.exec(url)?.[1];
+  return ref === undefined ? url : `${SWARM_GATEWAY}${ref.toLowerCase()}/`;
+}
+
+function withTimeout<T>(work: Promise<T>, ms: number, url: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`no answer from ${url} within ${ms / 1000}s`));
+    }, ms);
+  });
+  return Promise.race([work, expired]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+function loadFrom(r: RemoteEntry, url: string, timeoutMs: number): Promise<DecodedAttachment> {
+  return withTimeout(
+    RemoteAttachmentCodec.load<DecodedAttachment>(
+      { ...toRemoteDescriptor(r), url },
+      loadRegistry,
+    ),
+    timeoutMs,
+    url,
+  );
+}
+
+async function loadRemote(
+  r: RemoteEntry,
+  schedule: FetchSchedule,
+): Promise<DecodedAttachment> {
+  const url = remoteUrl(r.url);
+  let last = '';
+  for (const delay of [0, ...schedule.delaysMs]) {
+    if (delay > 0) await sleep(delay);
+    try {
+      return await loadFrom(r, url, schedule.requestTimeoutMs);
+    } catch (err) {
+      last = errMsg(err);
+    }
+  }
+  throw new Error(
+    `xmtp remote attachment fetch failed after ${schedule.delaysMs.length + 1} attempts: ${last}`,
+  );
+}
+
+export async function saveRemoteAttachment(
+  r: RemoteEntry,
+  messageId: string,
+  index = 0,
+  schedule: FetchSchedule = READ_SCHEDULE,
+): Promise<SavedAttachment> {
+  if (r.contentLength) assertAttachmentSize(r.contentLength);
+  const decoded = await loadRemote(r, schedule);
+  return saveBufferToCache(decoded.data, messageId, index, {
+    mime: decoded.mimeType,
+    name: decoded.filename ?? r.filename,
+  });
+}