Types

interface SDKInitOptions {
  license?: string; // Your license token — see Licensing
  engineUrl?: string; // A self-hosted copy of pdf-engine.bin — self-hosting licenses only; see Engine Binary Setup
  shaperUrl?: string; // A self-hosted copy of pdf-shaper.bin — likewise
  subsetterUrl?: string; // A self-hosted copy of pdf-subset.bin — likewise
  workerUrl?: string; // URL to render.worker.js — see Web Worker Rendering
  styleNonce?: string; // The page's CSP nonce, carried by every stylesheet the SDK injects — see Content security policy
  licensePopup?: LicensePopupOptions; // The "License required" popup in your own words — see Licensing
}

interface LicensePopupOptions {
  title?: string; // Default: "License required"
  text?: string; // The body, in place of the SDK's sentence naming the reason
  closeLabel?: string; // Default: "Close"
}

interface PDFViewerConfig {
  mode?: SDKMode; // Default: SDKMode.FULL
  tools?: ToolsConfig; // Per-tool visibility
  defaultTool?: 'selectText' | 'pan' | null; // The resting tool. Default: 'selectText'
  forms?: FormsConfig; // Form field behavior
  export?: ExportConfig; // Export defaults
  confirmations?: boolean | ConfirmationsConfig; // Ask before deleting, discarding or replacing. Default: true
  fonts?: FontsConfig; // Font loading & custom fonts
  toolbar?: ToolbarConfig; // Top toolbar
  navigation?: NavigationBarConfig; // Bottom navigation bar
  sidebar?: SidebarConfig; // The side panels: pages, outline, attachments, signatures, comments
  links?: LinksConfig; // The document's links: clickable, confirmed, named
  print?: PrintConfig; // Whether Print asks first
  theme?: ThemeConfig; // Visual theme
  locale?: LocaleConfig; // Language and translations
  callbacks?: CallbacksConfig; // Lifecycle callbacks
  performance?: PerformanceConfig; // Rendering performance
  accessibility?: AccessibilityConfig; // Accessible text layer
  loader?: LoaderConfig; // Loading indicator branding
  annotations?: AnnotationsConfig; // Comment author, review rule, colors and weights
  layout?: LayoutConfig; // Responsive layout & bar placement
}

type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode]

type GlobalEventMap = {
  initialized: { version: string };
  licenseChanged: LicenseState;
  documentLoaded: { document: PDFDocument; pageCount: number; hasPassword: boolean };
  documentClosed: { document: PDFDocument };
}

type ViewerEventMap = {
  pageChanged: { pageIndex: number };
  zoomChanged: { scale: number };
  toolChanged: { tool: ToolName | null; previous: ToolName | null };
  panelChanged: { panel: SidebarTab | null; previous: SidebarTab | null };
  pagesChanged: { pageCount: number };
  formFieldChanged: { field: FormFieldInfo };
  formFieldFocused: { field: FormFieldInfo };
  formFieldBlurred: { field: FormFieldInfo };
  signatureCaptured: { fieldName: string; pageIndex: number; method: 'draw' | 'type' | 'upload' | 'host'; dataUrl: string };
  textChanged: { changes: TextChange[] };
  documentChanged: { source: DocumentChangeSource; tool?: ToolName; hasUnsavedChanges: boolean; canUndo: boolean; canRedo: boolean };
  contentPlaced: { tool: ToolName; pageIndex: number };
  annotationsChanged: { pageIndex: number; changes: AnnotationChange[] };
  commentsChanged: { pageIndex: number; changes: CommentChange[] };
  error: { code: ErrorCodeValue; message: string; fatal: boolean };
  savedSignaturesChanged: { signatures: SavedSignature[] };
  userStampsChanged: { stamps: SavedStamp[] };
  exportStarted: Record<string, never>;
  exportCompleted: { sizeBytes: number; partial: boolean; pdfA?: 'kept' | 'dropped' };
}

type SDKEventMap = GlobalEventMap & ViewerEventMap

type EventHandler<T> = (data: T) => void

interface SubscribeOptions {
  once?: boolean; // Call the handler once, for the next emit, then unsubscribe it
  signal?: AbortSignal; // Unsubscribe when this signal aborts; a signal already aborted subscribes nothing
}

