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

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

@@ -0,0 +1,47 @@
+import { IdentifierKind, type Signer } from '@xmtp/node-sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SMART_CHAIN_ID, smartAccountFor, type SmartAccount } from './smart.js';
+
+export const XMTP_ENV = 'production' as const;
+
+export const expandHome = (p: string): string =>
+  p.startsWith('~') ? join(homedir(), p.slice(1)) : p;
+
+export interface Identity {
+  signer: Signer;
+  address: string;
+  smart: SmartAccount | null;
+}
+
+const bytesOf = (sig: string): Uint8Array => {
+  const hex = sig.slice(2);
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+
+export function signerFor(privateKey: string): Identity {
+  const acct = privateKeyToAccount(privateKey as `0x${string}`);
+  const signer: Signer = {
+    type: 'EOA',
+    getIdentifier: () => Promise.resolve({ identifier: acct.address, identifierKind: IdentifierKind.Ethereum }),
+    signMessage: async (msg: string) => bytesOf(await acct.signMessage({ message: msg })),
+  };
+  return { signer, address: acct.address, smart: null };
+}
+
+export async function smartSignerFor(privateKey: string, rpc?: string): Promise<Identity> {
+  const smart = await smartAccountFor(privateKey, rpc);
+  const signer: Signer = {
+    type: 'SCW',
+    getIdentifier: () => Promise.resolve({ identifier: smart.address, identifierKind: IdentifierKind.Ethereum }),
+    signMessage: async (msg: string) => bytesOf(await smart.signMessage(msg)),
+    getChainId: () => BigInt(SMART_CHAIN_ID),
+  };
+  return { signer, address: smart.address, smart };
+}
+
+export const identityFor = (privateKey: string, smart: boolean): Promise<Identity> =>
+  smart ? smartSignerFor(privateKey) : Promise.resolve(signerFor(privateKey));

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

@@ -0,0 +1,73 @@
+import { errMsg } from '@metro-labs/core/log';
+import type { DecodedMessage } from '@xmtp/node-sdk';
+import {
+  accounts,
+  bootAccount,
+  loadAccounts,
+  type Account,
+} from './accounts.js';
+import { emitInbound } from '@metro-labs/core/stations/train-events';
+import { announceAccounts } from '@metro-labs/core/stations/train-boot';
+import { envelope } from './emit.js';
+import { groupNameFor } from './conv-helpers.js';
+import { senderFieldsNow } from './sender.js';
+import { readCalls } from '@metro-labs/core/trains/protocol';
+import { handleCall } from './actions.js';
+import { streamMessages } from './stream.js';
+
+readCalls('xmtp', handleCall);
+
+const SILENT_TYPES = new Set([
+  'readReceipt',
+  'transactionReference',
+  'walletSendCalls',
+  'groupUpdated',
+  'group_updated',
+  'deleteRequest',
+]);
+
+async function handleStreamMessage(
+  acct: Account,
+  msg: DecodedMessage,
+): Promise<void> {
+  const { id } = acct.cfg;
+  if (msg.senderInboxId === acct.client.inboxId) return;
+  if (SILENT_TYPES.has(msg.contentType?.typeId ?? '')) return;
+  const conv = await acct.client.conversations.getConversationById(
+    msg.conversationId,
+  );
+  if (!conv) return;
+  const env = envelope(id, msg, conv);
+  Object.assign(env, senderFieldsNow(acct, msg.senderInboxId));
+  const name = await groupNameFor(msg.conversationId, conv);
+  if (name) env.line_name = name;
+  emitInbound(id, env);
+}
+
+async function runAccount(acct: Account): Promise<void> {
+  await streamMessages(acct.client.conversations, async (msg) => {
+    if (!msg) return;
+    await handleStreamMessage(acct, msg).catch((err: unknown) => {
+      process.stderr.write(`xmtp[${acct.cfg.id}] one message failed and was skipped: ${errMsg(err)}\n`);
+    });
+  });
+}
+
+const cfgs = loadAccounts();
+for (const cfg of cfgs) {
+  try {
+    await bootAccount(cfg);
+  } catch (err) {
+    process.stderr.write(
+      `xmtp[${cfg.id}] boot FAILED: ${errMsg(err)}\n`,
+    );
+  }
+}
+announceAccounts('xmtp', accounts.keys());
+
+for (const acct of accounts.values())
+  runAccount(acct).catch((err: unknown) => {
+    process.stderr.write(
+      `xmtp[${acct.cfg.id}] account loop failed: ${errMsg(err)}\n`,
+    );
+  });

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

@@ -0,0 +1,209 @@
+import { TrainError } from '@metro-labs/core/train-error';
+
+export interface GroupLike {
+  id: string;
+  appData?: string;
+  updateAppData?: (s: string) => Promise<void>;
+  updateName?: (s: string) => Promise<void>;
+  updateDescription?: (s: string) => Promise<void>;
+  removeMembers?: (inboxIds: string[]) => Promise<void>;
+  sync?: () => Promise<unknown>;
+}
+
+const MAX_LABELS = 16;
+const MAX_LABEL_LEN = 24;
+const MAX_APP_DATA_BYTES = 8192;
+export const PRIORITIES = ['Urgent', 'High', 'Medium', 'Low'] as const;
+type Priority = (typeof PRIORITIES)[number];
+
+function cleanLabel(raw: string): string {
+  return raw.trim().replace(/\s+/g, ' ').slice(0, MAX_LABEL_LEN);
+}
+
+function cleanLabels(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== 'string') continue;
+    const label = cleanLabel(item);
+    const key = label.toLowerCase();
+    if (!label || seen.has(key)) continue;
+    seen.add(key);
+    out.push(label);
+    if (out.length >= MAX_LABELS) break;
+  }
+  return out;
+}
+
+export function readAppDataObject(
+  existingAppData: string | undefined,
+): Record<string, unknown> {
+  if (!existingAppData?.trim()) return {};
+  const parsed: unknown = JSON.parse(existingAppData);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new TrainError('INVALID_ARGS', 'Channel appData must be a JSON object');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function normalizeAssigned(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new TrainError('INVALID_ARGS', 'assigned must be an array of Ethereum addresses');
+  }
+  const addresses: string[] = [];
+  for (const address of value) {
+    if (typeof address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(address.trim())) {
+      throw new TrainError('INVALID_ARGS', 'assigned must contain valid Ethereum addresses');
+    }
+    addresses.push(address.trim().toLowerCase());
+  }
+  return [...new Set(addresses)];
+}
+
+export function metadataPatch(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TrainError('INVALID_ARGS', 'metadata must be a JSON object');
+  }
+  const patch = value as Record<string, unknown>;
+  if (Object.hasOwn(patch, 'v')) {
+    throw new TrainError('INVALID_ARGS', 'metadata cannot change the reserved v field');
+  }
+  return patch;
+}
+
+function trimmedString(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+
+function cleanMetadataText(v: unknown): string | undefined {
+  return typeof v === 'string' ? cleanLabel(v) || undefined : undefined;
+}
+
+function cleanPriority(value: unknown): Priority | undefined {
+  return PRIORITIES.find((priority) => priority === (typeof value === 'string' ? value.trim() : value));
+}
+
+export function readAppData(appData: string | undefined): {
+  labels: string[];
+  category?: string;
+  status?: string;
+  priority?: Priority;
+  github?: string;
+  preview?: string;
+} {
+  if (!appData?.trim()) return { labels: [] };
+  try {
+    const p: unknown = JSON.parse(appData);
+    if (!p || typeof p !== 'object' || Array.isArray(p)) return { labels: [] };
+    const rec = p as Record<string, unknown>;
+    return {
+      labels: cleanLabels(rec.labels),
+      category: cleanMetadataText(rec.category),
+      status: cleanMetadataText(rec.status),
+      priority: cleanPriority(rec.priority),
+      github: trimmedString(rec.github),
+      preview: trimmedString(rec.preview),
+    };
+  } catch {
+    return { labels: [] };
+  }
+}
+
+function checkedLabels(value: unknown): string[] {
+  if (!Array.isArray(value) || value.some((label: unknown) => typeof label !== 'string')) {
+    throw new TrainError('INVALID_ARGS', 'labels must be an array of strings');
+  }
+  return cleanLabels(value);
+}
+
+function checkedMetadataText(key: string, value: unknown): string | undefined {
+  if (value !== undefined && value !== null && typeof value !== 'string') {
+    throw new TrainError('INVALID_ARGS', `${key} must be a string or null`);
+  }
+  return cleanMetadataText(value);
+}
+
+function checkedPriority(value: unknown): Priority | undefined {
+  if (value === undefined || value === null || (typeof value === 'string' && !value.trim())) return undefined;
+  const priority = cleanPriority(value);
+  if (!priority) {
+    throw new TrainError('INVALID_ARGS', 'priority must be Urgent, High, Medium, Low, or null');
+  }
+  return priority;
+}
+
+const KNOWN_FIELDS = new Map<string, (value: unknown) => unknown>([
+  ['labels', checkedLabels],
+  ['assigned', normalizeAssigned],
+  ['github', (value) => normalizeGithubUrl(value) || undefined],
+  ['preview', (value) => normalizePreviewUrl(value) || undefined],
+  ['category', (value) => checkedMetadataText('category', value)],
+  ['status', (value) => checkedMetadataText('status', value)],
+  ['priority', checkedPriority],
+]);
+
+function applyMergeKey(
+  merged: Record<string, unknown>,
+  k: string,
+  v: unknown,
+): void {
+  const normalize = KNOWN_FIELDS.get(k);
+  const value = normalize ? normalize(v) : v;
+  if (value === undefined || value === null) Reflect.deleteProperty(merged, k);
+  else Object.defineProperty(merged, k, { value, enumerable: true, configurable: true, writable: true });
+}
+
+export function mergeAppData(
+  existingAppData: string | undefined,
+  patch: Record<string, unknown>,
+): { blob: string; merged: Record<string, unknown> } {
+  const current = readAppDataObject(existingAppData);
+  const checked = metadataPatch(patch);
+  if (Object.hasOwn(checked, 'assigned') && Object.hasOwn(current, 'assigned')) {
+    normalizeAssigned(current.assigned);
+  }
+  const merged: Record<string, unknown> = { v: 1, ...current };
+  for (const [k, v] of Object.entries(checked)) applyMergeKey(merged, k, v);
+  const blob = JSON.stringify(merged);
+  if (Buffer.byteLength(blob, 'utf8') > MAX_APP_DATA_BYTES) {
+    throw new TrainError('INVALID_ARGS', `Channel appData exceeds ${MAX_APP_DATA_BYTES} bytes`);
+  }
+  return { blob, merged };
+}
+
+export function normalizeGithubUrl(url: unknown): string {
+  if (typeof url !== 'string')
+    throw new Error('setGithub requires a `url` string');
+  const trimmed = url.trim();
+  if (!trimmed) return '';
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`invalid url: ${trimmed}`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`github url must be http(s): ${trimmed}`);
+  }
+  if (
+    parsed.hostname !== 'github.com' &&
+    parsed.hostname !== 'www.github.com'
+  ) {
+    throw new Error(`url must be a github.com URL: ${trimmed}`);
+  }
+  return trimmed;
+}
+
+export function normalizePreviewUrl(url: unknown): string {
+  if (typeof url !== 'string')
+    throw new Error('setPreview requires a `preview` string');
+  const trimmed = url.trim();
+  if (!trimmed) return '';
+  try {
+    new URL(trimmed);
+  } catch {
+    throw new Error(`invalid preview url: ${trimmed}`);
+  }
+  return trimmed;
+}

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

