Skip to content
Seald Healthcare SDK

Open records and files

client.objects, an Objects, is where plaintext enters your application. Each open of a record or a file is one call, with one decision and one access event. The SDK fetches the stored object, checks it and decrypts it in memory. Your application renders the result and calls close() to discard the plaintext and every key. You cannot store anything the SDK returns and open it again later. No key remains to do it with.

Open by reference

An ObjectRef names a locator and, optionally, an earlier version. Leave version out for the current one. OpenAction says what the person is doing. Use view to show the object on screen. Use access-record when you open a record to give its subject a copy. Use download-file for a file the person is about to save outside your surface.

const opened = await allowed(await client.objects.open({ locator }, { action: 'view' }));

opened is an Opened: an OpenedRecord for a record ObjectKind, or an OpenedFile for a file. Both extend OpenedBase, as does Opened itself. opened.version and opened.close() need no case. OpenedBase carries:

  • the object’s own data: name, type, size and times (created and saved)
  • baseVersion: the version it was last saved from
  • pending: whether the version still waits for an AI agent’s delegator
  • writer: the recipient id of the device that saved this version
  • epoch: the epoch this version belongs to
  • offline: true when the copy came from the offline lease
if (opened?.kind === 'record') renderRecord(opened.fields, opened.masked);
else if (opened) renderFile(opened.name, opened.stream());

An OpenedRecord carries fields, a map of FieldValue. It also carries masked, the fields the policies withheld. Each masked field carries the DenyReason and the text to show beside it. The rest of the record still renders. An OpenedFile gives you the bytes two ways:

  • bytes() returns the whole file at once.
  • stream() returns a ReadableStream you can pipe to a viewer or a download.

Always call close() once you are done rendering. It discards the plaintext and every key this open used.

opened?.close();

Open one field alone

To open a single field, call openField. It opens only that field and gets its own decision, recorded as a View Field access event. It returns an OpenedField with the locator, version, field name, value and its own close().

const field = await allowed(await client.objects.openField({ locator }, 'mrn'));
field?.close();

Ask for a further action

Copy, Print, a later download and a later access-record open each get their own decision. Once something is open, call request with a FurtherAction: copy, print, download-file or access-record. On allow, your application carries out the action with the plaintext it already holds.

if (opened?.kind === 'record') {
  const decision = await allowed(await opened.request('copy'));
  if (decision) copyToClipboard(opened.fields);
}

What the SDK does for you

  • Fetches the stored object and verifies it in full before decrypting anything.
  • Decrypts in memory only, never writing plaintext to disk on your behalf.
  • Records one access event per open, per field open, and per further action.
  • Returns the copy the offline lease covers when the Seald Healthcare Cloud is unreachable, with offline: true.

Decisions and errors you may see

Outcome or ErrorCodeWhenWhat to do
denyThe policies refuse the action. reason and text say why.Show text and who can give access.
challengeThe policies require a fresh multi-factor sign-in first.Call stepUp(), or use the allowed helper.
container-invalidThe stored object is damaged, or its key does not open it.Do not retry. Report the object as unreadable.
storage-unreachableThe storage behind the object refused the request or could not be reached.Retry once storage is back.

Next