gdc-common-utils-ts 2.9.15 → 2.9.17

package/README.md

@@ -80,6 +80,12 @@ by its attached `Composition.section` graph.
 
 ## Identity Continuity
 
+For every Individual Organization, the initial `Organization.member` is the
+indexed subject itself and uses the HL7 relationship `ONESELF`. The creating
+`Organization.owner` is the controller by default. `ONESELF` describes who the
+subject is; controller authority such as `RESPRSN` describes who may act for
+that subject. Never copy the owner/controller role into the SELF member.
+
 For ICA-backed organization activation, the representative/controller proof is
 intentionally split into two complementary dimensions:
 

package/dist/constants/hl7-roles.d.ts

@@ -72,7 +72,18 @@ export declare const HL7_V3_ROLE_CODE_LEGAL_REPRESENTATIVE: Hl7RoleEntry[];
  * is required.
  */
 export declare const HL7_RELATED_PERSON_FUNCTIONAL_ROLES: readonly Hl7RelatedPersonFunctionalRoleEntry[];
-/** Default role code for animal-care and non-human subjects. */
+/** Default SELF-subject role for the initial Individual Organization member. */
+export declare const HL7_DEFAULT_INDIVIDUAL_MEMBER_ROLE = "ONESELF";
+/**
+ * @deprecated This is the human controller relationship, not the animal
+ * Individual Organization member role. Use
+ * `HL7_DEFAULT_CONTROLLER_RELATIONSHIP_ANIMAL_CARE`.
+ */
 export declare const HL7_DEFAULT_ROLE_ANIMAL_CARE = "RESPRSN";
+/**
+ * Default human controller-to-animal authorization relationship.
+ * This never replaces the animal subject's `ONESELF` member role.
+ */
+export declare const HL7_DEFAULT_CONTROLLER_RELATIONSHIP_ANIMAL_CARE = "RESPRSN";
 /** Default role code for health sector (patient self-represents). */
 export declare const HL7_DEFAULT_ROLE_HEALTH = "ONESELF";

package/dist/constants/hl7-roles.js

@@ -290,7 +290,18 @@ export const HL7_RELATED_PERSON_FUNCTIONAL_ROLES = [
         codingSystem: HL7_CODING_SYSTEM_V3_ROLE_CODE,
     },
 ];
-/** Default role code for animal-care and non-human subjects. */
+/** Default SELF-subject role for the initial Individual Organization member. */
+export const HL7_DEFAULT_INDIVIDUAL_MEMBER_ROLE = 'ONESELF';
+/**
+ * @deprecated This is the human controller relationship, not the animal
+ * Individual Organization member role. Use
+ * `HL7_DEFAULT_CONTROLLER_RELATIONSHIP_ANIMAL_CARE`.
+ */
 export const HL7_DEFAULT_ROLE_ANIMAL_CARE = 'RESPRSN';
+/**
+ * Default human controller-to-animal authorization relationship.
+ * This never replaces the animal subject's `ONESELF` member role.
+ */
+export const HL7_DEFAULT_CONTROLLER_RELATIONSHIP_ANIMAL_CARE = 'RESPRSN';
 /** Default role code for health sector (patient self-represents). */
 export const HL7_DEFAULT_ROLE_HEALTH = 'ONESELF';

package/dist/models/animal-onboarding.d.ts

@@ -49,8 +49,11 @@ export declare function buildNcbiTaxonomyUri(id: NcbiTaxonomyId): string;
  * Projects one controller-authorized animal card request to the existing
  * schema.org individual-organization claim envelope.
  *
- * The indexed subject is always an animal and its human actor is always a
- * responsible controller. Login identity proves only the application session;
+ * The indexed subject is always the first `Organization.member`, with the
+ * HL7 relationship `ONESELF`. The human that creates the envelope remains the
+ * separate `Organization.owner` controller; `RESPRSN` belongs to that
+ * controller authority and must never replace the subject's ONESELF role.
+ * Login identity proves only the application session;
  * GW must still verify the enrollment grant before accepting the request. A
  * card must not be shown as active until the authoritative GW transaction
  * returns success.