@@ -0,0 +1,40 @@
+import { TrainError } from '@metro-labs/core/train-error';
+
+type Args = Record<string, unknown>;
+
+export function filterStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((a) => typeof a === 'string' && a.length > 0) as string[];
+}
+
+export function resolveMembers(args: Args): {
+  addrs: string[];
+  inboxes: string[];
+} {
+  const { addresses, inboxIds, memberAddresses, memberInboxIds } = args as {
+    addresses?: string[];
+    inboxIds?: string[];
+    memberAddresses?: string[];
+    memberInboxIds?: string[];
+  };
+  return {
+    addrs: filterStrings(addresses ?? memberAddresses),
+    inboxes: filterStrings(inboxIds ?? memberInboxIds),
+  };
+}
+
+export function parseMemberArgs(
+  args: Args,
+  verb: string,
+): { line: string; addrs: string[]; inboxes: string[] } {
+  const { line } = args as { line: string };
+  if (!line || typeof line !== 'string')
+    throw new TrainError('INVALID_ARGS', `${verb} requires a \`line\``);
+  const { addrs, inboxes } = resolveMembers(args);
+  if (addrs.length === 0 && inboxes.length === 0)
+    throw new TrainError(
+      'INVALID_ARGS',
+      `${verb} requires addresses[] or inboxIds[]`,
+    );
+  return { line, addrs, inboxes };
+}

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

