Praetor SDK

This package provides the Praetor SDK, a custom interface and implementation for interacting with Praetor.

Prerequisites

Make sure you have Node.js and npm installed on your machine.

See Installing Node.js and npm for detailed instructions.

Installation

To use the Praetor SDK in your project, install it via npm.

Open a terminal and run the following command:

npm install @wkcz/praetor-sdk

Importing the package

TypeScript

import { Praetor } from "@wkcz/praetor-sdk";

JavaScript

const { Praetor } = require("@wkcz/praetor-sdk");

Examples

fetch(callName)

// GET request
const praetor = new Praetor();
const response = await praetor.fetch("someCallName");

fetch(callName, options)

// POST request
const praetor = new Praetor();
const response = await praetor.fetch("someCallName", { method: "POST", body: JSON.stringify({ someData: 200 }) });

fetch(callName).json()

fetch(callName, options).json()

// Bad
const praetor = new Praetor();
const response = await praetor.fetch("someCallName");
const data = JSON.parse(response.body);

// Good
const praetor = new Praetor();
const response = await praetor.fetch("someCallName");
const data = await response.json();

// Bad
const praetor = new Praetor();
const data = await praetor.fetch("someCallName").then(response => JSON.parse(response.body));

// Good
const praetor = new Praetor();
const data = await praetor.fetch("someCallName").then(response => response.json());

fetch(callName).blob()

fetch(callName, options).blob()

const praetor = new Praetor();
const response = await praetor.fetch("someCallName");
const data = await response.blob();

const praetor = new Praetor();
const data = await praetor.fetch("someCallName").then(response => response.blob());

devMode()

const praetor = new Praetor();
const devMode = await praetor.devMode();

closeWindow()

const praetor = new Praetor();
const closed = await praetor.closeWindow();

api.selectPerson()

const praetor = new Praetor();
const person = await praetor.api.selectPerson();

Events

praetor.events is an EventTarget that receives events sent by the Praetor host to the plugin. Listeners are registered with the standard addEventListener API and the event name is available as a constant, so no string literals are needed:

const praetor = new Praetor();

praetor.events.addEventListener(praetor.events.VIEW_REACTIVATED, () => {
  // The panel became active again - refresh the displayed data.
});

praetor.events is a shared instance: calling new Praetor() repeatedly always returns the very same events object, so a listener may be registered from anywhere in the plugin and every event is delivered exactly once.

Register listeners while the plugin initializes. Events are never queued - anything dispatched before a listener exists is lost.

VIEW_REACTIVATED

Dispatched when the plugin panel becomes active again, typically because the user switched back to it. The page is not reloaded, so the plugin keeps its state (pending forms, scroll position, SPA route) and only needs to refresh the data it displays.

Scope. The event is delivered to panels hosted in the case and person detail (manifest panel types Case and Person). Tabs opened through praetor.actions.openTab do not receive it.

In TypeScript the event detail is typed with PraetorSdkEvents.ViewReactivatedDetail:

import { Praetor, PraetorSdkEvents } from "@wkcz/praetor-sdk";

const praetor = new Praetor();

praetor.events.addEventListener(praetor.events.VIEW_REACTIVATED, (e) => {
  const event = e as CustomEvent<PraetorSdkEvents.ViewReactivatedDetail>;
  console.log("reactivated", event.detail);
});

ViewReactivatedDetail is currently empty - the event carries no data. It exists so that adding data later is a non-breaking change, and as the pattern followed by future events.

Triggering events outside of Praetor

When the plugin runs in a plain web browser there is no host to send events, so the SDK exposes mock methods that trigger them manually. They are meant to be called from the browser console:

// Triggers 'viewreactivated' for every registered listener.
new Praetor().events.mockViewReactivated();

// Triggers an arbitrary event, optionally with a detail payload.
new Praetor().events.mockEvent("someevent", { a: 1 });

Because events is a shared instance, new Praetor().events in the console is the same object the plugin registered its listeners on. The mock methods exist only in the browser build; inside Praetor the events arrive from the host.