fhir-data-utils-ts 0.3.3 → 0.3.4

package/.codex/skills/govern-fhir-data-utilities/SKILL.md

@@ -29,6 +29,10 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   projection. Do not invent resource-specific scalar aliases for indexing.
 - Keep Group membership and ResearchStudy associated parties descriptive;
   neither is a Consent, SMART scope or authorization grant.
+- Keep native R5 SubscriptionTopic/Subscription configuration and notification
+  Bundle parsing separate from the claims-first Communication being delivered.
+  This package owns their reusable types and validation, never HTTP delivery,
+  subscriber persistence, authentication or product notification policy.
 
 ## Change with executable contracts
 

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.4 - 2026-09-23
+
+- Add native FHIR R5 `SubscriptionTopic` and HTTPS rest-hook `Subscription`
+  builders plus the official resource-specific SearchParameter catalogs.
+- Add a strict `subscription-notification` Bundle parser that resolves each
+  advertised full-resource event focus and distinguishes handshake events.
+- Add the claims-first terminal-job `Communication` contract used by DataConv
+  and professional BFFs without introducing transport, storage or product
+  policy into the neutral package.
+
 ## 0.3.3 - 2026-09-23
 
 - Define product-neutral coding-review families and pending-proposal helpers.

package/README.md

@@ -42,6 +42,9 @@ The root export and stable subpaths provide:
   RelatedPerson/telecom helpers and type-only DICOMDIR tree contract;
 - cross-sector terminology, Immunization graphs/reminders, and FHIR R5 Group
   and ResearchStudy contracts previously located only in SOS or Vet packages.
+- native FHIR R5 SubscriptionTopic/Subscription configuration builders,
+  official search catalogs and a strict notification-Bundle parser; terminal
+  asynchronous job messages remain claims-first Communication resources.
 
 Claim catalogs and graph builders are deliberately different surfaces.
 `fhir-data-utils-ts/claims` owns canonical storage names and their specs;
@@ -111,6 +114,22 @@ The package exports builders, traversal/confirmation helpers and
 `CODING_REVIEW_EXAMPLES`. Tests and consumers reuse them instead of duplicating
 claim strings, terminology identifiers, codes or UUIDs.
 
+## R5 asynchronous notifications
+
+`fhir-data-utils-ts/subscription-r5` separates three boundaries:
+
+- `SubscriptionTopic` and `Subscription` are native R5 configuration resources;
+- the job-completion `Communication` is canonical flat-claim business data;
+- `Bundle[type=subscription-notification]` is parsed only at the receiving
+  rest-hook boundary.
+
+The shared package owns types, builders, official SearchParameter metadata and
+validation. DataConv owns emitting the terminal Communication, GW owns durable
+subscription delivery, and each BFF owns authenticated inbox persistence and
+browser/email/push fan-out. Tenant-level Communication subscriptions initially
+use no server-side filter; the receiving BFF routes the minimal full resource by
+its canonical `Communication.recipient` claim.
+
 ## Verification gate
 
 `npm run check` runs strict type checking, all contract tests and built-in

package/dist/claims/communication-claims.d.ts

