gdc-common-utils-ts 1.5.1 → 1.7.0

package/README.md

@@ -117,6 +117,7 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Shared network/environment labels for node-operator discovery/bootstrap.
 - [`SmartGatewayScopesFhirR4`](src/constants/smart.ts)
   - Current CORE GW SMART scope literals such as `organization/Consent.cruds`.
+  - Treat these as optional elevated scopes. Do not add them to the first read-only tutorial by default.
 
 ### Root exports
 
@@ -129,13 +130,14 @@ The canonical API contract should live in JSDoc on exported code. The README act
 
 ### Communication / document utilities
 
-- [`initializeCommunicationIdentityFromSeed(...)`](src/utils/communication-identity.ts)
+- [`initializeCommunicationIdentity(...)`](src/utils/communication-identity.ts)
   - Derives the technical ML-DSA/ML-KEM communication identity for a device, portal, or app profile and returns JOSE header templates for `meta.jws.protected` and `meta.jwe.header`.
-  - Accepts optional explicit `seedMaterial`; otherwise deterministic mode derives from `entityId`, while random mode delegates entropy generation to the cryptography engine.
+  - Uses explicit `seedMaterial` for deterministic derivation. Without `seedMaterial`, it defaults to random generation. `mode = deterministic` requires `seedMaterial`.
 - [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`](src/utils/did.ts)
   - Build canonical data-space `did:web` identifiers for hosted organizations, professionals, and individuals/family actors.
 - [`buildSmartCompositionReadScope(...)`](src/utils/smart-scope.ts)
   - Builds the current CORE GW pinned SMART root scope for `organization/Composition...` token requests.
+  - This is the preferred first scope to teach when the backend only needs subject-scoped read access.
 - [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`](src/utils/vp-token.ts)
   - Extract typed VC objects from a VP token when GW/SDK flows carry canonical proof only in `vp_token`.
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
@@ -156,6 +158,14 @@ The canonical API contract should live in JSDoc on exported code. The README act
 - [`ControllerBindingInput`, `OrganizationBindingInput`, `ActivationProofInput`, `OrganizationActivationRequest`](src/models/identity-bootstrap.ts)
   - Canonical bootstrap contracts that explicitly separate person/controller key binding from provider/organization key binding.
   - `vp_token` is the canonical proof carrier; `controller.*` and `organization.*` carry public key binding material for DID publication.
+- [`buildControllerBindingInput(...)`, `buildOrganizationBindingInput(...)`](src/utils/activation-request.ts)
+  - Build canonical `controller.*` and `organization.*` binding fragments from semantic variables such as `publicSignKey`, `publicKeys`, `did`, `sameAs`, or `url`.
+- [`RelationshipChannelInvitationInput`, `RelationshipChannelInvitationSummary`, `RelationshipChannelOtpStartInput`, `RelationshipChannelOtpConfirmInput`](src/models/relationship-access.ts)
+  - Shared contracts for controller-driven invitation and acceptance flows between an individual/subject and a related person or professional across phone, email, and app channels.
+- [`RelationshipEnrollmentChannels`, `RelationshipSubjectKinds`, `RelationshipAccessActorKinds`, `RelationshipOtpDeliveryChannels`](src/models/relationship-access.ts)
+  - Shared constant objects for relationship flows so docs and app code do not hardcode actor kinds or channel labels inline.
+- [`RelationshipChannelOtpChallengeSummary`, `RelationshipPinPolicy`, `RelationshipPinSetInput`, `RelationshipPinVerifyInput`, `RelationshipLocalKeyEnvelope`](src/models/relationship-access.ts)
+  - Shared OTP, relationship PIN, and offline-first local-key envelope contracts for channel enrollment and subject-scoped local protection.
 - [`IdentityBootstrapValidationIssue`, `IdentityBootstrapValidationResult`](src/models/identity-bootstrap.ts)
   - Shared validation result shapes used by bootstrap builders/validators.
 - [`buildOrganizationActivationRequest(...)`](src/utils/activation-request.ts)
@@ -186,13 +196,35 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - CORE canonical examples are email-first and do not require phone-only fields unless an extension layer adds them.
 - [`src/examples/professional.ts`](src/examples/professional.ts)
   - Professional/physician runtime access examples such as SMART token and clinical access request payloads.