type GlobalEvents = Pick<EventEmitter<GlobalEventMap>, 'on' | 'off'>

type LicenseState = LicenseStateValid | LicenseStateInvalid;

interface LicenseStateValid {
  valid: true;
  watermark: boolean; // true while output is marked: a development token
  env: 'development' | 'production';
  plan: string;
  features: LicenseFeature[]; // the features this SDK version enforces that the license names, in a fixed order
  expiresAt?: Date; // only on a license with an expiry date
  offline: boolean; // air-gapped: no status check, no network calls
  reason?: undefined;
  pauseReason?: undefined;
}

interface LicenseStateInvalid {
  valid: false;
  watermark: true; // unlicensed output is marked
  reason: LicenseInvalidReason; // why the license is not valid
  pauseReason?: LicensePauseReason; // why, when reason is 'paused'
  env?: undefined;
  plan?: undefined;
  features?: undefined;
  expiresAt?: undefined;
  offline?: undefined;
}

type LicenseFeature = 'edit-text' | 'add-text' | 'edit-pages' | 'annotations' | 'forms' | 'export' | 'print' | 'extract'

type LicenseInvalidReason =
  | 'no-license'
  | 'insecure-context' // plain HTTP: the SDK runs only over HTTPS or on localhost
  | 'malformed'
  | 'unsupported-algorithm'
  | 'invalid-signature'
  | 'not-yet-valid'
  | 'expired'
  | 'origin-mismatch'
  | 'wrong-holder' // the token was issued to another browser and copied to this one
  | 'revoked'
  | 'paused' // see LicensePauseReason
  | 'stale'; // not confirmed by the licensing API for more than 48 hours, or never on this browser

type LicensePauseReason = 'payment' | 'suspended' | 'term_ended' | 'trial_ended' | 'other'

interface OpenOptions {
  password?: string; // The password of an encrypted file
}

interface OpenUrlOptions extends OpenOptions {
  signal?: AbortSignal; // Aborting it rejects the load with ABORTED
  headers?: Record<string, string>; // Request headers, as fetch() takes them — an Authorization header, say
  credentials?: RequestCredentials; // fetch()'s credentials: 'omit', 'same-origin' or 'include'
}

interface OpenProgressiveOptions extends OpenUrlOptions {
  chunkSize?: number; // Range-request size in bytes. Default: 256 KiB
  onProgress?: (downloaded: number, total: number) => void; // Download progress
}

interface DocumentMetadata {
  title: string;
  author: string;
  subject: string;
  keywords: string; // as the file lists them, one string
  creator: string; // the application that produced the document
  producer: string; // the application that wrote the file
  creationDate: Date | null; // null when the file does not say, which is often
  modifiedDate: Date | null; // null when the file does not say. A save sets it
}

interface FormFieldInfo {
  name: string;
  type: FormFieldType; // 'text' | 'checkbox' | 'radio' | 'dropdown' | 'listbox' | 'signature'
  value: string;
  pageIndex: number;
  rect: Rect; // the widget's box, in page space — see Coordinates
  options?: { label: string; value: string; selected: boolean }[];
  readOnly: boolean;
  required: boolean;
  noExport: boolean; // left out of a form submission
  multiline: boolean; // a text field of several lines
  password: boolean; // a text field shown as dots
  comb: boolean; // a text field spread over maxLength equal cells
  multiSelect: boolean; // a list box that takes several choices
  hidden: boolean; // Hidden/NoView: no editor is drawn; still filled, read and exported
  maxLength?: number;
  exportValue?: string; // AcroForm export value ("on state") of checkbox/radio widgets
  dateFormat?: string; // a date field's format ('mm/dd/yyyy', 'd-mmm-yy' …), from its AFDate_* script
  signature?: 'digital' | 'appearance'; // a signature field that holds a digital signature, or only shows one (signed earlier, or in this viewer this session)
  format?: FieldFormat; // how it shows its value: number, percent, date, time, special, mask
  range?: FieldRange; // the values it accepts, { min?, max? }
  calculation?: FieldCalculation; // what it computes from other fields
  look?: FieldLook; // the box its widget draws: { background?, border?, borderWidth, borderStyle }
  rotation?: number; // 90 | 180 | 270: its widget's content turned counterclockwise on the page
}