@@ -15,6 +15,8 @@ export declare const CommunicationClaim: {
     readonly Status: "Communication.status";
     /** Stable communication identifier. */
     readonly Identifier: "Communication.identifier";
+    /** Request or Task that initiated this Communication. */
+    readonly BasedOn: "Communication.based-on";
     /** Subject identifier (typically `did:web`). */
     readonly Subject: "Communication.subject";
     /** Recipient identifier(s); CSV allowed. */
@@ -27,6 +29,8 @@ export declare const CommunicationClaim: {
     readonly NoteText: "Communication.note-text";
     /** Communication topic code (`system|code`). */
     readonly Topic: "Communication.topic";
+    /** Resource references that provide the Communication context; CSV allowed. */
+    readonly About: "Communication.about";
     /** Narrative text (short summary or body). */
     readonly Text: "Communication.text";
     /** Related resource references; CSV allowed. */

package/dist/claims/communication-claims.js

@@ -18,6 +18,8 @@ export const CommunicationClaim = {
     Status: 'Communication.status',
     /** Stable communication identifier. */
     Identifier: 'Communication.identifier',
+    /** Request or Task that initiated this Communication. */
+    BasedOn: 'Communication.based-on',
     /** Subject identifier (typically `did:web`). */
     Subject: 'Communication.subject',
     /** Recipient identifier(s); CSV allowed. */
@@ -30,6 +32,8 @@ export const CommunicationClaim = {
     NoteText: 'Communication.note-text',
     /** Communication topic code (`system|code`). */
     Topic: 'Communication.topic',
+    /** Resource references that provide the Communication context; CSV allowed. */
+    About: 'Communication.about',
     /** Narrative text (short summary or body). */
     Text: 'Communication.text',
     /** Related resource references; CSV allowed. */

package/dist/constants/fhir-code-systems.d.ts

@@ -9,6 +9,8 @@ export declare const FhirCodeSystems: Readonly<{
     readonly SnomedCt: "http://snomed.info/sct";
     readonly Ucum: "http://unitsofmeasure.org";
     readonly CommunicationCategory: "http://terminology.hl7.org/CodeSystem/communication-category";
+    readonly SubscriptionChannelType: "http://terminology.hl7.org/CodeSystem/subscription-channel-type";
+    readonly TaskStatus: "http://hl7.org/fhir/task-status";
     readonly ActReason: "http://terminology.hl7.org/CodeSystem/v3-ActReason";
     readonly ObservationCategory: "http://terminology.hl7.org/CodeSystem/observation-category";
     readonly EventTiming: "http://hl7.org/fhir/event-timing";

package/dist/constants/fhir-code-systems.js

@@ -9,6 +9,8 @@ export const FhirCodeSystems = Object.freeze({
     SnomedCt: 'http://snomed.info/sct',
     Ucum: 'http://unitsofmeasure.org',
     CommunicationCategory: 'http://terminology.hl7.org/CodeSystem/communication-category',
+    SubscriptionChannelType: 'http://terminology.hl7.org/CodeSystem/subscription-channel-type',
+    TaskStatus: 'http://hl7.org/fhir/task-status',
     ActReason: 'http://terminology.hl7.org/CodeSystem/v3-ActReason',
     ObservationCategory: 'http://terminology.hl7.org/CodeSystem/observation-category',
     EventTiming: 'http://hl7.org/fhir/event-timing',

package/dist/constants/fhir-resource-types.d.ts

@@ -108,6 +108,8 @@ export declare const FhirResourceTypes: Readonly<{
 }>;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export declare const ResourceTypesFhirR5: Readonly<{
+    readonly Subscription: "Subscription";
+    readonly SubscriptionTopic: "SubscriptionTopic";
     readonly SubscriptionStatus: "SubscriptionStatus";
     readonly AdverseEvent: "AdverseEvent";
     readonly AllergyIntolerance: "AllergyIntolerance";

package/dist/constants/fhir-resource-types.js

@@ -61,6 +61,8 @@ export const FhirResourceTypes = ResourceTypesFhirR4;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export const ResourceTypesFhirR5 = Object.freeze({
     ...ResourceTypesFhirR4,
+    Subscription: 'Subscription',
+    SubscriptionTopic: 'SubscriptionTopic',
     SubscriptionStatus: 'SubscriptionStatus',
 });
 /** FHIR complex datatypes used as discriminators inside claims-first payloads. */

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export * from './research-study-r5.js';
 export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
+export * from './subscription-r5.js';

package/dist/index.js

@@ -22,3 +22,4 @@ export * from './research-study-r5.js';
 export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
+export * from './subscription-r5.js';

package/dist/subscription-r5.d.ts

@@ -0,0 +1,150 @@
+import type { FhirResource } from './fhir-types.js';
+/** FHIR R5 version implemented by this native subscription boundary. */
+export declare const SubscriptionR5Version: "5.0.0";
+export declare const SubscriptionR5ChannelType: Readonly<{
+    readonly RestHook: "rest-hook";
+}>;
+export declare const SubscriptionR5Content: Readonly<{
+    readonly Empty: "empty";
+    readonly IdOnly: "id-only";
+    readonly FullResource: "full-resource";
+}>;
+export declare const SubscriptionR5Status: Readonly<{
+    readonly Requested: "requested";
+    readonly Active: "active";
+    readonly Error: "error";
+    readonly Off: "off";
+    readonly EnteredInError: "entered-in-error";
+}>;
+export declare const SubscriptionTopicR5Status: Readonly<{
+    readonly Draft: "draft";
+    readonly Active: "active";
+    readonly Retired: "retired";
+    readonly Unknown: "unknown";
+}>;
+export declare const SubscriptionR5NotificationType: Readonly<{
+    readonly Handshake: "handshake";
+    readonly Heartbeat: "heartbeat";
+    readonly EventNotification: "event-notification";
+    readonly QueryStatus: "query-status";
+}>;
+export declare const SubscriptionR5BundleType: Readonly<{
+    readonly Notification: "subscription-notification";
+}>;
+export declare const SubscriptionR5MediaType: "application/fhir+json";
+export declare const FhirFlatClaimContext: Readonly<{
+    readonly Api: "org.hl7.fhir.api";
+}>;
+export declare const CommunicationStatus: Readonly<{
+    readonly Completed: "completed";
+}>;
+export declare const CommunicationCategoryCode: Readonly<{
+    readonly Notification: "notification";
+}>;
+export declare const TaskStatusCode: Readonly<{
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+}>;
+type SearchParameterType = 'date' | 'reference' | 'string' | 'token' | 'uri';
+export type R5SearchParameterDefinition = Readonly<{
+    code: string;
+    type: SearchParameterType;
+    expression: string;
+}>;
+/** Exact Subscription-specific SearchParameters published by FHIR R5 5.0.0. */
+export declare const SubscriptionR5SearchParameterCatalog: readonly R5SearchParameterDefinition[];
+/** Exact SubscriptionTopic-specific SearchParameters published by FHIR R5 5.0.0. */
+export declare const SubscriptionTopicR5SearchParameterCatalog: readonly R5SearchParameterDefinition[];
+export type SubscriptionR5Filter = Readonly<{
+    resourceType?: string;
+    filterParameter: string;
+    comparator?: 'eq' | 'ne';
+    modifier?: string;
+    value: string;
+}>;
+export type SubscriptionR5Parameter = Readonly<{
+    name: string;
+    value: string;
+}>;
+export type SubscriptionR5 = Readonly<{
+    resourceType: 'Subscription';
+    id: string;
+    status: (typeof SubscriptionR5Status)[keyof typeof SubscriptionR5Status];
+    topic: string;
+    reason?: string;
+    filterBy?: readonly SubscriptionR5Filter[];
+    channelType: Readonly<{
+        system: string;
+        code: 'rest-hook';
+    }>;
+    endpoint: string;
+    parameter?: readonly SubscriptionR5Parameter[];
+    contentType: typeof SubscriptionR5MediaType;
+    content: (typeof SubscriptionR5Content)[keyof typeof SubscriptionR5Content];
+}>;
+export type SubscriptionTopicR5 = Readonly<{
+    resourceType: 'SubscriptionTopic';
+    id: string;
+    url: string;
+    status: (typeof SubscriptionTopicR5Status)[keyof typeof SubscriptionTopicR5Status];
+    resourceTrigger: readonly Readonly<{
+        resource: string;
+    }>[];
+    canFilterBy: readonly Readonly<{
+        resource: string;
+        filterParameter: string;
+        comparator: readonly ('eq' | 'ne')[];
+    }>[];
+}>;
+/** Builds the native R5 topic used to notify subscribers about Communication writes. */
+export declare function buildCommunicationSubscriptionTopicR5(input: Readonly<{
+    id: string;
+    url: string;
+}>): SubscriptionTopicR5;
+/** Builds one native R5 rest-hook Subscription. This resource is configuration, not flat clinical state. */
+export declare function buildRestHookSubscriptionR5(input: Readonly<{
+    id: string;
+    topic: string;
+    endpoint: string;
+    filters?: readonly SubscriptionR5Filter[];
+    parameters?: readonly SubscriptionR5Parameter[];
+    content?: SubscriptionR5['content'];
+    reason?: string;
+}>): SubscriptionR5;
+export type TerminalJobStatusCode = (typeof TaskStatusCode)[keyof typeof TaskStatusCode];
+/**
+ * Builds the canonical claims-first Communication emitted when an asynchronous
+ * Task reaches a terminal state. `Communication.status=completed` describes
+ * the sent message; `Communication.content-code` carries the linked Task state.
+ */
+export declare function buildTerminalJobCommunication(input: Readonly<{
+    id: string;
+    threadId: string;
+    jobId: string;
+    jobStatus: TerminalJobStatusCode;
+    recipient: string;
+    sender: string;
+    researchStudyReference: string;
+    sent: string;
+}>): FhirResource & Readonly<{
+    resourceType: 'Communication';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+export type ParsedSubscriptionNotificationEventR5 = Readonly<{
+    eventNumber: string;
+    timestamp?: string;
+    focusReference: string;
+    focusResource: FhirResource;
+}>;
+export type ParsedSubscriptionNotificationR5 = Readonly<{
+    type: (typeof SubscriptionR5NotificationType)[keyof typeof SubscriptionR5NotificationType];
+    subscriptionReference: string;
+    topic?: string;
+    events: readonly ParsedSubscriptionNotificationEventR5[];
+}>;
+/** Validates a standard R5 notification Bundle and resolves every advertised full-resource focus. */
+export declare function parseSubscriptionNotificationR5(input: unknown): ParsedSubscriptionNotificationR5;
+export {};

package/dist/subscription-r5.js

@@ -0,0 +1,202 @@
+import { CommunicationClaim } from './claims/communication-claims.js';
+import { FhirCodeSystems } from './constants/fhir-code-systems.js';
+import { ResourceTypesFhirR5 } from './constants/fhir-resource-types.js';
+/** FHIR R5 version implemented by this native subscription boundary. */
+export const SubscriptionR5Version = '5.0.0';
+export const SubscriptionR5ChannelType = Object.freeze({ RestHook: 'rest-hook' });
+export const SubscriptionR5Content = Object.freeze({
+    Empty: 'empty',
+    IdOnly: 'id-only',
+    FullResource: 'full-resource',
+});
+export const SubscriptionR5Status = Object.freeze({
+    Requested: 'requested',
+    Active: 'active',
+    Error: 'error',
+    Off: 'off',
+    EnteredInError: 'entered-in-error',
+});
+export const SubscriptionTopicR5Status = Object.freeze({
+    Draft: 'draft',
+    Active: 'active',
+    Retired: 'retired',
+    Unknown: 'unknown',
+});
+export const SubscriptionR5NotificationType = Object.freeze({
+    Handshake: 'handshake',
+    Heartbeat: 'heartbeat',
+    EventNotification: 'event-notification',
+    QueryStatus: 'query-status',
+});
+export const SubscriptionR5BundleType = Object.freeze({ Notification: 'subscription-notification' });
+export const SubscriptionR5MediaType = 'application/fhir+json';
+export const FhirFlatClaimContext = Object.freeze({ Api: 'org.hl7.fhir.api' });
+export const CommunicationStatus = Object.freeze({ Completed: 'completed' });
+export const CommunicationCategoryCode = Object.freeze({ Notification: 'notification' });
+export const TaskStatusCode = Object.freeze({ Completed: 'completed', Failed: 'failed' });
+const searchParameter = (code, type, expression) => Object.freeze({ code, type, expression });
+/** Exact Subscription-specific SearchParameters published by FHIR R5 5.0.0. */
+export const SubscriptionR5SearchParameterCatalog = Object.freeze([
+    searchParameter('contact', 'token', 'Subscription.contact'),
+    searchParameter('content-level', 'token', 'Subscription.content'),
+    searchParameter('filter-value', 'string', 'Subscription.filterBy.value'),
+    searchParameter('identifier', 'token', 'Subscription.identifier'),
+    searchParameter('name', 'string', 'Subscription.name'),
+    searchParameter('owner', 'reference', 'Subscription.managingEntity'),
+    searchParameter('payload', 'token', 'Subscription.contentType'),
+    searchParameter('status', 'token', 'Subscription.status'),
+    searchParameter('topic', 'uri', 'Subscription.topic'),
+    searchParameter('type', 'token', 'Subscription.channelType'),
+    searchParameter('url', 'uri', 'Subscription.endpoint'),
+]);
+/** Exact SubscriptionTopic-specific SearchParameters published by FHIR R5 5.0.0. */
+export const SubscriptionTopicR5SearchParameterCatalog = Object.freeze([
+    searchParameter('date', 'date', 'SubscriptionTopic.date'),
+    searchParameter('derived-or-self', 'uri', 'SubscriptionTopic.url | SubscriptionTopic.derivedFrom'),
+    searchParameter('effective', 'date', 'SubscriptionTopic.effectivePeriod'),
+    searchParameter('event', 'token', 'SubscriptionTopic.eventTrigger.event'),
+    searchParameter('identifier', 'token', 'SubscriptionTopic.identifier'),
+    searchParameter('resource', 'uri', 'SubscriptionTopic.resourceTrigger.resource | SubscriptionTopic.eventTrigger.resource | SubscriptionTopic.canFilterBy.resource | SubscriptionTopic.notificationShape.resource'),
+    searchParameter('status', 'token', 'SubscriptionTopic.status'),
+    searchParameter('title', 'string', 'SubscriptionTopic.title'),
+    searchParameter('trigger-description', 'string', 'SubscriptionTopic.resourceTrigger.description'),
+    searchParameter('url', 'uri', 'SubscriptionTopic.url'),
+    searchParameter('version', 'token', 'SubscriptionTopic.version'),
+]);
+/** Builds the native R5 topic used to notify subscribers about Communication writes. */
+export function buildCommunicationSubscriptionTopicR5(input) {
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.SubscriptionTopic,
+        id: required(input.id, 'subscription_topic_id_required'),
+        url: absoluteHttpsUrl(input.url, 'subscription_topic_url_invalid'),
+        status: SubscriptionTopicR5Status.Active,
+        resourceTrigger: Object.freeze([{ resource: ResourceTypesFhirR5.Communication }]),
+        canFilterBy: Object.freeze([
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'identifier', comparator: Object.freeze(['eq', 'ne']) }),
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'recipient', comparator: Object.freeze(['eq', 'ne']) }),
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'status', comparator: Object.freeze(['eq', 'ne']) }),
+        ]),
+    });
+}
+/** Builds one native R5 rest-hook Subscription. This resource is configuration, not flat clinical state. */
+export function buildRestHookSubscriptionR5(input) {
+    const filters = Object.freeze((input.filters ?? []).map(filter => Object.freeze({
+        ...(filter.resourceType ? { resourceType: required(filter.resourceType, 'subscription_filter_resource_required') } : {}),
+        filterParameter: required(filter.filterParameter, 'subscription_filter_parameter_required'),
+        ...(filter.comparator ? { comparator: filter.comparator } : {}),
+        ...(filter.modifier ? { modifier: filter.modifier } : {}),
+        value: required(filter.value, 'subscription_filter_value_required'),
+    })));
+    const parameters = Object.freeze((input.parameters ?? []).map(parameter => Object.freeze({
+        name: required(parameter.name, 'subscription_parameter_name_required'),
+        value: required(parameter.value, 'subscription_parameter_value_required'),
+    })));
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.Subscription,
+        id: required(input.id, 'subscription_id_required'),
+        status: SubscriptionR5Status.Requested,
+        topic: absoluteHttpsUrl(input.topic, 'subscription_topic_url_invalid'),
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        ...(filters.length ? { filterBy: filters } : {}),
+        channelType: Object.freeze({
+            system: FhirCodeSystems.SubscriptionChannelType,
+            code: SubscriptionR5ChannelType.RestHook,
+        }),
+        endpoint: absoluteHttpsUrl(input.endpoint, 'subscription_endpoint_invalid'),
+        ...(parameters.length ? { parameter: parameters } : {}),
+        contentType: SubscriptionR5MediaType,
+        content: input.content ?? SubscriptionR5Content.FullResource,
+    });
+}
+/**
+ * Builds the canonical claims-first Communication emitted when an asynchronous
+ * Task reaches a terminal state. `Communication.status=completed` describes
+ * the sent message; `Communication.content-code` carries the linked Task state.
+ */
+export function buildTerminalJobCommunication(input) {
+    if (!Object.values(TaskStatusCode).includes(input.jobStatus))
+        throw new TypeError('terminal_job_status_invalid');
+    const sent = required(input.sent, 'terminal_job_sent_required');
+    if (Number.isNaN(Date.parse(sent)))
+        throw new TypeError('terminal_job_sent_invalid');
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.Communication,
+        id: required(input.id, 'terminal_job_communication_id_required'),
+        meta: Object.freeze({ claims: Object.freeze({
+                '@context': FhirFlatClaimContext.Api,
+                [CommunicationClaim.Identifier]: required(input.threadId, 'terminal_job_thread_required'),
+                [CommunicationClaim.Status]: CommunicationStatus.Completed,
+                [CommunicationClaim.Category]: `${FhirCodeSystems.CommunicationCategory}|${CommunicationCategoryCode.Notification}`,
+                [CommunicationClaim.Recipient]: required(input.recipient, 'terminal_job_recipient_required'),
+                [CommunicationClaim.Sender]: required(input.sender, 'terminal_job_sender_required'),
+                [CommunicationClaim.Sent]: sent,
+                [CommunicationClaim.Subject]: required(input.researchStudyReference, 'terminal_job_study_required'),
+                [CommunicationClaim.ContentReference]: `${ResourceTypesFhirR5.Task}/${required(input.jobId, 'terminal_job_id_required')}`,
+                [CommunicationClaim.ContentCode]: `${FhirCodeSystems.TaskStatus}|${input.jobStatus}`,
+            }) }),
+    });
+}
+/** Validates a standard R5 notification Bundle and resolves every advertised full-resource focus. */
+export function parseSubscriptionNotificationR5(input) {
+    const bundle = record(input);
+    if (bundle.resourceType !== ResourceTypesFhirR5.Bundle || bundle.type !== SubscriptionR5BundleType.Notification) {
+        throw new TypeError('subscription_notification_bundle_invalid');
+    }
+    const entries = Array.isArray(bundle.entry) ? bundle.entry : [];
+    if (entries.length < 1 || entries.length > 101)
+        throw new TypeError('subscription_notification_entries_invalid');
+    const resources = entries.map(entry => record(record(entry).resource)).filter(resource => resource.resourceType);
+    const status = resources.find(resource => resource.resourceType === ResourceTypesFhirR5.SubscriptionStatus);
+    if (!status)
+        throw new TypeError('subscription_notification_status_missing');
+    const notificationType = required(String(status.type ?? ''), 'subscription_notification_type_missing');
+    if (!Object.values(SubscriptionR5NotificationType).includes(notificationType)) {
+        throw new TypeError('subscription_notification_type_invalid');
+    }
+    const subscriptionReference = required(String(record(status.subscription).reference ?? ''), 'subscription_notification_subscription_missing');
+    const rawEvents = Array.isArray(status.notificationEvent) ? status.notificationEvent : [];
+    if (notificationType === SubscriptionR5NotificationType.EventNotification && rawEvents.length < 1) {
+        throw new TypeError('subscription_notification_event_missing');
+    }
+    const events = rawEvents.map(rawEvent => {
+        const event = record(rawEvent);
+        const focusReference = required(String(record(event.focus).reference ?? ''), 'subscription_notification_focus_missing');
+        const focusResource = resources.find(resource => `${resource.resourceType}/${resource.id ?? ''}` === focusReference);
+        if (!focusResource)
+            throw new TypeError('subscription_notification_focus_missing');
+        return Object.freeze({
+            eventNumber: required(String(event.eventNumber ?? ''), 'subscription_notification_event_number_missing'),
+            ...(event.timestamp ? { timestamp: String(event.timestamp) } : {}),
+            focusReference,
+            focusResource: focusResource,
+        });
+    });
+    return Object.freeze({
+        type: notificationType,
+        subscriptionReference,
+        ...(status.topic ? { topic: String(status.topic) } : {}),
+        events: Object.freeze(events),
+    });
+}
+function absoluteHttpsUrl(value, error) {
+    const text = required(value, error);
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new TypeError(error);
+    }
+    if (url.protocol !== 'https:')
+        throw new TypeError(error);
+    return url.href;
+}
+function required(value, error) {
+    const text = String(value ?? '').trim();
+    if (!text)
+        throw new TypeError(error);
+    return text;
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -109,7 +109,22 @@ family for every assessment scale.
 | Preserve an obsolete input | Explicit read-only compatibility adapter |
 | Add transport, SMART or persistence behavior | Owning SDK/service, never this package |
 | Add sector terminology or policy | SOS, Vet or UHC data package |
+| Configure an R5 SubscriptionTopic/Subscription | Native builder and official search catalog in `subscription-r5`; registration remains in the owning service |
+| Persist or deliver a subscription event | GW/BFF transport and storage, never this package |
 
 Converters and builders import catalog symbols. Tests may spell native FHIR
 wire fields, but do not duplicate flat-claim paths except when proving that a
 malformed or invented path is rejected.
+
+## Subscription notification boundary
+
+FHIR R5 `SubscriptionTopic` and `Subscription` are native configuration
+resources, not flat clinical persistence. This package owns their strict typed
+builders, the official R5 resource-specific SearchParameter catalogs and the
+parser for `Bundle[type=subscription-notification]`. It also owns the minimal
+claims-first terminal Task `Communication` shape so producers and receivers do
+not duplicate claim paths.
+
+HTTP delivery, authentication, durable outbox/inbox storage and browser or
+email/push fan-out remain in GW, DataConv and the product BFFs. The neutral
+package contains no HTTP client and no gateway policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",
@@ -107,6 +107,10 @@
       "types": "./dist/imaging-types.d.ts",
       "default": "./dist/imaging-types.js"
     },
+    "./subscription-r5": {
+      "types": "./dist/subscription-r5.d.ts",
+      "default": "./dist/subscription-r5.js"
+    },
     "./constants": {
       "types": "./dist/constants/index.d.ts",
       "default": "./dist/constants/index.js"