feat(mail): in-app attachments on internal mail + surface media parts in thread reads

- MailInternalDto accepts attachments[]; deposit() stores each as a media
  part (image/video→MEDIA_REF, audio→VOICE_REF, else FILE_REF)
- ingest now persists part sizeBytes; contract + DTO carry it
- threads.getMessages returns mimeType + sizeBytes so mail readers can
  render inline images / file chips
- test: internal mail stores an image attachment as a MEDIA_REF part

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/iios-service/src/mail/mail.service.ts

@@ -20,12 +20,16 @@ export function contentToParts(content: RenderedContent): { subject?: string; pa
   return { ...(content.subject != null ? { subject: content.subject } : {}), parts };
 }
 
+export interface MailAttachment { filename?: string; contentRef: string; mimeType?: string; sizeBytes?: number }
+
 export interface PostInternalInput {
   source: TemplateSource;
   recipientUserId: string;
   vars?: Record<string, unknown>;
   locale?: string;
   idempotencyKey: string;
+  /** In-app attachment refs — stored as FILE message parts alongside the body. */
+  attachments?: MailAttachment[];
 }
 
 export interface SendExternalInput {
@@ -65,7 +69,7 @@ export class MailService {
 
   async postInternal(principal: MessagePrincipal, input: PostInternalInput): Promise<{ threadId: string; interactionId: string }> {
     const { content } = await this.templates.render(input.source, input.vars ?? {}, { channel: 'INTERNAL', ...(input.locale ? { locale: input.locale } : {}) });
-    return this.deposit(principal, input.recipientUserId, content, input.idempotencyKey, 'PORTAL');
+    return this.deposit(principal, input.recipientUserId, content, input.idempotencyKey, 'PORTAL', input.attachments);
   }
 
   async sendExternalWithMirror(principal: MessagePrincipal, input: SendExternalInput): Promise<{ commandId: string; mirror?: { threadId: string; interactionId: string } }> {
@@ -79,13 +83,21 @@ export class MailService {
     if (!input.mirrorToUserId) return { commandId: command.id };
 
     const { content } = await this.templates.render(input.source, input.vars ?? {}, { channel: 'EMAIL', ...(input.locale ? { locale: input.locale } : {}) });
-    const mirror = await this.deposit(principal, input.mirrorToUserId, content, `mirror:${input.idempotencyKey}`, 'EMAIL');
+    const mirror = await this.deposit(principal, input.mirrorToUserId, content, `mirror:${input.idempotencyKey}`, 'EMAIL', input.attachments);
     return { commandId: command.id, mirror };
   }
 
+  /** A stored media ref → a message part; kind follows the mime (image/video → MEDIA_REF, audio → VOICE_REF, else FILE_REF). */
+  private attachmentPart(a: MailAttachment): { kind: 'MEDIA_REF' | 'VOICE_REF' | 'FILE_REF'; bodyText?: string; contentRef: string; mimeType?: string; sizeBytes?: number } {
+    const mime = a.mimeType ?? '';
+    const kind = /^(image|video)\//.test(mime) ? 'MEDIA_REF' : /^audio\//.test(mime) ? 'VOICE_REF' : 'FILE_REF';
+    return { kind, ...(a.filename ? { bodyText: a.filename } : {}), contentRef: a.contentRef, ...(a.mimeType ? { mimeType: a.mimeType } : {}), ...(a.sizeBytes != null ? { sizeBytes: a.sizeBytes } : {}) };
+  }
+
   /** Ingest the rendered content as an EMAIL interaction on a per-email thread, visible to both parties. */
-  private async deposit(principal: MessagePrincipal, recipientUserId: string, content: RenderedContent, key: string, channelType: string): Promise<{ threadId: string; interactionId: string }> {
+  private async deposit(principal: MessagePrincipal, recipientUserId: string, content: RenderedContent, key: string, channelType: string, attachments?: MailAttachment[]): Promise<{ threadId: string; interactionId: string }> {
     const { subject, parts } = contentToParts(content);
+    const allParts = [...parts, ...(attachments ?? []).map((a) => this.attachmentPart(a))];
     const res = await this.ingest.ingest(
       {
         scope: { orgId: principal.orgId, appId: principal.appId, ...(principal.tenantId ? { tenantId: principal.tenantId } : {}) },
@@ -93,7 +105,7 @@ export class MailService {
         source: { handleKind: 'PORTAL_USER', externalId: principal.userId, ...(principal.displayName ? { displayName: principal.displayName } : {}) },
         kind: 'EMAIL',
         thread: { externalThreadId: key, ...(subject ? { subject } : {}) },
-        parts,
+        parts: allParts,
         occurredAt: new Date().toISOString(),
         providerEventId: key,
       },