Use Cases

Use Cases

Four end-to-end scenarios. Each combines pieces from Guides. Every example matches the SDK surface documented in API-Reference.

You want a live cardiovascular monitor that flags high LDL

Watch a twin's cardiovascular events, and whenever an LDL result arrives above target, flag it back onto the twin.

// ldl-monitor.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({ apiKey: process.env.DTP_API_KEY });
const twin = await dtp.twins.connect(grantToken);

const stream = twin.events.stream({ system: "cardiovascular" }, (event) => {
  if (event.data.code === "LDL" && Number(event.data.value) > 130) {
    twin.flag("cardiovascular", event);
  }
});

// later, when the monitor shuts down:
stream.stop();

The streamed event is a HealthEvent, and any HealthEvent satisfies FlagInput, so you forward it straight into twin.flag. stream polls list every 5s by default and emits only events it has not seen before.

You want to reconcile a medication list against known interactions

Resolve each drug name to a HOLON concept id, then check a pair for a known interaction.

// reconcile-meds.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({
  apiKey: process.env.DTP_API_KEY,
  holonApiUrl: process.env.HOLON_API_URL,
  holonApiKey: process.env.HOLON_API_KEY,
});

async function conceptId(name: string) {
  const results = await dtp.holon.concepts.search(name);
  return results.hits[0].conceptId;
}

const atorvastatin = await conceptId("atorvastatin");
const clarithromycin = await conceptId("clarithromycin");

const interaction = await dtp.holon.interactions.check(atorvastatin, clarithromycin);
console.log(interaction);

dtp.holon needs holonApiUrl and holonApiKey in the constructor. It returns a configured @ontomorph/holon-client; see its docs for the full surface.

You want to issue and use a scoped grant

The patient issues a grant token through their consent flow, scoped to the systems and event types they approved. Your code connects with that token and reads only what the grant covers.

// use-grant.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({ apiKey: process.env.DTP_API_KEY });

// grantToken comes from the patient's consent flow.
const twin = await dtp.twins.connect(grantToken);

// Inspect what the grant covers before reading.
console.log(twin.grant.systems);    // e.g. ["cardiovascular"], or null for all
console.log(twin.grant.eventTypes); // the event types the patient approved

if (twin.grant.systems === null || twin.grant.systems.includes("cardiovascular")) {
  const cardio = await twin.systems.get("cardiovascular");
  console.log(cardio.events.length, "events");
}

connect decodes the grant locally, so twin.grant claims are available before any network call. A request outside the grant's scope is refused server-side and surfaces as a DTPApiError; see error handling in API-Reference.

You want to rotate an API key

Create a fresh key, deploy it, then revoke the old one. dtp.keys requires a sessionToken in the constructor.

// rotate-key.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({
  apiKey: process.env.DTP_API_KEY,
  sessionToken: process.env.DTP_SESSION_TOKEN, // Zitadel user JWT
});

// 1. Create the replacement.
const created = await dtp.keys.create({
  name: "CI pipeline (rotated)",
  keyType: "personal",
  scopes: ["twins:read"],
  environment: "live",
});

// 2. Store created.key now; it is shown exactly once.
await deployKey(created.key);

// 3. Revoke the old key once the new one is live.
await dtp.keys.revoke(oldKeyId);

dtp.keys is user-authed, so it needs a sessionToken (a Zitadel user JWT), not the API key alone. created.key is the raw key and is returned only once, so persist it before moving on.

Related: Guides, API-Reference, FAQ.