policies

client.policies manages the tenant’s policies. It:

reads the floor, which no overlay may loosen
reads the tenant’s active policy version and its history
submits, approves, rejects, withdraws or cancels a change

floor

floor returns the tenant’s floor.

floor(): Promise<FloorRow[]>;

func floor() async throws -> [FloorRow]

suspend fun floor(): List<FloorRow>

Returns: Every FloorRow of the tenant’s floor.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

active

active returns the policy version in effect now.

active(): Promise<PolicyVersion>;

func active() async throws -> PolicyVersion

suspend fun active(): PolicyVersion

Returns: The PolicyVersion in effect now.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

versions

versions returns every policy version the tenant has had.

versions(): Promise<PolicyVersion[]>;

func versions() async throws -> [PolicyVersion]

suspend fun versions(): List<PolicyVersion>

Returns: Every PolicyVersion the tenant has had, pending ones included.

Records: Nothing. Not a decision.

Errors: no-session, unreachable.

overlay

overlay returns one version’s overlay document.

overlay(versionId?: string): Promise<Overlay>;

func overlay(_ versionId: String? = nil) async throws -> Overlay

suspend fun overlay(versionId: String? = null): Overlay

Parameter	Type	Description
`versionId`	string, optional	One version’s overlay. When absent, the active version’s overlay.

Returns: The Overlay document. Policies describes its format.

Records: Nothing. Not a decision.

Errors: no-session, unreachable, not-found.

submit

submit submits a proposed overlay. Seald Healthcare checks it against the floor. A valid overlay becomes the next version, pending approval.

submit(overlay: Overlay): Promise<Decided<Submitted>>;

func submit(_ overlay: Overlay) async throws -> Decided<Submitted>

suspend fun submit(overlay: Overlay): Decided<Submitted>

Parameter	Type	Description
`overlay`	`Overlay`	The proposed overlay document. Policies describes its format.

Returns: A Decided<Submitted>: on allow, Submitted reports either the pending version or, when the overlay would loosen the floor, the floor rows it failed.

Records: Submit Policy. See Audit actions.

Errors: no-session, unreachable.

approve

approve approves a pending version. After a fresh multi-factor sign-in, the approver signs the version’s hash and the time.

approve(versionId: string, effectiveAt?: Date): Promise<Decided<{}>>;

func approve(_ versionId: String, effectiveAt: Date? = nil) async throws -> Decided<Void>

suspend fun approve(versionId: String, effectiveAt: Instant? = null): Decided<Unit>

Parameter	Type	Description
`versionId`	string	The version to approve.
`effectiveAt`	date, optional	When it takes effect. When absent, immediately.

Returns: A Decided<{}>.

Records: Approve Policy. See Audit actions.

Who may call it: An Owner or Admin who is not the version’s author.

Errors: no-session, unreachable, canceled, not-found.

reject

reject rejects a pending version, with a reason for the author.

reject(versionId: string, reason: string): Promise<Decided<{}>>;

func reject(_ versionId: String, reason: String) async throws -> Decided<Void>

suspend fun reject(versionId: String, reason: String): Decided<Unit>

Parameter	Type	Description
`versionId`	string	The version to reject.
`reason`	string	Shown to the author.

Returns: A Decided<{}>.

Records: One decision and one access event.

Errors: no-session, unreachable, not-found.

withdraw

withdraw withdraws a pending version. Only its author may call it.

withdraw(versionId: string): Promise<Decided<{}>>;

func withdraw(_ versionId: String) async throws -> Decided<Void>

suspend fun withdraw(versionId: String): Decided<Unit>

Parameter	Type	Description
`versionId`	string	The pending version to withdraw.

Returns: A Decided<{}>.

Records: One decision and one access event.

Who may call it: The version’s author.

Errors: no-session, unreachable, not-found.

cancel

cancel cancels an approved version before it takes effect.

cancel(versionId: string): Promise<Decided<{}>>;

func cancel(_ versionId: String) async throws -> Decided<Void>

suspend fun cancel(versionId: String): Decided<Unit>

Parameter	Type	Description
`versionId`	string	The approved, not-yet-effective version to cancel.

Returns: A Decided<{}>.

Records: One decision and one access event.

Who may call it: The Owner role.

Errors: no-session, unreachable, not-found.

Types

FloorRow

interface FloorRow {
  rule: string;
  floor: string;
  tenantMay: string;
}

struct FloorRow {
  let rule: String
  let floor: String
  let tenantMay: String
}

data class FloorRow(
  val rule: String,
  val floor: String,
  val tenantMay: String,
)

Field	Type	Description
`rule`	string	The rule the floor sets.
`floor`	string	What the floor fixes.
`tenantMay`	string	What the tenant’s overlay may still narrow.

Overlay

Overlay is the tenant’s overlay as a document. Only the Seald Healthcare Cloud reads it. Policies describes its format.

type Overlay = unknown;

typealias Overlay = Any

typealias Overlay = Any

PolicyVersion

interface PolicyVersion {
  versionId: string;
  number: number;
  hash: string;
  state: 'pending' | 'approved' | 'active' | 'superseded' | 'rejected' | 'withdrawn' | 'canceled';
  author: RecipientId;
  approver?: RecipientId;
  submittedAt: Date;
  effectiveAt?: Date;
  difference: string;
}

struct PolicyVersion {
  let versionId: String
  let number: Int
  let hash: String
  let state: State
  let author: RecipientId
  let approver: RecipientId?
  let submittedAt: Date
  let effectiveAt: Date?
  let difference: String

  enum State { case pending, approved, active, superseded, rejected, withdrawn, canceled }
}

data class PolicyVersion(
  val versionId: String,
  val number: Int,
  val hash: String,
  val state: State,
  val author: RecipientId,
  val approver: RecipientId?,
  val submittedAt: Instant,
  val effectiveAt: Instant?,
  val difference: String,
) {
  enum class State { PENDING, APPROVED, ACTIVE, SUPERSEDED, REJECTED, WITHDRAWN, CANCELED }
}

Field	Type	Description
`versionId`	string	Identifies the version.
`number`	number	The version’s sequence number.
`hash`	string	The hash an approval signs.
`state`	one of the seven states	Where the version stands.
`author`	`RecipientId`	Who submitted it.
`approver`	`RecipientId`, optional	Who approved it, once approved.
`submittedAt`	date	When it was submitted.
`effectiveAt`	date, optional	When it takes or took effect.
`difference`	string	The difference from the version before it.

Submitted

type Submitted = { kind: 'pending'; version: PolicyVersion } | { kind: 'refused'; floorRows: FloorRow[] };

enum Submitted {
  case pending(PolicyVersion)
  case refused(floorRows: [FloorRow])
}

sealed interface Submitted {
  data class Pending(val version: PolicyVersion) : Submitted
  data class Refused(val floorRows: List<FloorRow>) : Submitted
}

Case	Payload	Description
`pending`	`version`	The overlay validated. This is the next version, pending approval.
`refused`	`floorRows`	The overlay would loosen the floor. No version was created. These are the rows it failed.