type FormType = 'none' | 'acroform' | 'xfa' | 'xfa-foreground'

type FormValue = string | string[]; // an array: a multi-select list box's choices

interface SetFieldResult {
  applied: string[]; // field names successfully set
  rejected: { name: string; reason: SetFieldRejectionReason }[];
}

type SetFieldRejectionReason = 'unknown_field' | 'read_only' | 'invalid_value' | 'unsupported_type'

type FieldFormat =
  | {
      kind: 'number';
      decimals: number;
      separator: number; // 0 1,234.56 · 1 1234.56 · 2 1.234,56 · 3 1234,56 · 4 1'234.56
      negative: number; // 0 -1,234.56 · 1 red · 2 (1,234.56) · 3 red in parentheses
      currency: string;
      currencyPrepend: boolean; // the currency before the number, else after
    }
  | { kind: 'percent'; decimals: number; separator: number; percentPrepend: boolean } // the value × 100
  | { kind: 'date'; format: string } // 'mm/dd/yyyy' …; the value is stored in this format
  | { kind: 'time'; format: string } // 'h:MM tt' …
  | { kind: 'special'; special: 'zip' | 'zip4' | 'phone' | 'ssn' } // stored as its digits
  | { kind: 'mask'; mask: string }; // 9 a digit, A a letter, O either, X anything

interface FieldRange { min?: number; max?: number } // both included; either may be absent

type FieldCalculation =
  | { kind: 'simple'; operation: 'SUM' | 'PRD' | 'AVG' | 'MIN' | 'MAX'; fields: string[] } // a group's name takes every field in it
  | { kind: 'expression'; expression: string }; // field names, numbers, + - * / and parentheses

interface FieldLook {
  background?: string; // '#rrggbb', absent when the widget draws none
  border?: string; // likewise
  borderWidth: number; // points
  borderStyle: 'solid' | 'dashed' | 'beveled' | 'inset' | 'underline';
}

interface AnnotationInfo {
  pageIndex: number;
  id: string; // its name when the file names it, else derived from its object in the file; never ''
  type: AnnotationType;
  rect: Rect | null;
  contents: string; // '' without the extract feature
  author: string; // '' without the extract feature
  color: string | null; // '#rrggbb': a shape's stroke, a mark's or note's own color; null for none
  opacity: number; // 0–1
  fillColor: string | null; // a shape's fill, '#rrggbb'
  created: Date | null;
  modified: Date | null;
  quads: Quad[];
  inkList: Point[][];
  vertices: Point[]; // a polygon's or polyline's corners; empty for other kinds
  line: { start: Point; end: Point } | null;
  lineEndings: { start: LineEnding; end: LineEnding } | null; // a line's caps; null for other kinds
  strokeWidth: number | null; // a square's, circle's, line's, drawing's, polygon's or polyline's (pt); null for other kinds or none stated
  uri: string | null; // a web link's address; '' without the extract feature
  targetPage: number | null;
  flags: AnnotationFlags; // its flags as booleans
  inReplyTo: string | null; // a reply's or status's comment, by id
  status: ReviewStatus | null; // the status a status entry records
}

type AnnotationType =
  // text marks — the selection bar's Highlight, Underline, Squiggly underline and Strikethrough; create() takes these
  | 'highlight' | 'underline' | 'squiggly' | 'strikeout'
  | 'note' | 'link' | 'square' | 'circle' | 'line' | 'ink' | 'polygon' | 'polyline' // and these
  | 'freeText' | 'stamp' | 'widget' | 'other'; // list() also reports these

