How one event becomes a set of people, why a person reached as both an assignee and a muted team member must be told anyway, which transports a notice may fall back onto without disclosing more than it started with, why a nine-hour quiet window is eight hours one night a year and ten another, and which end of a delivery needs somebody to have decided it and which needs only a clock.
Generated from libs/oshun/workbench-kit/src/notification-routing.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S8.7. Do not edit by hand.
Summary#
src/notification-routing.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/notification-routing |
contract |
S8.7 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| ACKNOWLEDGEMENT_SOURCES | enumeration | How the recipient said they had seen it. |
| AcknowledgementSource | type | — |
| ACTOR_SLOT_NAMES | enumeration | Slot names that name the actor behind an event. |
| ACTORLESS_AUTHORITIES | enumeration | The authorities whose transitions have no actor and must not carry one. |
| applyTiming | function | Decide when a notice goes out (S8.7.f). |
| AUDIENCE_GROUNDS | enumeration | The reasons a person is on the list for an event. |
| AudienceCandidate | interface | One reason one person is on the list, as the host resolved it. |
| AudienceGround | type | — |
| AudienceRequest | interface | Everything resolution needs that is a property of the EVENT, not the person. |
| authorityRank | function | — |
| bypassFaults | function | Check the bypass threshold itself against the taxonomy and the floor. |
| capUsage | function | How much of a cap is spent at a given moment. Counts deliveries only. |
| CHANNEL_EXPOSURES | enumeration | How far a transport carries what it is given, least exposing first. |
| CHANNEL_READINESS | enumeration | Why a channel is or is not usable for one person right now. |
| CHANNEL_ROUTING_FAULTS | enumeration | — |
| ChannelBinding | interface | — |
| channelBindingFaults | function | Check the bindings themselves, independently of any one routing decision. |
| ChannelExposure | type | — |
| ChannelReadiness | type | — |
| ChannelRequest | interface | — |
| ChannelRoutingFault | type | — |
| comparePrecedence | function | Order two matching settings. Authority first, then specificity (decision 5). |
| composePreference | function | Compose every applicable preference into one decision (S8.7.c). |
| CONSENT_GATED_EXPOSURES | enumeration | The exposures a person must have explicitly agreed to. |
| DELIVERY_LIFECYCLE_FAULTS | enumeration | — |
| DELIVERY_OBLIGATIONS | enumeration | How strongly the platform is obliged to deliver. |
| DELIVERY_STATES | enumeration | — |
| DELIVERY_TRANSITIONS | constant | The machine, as data. |
| DeliveryEvent | interface | — |
| deliveryKey | function | The key that makes two deliveries the same delivery. |
| DeliveryLifecycleFault | type | — |
| DeliveryObligation | type | — |
| DeliveryState | type | — |
| deliveryTransition | function | — |
| DeliveryTransition | interface | — |
| DEPLOYMENT_ONLY_SCOPES | enumeration | The scopes only a deployment may author. |
| DERIVED_GROUNDS | enumeration | The grounds whose membership was DERIVED and must therefore be pinned. |
| DIGESTABLE_OBLIGATIONS | enumeration | The obligations a digest may hold. Decision 7's boundary, as data. |
| DISPOSITIONS_THAT_STOP_A_NOTICE | enumeration | The dispositions under which no notice is produced at all. |
| EVENT_REGISTRY_FAULTS | enumeration | — |
| EVENT_SOURCES | enumeration | Where an event comes from, which decides what can be trusted about it. |
| EventRegistration | interface | One registered event kind. |
| EventRegistryFault | type | — |
| eventRegistryFaults | function | Check one deployment's event registry (S8.7.a). |
| EventSource | type | — |
| EXPOSURE_CEILING | constant | The most exposing transport a class of value may travel on. |
| exposurePermits | function | Whether a field's value may travel at this exposure. |
| exposureRank | function | — |
| fieldsForExposure | function | Re-render one notice's fields for a transport (decision 9). |
| fieldsForNotice | function | The fields as they must reach the renderer, for this transport and reader. |
| foldGrounds | function | Fold every ground that reached one person into one recipient (decision 2). |
| FrequencyCap | interface | A ceiling on how often a person may be INTERRUPTED on one channel. |
| GROUND_OBLIGATION_FLOOR | constant | The obligation a ground carries on its own, whatever the event says. |
| GROUND_RESOLUTION_DEPENDS_ON | constant | What each ground's resolution is a function of. |
| GROUNDS_OUTSIDE_THE_AUDIENCE | enumeration | The one ground that reaches outside the object's audience (decision 4). |
| InterruptionLedger | interface | What actually happened on a channel, kept apart from what was prevented. |
| isDerivedGround | function | — |
| isTerminalDelivery | function | — |
| isUsable | function | Whether a binding can carry a notice to this person at this moment. |
| LifecycleContext | interface | — |
| lifecycleFaults | function | Check one transition against the machine (S8.7.g). |
| NON_ACKNOWLEDGING_SOURCES | enumeration | The sources that are not an acknowledgement. |
| NotificationRoutingFault | type | — |
| obligationRank | function | — |
| PlannedDelivery | interface | One decided delivery: exactly the argument the delivery system demands. |
| planNotifications | function | Turn one event into the deliveries it produces. |
| PlanRequest | interface | — |
| PREFERENCE_AUTHORITIES | enumeration | WHO set a preference, strongest first. |
| PREFERENCE_COMPOSITION_FAULTS | enumeration | — |
| PREFERENCE_DECISIONS | enumeration | What a composed preference decides. |
| PREFERENCE_SCOPES | enumeration | HOW SPECIFIC a preference is, most specific first. The second axis. |
| PreferenceAuthority | type | — |
| PreferenceCompositionFault | type | — |
| PreferenceContext | interface | What the event and recipient are, for matching a setting's scope. |
| PreferenceDecision | type | — |
| PreferenceOutcome | interface | — |
| preferenceParityFaults | function | Check a decision a host says it composed, against the settings it had. |
| PreferenceScope | type | — |
| PreferenceSetting | interface | — |
| quietHoursRelease | function | The instant a hold placed at at is released (decision 6's second half). |
| quietHoursSpanMinutes | function | How long a hold entered at at actually lasts, in minutes. |
| QuietHoursWindow | interface | When somebody does not want to be interrupted. |
| RECIPIENT_FAULTS | enumeration | — |
| RECIPIENT_SIDE_READINESS | enumeration | The readiness values that are facts about the person rather than the build. |
| RecipientProfile | interface | Everything about one recipient that is a property of THEM, not of the event. |
| RecipientResolutionFault | type | — |
| RenderedNotice | interface | What a host says it rendered and is about to hand to the delivery system. |
| RenderRequest | interface | — |
| rendersClassesOnly | function | Whether this recipient gets classes rather than values, whatever the fields say. |
| RESOLUTION_PARITY_FAULTS | enumeration | Compare the kit's derivation with the audience a host says it resolved. |
| ResolutionParityFault | type | — |
| resolutionParityFaults | function | — |
| ResolvedRecipient | interface | One person, every reason they are on the list, and the strongest of them. |
| resolveRecipients | function | Turn one event's candidates into the people it will be delivered to (S8.7.b). |
| routeChannel | function | Walk the fallback chain and choose a transport (S8.7.e). |
| RoutingFinding | interface | — |
| scopeRank | function | — |
| settingMatches | function | Whether one setting applies to this event, recipient and channel. |
| SILENCEABLE_OBLIGATIONS | enumeration | What a preference may do to an obligation. |
| strongerObligation | function | The stronger of two obligations. Decision 2's fold, as one function. |
| TEMPLATE_FAULTS | enumeration | — |
| TemplateFault | type | — |
| templateFaults | function | Check one rendered notice (S8.7.d). |
| templateSlots | function | The slot names a template actually contains, in order of first appearance. |
| TERMINAL_DELIVERY_STATES | enumeration | — |
| TimeOfDay | interface | A time of day, with no date and no zone. The two are separate on purpose. |
| TIMING_DISPOSITIONS | enumeration | — |
| TIMING_FAULTS | enumeration | — |
| TimingDisposition | type | — |
| TimingFault | type | — |
| TimingRequest | interface | — |
| TRANSITION_AUTHORITIES | enumeration | Who causes a transition, which is the whole of decision 12. |
| TransitionAuthority | type | — |
| windowWraps | function | Whether a window crosses midnight. |
| withheldFields | function | Fields whose values are withheld from this render, for whatever reason. |
| withinQuietHours | function | Whether an instant falls inside the window, in the window's own zone. |
Shapes#
ACKNOWLEDGEMENT_SOURCES#
How the recipient said they had seen it.
Values: acted-on-the-notice, marked-read, opened-the-centre
AcknowledgementSource#
(typeof ACKNOWLEDGEMENT_SOURCES)[number];
ACTOR_SLOT_NAMES#
Slot names that name the actor behind an event.
Values: actor, author, by, who, triggeredBy
ACTORLESS_AUTHORITIES#
The authorities whose transitions have no actor and must not carry one.
Values: the-clock
applyTiming#
Decide when a notice goes out (S8.7.f).
applyTiming(request: TimingRequest): { readonly disposition: TimingDisposition; readonly releaseAt: Instant | null; readonly findings: readonly RoutingFinding[]; }
AUDIENCE_GROUNDS#
The reasons a person is on the list for an event.
Values: explicit, assignee, reviewer, owner, mention, role, team,
escalation, delegate
AudienceCandidate#
One reason one person is on the list, as the host resolved it.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
tenant |
TenantId | required | — |
ground |
AudienceGround | required | — |
derivedAt |
Instant | null — Instant |
required | When the membership behind this ground was derived. |
grant |
string | null |
required | The grant behind a delegate ground, as ActorRef's delegated variant carries. |
standing |
IdentityStanding | required | — |
targetDisposition |
AuthorizationDisposition |
required | What authorization.ts returned for THIS person against the event's target. |
locale |
string |
required | — |
zone |
string |
required | An IANA zone name. The recipient's, never the sender's. |
AudienceGround#
(typeof AUDIENCE_GROUNDS)[number];
AudienceRequest#
Everything resolution needs that is a property of the EVENT, not the person.
| Field | Type | Required | Notes |
|---|---|---|---|
eventKind |
string |
required | — |
registration |
EventRegistration | required | — |
tenant |
TenantId | required | — |
occurredAt |
Instant | required | — |
actor |
ActorRef | null — ActorRef |
required | The actor behind the event. Null for a scheduled one, which has none. |
candidates |
readonly AudienceCandidate[] — AudienceCandidate |
required | — |
maxFanOut |
number |
required | The largest audience a single event may produce, as the deployment sets it. |
escalationResolvedAt |
Instant | null — Instant |
required | When escalation was resolved, for an event that has that ground. |
authorityRank#
authorityRank(authority: PreferenceAuthority): number
bypassFaults#
Check the bypass threshold itself against the taxonomy and the floor.
bypassFaults(bypassThreshold: string, mandatoryUrgencies: readonly string[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]
capUsage#
How much of a cap is spent at a given moment. Counts deliveries only.
capUsage(cap: FrequencyCap, ledger: InterruptionLedger, at: Instant): { readonly used: number; readonly remaining: number; readonly exhausted: boolean }
CHANNEL_EXPOSURES#
How far a transport carries what it is given, least exposing first.
Values: in-product, account-mailbox, device-surface, carrier-plaintext,
third-party-endpoint
CHANNEL_READINESS#
Why a channel is or is not usable for one person right now.
Values: ready, not-configured, degraded, unavailable, no-address,
no-consent, unverified-address
CHANNEL_ROUTING_FAULTS#
Values: channel-outside-the-taxonomy,
channel-the-delivery-system-cannot-reach,
readiness-that-contradicts-the-binding,
consent-inferred-from-holding-an-address, delivery-to-an-unverified-address,
fallback-that-increases-exposure, fallback-behind-the-same-provider,
fallback-chain-that-does-not-terminate,
fallback-to-a-channel-that-is-not-bound,
in-product-channel-offered-a-fallback,
obliged-delivery-with-no-reachable-channel,
recipient-with-no-delivery-profile,
suspended-recipient-routed-outside-the-product
ChannelBinding#
| Field | Type | Required | Notes |
|---|---|---|---|
channel |
string |
required | — |
exposure |
ChannelExposure | required | — |
readiness |
ChannelReadiness | required | — |
hasAddress |
boolean |
required | Whether the platform holds an address, token or endpoint for this person. |
consentGiven |
boolean |
required | Whether the person agreed to be reached this way. Holding an address is not agreement. |
addressVerified |
boolean |
required | Whether the address has been proven to be theirs. |
provider |
string |
required | The provider the channel is bound to, for the shared-failure check. |
fallback |
string | null |
required | The channel to try when this one cannot be used, or null for a terminus. |
channelBindingFaults#
Check the bindings themselves, independently of any one routing decision.
channelBindingFaults(bindings: readonly ChannelBinding[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]
ChannelExposure#
(typeof CHANNEL_EXPOSURES)[number];
ChannelReadiness#
(typeof CHANNEL_READINESS)[number];
ChannelRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
preferred |
string |
required | — |
bindings |
readonly ChannelBinding[] — ChannelBinding |
required | — |
obligation |
DeliveryObligation | required | — |
recipientStanding |
IdentityStanding | required | The recipient's standing, which bounds the transports before anything else. |
ChannelRoutingFault#
(typeof CHANNEL_ROUTING_FAULTS)[number];
comparePrecedence#
Order two matching settings. Authority first, then specificity (decision 5).
comparePrecedence(a: PreferenceSetting, b: PreferenceSetting): number
composePreference#
Compose every applicable preference into one decision (S8.7.c).
composePreference(settings: readonly PreferenceSetting[], context: PreferenceContext, taxonomy: NotificationTaxonomy): { readonly outcome: PreferenceOutcome; readonly findings: readonly RoutingFinding[] }
CONSENT_GATED_EXPOSURES#
The exposures a person must have explicitly agreed to.
Values: carrier-plaintext, third-party-endpoint
DELIVERY_LIFECYCLE_FAULTS#
Values: transition-that-is-not-in-the-machine,
departure-from-a-terminal-state, transition-with-no-actor,
clock-driven-transition-carrying-an-actor, transition-with-no-reason,
acknowledgement-inferred-from-opening-the-centre,
acknowledgement-by-somebody-who-is-not-the-recipient,
sent-with-no-provider-receipt, provider-transition-with-no-provider-receipt,
permanent-bounce-retried,
permanent-bounce-that-did-not-unverify-the-address, retry-under-a-new-key,
retry-past-the-attempt-bound, deduped-against-nothing,
deduped-against-its-own-key, transition-before-the-notice-was-planned
DELIVERY_OBLIGATIONS#
How strongly the platform is obliged to deliver.
Values: mandatory, required, optional
DELIVERY_STATES#
Values: planned, sent, delivered, failed, bounced, suppressed,
deduped, expired, acknowledged
DELIVERY_TRANSITIONS#
The machine, as data.
DeliveryEvent#
| Field | Type | Required | Notes |
|---|---|---|---|
key |
string |
required | — |
from |
DeliveryState | required | — |
to |
DeliveryState | required | — |
at |
Instant | required | — |
actor |
ActorRef | null — ActorRef |
required | Null wherever the authority has none, and required wherever it has one. |
reason |
string | null |
required | — |
providerReceipt |
string | null |
required | What the provider actually answered. Evidence for a provider transition. |
againstKey |
string | null |
required | For deduped, the key this one deduplicated against. |
bounceIsPermanent |
boolean |
required | For a bounce: whether it is permanent, and whether the address was un-verified. |
addressUnverified |
boolean |
required | — |
acknowledgementSource |
AcknowledgementSource | null — AcknowledgementSource |
required | — |
attempt |
number |
required | How many times this key has been sent, including this one. |
deliveryKey#
The key that makes two deliveries the same delivery.
deliveryKey(eventId: string, recipient: ActorId, channel: string): string
DeliveryLifecycleFault#
(typeof DELIVERY_LIFECYCLE_FAULTS)[number];
DeliveryObligation#
(typeof DELIVERY_OBLIGATIONS)[number];
DeliveryState#
(typeof DELIVERY_STATES)[number];
deliveryTransition#
deliveryTransition(from: DeliveryState, to: DeliveryState): DeliveryTransition | null
DeliveryTransition#
| Field | Type | Required | Notes |
|---|---|---|---|
from |
DeliveryState | required | — |
to |
DeliveryState | required | — |
authority |
TransitionAuthority | required | — |
requiresReason |
boolean |
required | — |
DEPLOYMENT_ONLY_SCOPES#
The scopes only a deployment may author.
Values: role
DERIVED_GROUNDS#
The grounds whose membership was DERIVED and must therefore be pinned.
Values: assignee, reviewer, owner, role, team, escalation,
delegate
DIGESTABLE_OBLIGATIONS#
The obligations a digest may hold. Decision 7's boundary, as data.
Values: optional
DISPOSITIONS_THAT_STOP_A_NOTICE#
The dispositions under which no notice is produced at all.
Values: conceal, deny, unavailable
EVENT_REGISTRY_FAULTS#
Values: event-with-no-source, event-with-no-audience-ground,
event-urgency-outside-the-taxonomy, event-category-outside-the-taxonomy,
event-with-no-expiry, template-slot-with-no-declared-field,
declared-field-that-the-template-never-uses,
dedupe-key-that-is-not-a-function-of-the-event,
dedupe-key-over-fields-the-event-does-not-declare,
mandatory-event-that-is-digest-eligible,
never-collapsed-kind-that-is-digest-eligible,
escalation-ground-with-no-silence-window,
silence-window-on-an-event-that-never-escalates,
escalation-window-past-the-events-own-expiry,
scheduled-event-whose-template-names-an-actor,
sensitive-event-whose-template-prints-its-subject
EVENT_SOURCES#
Where an event comes from, which decides what can be trusted about it.
Values: authored, derived, scheduled
EventRegistration#
One registered event kind.
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
string |
required | — |
source |
EventSource | required | — |
category |
string |
required | — |
audienceGrounds |
readonly AudienceGround[] — AudienceGround |
required | The grounds this event's audience may be drawn from. |
defaultUrgency |
string |
required | — |
obligation |
DeliveryObligation | required | — |
sensitivity |
SensitivityClass | null — SensitivityClass |
required | The strongest class any field of this event's template may carry. |
summaryTemplate |
string |
required | — |
templateFields |
readonly string[] |
required | The names of the fields the template's slots are filled from. |
dedupeKeyFields |
readonly string[] |
required | What makes two of these the same notice. |
expiryMinutes |
number | null |
required | How long the notice stays worth sending. Null is refused. |
digestEligible |
boolean |
required | — |
escalationAfterMinutes |
number | null |
required | How long an event may go unanswered before escalation resolves. |
EventRegistryFault#
(typeof EVENT_REGISTRY_FAULTS)[number];
eventRegistryFaults#
Check one deployment's event registry (S8.7.a).
eventRegistryFaults(registry: readonly EventRegistration[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]
EventSource#
(typeof EVENT_SOURCES)[number];
EXPOSURE_CEILING#
The most exposing transport a class of value may travel on.
exposurePermits#
Whether a field's value may travel at this exposure.
exposurePermits(field: SummaryField, exposure: ChannelExposure): boolean
exposureRank#
exposureRank(exposure: ChannelExposure): number
fieldsForExposure#
Re-render one notice's fields for a transport (decision 9).
fieldsForExposure(fields: readonly SummaryField[], exposure: ChannelExposure): readonly SummaryField[]
fieldsForNotice#
The fields as they must reach the renderer, for this transport and reader.
fieldsForNotice(fields: readonly SummaryField[], exposure: ChannelExposure, classOnly: boolean): readonly SummaryField[]
foldGrounds#
Fold every ground that reached one person into one recipient (decision 2).
foldGrounds(candidates: readonly AudienceCandidate[], eventObligation: DeliveryObligation): ResolvedRecipient | null
FrequencyCap#
A ceiling on how often a person may be INTERRUPTED on one channel.
| Field | Type | Required | Notes |
|---|---|---|---|
channel |
string |
required | — |
windowMinutes |
number |
required | — |
maxInterruptions |
number |
required | — |
GROUND_OBLIGATION_FLOOR#
The obligation a ground carries on its own, whatever the event says.
GROUND_RESOLUTION_DEPENDS_ON#
What each ground's resolution is a function of.
GROUNDS_OUTSIDE_THE_AUDIENCE#
The one ground that reaches outside the object's audience (decision 4).
Values: escalation
InterruptionLedger#
What actually happened on a channel, kept apart from what was prevented.
| Field | Type | Required | Notes |
|---|---|---|---|
delivered |
readonly Instant[] — Instant |
required | — |
suppressedByTheCap |
readonly Instant[] — Instant |
required | — |
isDerivedGround#
isDerivedGround(ground: AudienceGround): boolean
isTerminalDelivery#
isTerminalDelivery(state: DeliveryState): boolean
isUsable#
Whether a binding can carry a notice to this person at this moment.
isUsable(binding: ChannelBinding): boolean
LifecycleContext#
| Field | Type | Required | Notes |
|---|---|---|---|
eventId |
string |
required | — |
recipient |
ActorId | required | — |
channel |
string |
required | — |
maxAttempts |
number |
required | — |
addressPreviouslyBounced |
boolean |
required | Whether the address was permanently bounced before this event. |
plannedAt |
Instant | required | When the delivery entered planned. Nothing about it precedes this. |
lifecycleFaults#
Check one transition against the machine (S8.7.g).
lifecycleFaults(event: DeliveryEvent, context: LifecycleContext): readonly RoutingFinding[]
NON_ACKNOWLEDGING_SOURCES#
The sources that are not an acknowledgement.
Values: opened-the-centre
NotificationRoutingFault#
| EventRegistryFault
| RecipientResolutionFault
| ResolutionParityFault
| PreferenceCompositionFault
| TemplateFault
| ChannelRoutingFault
| TimingFault
| DeliveryLifecycleFault
obligationRank#
obligationRank(obligation: DeliveryObligation): number
PlannedDelivery#
One decided delivery: exactly the argument the delivery system demands.
| Field | Type | Required | Notes |
|---|---|---|---|
key |
string |
required | — |
eventId |
string |
required | — |
eventKind |
string |
required | — |
recipient |
ActorId | required | — |
tenant |
TenantId | required | — |
grounds |
readonly AudienceGround[] — AudienceGround |
required | — |
obligation |
DeliveryObligation | required | — |
channel |
string |
required | — |
exposure |
ChannelExposure | required | — |
category |
string |
required | — |
urgency |
string |
required | — |
locale |
string |
required | — |
zone |
string |
required | — |
classOnly |
boolean |
required | True where the notice must be composed from classes rather than values. |
timing |
TimingDisposition | required | — |
releaseAt |
Instant | null — Instant |
required | — |
state |
DeliveryState | required | — |
planNotifications#
Turn one event into the deliveries it produces.
planNotifications(request: PlanRequest): { readonly plan: readonly PlannedDelivery[]; readonly findings: readonly RoutingFinding[]; }
PlanRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
eventId |
string |
required | — |
registration |
EventRegistration | required | — |
audience |
AudienceRequest | required | — |
profiles |
readonly RecipientProfile[] — RecipientProfile |
required | — |
project |
string |
required | — |
domain |
string |
required | — |
now |
Instant | required | — |
bypassThreshold |
string |
required | — |
ambiguityPolicy |
AmbiguityPolicy | required | — |
taxonomy |
NotificationTaxonomy |
required | — |
PREFERENCE_AUTHORITIES#
WHO set a preference, strongest first.
Values: platform-floor, the-person, the-deployment
PREFERENCE_COMPOSITION_FAULTS#
Values: mandatory-notice-silenced-by-a-preference,
required-notice-muted-rather-than-moved,
preference-for-a-channel-the-taxonomy-does-not-have,
role-scoped-preference-authored-by-the-person,
scoped-preference-with-no-scope-value,
global-preference-carrying-a-scope-value,
preference-threshold-outside-the-taxonomy,
digest-choice-on-an-event-that-may-not-be-digested,
deployment-default-overriding-the-person,
more-specific-setting-lost-to-a-broader-one,
absence-of-a-preference-treated-as-a-mute
PREFERENCE_DECISIONS#
What a composed preference decides.
Values: deliver, digest, mute
PREFERENCE_SCOPES#
HOW SPECIFIC a preference is, most specific first. The second axis.
Values: event-kind, category, project, domain, role, global
PreferenceAuthority#
(typeof PREFERENCE_AUTHORITIES)[number];
PreferenceCompositionFault#
(typeof PREFERENCE_COMPOSITION_FAULTS)[number];
PreferenceContext#
What the event and recipient are, for matching a setting's scope.
| Field | Type | Required | Notes |
|---|---|---|---|
eventKind |
string |
required | — |
category |
string |
required | — |
project |
string |
required | — |
domain |
string |
required | — |
roles |
readonly string[] |
required | — |
urgency |
string |
required | — |
channel |
string |
required | — |
obligation |
DeliveryObligation | required | — |
PreferenceDecision#
(typeof PREFERENCE_DECISIONS)[number];
PreferenceOutcome#
| Field | Type | Required | Notes |
|---|---|---|---|
decision |
PreferenceDecision | required | — |
decidedBy |
PreferenceSetting | null — PreferenceSetting |
required | The setting that decided, or null where the floor did. |
considered |
readonly PreferenceSetting[] — PreferenceSetting |
required | Every setting that matched, strongest first. |
preferenceParityFaults#
Check a decision a host says it composed, against the settings it had.
preferenceParityFaults(claimed: PreferenceDecision, settings: readonly PreferenceSetting[], context: PreferenceContext, taxonomy: NotificationTaxonomy): readonly RoutingFinding[]
PreferenceScope#
(typeof PREFERENCE_SCOPES)[number];
PreferenceSetting#
| Field | Type | Required | Notes |
|---|---|---|---|
authority |
PreferenceAuthority | required | — |
scope |
PreferenceScope | required | — |
scopeValue |
string | null |
required | What the scope is bound to — the category, project, domain or role name. |
channel |
string | null |
required | The channel this applies to, or null for every channel. |
decision |
PreferenceDecision | required | — |
urgencyThreshold |
string | null |
required | The weakest urgency this setting still lets through. Null to apply always. |
quietHoursRelease#
The instant a hold placed at at is released (decision 6's second half).
quietHoursRelease(window: QuietHoursWindow, at: Instant, policy: AmbiguityPolicy): { readonly instant: Instant; readonly resolution: ZoneResolution }
quietHoursSpanMinutes#
How long a hold entered at at actually lasts, in minutes.
quietHoursSpanMinutes(window: QuietHoursWindow, at: Instant, policy: AmbiguityPolicy): number
QuietHoursWindow#
When somebody does not want to be interrupted.
| Field | Type | Required | Notes |
|---|---|---|---|
start |
TimeOfDay | required | — |
end |
TimeOfDay | required | — |
zone |
string |
required | An IANA zone name — the RECIPIENT's. |
behaviour |
QuietHoursBehaviour |
required | — |
RECIPIENT_FAULTS#
Values: recipient-in-another-tenant, ground-the-event-does-not-declare,
derived-ground-with-no-pinned-instant,
pinning-instant-on-a-ground-that-derives-nothing,
audience-pinned-before-the-event-happened,
escalation-resolved-at-event-time,
escalation-resolved-before-the-silence-window-elapsed,
delegate-with-no-grant, grant-on-a-ground-that-is-not-a-delegation,
recipient-notified-of-their-own-act,
recipient-whose-identity-has-been-erased, recipient-who-has-departed,
recipient-with-no-locale, recipient-in-a-zone-the-platform-does-not-know,
fan-out-over-the-ceiling
RECIPIENT_SIDE_READINESS#
The readiness values that are facts about the person rather than the build.
Values: no-address, no-consent, unverified-address
RecipientProfile#
Everything about one recipient that is a property of THEM, not of the event.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
roles |
readonly string[] |
required | — |
settings |
readonly PreferenceSetting[] — PreferenceSetting |
required | — |
bindings |
readonly ChannelBinding[] — ChannelBinding |
required | — |
preferredChannel |
string |
required | — |
quietHours |
QuietHoursWindow | null — QuietHoursWindow |
required | — |
cap |
FrequencyCap | null — FrequencyCap |
required | — |
ledger |
InterruptionLedger | required | — |
RecipientResolutionFault#
(typeof RECIPIENT_FAULTS)[number];
RenderedNotice#
What a host says it rendered and is about to hand to the delivery system.
| Field | Type | Required | Notes |
|---|---|---|---|
locale |
string |
required | — |
zone |
string |
required | — |
exposure |
ChannelExposure | required | — |
summary |
string |
required | — |
plainAlternative |
string |
required | The plain alternative: an email's text part, or what a screen reader gets. |
targetLabel |
string | null |
required | — |
targetLink |
string | null |
required | — |
occurredAtWall |
WallClock | required | The event's instant as this notice printed it. |
RenderRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
registration |
EventRegistration | required | — |
fields |
readonly SummaryField[] |
required | — |
recipient |
ResolvedRecipient | required | — |
exposure |
ChannelExposure | required | — |
occurredAt |
Instant | required | — |
targetLabelDisposition |
AuthorizationDisposition |
required | — |
senderLocale |
string |
required | — |
rendersClassesOnly#
Whether this recipient gets classes rather than values, whatever the fields say.
rendersClassesOnly(recipient: ResolvedRecipient): boolean
RESOLUTION_PARITY_FAULTS#
Compare the kit's derivation with the audience a host says it resolved.
Values: recipient-the-derivation-did-not-produce,
recipient-the-host-dropped, obligation-weaker-than-the-grounds-support,
grounds-the-host-discarded
ResolutionParityFault#
(typeof RESOLUTION_PARITY_FAULTS)[number];
resolutionParityFaults#
resolutionParityFaults(derived: readonly ResolvedRecipient[], claimed: readonly ResolvedRecipient[]): readonly RoutingFinding[]
ResolvedRecipient#
One person, every reason they are on the list, and the strongest of them.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
tenant |
TenantId | required | — |
grounds |
readonly AudienceGround[] — AudienceGround |
required | Every ground that reached this person, sorted. Decision 2 keeps the set. |
obligation |
DeliveryObligation | required | — |
insideTheAudience |
boolean |
required | Whether every ground that reached them is one that implies access. |
targetDisposition |
AuthorizationDisposition |
required | — |
standing |
IdentityStanding | required | — |
locale |
string |
required | — |
zone |
string |
required | — |
resolveRecipients#
Turn one event's candidates into the people it will be delivered to (S8.7.b).
resolveRecipients(request: AudienceRequest): { readonly recipients: readonly ResolvedRecipient[]; readonly findings: readonly RoutingFinding[]; }
routeChannel#
Walk the fallback chain and choose a transport (S8.7.e).
routeChannel(request: ChannelRequest): { readonly chosen: ChannelBinding | null; readonly attempted: readonly string[]; readonly findings: readonly RoutingFinding[]; }
RoutingFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
NotificationRoutingFault | required | — |
subject |
string |
required | The event, recipient, channel, window or delivery the finding is about. |
detail |
string |
required | — |
scopeRank#
scopeRank(scope: PreferenceScope): number
settingMatches#
Whether one setting applies to this event, recipient and channel.
settingMatches(setting: PreferenceSetting, context: PreferenceContext): boolean
SILENCEABLE_OBLIGATIONS#
What a preference may do to an obligation.
Values: optional
strongerObligation#
The stronger of two obligations. Decision 2's fold, as one function.
strongerObligation(a: DeliveryObligation, b: DeliveryObligation): DeliveryObligation
TEMPLATE_FAULTS#
Values: rendered-in-the-senders-locale,
time-rendered-outside-the-recipients-zone,
summary-not-produced-by-the-renderer, value-the-exposure-may-not-carry,
presence-disclosing-field-in-a-notification,
plain-alternative-carrying-a-withheld-value,
target-named-under-a-label-refusal, denied-target-offered-as-a-link,
link-carrying-a-withheld-value, escalation-notice-composed-from-values,
notice-rendered-for-a-different-exposure
TemplateFault#
(typeof TEMPLATE_FAULTS)[number];
templateFaults#
Check one rendered notice (S8.7.d).
templateFaults(request: RenderRequest, notice: RenderedNotice): readonly RoutingFinding[]
templateSlots#
The slot names a template actually contains, in order of first appearance.
templateSlots(template: string): readonly string[]
TERMINAL_DELIVERY_STATES#
Values: bounced, suppressed, deduped, expired, acknowledged
TimeOfDay#
A time of day, with no date and no zone. The two are separate on purpose.
| Field | Type | Required | Notes |
|---|---|---|---|
hour |
number |
required | — |
minute |
number |
required | — |
TIMING_DISPOSITIONS#
Values: send-now, hold-until-release, defer-to-digest, expired
TIMING_FAULTS#
Values: quiet-window-evaluated-as-a-simple-range,
quiet-hours-release-at-a-wall-clock-that-does-not-exist,
quiet-hours-evaluated-outside-the-recipients-zone,
quiet-hours-that-suppress-rather-than-delay,
quiet-hours-applied-to-a-mandatory-notice,
bypass-threshold-outside-the-taxonomy,
bypass-that-does-not-reach-the-mandatory-kinds,
cap-counted-over-suppressions, cap-applied-to-the-in-product-channel,
capped-notice-dropped-rather-than-deferred, held-past-its-own-expiry,
digest-eligibility-decided-without-the-urgency
TimingDisposition#
(typeof TIMING_DISPOSITIONS)[number];
TimingFault#
(typeof TIMING_FAULTS)[number];
TimingRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
now |
Instant | required | — |
occurredAt |
Instant | required | — |
registration |
EventRegistration | required | — |
obligation |
DeliveryObligation | required | — |
urgency |
string |
required | — |
exposure |
ChannelExposure | required | — |
channel |
string |
required | The channel being routed, so a cap bound to another one does not apply. |
recipientZone |
string |
required | The recipient's zone, to be checked against the window's. |
quietHours |
QuietHoursWindow | null — QuietHoursWindow |
required | — |
hostSaysQuiet |
boolean | null |
required | Whether the HOST believes this instant is inside the window, or null. |
bypassThreshold |
string |
required | Urgencies at least this strong ignore quiet hours. |
cap |
FrequencyCap | null — FrequencyCap |
required | — |
ledger |
InterruptionLedger | required | — |
ambiguityPolicy |
AmbiguityPolicy | required | — |
taxonomy |
NotificationTaxonomy |
required | — |
TRANSITION_AUTHORITIES#
Who causes a transition, which is the whole of decision 12.
Values: the-platform, the-provider, the-recipient, the-clock
TransitionAuthority#
(typeof TRANSITION_AUTHORITIES)[number];
windowWraps#
Whether a window crosses midnight.
windowWraps(window: QuietHoursWindow): boolean
withheldFields#
Fields whose values are withheld from this render, for whatever reason.
withheldFields(fields: readonly SummaryField[], exposure: ChannelExposure): readonly SummaryField[]
withinQuietHours#
Whether an instant falls inside the window, in the window's own zone.
withinQuietHours(window: QuietHoursWindow, at: Instant): boolean
Valid examples#
No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.
Invalid examples#
No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.
Authorization and scope#
| Symbol | Type | Notes |
| ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| ACTOR_SLOT_NAMES | enumeration | Slot names that name the actor behind an event. |
| ACTORLESS_AUTHORITIES | enumeration | The authorities whose transitions have no actor and must not carry one. |
| AudienceCandidate.actorId | ActorId | — |
| AudienceCandidate.grant | string | null | The grant behind a delegate ground, as ActorRef's delegated variant carries. |
| AudienceCandidate.tenant | TenantId | — |
| AudienceRequest.actor | ActorRef | null | The actor behind the event. Null for a scheduled one, which has none. |
| AudienceRequest.tenant | TenantId | — |
| ChannelBinding.consentGiven | boolean | Whether the person agreed to be reached this way. Holding an address is not agreement. |
| CONSENT_GATED_EXPOSURES | enumeration | The exposures a person must have explicitly agreed to. |
| DeliveryEvent.actor | ActorRef | null | Null wherever the authority has none, and required wherever it has one. |
| DEPLOYMENT_ONLY_SCOPES | enumeration | The scopes only a deployment may author. |
| PlannedDelivery.tenant | TenantId | — |
| PREFERENCE_SCOPES | enumeration | HOW SPECIFIC a preference is, most specific first. The second axis. |
| PreferenceScope | type | — |
| PreferenceSetting.scope | PreferenceScope | — |
| PreferenceSetting.scopeValue | string | null | What the scope is bound to — the category, project, domain or role name. |
| RecipientProfile.actorId | ActorId | — |
| ResolvedRecipient.actorId | ActorId | — |
| ResolvedRecipient.tenant | TenantId | — |
| scopeRank | function | — |
Idempotency and concurrency#
| Symbol | Type | Notes |
|---|---|---|
DeliveryEvent.attempt |
number |
How many times this key has been sent, including this one. |
EventRegistration.dedupeKeyFields |
readonly string[] |
What makes two of these the same notice. |
LifecycleContext.maxAttempts |
number |
— |
Pagination#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
|---|---|---|
DELIVERY_STATES |
enumeration |
— |
DeliveryState |
type |
— |
PlannedDelivery.state |
DeliveryState |
— |
TERMINAL_DELIVERY_STATES |
enumeration |
— |
Compatibility#
Not applicable: nothing on this page is versioned independently of the package.
Deprecation#
| Symbol | Type | Notes |
|---|---|---|
DELIVERY_LIFECYCLE_FAULTS |
enumeration |
— |
DeliveryLifecycleFault |
type |
— |
lifecycleFaults |
function |
Check one transition against the machine (S8.7.g). |
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/notification-routing.ts