-
Notifications
You must be signed in to change notification settings - Fork 0
API Reference
Every export from @ontomorph/dtp-sdk. For narrative and when-to-use notes see Guides.
The client class. Construct it once with a DTPConfig, then reach the platform through its namespaces: dtp.twins, dtp.keys, and dtp.holon.
// create a client
new DTP(config: DTPConfig)A DTPConfig object. Only apiKey is required; see DTPConfig for every field.
// dtp.twins.connect
connect(grantToken: string): Promise<Twin>Decodes the grant locally and returns a Twin. It does not hit the network; the token is verified server-side on the first data request, so it returns fast and the twin.grant claims are available right away.
The signed grant token (a JWT) the patient issued.
A Twin whose grant holds the decoded GrantClaims.
DTPApiError on the first data request if the token is rejected server-side (for example UNAUTHORIZED or FORBIDDEN).
The object returned by dtp.twins.connect. It exposes twin.grant, twin.systems, twin.events, and twin.flag.
The decoded GrantClaims for the connected twin (grantId, twinId, systems, eventTypes). Available immediately after connect, with no network call. See GrantClaims.
// twin.systems.get
get(system: string): Promise<SystemView>Returns a SystemView built from the twin's grant-scoped events filtered by event.data.system.
The body system to read, for example "cardiovascular".
A SystemView. See SystemView.
DTPApiError on a failed request.
// twin.events.list
list(filter: EventFilter): Promise<HealthEvent[]>One-shot, paginated list of events matching the filter.
An EventFilter, for example { system: "cardiovascular", limit: 50 }. See EventFilter.
An array of HealthEvent.
DTPApiError on a failed request.
// twin.events.stream
stream(options: StreamOptions, onEvent: (event: HealthEvent) => void): StreamHandleWatches for new events. Twin-core has no grant-scoped push stream, so stream polls list on an interval and emits only events it has not seen before. Returns a StreamHandle; call stop() to end it.
A StreamOptions, for example { system: "cardiovascular", intervalMs: 5_000 }. intervalMs defaults to 5000. See StreamOptions.
Called once per new HealthEvent.
A StreamHandle with a stop() method. See StreamHandle.
// twin.flag: write a flag event back onto the twin
await twin.flag(system, input);Writes a flag event back onto the twin as a new health event.
The body system to record the flag under, for example "cardiovascular".
A FlagInput. Any HealthEvent also satisfies FlagInput, so a streamed event can be forwarded straight through. See FlagInput.
Resolves once the flag event has been written back onto the twin.
DTPApiError on a failed request. The grant must permit the flag's eventType (default "flag"), or the request fails.
Manage your own API keys. Requires sessionToken in the constructor.
// dtp.keys.list
list(): Promise<ApiKeyRecord[]>Returns your API keys as ApiKeyRecord values. Throws DTPApiError on a failed request.
// dtp.keys.create
create(input: CreateApiKeyInput): Promise<CreateApiKeyResult>Creates a key and returns a CreateApiKeyResult. The result's key is the raw key, shown exactly once. See CreateApiKeyInput and CreateApiKeyResult. Throws DTPApiError on a failed request.
// dtp.keys.revoke
revoke(id: string): Promise<void>Revokes the key with the given id. Resolves when the key is revoked. Throws DTPApiError on a failed request.
// dtp.holon
dtp.holon; // a configured @ontomorph/holon-clientReturns a configured @ontomorph/holon-client. Requires holonApiUrl and holonApiKey in the constructor. Its full surface (concepts, interactions, reference ranges, phenotype similarity) is documented in the @ontomorph/holon-client docs.
The constructor config object.
Required. Your DTP API key (dtp_live_… or dtp_test_…). Sent as X-DTP-API-Key on twin requests.
Twin-core endpoint. Defaults to https://api.ontomorph.com.
Identity-consent endpoint used by dtp.keys. Defaults to https://api.ontomorph.com.
A Zitadel user JWT. Required only for dtp.keys.*.
HOLON base URL. Required only for dtp.holon.
HOLON API key (holon_…). Required only for dtp.holon.
Per-request timeout in milliseconds. Defaults to 30000.
One timestamped entry on a twin.
The event's unique id.
An object holding the event's payload. The clinical fields live here, not at the top level: code (the measurement code), value, unit, and system (the body system). Keeping them inside data lets the platform stay agnostic about which coding system you use.
The result of twin.systems.get.
The body system this view covers.
The twin the view belongs to.
The grant-scoped HealthEvent[] for this system, filtered by event.data.system.
The argument to twin.events.list.
The body system to list events for, for example "cardiovascular".
Maximum number of events to return in one page.
The first argument to twin.events.stream.
The body system to watch.
Poll interval in milliseconds. Defaults to 5000.
The value returned by twin.events.stream.
Call handle.stop() to end the watch.
The second argument to twin.flag. Any HealthEvent also satisfies this shape.
The measurement or finding code, for example "LDL".
The value for that code, for example 190.
A short label for the flag, for example "LDL above target".
A longer note, for example a recommended action.
The event type recorded for the flag. Defaults to "flag". The grant must permit it.
The decoded claims on twin.grant, also the return of decodeGrantToken.
The grant's id.
The twin this grant authorizes.
The body systems the grant covers, for example ["cardiovascular"], or null for all.
The event types the grant covers.
Metadata for one API key, as returned by dtp.keys.list. It does not carry the raw secret; the raw key is returned only once, by dtp.keys.create.
The argument to dtp.keys.create.
A human-readable name for the key, for example "CI pipeline".
One of personal, org, device, or research.
The scopes the key grants, for example ["twins:read"].
live or test.
The result of dtp.keys.create.
The new key's id. Pass it to dtp.keys.revoke.
The raw API key, shown exactly once. Store it immediately.
// decodeGrantToken
decodeGrantToken(token: string): GrantClaimsReads the grant claims from a token without verifying it. Client-side only. Returns GrantClaims.
// filterBySystem
filterBySystem(events: HealthEvent[], system: string): HealthEvent[]Filters a HealthEvent[] by data.system. A pure utility the SDK uses internally.
// diffNewEvents
diffNewEvents(events, seen)Returns the members of events not already present in seen. This is the set difference the stream loop uses to emit only events it has not seen before.
Thrown by every failed request.
A machine-readable DTPErrorCode, for example FORBIDDEN.
A human-readable description of the failure.
An object of { status, body }, where status is the HTTP status (403 for a forbidden request) and 0 for transport-level failures such as a network drop or timeout.
Thrown on configuration mistakes (for example a missing credential a feature needs).
A human-readable description of the misconfiguration.
The enum used for DTPApiError.code. Branch on it to react to specific failures.
Credentials are missing or were rejected.
Authenticated, but not allowed to perform the request (HTTP 403).
The requested resource does not exist.
The request failed validation.
The grant or key does not cover the requested scope.
Too many requests.
A server-side error.
A transport-level failure. details.status is 0.
The request exceeded the configured timeout. details.status is 0.
// error-handling.ts
import { DTP, DTPApiError, DTPConfigError, DTPErrorCode } from "@ontomorph/dtp-sdk";
try {
const twin = await dtp.twins.connect(grantToken);
await twin.systems.get("cardiovascular");
} catch (err) {
if (err instanceof DTPApiError) {
console.error(err.code, err.details.status, err.message); // e.g. FORBIDDEN 403 …
if (err.code === DTPErrorCode.UNAUTHORIZED) refreshCredentials();
} else if (err instanceof DTPConfigError) {
console.error("SDK misconfigured:", err.message);
}
}