gdc-common-utils-ts 1.17.0 → 1.18.1

package/README.md

@@ -30,6 +30,24 @@ boundaries used in `gdc-common-utils-ts`.
 - `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
 - `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
 
+## 101 Test Convention
+
+Every `101` test in this repo is expected to be a didactic executable tutorial,
+not only a behavior check.
+
+Required shape for `101` tests:
+
+- start with a short `Teaching goal` comment block
+- explain the main app/business flow, not only internal plumbing
+- use explicit `Step 1.`, `Step 2.`, ... comments for the happy path
+- make clear what the user/app already has, what is shown, what is edited,
+  what is saved, and what is reloaded
+- if a low-level helper path is shown, mark it explicitly as an escape hatch
+  and not the primary `101` path
+
+The goal is that a developer can read the test top-to-bottom as tutorial
+material without needing chat history or private repo context.
+
 If you need the canonical explanation of how DIDComm envelope, batch body,
 entry types, FHIR-like resources, and `resource.meta.claims` fit together,
 read first:
@@ -213,13 +231,14 @@ import { HostNetworkTypes } from 'gdc-common-utils-ts/constants/network';
 
 const hostContext = {
   participantId: 'host',
+  hostCoverageScope: 'EU',
   jurisdiction: 'ES',
   version: 'v1',
   hostNetwork: HostNetworkTypes.Test,
 };
 
 const discoveryPath = buildGwDspaceVersionWellKnownPath(hostContext);