interface NewAnnotation {
  type:
    | 'highlight' | 'underline' | 'squiggly' | 'strikeout'
    | 'note' | 'link' | 'square' | 'circle' | 'line' | 'ink' | 'polygon' | 'polyline';
  rect: Rect;
  contents?: string;
  author?: string;
  color?: string | null; // any CSS color string the API takes; its alpha is the opacity unless opacity is given
  opacity?: number; // 0–1
  fillColor?: string | null; // a square's, circle's or polygon's fill; drawn at opacity
  quads?: Quad[]; // a text mark's lines; omitted, it covers rect
  line?: { start: Point; end: Point };
  inkList?: Point[][];
  vertices?: Point[]; // a polygon's corners, three or more; a polyline's, two or more
  strokeWidth?: number | null; // up to 14 400 pt; 0: no outline on a square, circle or polygon; omitted: 1
  lineEndings?: { start?: LineEnding; end?: LineEnding } | null; // a line's; omitted: 'none'
  borderStyle?: BorderStyle | null; // a shape's outline; omitted: 'solid'; 'cloudy' on a square, circle or polygon only
  uri?: string;
  targetPage?: number;
  id?: string; // your own, written as its name and saved for every reader; at most 256 chars, no control chars, unused in the document
  flags?: Partial<AnnotationFlags>; // a flag left out is off; it prints unless noPrint
  created?: Date; // omitted: now
  modified?: Date; // omitted: the same as created
}

interface AnnotationUpdate { rect?: Rect; contents?: string; author?: string; color?: string; fillColor?: string; opacity?: number }

interface CommentThread {
  comment: AnnotationInfo; // the note, highlight, shape or stamp commented on
  replies: AnnotationInfo[]; // replies to replies included, oldest first
  statuses: AnnotationInfo[]; // each reviewer's latest status entry, oldest first
  status: ReviewStatus | null; // the latest any reviewer set
}

interface NewReply { contents: string; author?: string }

type ReviewStatus = 'accepted' | 'rejected' | 'cancelled' | 'completed' | 'none'

interface CommentPermissions {
  reply: boolean; // Write a reply under it
  setStatus: boolean; // Set their review status on it
  edit: boolean; // Change its words
  delete: boolean; // Delete it, with its thread
}

interface CommentChange {
  type: 'added' | 'edited' | 'deleted' | 'replied' | 'status';
  id: string; // the comment's id, as doc.annotations addresses it
}

interface AnnotationChange {
  type: 'added' | 'modified' | 'deleted';
  id: string; // the annotation's id, as doc.annotations addresses it
}

interface TextChange {
  pageIndex: number;
  blockId: string; // the id the block had in the session that ended, as listBlocks() listed it then
  kind: 'text' | 'style' | 'box' | 'deleted';
  oldText: string; // the block's text as the session found it, its lines joined by one space
  newText: string; // as the commit left it; the same as oldText for 'style' or 'box', empty for 'deleted'
}

type DocumentChangeSource = 'tool' | 'pages' | 'outline' | 'attachments' | 'comments' | 'forms' | 'api' | 'undo' | 'redo'

type XFDFSkipReason = 'unsupported' | 'no_page' | 'invalid' | 'no_parent'

type BorderStyle = 'solid' | 'dashed' | 'dotted' | 'cloudy'; // a cloud goes only round a rectangle, ellipse or polygon

type LineEnding = 'none' | 'square' | 'circle' | 'diamond' | 'openArrow' | 'closedArrow'
  | 'butt' | 'rOpenArrow' | 'rClosedArrow' | 'slash';

interface SearchMatch { pageIndex: number; text: string; rects: Rect[] }

interface DocumentPermissions { // all optional in protect(); all present in permissions
  print?: boolean;
  printHighQuality?: boolean;
  modify?: boolean;
  copy?: boolean;
  annotate?: boolean;
  fillForms?: boolean;
  extractForAccessibility?: boolean;
  assemble?: boolean;
}

interface ProtectionSettings { userPassword?: string; ownerPassword?: string; permissions?: DocumentPermissions; invalidateSignatures?: boolean }

interface OutlineNode {
  title: string;
  pageIndex: number | null; // null when the bookmark has no page (it only groups children)
  children: OutlineNode[];
}

interface AttachmentInfo {
  index: number; // pass to doc.attachments.data / delete
  name: string; // as stored in the file: untrusted input
  size: number; // bytes; 0 when the entry has no file stream
}