+  - The base token examples are read-only; richer scenario fixtures intentionally add `organization/Consent.cruds`.
 - [`src/examples/related-person.ts`](src/examples/related-person.ts)
   - RelatedPerson/family-member examples.
 - [`src/examples/frontend-session.ts`](src/examples/frontend-session.ts)
   - Frontend profile/session bootstrap examples.
+- [`src/examples/lifecycle.ts`](src/examples/lifecycle.ts)
+  - Canonical `enable/disable/delete` lifecycle examples with placeholders and no personal data.
+  - This is the source of truth for GW, Swagger, Node SDK, Front SDK, and portal examples.
 - [`src/examples/shared.ts`](src/examples/shared.ts)
   - Shared route contexts, controller binding fragments, and reusable helper builders.
   - `tenantId` is modeled as an identifier-like route token (`acme-id`), not as a friendly alternate name.
+- [`docs/LIFECYCLE_101.md`](docs/LIFECYCLE_101.md)
+  - Copy/paste lifecycle guide "for torpes" with semantic rules and reusable placeholders.
+
+## Documentation Naming Rules
+
+Prefer these semantic names in docs and examples:
+
+- `subjectDid`
+- `professionalDid`
+- `orgControllerDid`
+- `individualControllerDid`
+- `emailProfessional`
+- `emailControllerOrg`
+- `emailControllerIndividual`
+- `emailRelatedPerson`
+
+Avoid teaching new integrations from legacy names such as `individualDidWeb`
+when the active runtime variable is really the subject identifier.
 - [`src/examples/api-flow-examples.ts`](src/examples/api-flow-examples.ts)
   - Preferred compatibility aggregator for consumers that want one import surface without using the overloaded term `contract`.
 - [`src/examples/contract-examples.ts`](src/examples/contract-examples.ts)
@@ -347,7 +379,7 @@ Those request/response flows belong in connector SDKs and backend orchestration
 
 When integrating the converged SDKs:
 
-- use [`initializeCommunicationIdentityFromSeed(...)`](src/utils/communication-identity.ts) from this package for the technical communication identity bootstrap
+- use [`initializeCommunicationIdentity(...)`](src/utils/communication-identity.ts) from this package for the technical communication identity bootstrap
 - use `gdc-sdk-core-ts` for runtime-neutral communication/document helpers
 - use `gdc-sdk-front-ts` or `gdc-sdk-node-ts` for the runtime-specific session and orchestration layer
 
@@ -360,5 +392,5 @@ When integrating the converged SDKs:
 - The `files` field only publishes `dist/`, so source imports should use the documented package entry points rather than local file paths.
 
 ## Roadmap and Briefing
-- `BRIEFING_DATASPACE_EN.md`
+- `docs/BRIEFING_DATASPACE_EN.md`
 - `TODO_ROADMAP.md`

package/dist/constants/index.d.ts

@@ -12,3 +12,5 @@ export * from './vital-signs';
 export * from './network';
 export * from './sectors';
 export * from './smart';
+export * from './service-capabilities';
+export * from './verifiable-credentials';

package/dist/constants/index.js

@@ -12,3 +12,5 @@ export * from './vital-signs.js';
 export * from './network.js';
 export * from './sectors.js';
 export * from './smart.js';
+export * from './service-capabilities.js';
+export * from './verifiable-credentials.js';

package/dist/constants/schemaorg.d.ts

@@ -43,6 +43,8 @@ export declare enum ClaimsOrganizationSchemaorg {
     ownerEmail = "org.schema.Organization.owner.email",
     /** Individual/family owner telephone used by subject-index registration flows. */
     ownerTelephone = "org.schema.Organization.owner.telephone",
+    /** Individual/family owner legal identifier used by subject-index registration flows. */
+    ownerIdentifierValue = "org.schema.Organization.owner.identifier.value",
     numberOfEmployees = "org.schema.Organization.numberOfEmployees.value"
 }
 export declare enum ClaimsOfferSchemaorg {

package/dist/constants/schemaorg.js

@@ -46,6 +46,8 @@ export var ClaimsOrganizationSchemaorg;
     ClaimsOrganizationSchemaorg["ownerEmail"] = "org.schema.Organization.owner.email";
     /** Individual/family owner telephone used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerTelephone"] = "org.schema.Organization.owner.telephone";
+    /** Individual/family owner legal identifier used by subject-index registration flows. */
+    ClaimsOrganizationSchemaorg["ownerIdentifierValue"] = "org.schema.Organization.owner.identifier.value";
     ClaimsOrganizationSchemaorg["numberOfEmployees"] = "org.schema.Organization.numberOfEmployees.value"; // to purchase licenses for device profile's activation
 })(ClaimsOrganizationSchemaorg || (ClaimsOrganizationSchemaorg = {}));
 export var ClaimsOfferSchemaorg;

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

