Message API/docs/components/files/api

API References

Payloads and events for file upload, tabs, metadata, PDF page workflows, and export.

Message Structure

File workflows use view, fileTabs, fileInfo, pageList/selectPage/pageManipulation, and export events.

type FileMessage =
  | { type: 'view'; payload: { fileUrl: string; displayName?: string; username?: string; email?: string } }
  | { type: 'setActiveFileByIndex'; payload: { fileIndex: number } }
  | { type: 'selectPage'; payload: { pageIndex?: number; pageNumber?: number } }
  | { type: 'pageManipulation'; payload: { requestId: string; action: string; [key: string]: unknown } }
  | { type: 'export' }
  | { type: 'print' };

type FileEvent =
  | { type: 'fileInfo'; payload: FileInfoPayload }
  | { type: 'fileTabs'; payload: FileTabsPayload }
  | { type: 'pageList'; payload: PageListPayload }
  | { type: 'selectPageResult'; payload: SelectPageResultPayload }
  | { type: 'pageManipulationResult'; payload: PageManipulationResultPayload }
  | { type: 'exportComplete'; payload: ExportCompletePayload };

Message Structure

Interfaces & Types

Reference the core payload shapes for file workflows.

view Payload

The structure used to initiate a new file session.

interface ViewPayload {
  /** The absolute, publicly accessible URL of the document to load */
  fileUrl: string;
}

fileInfo Payload

The metadata emitted by the viewer after a successful load.

interface FileInfoPayload {
  fileInfo: {
    /** The filename extracted from the URL or headers */
    name: string;
    /** The original source URL of the document */
    url: string;
    /** Logical width of the document in pixels */
    width: number;
    /** Logical height of the document in pixels */
    height: number;
    /** ISO 8601 timestamp of last modification (if available) */
    date: string;
  };
}

setActiveFileByIndex Payload

The structure of the message sent from the host.

interface SetActiveFilePayload {
  /** The 0-based index of the file to activate */
  fileIndex: number;
}

fileTabs Payload

The structure of the event emitted from the viewer.

interface FileTabsPayload {
  /** The ID of the currently active file tab */
  activeId: string;
  /** The complete list of open tabs */
  tabs: FileTab[];
}

interface FileTab {
  /** Unique identifier for the file */
  id: string;
  /** Display label for the tab */
  title: string;
  /** 0-based index, required for switching */
  index: number;
  /** Resolved file type icon */
  icon: 'pdf' | 'image' | 'cad' | 'doc' | 'generic';
}

pageList Payload

The page snapshot emitted from the viewer for host-side page rails.

interface PageListPayload {
  activeId: string;
  activeIndex: number;
  currentPage: number;
  pageCount: number;
  pages: Array<{
    index: number;
    pageNumber: number;
    title: string;
    label: string;
    isSelected: boolean;
    thumbnailDataUrl?: string;
    thumbnailWidth?: number;
    thumbnailHeight?: number;
  }>;
}

pageManipulation Payload

The host command used for page-level PDF operations.

interface PageManipulationPayload {
  requestId: string;
  action:
    | 'move-top' | 'move-bottom' | 'move-up' | 'move-down'
    | 'rotate-r' | 'rotate-l'
    | 'page-copy' | 'page-paste'
    | 'page-extract' | 'page-extract-delete' | 'page-delete'
    | 'page-insert' | 'page-replace' | 'page-insert-blank';
  pageRange?: Array<[number] | [number, number]>;
  targetPageIndex?: number;
  file?: File;
  selectedPages?: Array<[number] | [number, number]>;
  count?: number;
  width?: number;
  height?: number;
}

exportComplete Payload

The event emitted after successfully generating a file.

interface ExportCompletePayload {
  /** The direct-download URL for the exported file */
  fileUrl: string;
}