interface SignatureInfo {
  index: number;
  reason: string; // '' when absent
  signedAt: Date | null; // when it was signed, as the signature says; null when it does not
  subFilter: string; // the signature's format as the file names it ('adbe.pkcs7.detached', …), or ''
  changesAllowed: SignatureChangesAllowed | null; // what the signer allowed afterwards; null when unsaid
  signed: boolean; // whether it holds signature bytes, or is a field still to be signed
}

type SignatureChangesAllowed = 'none' | 'forms' | 'annotations'

interface SignedDocumentOptions {
  invalidateSignatures?: boolean; // Go ahead although the signature would not survive it
}

interface PageBoxes { // every box a Rect in page space, resolved as a reader resolves it
  mediaBox: Rect; // the full sheet; US Letter when the file has none
  cropBox: Rect; // what renders; the MediaBox when the file declares none
  trimBox: Rect; // the CropBox when the file declares none
  bleedBox: Rect; // likewise
  artBox: Rect; // likewise
}

type PageTurn = 90 | 180 | 270 | -90 | -180 | -270

type PageOrientation = 0 | 90 | 180 | 270

interface EditableTextBlock {
  id: string; // stable within one detection pass
  pageIndex: number;
  text: string; // including an uncommitted edit
  bounds: Rect; // in page space — see Coordinates
  fontFamily: string; // as named in the PDF
  fontSize: number; // points
  fontWeight: number; // 100–900
  isItalic: boolean;
  fillColor: string; // '#rrggbb'
  opacity: number; // 0–1
}

interface ExportOptions {
  flatten?: boolean; // Override the configured flatten behavior for this export
  invalidateSignatures?: boolean; // Flatten a signed document anyway; the signature reads as broken afterwards
  pages?: number[]; // Only these pages (zero-based, in this order)
  onProgress?: (done: number, total: number) => void; // Called per page while the export prepares pages
  signal?: AbortSignal; // Aborting cancels the export; it rejects with ABORTED
}

interface UploadOptions extends ExportOptions {
  method?: string; // HTTP method. Default: 'PUT'
  headers?: Record<string, string>; // Content-Type: application/pdf unless these name one (any case)
  credentials?: RequestCredentials; // fetch()'s; 'same-origin' by default, 'include' for a cookie-authenticated endpoint on another origin
}

interface DownloadResult { sizeBytes: number; pdfA?: 'kept' | 'dropped' }

type ToolName =
  | 'pan' // Pan/scroll mode
  | 'selectText' // Text selection mode
  | 'addText' // Click-to-place text
  | 'editText' // Inline edit existing PDF text
  | 'sign' // Electronic signature
  | 'arrow' // Arrow drawing
  | 'draw' // Freehand drawing
  | 'line' // Line drawing
  | 'rectangle' // Rectangle drawing
  | 'ellipse' // Ellipse drawing
  | 'polygon' // Polygon drawing
  | 'polyline' // Polyline drawing
  | 'check' // Check mark
  | 'cross' // Cross mark
  | 'dot' // Dot mark
  | 'erase' // Universal eraser (click to delete any object)
  | 'highlight' // Area highlight annotation
  | 'textHighlight' // Text selection highlight annotation
  | 'image' // Image insertion
  | 'stamp' // Stamp placement (APPROVED, DRAFT, etc.)
  | 'link' // URL or internal page link annotation
  | 'note' // Sticky note annotation
  | 'freeText' // Text box: a free-text comment
  | 'search' // Text search: a panel, not a tool
  | 'managePages' // Page management: a panel, not a tool
  | 'security'; // Password protection and permissions

interface ToolBlockedReason {
  reason: 'permission' | 'certified' | 'downloading';
  message: string; // the reason in words, in the viewer's language
}

type SidebarTab = 'pages' | 'outline' | 'attachments' | 'signatures' | 'comments'

interface Point { x: number; y: number }

interface Size { width: number; height: number }

interface Rect extends Point, Size {} // its bottom-left corner and its size; width and height never negative

interface RectEdges { left: number; bottom: number; right: number; top: number } // how a PDF file stores a rectangle

interface Quad { topLeft: Point; topRight: Point; bottomLeft: Point; bottomRight: Point } // one line a text mark covers