@@ -0,0 +1,53 @@
+/**
+ * Canonical capability families persisted through
+ * `org.schema.Service.serviceType`.
+ */
+export declare const ServiceCapabilityFamily: {
+    readonly Indexing: "indexing";
+    readonly DigitalTwin: "digitaltwin";
+};
+export type ServiceCapabilityFamilyValue = typeof ServiceCapabilityFamily[keyof typeof ServiceCapabilityFamily];
+/**
+ * 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.
+ */
+export declare const ServiceCapabilityToken: {
+    readonly IndexingReadSearch: "indexing.rs";
+    readonly IndexingCruds: "indexing.cruds";
+    readonly DigitalTwinReadSearch: "digitaltwin.rs";
+    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 IndexingProvider: "indexing.cruds";
+    readonly IndexingReader: "indexing.rs";
+    readonly DigitalTwinProvider: "digitaltwin.cruds";
+    readonly DigitalTwinReader: "digitaltwin.rs";
+};
+export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
+/**
+ * Parses the CSV stored in `org.schema.Service.serviceType`.
+ */
+export declare function parseServiceCapabilityTokens(value: unknown): string[];
+/**
+ * Serializes capability tokens into the canonical CSV claim format.
+ */
+export declare function serializeServiceCapabilityTokens(values: ReadonlyArray<string | undefined | null>): string | undefined;
+/**
+ * Returns the capability family prefix from a token.
+ */
+export declare function getServiceCapabilityFamily(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;

package/dist/constants/service-capabilities.js

@@ -0,0 +1,72 @@
+// 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
+ * `org.schema.Service.serviceType`.
+ */
+export const ServiceCapabilityFamily = {
+    Indexing: 'indexing',
+    DigitalTwin: 'digitaltwin',
+};
+/**
+ * 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.
+ */
+export const ServiceCapabilityToken = {
+    IndexingReadSearch: 'indexing.rs',
+    IndexingCruds: 'indexing.cruds',
+    DigitalTwinReadSearch: 'digitaltwin.rs',
+    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 = {
+    IndexingProvider: ServiceCapabilityToken.IndexingCruds,
+    IndexingReader: ServiceCapabilityToken.IndexingReadSearch,
+    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinCruds,
+    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReadSearch,
+};
+/**
+ * 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)));
+}
+/**
+ * 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)));
+    return normalized.length ? normalized.join(',') : undefined;
+}
+/**
+ * Returns the capability family prefix from a token.
+ */
+export function getServiceCapabilityFamily(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return normalized.split('.')[0] || undefined;
+}
+/**
+ * Checks whether the claim contains at least one capability from the requested
+ * family.
+ */
+export function hasServiceCapabilityFamily(value, family) {
+    const normalizedFamily = String(family || '').trim().toLowerCase();
+    if (!normalizedFamily)
+        return false;
+    return parseServiceCapabilityTokens(value).some((item) => getServiceCapabilityFamily(item) === normalizedFamily);
+}

package/dist/constants/verifiable-credentials.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonical W3C credential contexts reused by activation/VP helpers and tests.
+ *
+ * Keep these values centralized so examples and unit suites do not re-hardcode
+ * W3C context URLs inline.
+ */
+export declare const W3cCredentialContexts: Readonly<{
+    V1: "https://www.w3.org/2018/credentials/v1";
+    V2: "https://www.w3.org/ns/credentials/v2";
+}>;
+/**
+ * Canonical W3C credential and presentation base types.
+ */
+export declare const W3cCredentialTypes: Readonly<{
+    VerifiableCredential: "VerifiableCredential";
+    VerifiablePresentation: "VerifiablePresentation";
+}>;
+/**
+ * Canonical activation VC subtype names currently accepted by CORE helpers.
+ *
+ * Notes:
+ * - `LegalOrganizationCredential` and `PersonCredential` remain accepted as
+ *   compatibility aliases while ICA/GW contracts converge.
+ * - Example/test code must import these constants instead of re-hardcoding the
+ *   subtype strings inline.
+ */
+export declare const ActivationCredentialTypes: Readonly<{
+    OrganizationCredential: "OrganizationCredential";
+    LegalOrganizationCredential: "LegalOrganizationCredential";
+    LegalRepresentativeCredential: "LegalRepresentativeCredential";
+    PersonCredential: "PersonCredential";
+}>;
+export declare const ORGANIZATION_ACTIVATION_VC_TYPES: readonly ("OrganizationCredential" | "LegalOrganizationCredential")[];
+export declare const REPRESENTATIVE_ACTIVATION_VC_TYPES: readonly ("LegalRepresentativeCredential" | "PersonCredential")[];

package/dist/constants/verifiable-credentials.js

@@ -0,0 +1,42 @@
+// 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 W3C credential contexts reused by activation/VP helpers and tests.
+ *
+ * Keep these values centralized so examples and unit suites do not re-hardcode
+ * W3C context URLs inline.
+ */
+export const W3cCredentialContexts = Object.freeze({
+    V1: 'https://www.w3.org/2018/credentials/v1',
+    V2: 'https://www.w3.org/ns/credentials/v2',
+});
+/**
+ * Canonical W3C credential and presentation base types.
+ */
+export const W3cCredentialTypes = Object.freeze({
+    VerifiableCredential: 'VerifiableCredential',
+    VerifiablePresentation: 'VerifiablePresentation',
+});
+/**
+ * Canonical activation VC subtype names currently accepted by CORE helpers.
+ *
+ * Notes:
+ * - `LegalOrganizationCredential` and `PersonCredential` remain accepted as
+ *   compatibility aliases while ICA/GW contracts converge.
+ * - Example/test code must import these constants instead of re-hardcoding the
+ *   subtype strings inline.
+ */
+export const ActivationCredentialTypes = Object.freeze({
+    OrganizationCredential: 'OrganizationCredential',
+    LegalOrganizationCredential: 'LegalOrganizationCredential',
+    LegalRepresentativeCredential: 'LegalRepresentativeCredential',
+    PersonCredential: 'PersonCredential',
+});
+export const ORGANIZATION_ACTIVATION_VC_TYPES = Object.freeze([
+    ActivationCredentialTypes.OrganizationCredential,
+    ActivationCredentialTypes.LegalOrganizationCredential,
+]);
+export const REPRESENTATIVE_ACTIVATION_VC_TYPES = Object.freeze([
+    ActivationCredentialTypes.LegalRepresentativeCredential,
+    ActivationCredentialTypes.PersonCredential,
+]);

package/dist/examples/api-flow-examples.d.ts

@@ -6,8 +6,10 @@
  * while preserving a stable migration target for older imports.
  */
 export * from './shared';
+export * from './ica-activation-proof';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';
 export * from './related-person';
 export * from './frontend-session';
+export * from './lifecycle';

package/dist/examples/api-flow-examples.js

@@ -7,8 +7,10 @@
  * while preserving a stable migration target for older imports.
  */
 export * from './shared.js';
+export * from './ica-activation-proof.js';
 export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';
 export * from './related-person.js';
 export * from './frontend-session.js';
+export * from './lifecycle.js';

package/dist/examples/consent-access.d.ts

@@ -1,135 +1,27 @@
+import { ClaimConsent, type ConsentRule } from '../models/consent-rule';
+import { EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON } from './shared';
+export declare const EXAMPLE_INDIVIDUAL_DID_WEB: "did:web:api.acme.org:individual:123";
+export declare const EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB: "did:web:hospital.acme.org";
+export { EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON };
+export declare const EXAMPLE_CONSENT_ACCESS_JURISDICTION: "ES";
+/**
+ * Legacy compatibility aliases kept so older docs/tests/imports continue to work
+ * while the canonical variable names converge.
+ */
 export declare const EXAMPLE_CONSENT_ACCESS_SUBJECT: "did:web:api.acme.org:individual:123";
 export declare const EXAMPLE_CONSENT_ACCESS_PROVIDER_DID: "did:web:hospital.acme.org";
 export declare const EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL: "doctor.oncall@example.org";
 export declare const EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL: "parent.guardian@example.org";
-export declare const EXAMPLE_CONSENT_ACCESS_JURISDICTION: "ES";
 export declare const EXAMPLE_CONSENT_ACCESS_RULES: Readonly<{
-    physicianByEmailContinuousCare: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    physicianByEmailEmergency: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    physicianByOrganizationContinuousCare: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    physicianByJurisdictionEmergency: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    nurseByOrganization: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    paramedicByJurisdiction: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    directPhysicianDenyInsideAllowedOrganization: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    relatedPersonByEmail: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
-    revokedPhysicianEmailConsent: {
-        readonly 'Consent.date': "2026-05-20";
-        readonly 'Consent.period-end'?: string | undefined;
-        readonly 'Consent.period-start'?: string | undefined;
-        readonly 'Consent.resourceType'?: string | undefined;
-        readonly '@context': "org.hl7.fhir.api";
-        readonly 'Consent.identifier': string;
-        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
-        readonly 'Consent.actor-identifier': string;
-        readonly 'Consent.actor-role': string;
-        readonly 'Consent.decision': "permit" | "deny";
-        readonly 'Consent.purpose': string;
-        readonly 'Consent.action': string;
-    };
+    physicianByEmailContinuousCare: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    physicianByEmailEmergency: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    physicianByOrganizationContinuousCare: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    physicianByJurisdictionEmergency: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    nurseByOrganization: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    paramedicByJurisdiction: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    directPhysicianDenyInsideAllowedOrganization: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    relatedPersonByEmail: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    revokedPhysicianEmailConsent: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
 }>;
 export declare const EXAMPLE_CONSENT_PHONE_EXTENSION_PENDING: Readonly<{
     target: "tel:+34600111222";

package/dist/examples/consent-access.js

@@ -1,31 +1,48 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, } from '../constants/healthcare.js';
+import { ClaimConsent } from '../models/consent-rule.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
-export const EXAMPLE_CONSENT_ACCESS_SUBJECT = 'did:web:api.acme.org:individual:123';
-export const EXAMPLE_CONSENT_ACCESS_PROVIDER_DID = 'did:web:hospital.acme.org';
-export const EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL = 'doctor.oncall@example.org';
-export const EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL = 'parent.guardian@example.org';
-export const EXAMPLE_CONSENT_ACCESS_JURISDICTION = 'ES';
+import { EXAMPLE_CONSENT_DATE, EXAMPLE_CONSENT_PERIOD_END, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON, EXAMPLE_HEALTHCARE_JURISDICTION, EXAMPLE_PROVIDER_ORGANIZATION_DID, EXAMPLE_RELATED_PERSON_ROLE, EXAMPLE_SUBJECT_DID, } from './shared.js';
+export const EXAMPLE_INDIVIDUAL_DID_WEB = EXAMPLE_SUBJECT_DID;
+export const EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB = EXAMPLE_PROVIDER_ORGANIZATION_DID;
+export { EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON };
+export const EXAMPLE_CONSENT_ACCESS_JURISDICTION = EXAMPLE_HEALTHCARE_JURISDICTION;
+/**
+ * Legacy compatibility aliases kept so older docs/tests/imports continue to work
+ * while the canonical variable names converge.
+ */
+export const EXAMPLE_CONSENT_ACCESS_SUBJECT = EXAMPLE_INDIVIDUAL_DID_WEB;
+export const EXAMPLE_CONSENT_ACCESS_PROVIDER_DID = EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB;
+export const EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL = EXAMPLE_EMAIL_PROFESSIONAL;
+export const EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL = EXAMPLE_EMAIL_RELATED_PERSON;
+/**
+ * Consent example builder used by docs/tests.
+ *
+ * Contract note:
+ * repeated actor identifiers, dates, jurisdictions, role fixtures, and
+ * canonical consent claim keys must be imported, never re-hardcoded inline in
+ * each example rule.
+ */
 function buildRule(input) {
     return {
         '@context': 'org.hl7.fhir.api',
-        'Consent.identifier': input.identifier,
-        'Consent.subject': EXAMPLE_CONSENT_ACCESS_SUBJECT,
-        'Consent.actor-identifier': input.actorIdentifier,
-        'Consent.actor-role': input.actorRole,
-        'Consent.decision': input.decision || 'permit',
-        'Consent.purpose': input.purpose,
-        'Consent.action': input.actions.join(','),
-        ...(input.resourceTypes?.length ? { 'Consent.resourceType': input.resourceTypes.join(',') } : {}),
-        ...(input.periodStart ? { 'Consent.period-start': input.periodStart } : {}),
-        ...(input.periodEnd ? { 'Consent.period-end': input.periodEnd } : {}),
-        'Consent.date': '2026-05-20',
+        [ClaimConsent.identifier]: input.identifier,
+        [ClaimConsent.subject]: EXAMPLE_INDIVIDUAL_DID_WEB,
+        [ClaimConsent.actorIdentifier]: input.actorIdentifier,
+        [ClaimConsent.actorRole]: input.actorRole,
+        [ClaimConsent.decision]: input.decision || 'permit',
+        [ClaimConsent.purpose]: input.purpose,
+        [ClaimConsent.action]: input.actions.join(','),
+        ...(input.resourceTypes?.length ? { [ClaimConsent.resourceType]: input.resourceTypes.join(',') } : {}),
+        ...(input.periodStart ? { [ClaimConsent.periodStart]: input.periodStart } : {}),
+        ...(input.periodEnd ? { [ClaimConsent.periodEnd]: input.periodEnd } : {}),
+        [ClaimConsent.date]: EXAMPLE_CONSENT_DATE,
     };
 }
 export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     physicianByEmailContinuousCare: buildRule({
         identifier: 'urn:uuid:consent-physician-email-treatment',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorIdentifier: EXAMPLE_EMAIL_PROFESSIONAL,
         actorRole: HealthcareActorRoles.Physician,
         purpose: HealthcareConsentPurposes.Treatment,
         actions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
@@ -33,7 +50,7 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     }),
     physicianByEmailEmergency: buildRule({
         identifier: 'urn:uuid:consent-physician-email-emergency',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorIdentifier: EXAMPLE_EMAIL_PROFESSIONAL,
         actorRole: HealthcareActorRoles.Physician,
         purpose: HealthcareConsentPurposes.EmergencyTreatment,
         actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
@@ -41,7 +58,7 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     }),
     physicianByOrganizationContinuousCare: buildRule({
         identifier: 'urn:uuid:consent-physician-org-treatment',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_DID,
+        actorIdentifier: EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB,
         actorRole: HealthcareActorRoles.Physician,
         purpose: HealthcareConsentPurposes.Treatment,
         actions: [HealthcareBasicSections.Results.claim],
@@ -57,7 +74,7 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     }),
     nurseByOrganization: buildRule({
         identifier: 'urn:uuid:consent-nurse-org-treatment',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_DID,
+        actorIdentifier: EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB,
         actorRole: HealthcareActorRoles.NursingProfessional,
         purpose: HealthcareConsentPurposes.Treatment,
         actions: [HealthcareBasicSections.HistoryOfMedicationUse.claim],
@@ -73,7 +90,7 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     }),
     directPhysicianDenyInsideAllowedOrganization: buildRule({
         identifier: 'urn:uuid:consent-physician-direct-deny',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorIdentifier: EXAMPLE_EMAIL_PROFESSIONAL,
         actorRole: HealthcareActorRoles.Physician,
         decision: 'deny',
         purpose: HealthcareConsentPurposes.Treatment,
@@ -82,19 +99,19 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
     }),
     relatedPersonByEmail: buildRule({
         identifier: 'urn:uuid:consent-related-person-email',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL,
-        actorRole: 'v3-RoleCode|RESPRSN',
+        actorIdentifier: EXAMPLE_EMAIL_RELATED_PERSON,
+        actorRole: EXAMPLE_RELATED_PERSON_ROLE,
         purpose: HealthcareConsentPurposes.Treatment,
         actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
         resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DocumentReference],
     }),
     revokedPhysicianEmailConsent: buildRule({
         identifier: 'urn:uuid:consent-physician-email-revoked',
-        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorIdentifier: EXAMPLE_EMAIL_PROFESSIONAL,
         actorRole: HealthcareActorRoles.Physician,
         purpose: HealthcareConsentPurposes.EmergencyTreatment,
         actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
-        periodEnd: '2026-05-01T00:00:00Z',
+        periodEnd: EXAMPLE_CONSENT_PERIOD_END,
     }),
 });
 export const EXAMPLE_CONSENT_PHONE_EXTENSION_PENDING = Object.freeze({

package/dist/examples/contract-examples.d.ts

@@ -6,8 +6,10 @@
  * breaking while the examples are reorganized by flow/case of use.
  */
 export * from './shared';
+export * from './ica-activation-proof';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';
 export * from './related-person';
 export * from './frontend-session';
+export * from './lifecycle';