`@trupdf/sdk`

The framework-agnostic public surface. Hosts that want a curated entry point use this; everyone else can talk to @trupdf/core directly.

TruPDFSDK

const sdk = new TruPDFSDK({ plugins: [myPlugin] });
sdk.events.on('annotation.added', ({ id, kind, page }) => /* … */);
await sdk.attach(viewerEngine);   // forward all engine events
sdk.goToPage(5);
await sdk.destroy();

Method	Purpose
`attach(engine)`	Bind a `ViewerEngine`; forwards all engine events onto `events`
`detach()`	Unbind without destroying the engine; plugins' `onDestroy` fires
`destroy()`	Detach + uninstall every plugin + clear listeners
`install(plugin)`	Install a plugin (runs `onInit`)
`uninstall(id)`	Uninstall a plugin (runs `onDestroy`)
`getAnnotations()`	`AnnotationsApi \| null` — see below
`getForms()`	`FormsApi \| null` — see below
`goToPage(n)`	Navigate
`setScale(s)`	Zoom
`rotate(deltaDeg)`	Rotate by a delta in degrees
`getPdfAClaim()`	Read the document's declared PDF/A claim (`null` if none)
`validatePdfA(options)`	Full ISO 19005 validation via the TruPDF document service
`getTaggedPdfInfo()`	`{ isTagged, suspects }` structure info
`getStructureTree(page)`	Structure tree for one page (`null` if untagged)

attach() and detach() are lifecycle-safe — call them any number of times, in any order.

EventBus

Strongly typed. Full catalog (SDKEventMap):

type SDKEventMap = {
  'document.loaded': { numPages: number };
  'document.error': { error: Error };
  'document.destroyed': void;
  'page.changed': { page: number };
  'scale.changed': { scale: number };
  'rotation.changed': { rotation: number };
  'secureMode.changed': { enabled: boolean };
  'annotation.added': { id: string; kind: string; page: number };
  'annotation.updated': { id: string; kind: string; page: number };
  'annotation.removed': { id: string };
  'annotations.cleared': void;
  'form.field.added': { id: string; kind: string };
  'form.field.updated': { id: string; kind: string };
  'form.value.changed': { id: string; value: unknown };
  'form.validation.changed': { issues: ValidationIssue[] };
  'tool.changed': { tool: string };
  'plugin.toolbar.action': { id: string; payload?: unknown };
};

AnnotationsApi

Returned by sdk.getAnnotations() once an engine with an annotation manager is attached.

Method	Purpose
`list()`	All annotation records (snapshot array)
`getById(id)`	One record or `undefined`
`add(record)`	Add; returns the new id
`update(id, patch)`	Patch an existing record
`remove(id)`	Remove
`ingest(records)`	Bulk-load without firing per-record undo steps
`clear()`	Remove everything
`on(event, handler)`	`annotation.added \| updated \| removed`, `annotations.cleared`
`off(event, handler)`	Unsubscribe

FormsApi

Returned by sdk.getForms().

Method	Purpose
`list()`	All form field records
`getValues()`	`{ fieldId: value }` snapshot map
`setValue(id, value)`	Set one value; fires `value.changed`
`fromValueMap(map)`	Bulk-set values
`on(event, handler)`	`field.added \| updated \| removed`, `value.changed`, `fields.cleared`
`off(event, handler)`	Unsubscribe

PluginAPI

Plugins are pure objects with optional lifecycle hooks:

const plugin: TruPDFPlugin = {
  id: 'my-plugin',
  toolbar: [
    {
      id: 'mark-reviewed',
      label: 'Mark reviewed',
      icon: '✓',
      handler: () => /* … */,
    },
  ],
  onInit: async (api) => { /* … */ },
};

api.listToolbarActions() / api.listSidebarPanels() / api.listMenuItems() aggregate contributions across every installed plugin so framework wrappers can render them once.