package/dist/models/animal-onboarding.js

@@ -1,5 +1,6 @@
 import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
 import { DataspaceSectors } from '../constants/sectors.js';
+import { HL7_DEFAULT_INDIVIDUAL_MEMBER_ROLE } from '../constants/hl7-roles.js';
 /**
  * @deprecated Animal-card vocabulary is owned by the consuming product SDK.
  * Retained only so consumers of 2.3.x can migrate without a breaking removal.
@@ -42,8 +43,11 @@ export function buildNcbiTaxonomyUri(id) {
  * Projects one controller-authorized animal card request to the existing
  * schema.org individual-organization claim envelope.
  *
- * The indexed subject is always an animal and its human actor is always a
- * responsible controller. Login identity proves only the application session;
+ * The indexed subject is always the first `Organization.member`, with the
+ * HL7 relationship `ONESELF`. The human that creates the envelope remains the
+ * separate `Organization.owner` controller; `RESPRSN` belongs to that
+ * controller authority and must never replace the subject's ONESELF role.
+ * Login identity proves only the application session;
  * GW must still verify the enrollment grant before accepting the request. A
  * card must not be shown as active until the authoritative GW transaction
  * returns success.
@@ -68,7 +72,7 @@ export function buildAnimalOnboardingClaims(input) {
         [ClaimsOrganizationSchemaorg.sameAs]: cardDidWeb,
         [ClaimsOrganizationSchemaorg.memberName]: alternateName,
         [ClaimsOrganizationSchemaorg.memberAdditionalType]: buildNcbiTaxonomyUri(input.ncbiTaxonomyId),
-        [ClaimsOrganizationSchemaorg.memberRole]: 'RESPRSN',
+        [ClaimsOrganizationSchemaorg.memberRole]: HL7_DEFAULT_INDIVIDUAL_MEMBER_ROLE,
         ...(birthDate ? { [ClaimsOrganizationSchemaorg.memberBirthDate]: birthDate } : {}),
         ...(gender ? { [ClaimsOrganizationSchemaorg.memberGender]: gender } : {}),
         [ClaimsOrganizationSchemaorg.ownerEmail]: input.controllerEmail?.trim() || '',

package/dist/utils/clinical-resource-view.d.ts

@@ -162,7 +162,10 @@ export declare function toClinicalResourceCardView(entry: ClinicalResourceEntryL
  * Short claims take precedence over their expanded
  * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
  * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
- * FHIR representation namespaces, never claims vocabularies.
+ * FHIR representation namespaces, never claims vocabularies. Native
+ * structural projections such as `<ResourceType>.meta.versionId` or array
+ * paths are ignored: they remain part of the FHIR resource, but are not API
+ * SearchParameters and must never become editable clinical fields.
  */
 export declare function toClinicalResourceClaimFieldViews(claims: ClinicalViewClaims): ClinicalResourceClaimFieldView[];
 /**

package/dist/utils/clinical-resource-view.js

@@ -113,7 +113,10 @@ export function toClinicalResourceCardView(entry, options = {}) {
  * Short claims take precedence over their expanded
  * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
  * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
- * FHIR representation namespaces, never claims vocabularies.
+ * FHIR representation namespaces, never claims vocabularies. Native
+ * structural projections such as `<ResourceType>.meta.versionId` or array
+ * paths are ignored: they remain part of the FHIR resource, but are not API
+ * SearchParameters and must never become editable clinical fields.
  */
 export function toClinicalResourceClaimFieldViews(claims) {
     const fields = new Map();
@@ -126,7 +129,9 @@ export function toClinicalResourceClaimFieldViews(claims) {
         }
         if (!rawClaim.startsWith('org.hl7.fhir.api.') && !/^[A-Z][A-Za-z0-9]+\./.test(rawClaim))
             continue;
-        const claim = normalizeFhirApiClaimKey(rawClaim);
+        const claim = normalizeViewClaim(rawClaim);
+        if (!claim)
+            continue;
         const separator = claim.indexOf('.');
         if (separator <= 0 || separator === claim.length - 1)
             continue;
@@ -145,17 +150,28 @@ export function toClinicalResourceClaimFieldViews(claims) {
             continue;
         if (!/^[A-Z][A-Za-z0-9]+\./.test(claim))
             continue;
-        const separator = claim.indexOf('.');
-        if (separator <= 0 || separator === claim.length - 1)
+        const normalizedClaim = normalizeViewClaim(claim);
+        if (!normalizedClaim)
+            continue;
+        const separator = normalizedClaim.indexOf('.');
+        if (separator <= 0 || separator === normalizedClaim.length - 1)
             continue;
-        fields.set(claim, {
-            claim,
-            parameter: claim.slice(separator + 1),
+        fields.set(normalizedClaim, {
+            claim: normalizedClaim,
+            parameter: normalizedClaim.slice(separator + 1),
             value,
         });
     }
     return [...fields.values()].sort((left, right) => left.claim.localeCompare(right.claim));
 }
+function normalizeViewClaim(rawClaim) {
+    try {
+        return normalizeFhirApiClaimKey(rawClaim);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Maps all entries from a Bundle into minimal card views.
  */

package/dist/utils/family-organization-summary.d.ts

@@ -1,4 +1,4 @@
-export type FamilyRegistrationStatus = 'new_created' | 'resume_required' | 'already_exists' | 'not_found';
+export type FamilyRegistrationStatus = 'new_created' | 'draft_saved' | 'resume_required' | 'already_exists' | 'not_found';
 export type FamilyOrganizationSubjectInfo = Readonly<{
     identifierType?: string;
     identifierValue?: string;

package/dist/utils/family-organization-summary.js

@@ -1,4 +1,11 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+const FAMILY_REGISTRATION_STATUSES = new Set([
+    'new_created',
+    'draft_saved',
+    'resume_required',
+    'already_exists',
+    'not_found',
+]);
 function asRecord(value) {
     return value && typeof value === 'object' ? value : {};
 }
@@ -38,8 +45,12 @@ export function readFamilyOrganizationSummaryFromResponseBody(body) {
         ...asRecord(entryMeta.claims),
         ...asRecord(entryResourceMeta.claims),
     };
-    const status = normalizeText(claims['org.schema.FamilyRegistration.status'] ?? claims.status);
-    if (!status || status === 'not_found') {
+    const rawStatus = normalizeText(claims['org.schema.FamilyRegistration.status'] ?? claims.status);
+    if (!rawStatus || !FAMILY_REGISTRATION_STATUSES.has(rawStatus)) {
+        return null;
+    }
+    const status = rawStatus;
+    if (status === 'not_found') {
         return null;
     }
     return {
@@ -50,7 +61,8 @@ export function readFamilyOrganizationSummaryFromResponseBody(body) {
             identifierType: normalizeText(claims['org.schema.Organization.identifier.additionalType']),
             identifierValue: normalizeText(claims['org.schema.Organization.identifier.value']),
             alternateName: normalizeText(claims['org.schema.Organization.alternateName']),
-            birthDate: normalizeText(claims['org.schema.Organization.foundingDate']),
+            birthDate: normalizeText(claims['org.schema.Person.birthDate']
+                ?? claims['org.schema.Organization.foundingDate']),
             ownerTelephone: normalizeText(claims['org.schema.Organization.owner.telephone']),
         },
         missingFields: normalizeStringList(claims['org.schema.FamilyRegistration.missingFields'] ?? claims.missingFields),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.9.15",
+  "version": "2.9.17",
   "publishConfig": {
     "access": "public"
   },