interface ColorOption {
  color: string; // '#rgb' or '#rrggbb'; stored and written as '#RRGGBB'
  label: string; // What the color is called: tooltip and screen-reader name. Empty: the hex
}

type ColorList = readonly (string | ColorOption)[]

interface SignatureFont {
  family: string; // A CSS font-family value — load the face yourself (@font-face)
  label: string; // The name shown beside the preview
}

interface SavedSignature {
  dataUrl: string; // The signature, as a PNG data URL
  initialsDataUrl?: string | null; // The initials, as a PNG data URL, when the user typed them
  name?: string; // The typed name, for labeling the row; empty for a drawn or uploaded one
  method: 'draw' | 'type' | 'upload';
}

type SavedStamp =
  | {
      kind: 'text';
      label: string; // The wording
      color: string; // '#RRGGBB'
      dated: boolean; // The placing date under the wording
      border: 'boxed' | 'ribbon' | 'plain';
    }
  | {
      kind: 'image';
      label: string;
      dataUrl: string; // The picture, as a PNG data URL
      widthPt: number; // Its size on the page, in points
      heightPt: number;
    };

interface StampPreset {
  label: string; // The wording, written into the PDF as given — e.g. 'PAID', 'BEZAHLT'
  color?: string; // Hex ink. Default: the first of inks
  dated?: boolean; // Add the placing date under the wording. Default: false
  border?: 'boxed' | 'ribbon' | 'plain'; // Default: 'boxed'
}

interface CustomFont {
  id: string; // Unique font identifier
  displayName: string; // Name shown in font picker
  ttfUrl?: string; // URL to TTF file (fetched on demand)
  ttfBytes?: Uint8Array; // Pre-loaded TTF bytes (skips fetch)
  category?: 'sans-serif' | 'serif' | 'monospace' | 'display'; // default 'sans-serif'
  cssFallback?: string; // CSS font-family stack for previews; default the display name, then sans-serif
}

interface FontDefinition {
  id: string;
  displayName: string;
  category: 'sans-serif' | 'serif' | 'monospace' | 'display';
  source: 'standard' | 'bundled' | 'custom';
  cssFallback: string; // CSS font-family stack for previews
  ttfPath?: string; // file name under fonts.fontsBaseUrl (self-hosting)
  ttfUrl?: string; // custom fonts
  ttfBytes?: Uint8Array; // custom fonts
}

type ConfirmableAction =
  | 'deleteTextBlock'
  | 'deletePages'
  | 'discardPageEdits'
  | 'deleteComment'
  | 'deleteBookmark'
  | 'deleteAnnotation'
  | 'removeAttachment'
  | 'replaceSignature';

interface ToolbarAction {
  id: string; // Your own name for the action; the SDK uses it only to name the action in an error report
  label: string; // Button text
  icon?: string; // An IconName, or raw SVG markup starting with <svg
  variant?: 'default' | 'primary'; // 'primary' = accent-colored
  onClick: () => void | Promise<void>;
}

type ToolbarLayout = 'bar' | 'ribbon' | 'none' | 'rail'

type IconName = keyof typeof ICONS

type UIStrings = { readonly [K in UIStringKey]: string }

type UIStringKey = keyof typeof EN_STRINGS; // 'tool.highlight', 'download.title', …

type LayoutSize = 'comfortable' | 'compact' | 'narrow' | 'tiny'

type BarPosition = 'top' | 'bottom'

type ToolOverflowMode = 'menu' | 'scroll'

type PanelDisplayMode = 'auto' | 'push' | 'overlay'

type PointerKind = 'fine' | 'coarse'

type PhoneLayout = 'sheet' | 'dock' | 'split' | 'float' | 'none'

type TabletLayout = 'rail' | 'none'

type TextEditSurface = 'auto' | 'inline' | 'sheet'

type TextBlockDetection = 'rows' | 'paragraphs'

interface DropZone {
  readonly element: HTMLElement;
  open: () => void; // Opens the file picker — wire it to Ctrl+O
  destroy: () => void;
}

interface PasswordPrompt {
  readonly element: HTMLElement;
  destroy: () => void;
}

interface LoadErrorCard {
  readonly element: HTMLElement;
  destroy: () => void;
}