-const metadata = buildDspaceVersionMetadata('/host/cds-ES/v1/test/dsp');
+const metadata = buildDspaceVersionMetadata('/host/cds-EU/v1/test/dsp');
 const catalogPath = buildGwCatalogArtifactPath(hostContext);
 const catalogUrl = deriveGwCatalogArtifactUrlFromDspaceVersion(
   `https://host.example.org${discoveryPath}`,

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

@@ -9,6 +9,8 @@ export declare function getCommunicationCategoryList(claims: CommunicationIntero
 export declare function setCommunicationCategory(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
 export declare function addCommunicationCategoryList(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
 export declare function removeCommunicationCategoryList(claims: CommunicationInteroperableClaims, value: string | readonly string[]): CommunicationInteroperableClaims;
+export declare function getCommunicationTopic(claims: CommunicationInteroperableClaims): string;
+export declare function setCommunicationTopic(claims: CommunicationInteroperableClaims, value: unknown): CommunicationInteroperableClaims;
 export declare function getCommunicationText(claims: CommunicationInteroperableClaims): string;
 export declare function setCommunicationText(claims: CommunicationInteroperableClaims, value: unknown): CommunicationInteroperableClaims;
 export declare function getCommunicationContentAttachmentData(claims: CommunicationInteroperableClaims): string;

package/dist/claims/claims-helpers-communication.js

@@ -37,6 +37,12 @@ export function addCommunicationCategoryList(claims, value) {
 export function removeCommunicationCategoryList(claims, value) {
     return removeClaimValues(claims, CommunicationClaim.Category, value);
 }
+export function getCommunicationTopic(claims) {
+    return getCommunicationScalar(claims, CommunicationClaim.Topic);
+}
+export function setCommunicationTopic(claims, value) {
+    return setCommunicationScalar(claims, CommunicationClaim.Topic, value);
+}
 export function getCommunicationText(claims) {
     return getCommunicationScalar(claims, CommunicationClaim.Text);
 }

package/dist/constants/service-capabilities.d.ts

@@ -1,63 +1,93 @@
 /**
- * Canonical capability families persisted through
+ * Canonical persisted capability values stored in
  * `org.schema.Service.serviceType`.
  */
-export declare const ServiceCapabilityFamily: {
-    readonly Indexing: "indexing";
-    readonly DigitalTwin: "digitaltwin";
+export declare const ServiceCapability: {
+    readonly IndexReader: "organization/Composition.rs";
+    readonly IndexProvider: "organization/Composition.cruds";
+    readonly DigitalTwinReader: "organization/ResearchSubject.rs";
+    readonly DigitalTwinProvider: "organization/ResearchSubject.cruds";
 };
-export type ServiceCapabilityFamilyValue = typeof ServiceCapabilityFamily[keyof typeof ServiceCapabilityFamily];
+export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
 /**
- * Canonical capability tokens currently documented for tenant activation.
- *
- * The family prefix is the stable part of the contract. Suffixes such as
- * `.rs` and `.cruds` can evolve independently across runtimes.
+ * Canonical capability families derived from the persisted service capability
+ * values.
  */
-export declare const ServiceCapabilityToken: {
+export declare const ServiceCapabilityKind: {
+    readonly Indexing: "organization/composition";
+    readonly DigitalTwin: "organization/researchsubject";
+};
+export type ServiceCapabilityKindValue = typeof ServiceCapabilityKind[keyof typeof ServiceCapabilityKind];
+/**
+ * @deprecated Legacy serviceType values accepted for backward compatibility.
+ */
+export declare const DeprecatedServiceCapabilityToken: {
     readonly IndexReader: "indexing.rs";
     readonly IndexProvider: "indexing.cruds";
     readonly DigitalTwinReader: "digitaltwin.rs";
     readonly DigitalTwinProvider: "digitaltwin.cruds";
+};
+export type DeprecatedServiceCapabilityTokenValue = typeof DeprecatedServiceCapabilityToken[keyof typeof DeprecatedServiceCapabilityToken];
+/**
+ * @deprecated Prefer `ServiceCapability`.
+ *
+ * Kept as a compatibility alias for older callers that imported
+ * `ServiceCapabilityToken`.
+ */
+export declare const ServiceCapabilityToken: {
+    readonly IndexReader: "organization/Composition.rs";
+    readonly IndexProvider: "organization/Composition.cruds";
+    readonly DigitalTwinReader: "organization/ResearchSubject.rs";
+    readonly DigitalTwinProvider: "organization/ResearchSubject.cruds";
     /**
      * @deprecated Prefer `IndexReader`.
      */
-    readonly IndexingReadSearch: "indexing.rs";
+    readonly IndexingReadSearch: "organization/Composition.rs";
     /**
      * @deprecated Prefer `IndexProvider`.
      */
-    readonly IndexingCruds: "indexing.cruds";
+    readonly IndexingCruds: "organization/Composition.cruds";
     /**
      * @deprecated Prefer `DigitalTwinReader`.
      */
-    readonly DigitalTwinReadSearch: "digitaltwin.rs";
+    readonly DigitalTwinReadSearch: "organization/ResearchSubject.rs";
     /**
      * @deprecated Prefer `DigitalTwinProvider`.
      */
-    readonly DigitalTwinCruds: "digitaltwin.cruds";
-};
-export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
-/**
- * SDK-facing capability names.
- *
- * These names are intentionally more explicit than the persisted claim tokens:
- * - `Provider` maps to write/manage capability (`*.cruds`)
- * - `Reader` maps to read/search capability (`*.rs`)
- */
-export declare const ServiceCapability: {
-    readonly IndexProvider: "indexing.cruds";
-    readonly IndexReader: "indexing.rs";
-    readonly DigitalTwinProvider: "digitaltwin.cruds";
-    readonly DigitalTwinReader: "digitaltwin.rs";
+    readonly DigitalTwinCruds: "organization/ResearchSubject.cruds";
     /**
-     * @deprecated Prefer `IndexProvider`.
+     * @deprecated Prefer `ServiceCapability.IndexReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.rs`.
      */
-    readonly IndexingProvider: "indexing.cruds";
+    readonly LegacyIndexReader: "indexing.rs";
     /**
-     * @deprecated Prefer `IndexReader`.
+     * @deprecated Prefer `ServiceCapability.IndexProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.cruds`.
+     */
+    readonly LegacyIndexProvider: "indexing.cruds";
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.rs`.
      */
-    readonly IndexingReader: "indexing.rs";
+    readonly LegacyDigitalTwinReader: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.cruds`.
+     */
+    readonly LegacyDigitalTwinProvider: "digitaltwin.cruds";
 };
-export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
+/**
+ * @deprecated Prefer `ServiceCapabilityValue`.
+ */
+export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
+/**
+ * Normalizes a service capability token into its canonical persisted form.
+ */
+export declare function normalizeServiceCapability(value: string | undefined | null): string | undefined;
 /**
  * Parses the CSV stored in `org.schema.Service.serviceType`.
  */
@@ -67,14 +97,14 @@ export declare function parseServiceCapabilityTokens(value: unknown): string[];
  */
 export declare function serializeServiceCapabilityTokens(values: ReadonlyArray<string | undefined | null>): string | undefined;
 /**
- * Returns the capability family prefix from a token.
+ * Returns the capability family prefix from a persisted capability token.
  */
-export declare function getServiceCapabilityFamily(value: string | undefined): string | undefined;
+export declare function getServiceCapabilityKind(value: string | undefined): string | undefined;
 /**
  * Checks whether the claim contains at least one capability from the requested
  * family.
  */
-export declare function hasServiceCapabilityFamily(value: unknown, family: ServiceCapabilityFamilyValue | string): boolean;
+export declare function hasServiceCapabilityKind(value: unknown, family: ServiceCapabilityKindValue | string): boolean;
 /**
  * Returns whether a capability token denotes a discoverable provider/service
  * role rather than a reader-only role.

package/dist/constants/service-capabilities.js

@@ -1,105 +1,156 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 /**
- * Canonical capability families persisted through
+ * Canonical persisted capability values stored in
  * `org.schema.Service.serviceType`.
  */
-export const ServiceCapabilityFamily = {
-    Indexing: 'indexing',
-    DigitalTwin: 'digitaltwin',
+export const ServiceCapability = {
+    IndexReader: 'organization/Composition.rs',
+    IndexProvider: 'organization/Composition.cruds',
+    DigitalTwinReader: 'organization/ResearchSubject.rs',
+    DigitalTwinProvider: 'organization/ResearchSubject.cruds',
 };
 /**
- * Canonical capability tokens currently documented for tenant activation.
- *
- * The family prefix is the stable part of the contract. Suffixes such as
- * `.rs` and `.cruds` can evolve independently across runtimes.
+ * Canonical capability families derived from the persisted service capability
+ * values.
  */
-export const ServiceCapabilityToken = {
+export const ServiceCapabilityKind = {
+    Indexing: 'organization/composition',
+    DigitalTwin: 'organization/researchsubject',
+};
+/**
+ * @deprecated Legacy serviceType values accepted for backward compatibility.
+ */
+export const DeprecatedServiceCapabilityToken = {
     IndexReader: 'indexing.rs',
     IndexProvider: 'indexing.cruds',
     DigitalTwinReader: 'digitaltwin.rs',
     DigitalTwinProvider: 'digitaltwin.cruds',
+};
+/**
+ * @deprecated Prefer `ServiceCapability`.
+ *
+ * Kept as a compatibility alias for older callers that imported
+ * `ServiceCapabilityToken`.
+ */
+export const ServiceCapabilityToken = {
+    IndexReader: ServiceCapability.IndexReader,
+    IndexProvider: ServiceCapability.IndexProvider,
+    DigitalTwinReader: ServiceCapability.DigitalTwinReader,
+    DigitalTwinProvider: ServiceCapability.DigitalTwinProvider,
     /**
      * @deprecated Prefer `IndexReader`.
      */
-    IndexingReadSearch: 'indexing.rs',
+    IndexingReadSearch: ServiceCapability.IndexReader,
     /**
      * @deprecated Prefer `IndexProvider`.
      */
-    IndexingCruds: 'indexing.cruds',
+    IndexingCruds: ServiceCapability.IndexProvider,
     /**
      * @deprecated Prefer `DigitalTwinReader`.
      */
-    DigitalTwinReadSearch: 'digitaltwin.rs',
+    DigitalTwinReadSearch: ServiceCapability.DigitalTwinReader,
     /**
      * @deprecated Prefer `DigitalTwinProvider`.
      */
-    DigitalTwinCruds: 'digitaltwin.cruds',
-};
-/**
- * SDK-facing capability names.
- *
- * These names are intentionally more explicit than the persisted claim tokens:
- * - `Provider` maps to write/manage capability (`*.cruds`)
- * - `Reader` maps to read/search capability (`*.rs`)
- */
-export const ServiceCapability = {
-    IndexProvider: ServiceCapabilityToken.IndexProvider,
-    IndexReader: ServiceCapabilityToken.IndexReader,
-    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinProvider,
-    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReader,
+    DigitalTwinCruds: ServiceCapability.DigitalTwinProvider,
     /**
-     * @deprecated Prefer `IndexProvider`.
+     * @deprecated Prefer `ServiceCapability.IndexReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.rs`.
      */
-    IndexingProvider: ServiceCapabilityToken.IndexProvider,
+    LegacyIndexReader: DeprecatedServiceCapabilityToken.IndexReader,
     /**
-     * @deprecated Prefer `IndexReader`.
+     * @deprecated Prefer `ServiceCapability.IndexProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `indexing.cruds`.
+     */
+    LegacyIndexProvider: DeprecatedServiceCapabilityToken.IndexProvider,
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinReader`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.rs`.
+     */
+    LegacyDigitalTwinReader: DeprecatedServiceCapabilityToken.DigitalTwinReader,
+    /**
+     * @deprecated Prefer `ServiceCapability.DigitalTwinProvider`.
+     * Legacy persisted value kept for compatibility while external payloads
+     * still emit `digitaltwin.cruds`.
      */
-    IndexingReader: ServiceCapabilityToken.IndexReader,
+    LegacyDigitalTwinProvider: DeprecatedServiceCapabilityToken.DigitalTwinProvider,
 };
+const CANONICAL_SERVICE_CAPABILITY_BY_VALUE = new Map([
+    [String(ServiceCapability.IndexReader).toLowerCase(), ServiceCapability.IndexReader],
+    [String(ServiceCapability.IndexProvider).toLowerCase(), ServiceCapability.IndexProvider],
+    [String(ServiceCapability.DigitalTwinReader).toLowerCase(), ServiceCapability.DigitalTwinReader],
+    [String(ServiceCapability.DigitalTwinProvider).toLowerCase(), ServiceCapability.DigitalTwinProvider],
+    [String(DeprecatedServiceCapabilityToken.IndexReader).toLowerCase(), ServiceCapability.IndexReader],
+    [String(DeprecatedServiceCapabilityToken.IndexProvider).toLowerCase(), ServiceCapability.IndexProvider],
+    [String(DeprecatedServiceCapabilityToken.DigitalTwinReader).toLowerCase(), ServiceCapability.DigitalTwinReader],
+    [String(DeprecatedServiceCapabilityToken.DigitalTwinProvider).toLowerCase(), ServiceCapability.DigitalTwinProvider],
+]);
+function splitServiceCapabilityToken(value) {
+    const lastDot = value.lastIndexOf('.');
+    if (lastDot < 0) {
+        return { family: value || undefined, suffix: undefined };
+    }
+    return {
+        family: value.slice(0, lastDot) || undefined,
+        suffix: value.slice(lastDot + 1) || undefined,
+    };
+}
+/**
+ * Normalizes a service capability token into its canonical persisted form.
+ */
+export function normalizeServiceCapability(value) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        return undefined;
+    return CANONICAL_SERVICE_CAPABILITY_BY_VALUE.get(normalized.toLowerCase()) || normalized;
+}
 /**
  * Parses the CSV stored in `org.schema.Service.serviceType`.
  */
 export function parseServiceCapabilityTokens(value) {
     return Array.from(new Set(String(value || '')
         .split(',')
-        .map((item) => item.trim())
-        .filter(Boolean)));
+        .map((item) => normalizeServiceCapability(item))
+        .filter((item) => Boolean(item))));
 }
 /**
  * Serializes capability tokens into the canonical CSV claim format.
  */
 export function serializeServiceCapabilityTokens(values) {
     const normalized = Array.from(new Set(values
-        .map((item) => String(item || '').trim())
-        .filter(Boolean)));
+        .map((item) => normalizeServiceCapability(item))
+        .filter((item) => Boolean(item))));
     return normalized.length ? normalized.join(',') : undefined;
 }
 /**
- * Returns the capability family prefix from a token.
+ * Returns the capability family prefix from a persisted capability token.
  */
-export function getServiceCapabilityFamily(value) {
-    const normalized = String(value || '').trim().toLowerCase();
+export function getServiceCapabilityKind(value) {
+    const normalized = normalizeServiceCapability(value)?.toLowerCase();
     if (!normalized)
         return undefined;
-    return normalized.split('.')[0] || undefined;
+    return splitServiceCapabilityToken(normalized).family;
 }
 /**
  * Checks whether the claim contains at least one capability from the requested
  * family.
  */
-export function hasServiceCapabilityFamily(value, family) {
+export function hasServiceCapabilityKind(value, family) {
     const normalizedFamily = String(family || '').trim().toLowerCase();
     if (!normalizedFamily)
         return false;
-    return parseServiceCapabilityTokens(value).some((item) => getServiceCapabilityFamily(item) === normalizedFamily);
+    return parseServiceCapabilityTokens(value).some((item) => getServiceCapabilityKind(item) === normalizedFamily);
 }
 /**
  * Returns whether a capability token denotes a discoverable provider/service
  * role rather than a reader-only role.
  */
 export function isProviderServiceCapability(value) {
-    const normalized = String(value || '').trim().toLowerCase();
-    return normalized === ServiceCapabilityToken.IndexProvider
-        || normalized === ServiceCapabilityToken.DigitalTwinProvider;
+    const normalized = normalizeServiceCapability(value);
+    return normalized === ServiceCapability.IndexProvider
+        || normalized === ServiceCapability.DigitalTwinProvider;
 }

package/dist/examples/communication-attached-bundle-session.js

@@ -1,17 +1,18 @@
 // Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
-import { HealthcareBasicSections, HealthcareCanonicalSectionFamilies, HealthcareConsentPurposes, HealthcareCoreSections, } from '../constants/healthcare.js';
+import { HealthcareBasicSections, HealthcareCanonicalSectionFamilies, HealthcareConsentPurposes, HealthcareCoreSections, HealthcareKindOfDocumentSections, } from '../constants/healthcare.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { DataspaceSectors } from '../constants/sectors.js';
 import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
 import { EXAMPLE_COMMUNICATION_IDENTIFIER, EXAMPLE_CONSENT_DATE, EXAMPLE_CONSENT_IDENTIFIER, EXAMPLE_CONSENT_PERIOD_END, EXAMPLE_CONSENT_PERIOD_START, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_CONSENT_PURPOSE_EMERGENCY_TREATMENT, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_HEALTHCARE_ACTOR_ROLE_GENERALIST_MEDICAL_PRACTITIONER, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_HEALTHCARE_JURISDICTION, EXAMPLE_IPS_BUNDLE_NOTE_TEXT, EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER, EXAMPLE_MEDICATION_STATEMENT_STATUS, EXAMPLE_MEDICATION_STATEMENT_TEXT, EXAMPLE_PROVIDER_ORGANIZATION_DID, EXAMPLE_SECONDARY_HEALTHCARE_JURISDICTION, EXAMPLE_SUBJECT_DID, } from './shared.js';
 import { CommunicationAttachedBundleSession, createConsentAccessEditor, } from '../utils/communication-attached-bundle-session.js';
-import { setCommunicationCategory, setCommunicationIdentifier, setCommunicationSubject, setCommunicationText, } from '../claims/claims-helpers-communication.js';
+import { setCommunicationCategory, setCommunicationIdentifier, setCommunicationSubject, setCommunicationText, setCommunicationTopic, } from '../claims/claims-helpers-communication.js';
 import { setActorIdentifierList, setActorRoleList, setConsentDate, setConsentDecision, setConsentIdentifier, setConsentPeriodEnd, setConsentPeriodStart, setConsentSubject, setPurposeList, setSectionList, } from '../claims/claims-helpers-consent.js';
 import { setClaimValues } from '../claims/claim-list-helpers.js';
 import { ClaimConsent, ConsentDecisions } from '../models/consent-rule.js';
 import { exportConsentEntry, importPermissionTemplate, PermissionTemplateOperationCodes, PermissionTemplateTargetKinds, resolvePermissionTemplate, } from '../utils/permission-templates.js';
+const CONSENT_BUNDLE_COMMUNICATION_TOPIC = HealthcareKindOfDocumentSections['LP173394-0'].attributeValue;
 /**
  * First developer use case:
  * - edit a Consent entry inside a Communication-attached Bundle
@@ -24,6 +25,7 @@ export function buildConsentEditingCommunicationSessionExample() {
     communicationClaims = setCommunicationIdentifier(communicationClaims, EXAMPLE_COMMUNICATION_IDENTIFIER);
     communicationClaims = setCommunicationSubject(communicationClaims, EXAMPLE_SUBJECT_DID);
     communicationClaims = setCommunicationCategory(communicationClaims, CommunicationCategoryCodes.Notification.attributeValue);
+    communicationClaims = setCommunicationTopic(communicationClaims, CONSENT_BUNDLE_COMMUNICATION_TOPIC);
     communicationClaims = setCommunicationText(communicationClaims, EXAMPLE_IPS_BUNDLE_NOTE_TEXT);
     const bundleEditor = new CommunicationAttachedBundleSession({
         communicationClaims,
@@ -95,6 +97,7 @@ export function buildConsentPermissionTemplateImportExportSessionExample() {
     communicationClaims = setCommunicationIdentifier(communicationClaims, EXAMPLE_COMMUNICATION_IDENTIFIER);
     communicationClaims = setCommunicationSubject(communicationClaims, EXAMPLE_SUBJECT_DID);
     communicationClaims = setCommunicationCategory(communicationClaims, CommunicationCategoryCodes.Notification.attributeValue);
+    communicationClaims = setCommunicationTopic(communicationClaims, CONSENT_BUNDLE_COMMUNICATION_TOPIC);
     communicationClaims = setCommunicationText(communicationClaims, EXAMPLE_IPS_BUNDLE_NOTE_TEXT);
     const templateDraft = {
         decision: ConsentDecisions.Permit,
@@ -172,6 +175,7 @@ export function buildSeparateConsentPermissionBundleExample() {
     communicationClaims = setCommunicationIdentifier(communicationClaims, EXAMPLE_COMMUNICATION_IDENTIFIER);
     communicationClaims = setCommunicationSubject(communicationClaims, EXAMPLE_SUBJECT_DID);
     communicationClaims = setCommunicationCategory(communicationClaims, CommunicationCategoryCodes.Notification.attributeValue);
+    communicationClaims = setCommunicationTopic(communicationClaims, CONSENT_BUNDLE_COMMUNICATION_TOPIC);
     communicationClaims = setCommunicationText(communicationClaims, EXAMPLE_IPS_BUNDLE_NOTE_TEXT);
     const physicianTemplate = resolvePermissionTemplate({
         sector: DataspaceSectors.HealthCare,

package/dist/examples/dataspace-discovery.js

@@ -1,6 +1,6 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
-import { serializeServiceCapabilityTokens, ServiceCapabilityToken } from '../constants/service-capabilities.js';
+import { serializeServiceCapabilityTokens, ServiceCapability, } from '../constants/service-capabilities.js';
 import { EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL, EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL, EXAMPLE_HOSTING_OPERATOR_DID, EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL, EXAMPLE_JURISDICTION, EXAMPLE_SECTOR, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
 function firstOrCsv(values) {
     return values.length <= 1 ? (values[0] || '') : values.join(',');
@@ -16,8 +16,8 @@ function firstOrCsv(values) {
  */
 export function buildExampleHostingOperatorCredentialSubject(input = {}) {
     const serviceTypes = input.serviceTypes || [
-        ServiceCapabilityToken.IndexProvider,
-        ServiceCapabilityToken.DigitalTwinProvider,
+        ServiceCapability.IndexProvider,
+        ServiceCapability.DigitalTwinProvider,
     ];
     const categories = input.categories || [EXAMPLE_SECTOR];
     const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
@@ -39,7 +39,7 @@ export function buildExampleHostingOperatorCredentialSubject(input = {}) {
  * @returns Schema.org-shaped semantic subject with public service metadata.
  */
 export function buildExampleTenantServiceCredentialSubject(input = {}) {
-    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const serviceTypes = input.serviceTypes || [ServiceCapability.IndexProvider];
     const categories = input.categories || [EXAMPLE_SECTOR];
     const areaServed = input.areaServed || ['EU'];
     const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
@@ -62,8 +62,8 @@ export function buildExampleTenantServiceCredentialSubject(input = {}) {
  */
 export function buildExampleHostingOperatorMetaClaims(input = {}) {
     const serviceTypes = input.serviceTypes || [
-        ServiceCapabilityToken.IndexProvider,
-        ServiceCapabilityToken.DigitalTwinProvider,
+        ServiceCapability.IndexProvider,
+        ServiceCapability.DigitalTwinProvider,
     ];
     const categories = input.categories || [EXAMPLE_SECTOR];
     const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
@@ -83,7 +83,7 @@ export function buildExampleHostingOperatorMetaClaims(input = {}) {
  * @returns Flat operational claims derived from the semantic subject.
  */
 export function buildExampleTenantServiceMetaClaims(input = {}) {
-    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const serviceTypes = input.serviceTypes || [ServiceCapability.IndexProvider];
     const categories = input.categories || [EXAMPLE_SECTOR];
     const areaServed = input.areaServed || ['EU'];
     const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
@@ -107,12 +107,12 @@ export function buildExampleTenantServiceMetaClaims(input = {}) {
  * @returns Shared host-catalog provider entry.
  */
 export function buildExamplePublishedProviderCatalogRecord(input = {}) {
-    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const serviceTypes = input.serviceTypes || [ServiceCapability.IndexProvider];
     const categories = input.categories || [EXAMPLE_SECTOR];
     const areaServed = input.areaServed || ['EU'];
     return {
         providerDid: input.did || EXAMPLE_TENANT_SERVICE_DID,
-        serviceType: serviceTypes[0] || ServiceCapabilityToken.IndexProvider,
+        serviceType: serviceTypes[0] || ServiceCapability.IndexProvider,
         category: categories[0] || EXAMPLE_SECTOR,
         areaServed: firstOrCsv(areaServed) || 'EU',
         endpointUrl: EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL,

package/dist/examples/organization-controller.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, ClaimsServiceSchemaorg, } from '../constants/schemaorg.js';
-import { ServiceCapabilityToken, serializeServiceCapabilityTokens, } from '../constants/service-capabilities.js';
+import { serializeServiceCapabilityTokens, ServiceCapability, } from '../constants/service-capabilities.js';
 import { EXAMPLE_CONTROLLER_BINDING, EXAMPLE_DEVICE_CLIENT_ID, EXAMPLE_EMAIL_CONTROLLER_ORG, EXAMPLE_EMPLOYEE_ACTIVATION_CODE, EXAMPLE_HEALTHCARE_ACTOR_ROLE_RECEPTIONIST, EXAMPLE_JURISDICTION, EXAMPLE_ORGANIZATION_CONTROLLER_ROLE, EXAMPLE_SECTOR, EXAMPLE_SERVICE_PUBLIC_DID, } from './shared.js';
 /**
  * Examples for organization-controller and host-onboarding flows.
@@ -26,8 +26,8 @@ export const EXAMPLE_ACTIVATE_ORGANIZATION_FROM_ICA_PROOF_INPUT = {
         [ClaimsServiceSchemaorg.identifier]: EXAMPLE_SERVICE_PUBLIC_DID,
         [ClaimsServiceSchemaorg.url]: `https://operator.example.net/acme/cds-${String(EXAMPLE_JURISDICTION).toLowerCase()}/v1/${EXAMPLE_SECTOR}`,
         [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens([
-            ServiceCapabilityToken.IndexProvider,
-            ServiceCapabilityToken.DigitalTwinReader,
+            ServiceCapability.IndexProvider,
+            ServiceCapability.DigitalTwinReader,
         ]),
     },
 };

package/dist/examples/shared.d.ts

@@ -10,6 +10,7 @@
  */
 export declare const EXAMPLE_TENANT_IDENTIFIER: "acme-id";
 export declare const EXAMPLE_JURISDICTION: "ES";
+export declare const EXAMPLE_HOST_COVERAGE_SCOPE: "EU";
 export declare const EXAMPLE_NETWORK_TYPE: "test";
 export declare const EXAMPLE_ROUTE_VERSION: "v1";
 export declare const EXAMPLE_SECTOR: "health-care";
@@ -21,6 +22,7 @@ export declare const EXAMPLE_TENANT_ROUTE_CONTEXT: {
     readonly sector: "health-care";
 };
 export declare const EXAMPLE_HOST_ROUTE_CONTEXT: {
+    readonly hostCoverageScope: "EU";
     readonly jurisdiction: "ES";
     readonly sector: "test";
 };
@@ -41,10 +43,10 @@ export declare const EXAMPLE_HOSTING_OPERATOR_DID: "did:web:host.example.org";
 export declare const EXAMPLE_TENANT_SERVICE_DID: "did:web:provider.example.org";
 export declare const EXAMPLE_SECONDARY_TENANT_SERVICE_DID: "did:web:provider-b.example.org";
 export declare const EXAMPLE_INDEX_PROVIDER_SECTOR_DID_WEB: "did:web:provider.example.org:acme-id:cds-es:v1:health-care";
-export declare const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
-export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL: "https://host.example.org/host/cds-ES/v1/test/dsp/catalog/dcat.json";
+export declare const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL: "https://host.example.org/host/cds-EU/v1/test/.well-known/dspace-version";
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL: "https://host.example.org/host/cds-EU/v1/test/dsp/catalog/dcat.json";
 /** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
-export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/host/cds-EU/v1/test/.well-known/dspace-version";
 export declare const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL: "https://host.example.org/catalog/provider-a";
 export declare const EXAMPLE_PROVIDER_LEGAL_NAME: "ACME Health Provider";
 export declare const EXAMPLE_SECONDARY_PROVIDER_LEGAL_NAME: "Reader Only Provider";

package/dist/examples/shared.js

@@ -18,6 +18,7 @@ import { medicationStatementFlatToFhirR4 } from '../utils/clinical-resource-conv
  */
 export const EXAMPLE_TENANT_IDENTIFIER = 'acme-id';
 export const EXAMPLE_JURISDICTION = 'ES';
+export const EXAMPLE_HOST_COVERAGE_SCOPE = 'EU';
 export const EXAMPLE_NETWORK_TYPE = HostNetworkTypes.Test;
 export const EXAMPLE_ROUTE_VERSION = 'v1';
 export const EXAMPLE_SECTOR = DataspaceSectors.HealthCare;
@@ -29,6 +30,7 @@ export const EXAMPLE_TENANT_ROUTE_CONTEXT = {
     sector: EXAMPLE_SECTOR,
 };
 export const EXAMPLE_HOST_ROUTE_CONTEXT = {
+    hostCoverageScope: EXAMPLE_HOST_COVERAGE_SCOPE,
     jurisdiction: EXAMPLE_JURISDICTION,
     sector: HostNetworkTypes.Test,
 };
@@ -49,8 +51,8 @@ export const EXAMPLE_HOSTING_OPERATOR_DID = 'did:web:host.example.org';
 export const EXAMPLE_TENANT_SERVICE_DID = 'did:web:provider.example.org';
 export const EXAMPLE_SECONDARY_TENANT_SERVICE_DID = 'did:web:provider-b.example.org';
 export const EXAMPLE_INDEX_PROVIDER_SECTOR_DID_WEB = 'did:web:provider.example.org:acme-id:cds-es:v1:health-care';
-export const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL = `https://host.example.org/host/cds-ES/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/.well-known/dspace-version`;
-export const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL = `https://host.example.org/host/cds-ES/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/dsp/catalog/dcat.json`;
+export const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL = `https://host.example.org/host/cds-${EXAMPLE_HOST_COVERAGE_SCOPE}/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/.well-known/dspace-version`;
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL = `https://host.example.org/host/cds-${EXAMPLE_HOST_COVERAGE_SCOPE}/${EXAMPLE_ROUTE_VERSION}/${EXAMPLE_NETWORK_TYPE}/dsp/catalog/dcat.json`;
 /** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
 export const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL = EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL;
 export const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL = 'https://host.example.org/catalog/provider-a';

package/dist/models/identity-bootstrap.d.ts

@@ -1,4 +1,5 @@
 import { PublicJwk } from '../interfaces/Cryptography.types';
+import { type IssueSeverityAttentionCode } from './issue';
 import { JwkSet } from './jwk';
 /**
  * Public key binding for a human actor/controller identity.
@@ -83,7 +84,7 @@ export interface OrganizationActivationRequest extends ActivationProofInput {
  */
 export type IdentityBootstrapValidationIssue = {
     /** Validation severity. Errors fail the contract, warnings flag compatibility debt. */
-    severity: 'error' | 'warning';
+    severity: IssueSeverityAttentionCode;
     /** Stable machine-readable issue identifier. */
     code: string;
     /** Human-readable description of the problem or compatibility note. */

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

@@ -25,6 +25,8 @@ export declare const CommunicationClaim: {
     readonly Sent: "Communication.sent";
     /** Human note text for the communication context. */
     readonly NoteText: "Communication.note-text";
+    /** Communication topic code (`system|code`). */
+    readonly Topic: "Communication.topic";
     /** Narrative text (short summary or body). */
     readonly Text: "Communication.text";
     /** Related resource references; CSV allowed. */

package/dist/models/interoperable-claims/communication-claims.js

@@ -28,6 +28,8 @@ export const CommunicationClaim = {
     Sent: 'Communication.sent',
     /** Human note text for the communication context. */
     NoteText: 'Communication.note-text',
+    /** Communication topic code (`system|code`). */
+    Topic: 'Communication.topic',
     /** Narrative text (short summary or body). */
     Text: 'Communication.text',
     /** Related resource references; CSV allowed. */