@@ -0,0 +1,61 @@
+import { TrainError } from '@metro-labs/core/train-error';
+
+export const STAGE_NAMES_PARENT = 'stage.base.eth';
+export const STAGE_PROXY = 'https://proxy.stage.box';
+const LABEL_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MIN = 6;
+const MAX = 32;
+const HEADERS = { 'content-type': 'application/json', 'x-stage-client': '1' };
+
+export const proxyBase = (): string => process.env.METRO_STAGE_PROXY ?? STAGE_PROXY;
+
+export const stageNameOf = (label: string): string => `${label}.${STAGE_NAMES_PARENT}`;
+
+export function parseLabel(raw: unknown): string {
+  const label = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  if (label.length < MIN) throw new TrainError('bad_request', `a name needs at least ${String(MIN)} characters`);
+  if (label.length > MAX) throw new TrainError('bad_request', `a name can have at most ${String(MAX)} characters`);
+  if (!LABEL_RE.test(label)) throw new TrainError('bad_request', 'a name is lowercase letters, digits and single inner hyphens');
+  return label;
+}
+
+export const claimMessage = (label: string, address: string, issuedAt: number): string =>
+  `Claim ${stageNameOf(label)} for ${address.toLowerCase()} at ${String(issuedAt)}`;
+
+async function ask(path: string, init: RequestInit, fetchImpl: typeof fetch): Promise<Record<string, unknown>> {
+  let res: Response;
+  try {
+    res = await fetchImpl(`${proxyBase()}/names/${path}`, { ...init, headers: HEADERS, signal: AbortSignal.timeout(30_000) });
+  } catch (err) {
+    throw new TrainError('names_unreachable', `could not reach the stage name service: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const body: unknown = await res.json().catch(() => null);
+  const record = typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {};
+  if (!res.ok) throw new TrainError('names_refused', typeof record.error === 'string' ? record.error : `the stage name service answered ${String(res.status)}`);
+  return record;
+}
+
+export async function nameOf(address: string, fetchImpl: typeof fetch = fetch): Promise<string | null> {
+  const body = await ask(`status?address=${encodeURIComponent(address)}`, {}, fetchImpl);
+  return typeof body.name === 'string' && body.name !== '' ? body.name : null;
+}
+
+export async function checkLabel(label: string, fetchImpl: typeof fetch = fetch): Promise<void> {
+  const body = await ask(`check?label=${encodeURIComponent(label)}`, {}, fetchImpl);
+  if (body.valid !== true) throw new TrainError('bad_request', typeof body.reason === 'string' ? body.reason : `${stageNameOf(label)} is not a valid name`);
+  if (body.available !== true) throw new TrainError('name_taken', `${stageNameOf(label)} is already taken`);
+}
+
+export async function claimName(
+  label: string,
+  address: string,
+  sign: (message: string) => Promise<string>,
+  fetchImpl: typeof fetch = fetch,
+  now = Date.now(),
+): Promise<string> {
+  await checkLabel(label, fetchImpl);
+  const signature = await sign(claimMessage(label, address, now));
+  const body = await ask('claim', { method: 'POST', body: JSON.stringify({ label, address, issuedAt: now, signature }) }, fetchImpl);
+  if (typeof body.name !== 'string' || body.name === '') throw new TrainError('names_refused', 'the stage name service issued no name');
+  return body.name;
+}

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

@@ -0,0 +1,114 @@
+import { errMsg } from '@metro-labs/core/log';
+import { TrainError } from '@metro-labs/core/train-error';
+
+const RATE_DELAY_MS = 60_000;
+const MAX_DELAY_MS = 300_000;
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {};
+}
+
+function retryAfter(error: unknown, now: number): number {
+  const fields = recordOf(error);
+  if (typeof fields.retryAfterMs === 'number' && Number.isFinite(fields.retryAfterMs))
+    return Math.max(0, fields.retryAfterMs);
+  const headers = fields.headers ?? recordOf(fields.response).headers ?? fields.metadata;
+  const get = recordOf(headers).get;
+  const raw: unknown = typeof get === 'function' ? get.call(headers, 'retry-after') : recordOf(headers)['retry-after'];
+  return retryDelay(Array.isArray(raw) ? raw[0] : raw, now);
+}
+
+function retryDelay(value: unknown, now: number): number {
+  if (typeof value !== 'string' && typeof value !== 'number') return 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(String(value));
+  return Number.isFinite(date) ? Math.max(0, date - now) : 0;
+}
+
+function rateLimited(error: unknown): boolean {
+  const fields = recordOf(error);
+  return fields.code === 8 || fields.code === 429 || fields.status === 429 ||
+    /resource.?exhausted|resource has been exhausted|exceeds rate limit|\b429\b/i.test(errMsg(error));
+}
+
+export class NetworkBackoff {
+  private until = 0;
+  private delay = RATE_DELAY_MS;
+  private reason = '';
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  remaining(): number {
+    return Math.max(0, this.until - this.now());
+  }
+
+  note(error: unknown): void {
+    if (!rateLimited(error)) return;
+    const now = this.now();
+    if (now < this.until) {
+      this.until = Math.max(this.until, now + retryAfter(error, now));
+      return;
+    }
+    if (now - this.until >= MAX_DELAY_MS) this.delay = RATE_DELAY_MS;
+    this.until = now + Math.max(this.delay, retryAfter(error, now));
+    this.delay = Math.min(this.delay * 2, MAX_DELAY_MS);
+    this.reason = errMsg(error);
+  }
+
+  async run<T>(task: () => Promise<T>): Promise<T> {
+    const remaining = this.remaining();
+    if (remaining > 0)
+      throw new TrainError('xmtp_rate_limited', `XMTP is rate limited; retry in ${Math.ceil(remaining / 1000)}s. ${this.reason}`, {
+        retryable: true, retryAfterMs: remaining,
+      });
+    try {
+      return await task();
+    } catch (error) {
+      this.note(error);
+      throw error;
+    }
+  }
+}
+
+export const network = new NetworkBackoff();
+
+export class SyncRequests {
+  private tail: Promise<unknown> = Promise.resolve();
+  private readonly pending = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+  constructor(
+    private readonly backoff: NetworkBackoff = network,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  run(owner: object, id: string, task: () => Promise<unknown>): Promise<unknown> {
+    let requests = this.pending.get(owner);
+    if (!requests) {
+      requests = new Map();
+      this.pending.set(owner, requests);
+    }
+    const previous = requests.get(id);
+    if (previous) return previous;
+    const queuedAt = this.now();
+    const run = () => {
+      if (this.now() - queuedAt >= 30_000)
+        throw new TrainError('xmtp_sync_busy', 'XMTP sync waited 30s; retry the request.', { retryable: true });
+      return this.backoff.run(task);
+    };
+    const pending = this.tail.then(run, run).finally(() => { requests.delete(id); });
+    requests.set(id, pending);
+    this.tail = pending;
+    return pending;
+  }
+}
+
+const syncs = new SyncRequests();
+
+export function syncConversation(owner: object, conv: { id: string; sync: () => Promise<unknown> }): Promise<unknown> {
+  return syncs.run(owner, conv.id, () => conv.sync());
+}
+
+export function syncConversations(source: { sync: () => Promise<unknown> }): Promise<unknown> {
+  return syncs.run(source, 'directory', () => source.sync());
+}