Structured Data Types

TypeScript type definitions for structured data

This page documents all TypeScript types used for structured data. These types are exported from @mirra-messenger/shared-types.

These types are auto-generated from the source code. Changes to the source types will be reflected here after regeneration.

StructuredDisplayType

Display types that determine how structured data is rendered.

type StructuredDisplayType =
  | 'list'           // List of items (contacts, chats, files, etc.)
  | 'card'           // Single card with rich details
  | 'table'          // Tabular data with rows/columns
  | 'grid'           // Grid layout (e.g., photo grid)
  | 'summary'        // Summary/stats view with aggregated info
  | 'conversation'   // Message thread or conversation view
  | 'media_grid'     // Grid of images/videos
  | 'custom';        // Custom component (requires special handling)

Currently, only list and card are fully supported in the mobile app.

StructuredData

Main container for structured data. Include this in the structuredData array when sending messages.

interface StructuredData {
  displayType: StructuredDisplayType;
  templateId: string;
  data: {
    // For 'list' display type
    items?: StructuredDisplayItem[];
 
    // For 'card' display type
    title?: string;
    subtitle?: string;
    icon?: string;
    badges?: StructuredCardBadge[];
    steps?: StructuredCardStep[];
    summary?: Record<string, string | number>;
    defaultExpanded?: boolean;
  };
  metadata?: {
    totalCount?: number;
    query?: string;
    source?: string;
    timestamp?: string | Date;
    [key: string]: any;
  };
  interactions?: StructuredDataInteractions;
  targets?: StructuredDataTarget[];
}

Property	Type	Required	Description
`displayType`	`StructuredDisplayType`	Yes	How this data should be rendered
`templateId`	`string`	Yes	Template identifier for specific rendering logic
`data`	`object`	Yes	The actual data to display (structure varies by displayType)
`metadata`	`object`	No	Metadata about the result (counts, source, etc.)
`interactions`	`StructuredDataInteractions`	No	Available user interactions
`targets`	`StructuredDataTarget[]`	No	Target entities for actions

StructuredDisplayItem

Core display item structure used in lists. Each item represents a selectable row.

interface StructuredDisplayItem {
  id: string;
  title: string;
  subtitle?: string;
  icon?: string;
  iconUrl?: string;
  badge?: string;
  badgeVariant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
  imageUrl?: string;
  metadata?: Record<string, any>;
}

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the item
`title`	`string`	Yes	Primary display text
`subtitle`	`string`	No	Secondary display text
`icon`	`string`	No	Icon identifier (e.g., 'person', 'document')
`iconUrl`	`string`	No	Custom icon image URL (overrides icon)
`badge`	`string`	No	Badge text (e.g., count, status)
`badgeVariant`	`string`	No	Badge color variant
`imageUrl`	`string`	No	Optional image URL
`metadata`	`object`	No	Additional item-specific metadata

StructuredCardStep

A step/item within a card display. Used for showing execution progress or sequential items.

interface StructuredCardStep {
  id: string;
  title: string;
  description?: string;
  status?: 'success' | 'error' | 'pending' | 'skipped';
  icon?: string;
  detail?: string;
  timestamp?: string;
  durationMs?: number;
}

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the step
`title`	`string`	Yes	Primary text for the step
`description`	`string`	No	Secondary description
`status`	`string`	No	Status indicator (affects icon and color)
`icon`	`string`	No	Icon identifier
`detail`	`string`	No	Expandable detail content (code, output)
`timestamp`	`string`	No	When this step occurred
`durationMs`	`number`	No	Duration in milliseconds

StructuredCardBadge

Badge displayed in card headers. Shows counts, status indicators, or labels.

interface StructuredCardBadge {
  label: string;
  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
}

Property	Type	Required	Description
`label`	`string`	Yes	Badge text
`variant`	`string`	No	Color variant (affects background and text color)

StructuredDataInteractions

Defines what interactions users can have with the structured data.

interface StructuredDataInteractions {
  primaryAction?: string;
  secondaryActions?: string[];
  allowSelection?: boolean;
  allowMultiSelect?: boolean;
  customActions?: Array<{
    id: string;
    label: string;
    icon?: string;
    variant?: 'default' | 'primary' | 'destructive';
  }>;
}

Property	Type	Required	Description
`primaryAction`	`string`	No	Primary action (e.g., 'view', 'edit')
`secondaryActions`	`string[]`	No	Additional available actions
`allowSelection`	`boolean`	No	Whether items are selectable
`allowMultiSelect`	`boolean`	No	Whether multiple items can be selected
`customActions`	`array`	No	Custom action buttons

StructuredDataTarget

Target entity for an action. Used to show what will be affected by an action.

interface StructuredDataTarget {
  friendlyName: string;
  technicalName: string;
  username?: string;
  type?: 'person' | 'chat' | 'group' | 'channel' | 'email' | 'file' | 'calendar' | 'other';
  icon?: string;
  iconUrl?: string;
  metadata?: Record<string, any>;
}

Property	Type	Required	Description
`friendlyName`	`string`	Yes	User-recognizable name
`technicalName`	`string`	Yes	Technical identifier (ID, email, etc.)
`username`	`string`	No	Username or handle
`type`	`string`	No	Type of target entity
`icon`	`string`	No	Icon name
`iconUrl`	`string`	No	Custom icon URL
`metadata`	`object`	No	Additional target metadata