Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
6.3 KB
Raw Blame
/** Canonical chat-attachment policy and boundary parsing.
 *
 * Messages historically stored one descriptor in `messages.attachment`; email
 * and newer clients also need ordered lists. Keep the persisted/wire value
 * tolerant while giving application code one normalized shape. This module is
 * deliberately storage-free so the browser, server, and tests can share it.
 */

export const ATTACHMENT_MAX_FILES = 16
export const ATTACHMENT_MAX_FILE_BYTES = 25 * 1024 * 1024
export const ATTACHMENT_MAX_TOTAL_BYTES = 25 * 1024 * 1024
export const ATTACHMENT_TEXT_EXCERPT_BYTES = 50 * 1024

export const ATTACHMENT_KINDS = ['img', 'pdf', 'file', 'fig'] as const
export type AttachmentKind = (typeof ATTACHMENT_KINDS)[number]

export interface AttachmentDescriptor {
  readonly name: string
  readonly kind: AttachmentKind
  readonly url?: string
  readonly key?: string
  readonly mime?: string
  readonly size?: number
  /** Renderer-only legacy label used by old mock rows. */
  readonly meta?: string
}

export type AttachmentInput = AttachmentDescriptor | readonly AttachmentDescriptor[]

export type AttachmentValidationIssue =
  | 'invalid-shape'
  | 'too-many-files'
  | 'file-too-large'
  | 'total-too-large'

export type AttachmentValidationResult =
  | { readonly ok: true; readonly attachments: readonly AttachmentDescriptor[] }
  | { readonly ok: false; readonly issue: AttachmentValidationIssue; readonly index?: number }

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
}

function isAttachmentKind(value: unknown): value is AttachmentKind {
  return typeof value === 'string' && (ATTACHMENT_KINDS as readonly string[]).includes(value)
}

function nonEmptyString(value: unknown): string | null {
  if (typeof value !== 'string') return null
  const trimmed = value.trim()
  return trimmed ? trimmed : null
}

function parseOne(value: unknown): AttachmentDescriptor | null {
  if (!isRecord(value)) return null
  const name = nonEmptyString(value.name)
  if (!name || !isAttachmentKind(value.kind)) return null

  const parsedUrl = value.url === undefined ? undefined : nonEmptyString(value.url)
  const parsedKey = value.key === undefined ? undefined : nonEmptyString(value.key)
  if (value.url !== undefined && parsedUrl === null) return null
  if (value.key !== undefined && parsedKey === null) return null
  const url = parsedUrl ?? undefined
  const key = parsedKey ?? undefined
  if (url === undefined && key === undefined && value.meta === undefined) return null

  const parsedMime = value.mime === undefined ? undefined : nonEmptyString(value.mime)
  if (value.mime !== undefined && parsedMime === null) return null
  const mime = parsedMime ?? undefined
  const parsedMeta = value.meta === undefined ? undefined : nonEmptyString(value.meta)
  if (value.meta !== undefined && parsedMeta === null) return null
  const meta = parsedMeta ?? undefined
  if (value.size !== undefined && (typeof value.size !== 'number'
    || !Number.isSafeInteger(value.size) || value.size <= 0)) return null

  return {
    name,
    kind: value.kind,
    ...(url === undefined ? {} : { url }),
    ...(key === undefined ? {} : { key }),
    ...(mime === undefined ? {} : { mime: mime.toLowerCase() }),
    ...(value.size === undefined ? {} : { size: value.size }),
    ...(meta === undefined ? {} : { meta }),
  }
}

/** Parse the old single-object wire value or the canonical array. A missing
 * value is an empty attachment list; malformed entries reject the whole value
 * so a router cannot partially persist a multi-file message. */
export function validateAttachmentInput(value: unknown): AttachmentValidationResult {
  if (value === null || value === undefined) return { ok: true, attachments: [] }
  if (Array.isArray(value) && value.length === 0) return { ok: true, attachments: [] }
  if (Array.isArray(value) && value.length > ATTACHMENT_MAX_FILES) {
    return { ok: false, issue: 'too-many-files' }
  }

  const raw = Array.isArray(value) ? value : [value]
  const attachments: AttachmentDescriptor[] = []
  let totalBytes = 0
  for (let index = 0; index < raw.length; index++) {
    const attachment = parseOne(raw[index])
    if (!attachment) return { ok: false, issue: 'invalid-shape', index }
    if (attachment.size !== undefined) {
      if (attachment.size > ATTACHMENT_MAX_FILE_BYTES) {
        return { ok: false, issue: 'file-too-large', index }
      }
      totalBytes += attachment.size
      if (totalBytes > ATTACHMENT_MAX_TOTAL_BYTES) {
        return { ok: false, issue: 'total-too-large', index }
      }
    }
    attachments.push(attachment)
  }
  return { ok: true, attachments }
}

/** Normalize a persisted single attachment to a list, and pass through a
 * canonical list. Invalid legacy data becomes empty rather than crashing a
 * historical-message read. */
export function normalizeAttachments(value: unknown): readonly AttachmentDescriptor[] {
  const parsed = validateAttachmentInput(value)
  return parsed.ok ? parsed.attachments : []
}

export function attachmentTotalBytes(attachments: readonly AttachmentDescriptor[]): number {
  return attachments.reduce((total, attachment) => total + (attachment.size ?? 0), 0)
}

export type AttachmentSelectionCheck =
  | { readonly ok: true }
  | {
      readonly ok: false
      readonly reason: 'too-many-files' | 'file-too-large' | 'total-too-large'
      readonly maxFiles?: number
      readonly maxBytes?: number
    }

/** Pure pre-upload check for the composer. Existing attachments are included
 * because aggregate policy applies to the whole send, not one picker action. */
export function checkAttachmentSelection(
  current: readonly AttachmentDescriptor[],
  incoming: readonly AttachmentDescriptor[],
): AttachmentSelectionCheck {
  const all = [...current, ...incoming]
  if (all.length > ATTACHMENT_MAX_FILES) {
    return { ok: false, reason: 'too-many-files', maxFiles: ATTACHMENT_MAX_FILES }
  }
  for (const attachment of incoming) {
    if (attachment.size !== undefined && attachment.size > ATTACHMENT_MAX_FILE_BYTES) {
      return { ok: false, reason: 'file-too-large', maxBytes: ATTACHMENT_MAX_FILE_BYTES }
    }
  }
  if (attachmentTotalBytes(all) > ATTACHMENT_MAX_TOTAL_BYTES) {
    return { ok: false, reason: 'total-too-large', maxBytes: ATTACHMENT_MAX_TOTAL_BYTES }
  }
  return { ok: true }
}