feat(appservice): Matrix Application Service core library (M4a) (#530)

packages/appservice/src/bridge.dto.ts

@@ -0,0 +1,52 @@
+/** DTOs for the internal bridge API consumed by agent-comms host daemons. */
+
+export interface BridgeMessageDto {
+  room_id: string;
+  /** Agent slug (localpart suffix), e.g. "pi0-web1". */
+  agent: string;
+  body: string;
+  thread_root?: string;
+  msgtype?: string;
+  /** Optional protocol payload merged into content (e.g. org.uscllc.agent). */
+  extra_content?: Record<string, unknown>;
+}
+
+export interface BridgeTypingDto {
+  room_id: string;
+  agent: string;
+  typing: boolean;
+}
+
+const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
+
+const assertAgentSlug = (agent: unknown): void => {
+  if (typeof agent !== 'string' || !AGENT_SLUG_RE.test(agent.toLowerCase())) {
+    throw new Error('agent must match [a-z0-9][a-z0-9_.-]*');
+  }
+};
+
+export function validateBridgeMessage(input: unknown): asserts input is BridgeMessageDto {
+  const o = input as Partial<BridgeMessageDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.body !== 'string') throw new Error('body must be a string');
+  if (o.thread_root !== undefined && typeof o.thread_root !== 'string')
+    throw new Error('thread_root must be a string');
+  if (
+    o.extra_content !== undefined &&
+    (typeof o.extra_content !== 'object' || o.extra_content === null)
+  ) {
+    throw new Error('extra_content must be an object');
+  }
+}
+
+export function validateBridgeTyping(input: unknown): asserts input is BridgeTypingDto {
+  const o = input as Partial<BridgeTypingDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
+}