vet-sdk-core-ts 0.4.37 → 0.4.39

package/README.md

@@ -1,5 +1,24 @@
 # VetChain Core SDK
 
+## Animal Individual Organization identity
+
+An animal is the first member of its own Individual Organization, so
+`Organization.member.role` is always the HL7 code `ONESELF`. The authenticated
+human that creates it is `Organization.owner`, the controller by default;
+`RESPRSN` must never be copied into the animal member.
+
+Name, birth date, exact NCBI species and optional breed are animal
+demographics. Breed remains separate descriptive text. Controller-authored
+demographics remain editable until a veterinarian attests them; attestation
+does not rewrite the original author, and later correction creates a new
+veterinarian-authored version.
+
+Use `buildVetChainAnimalDraftClaims(...)` while the name, exact NCBI species or
+public Card is missing. Only a draft for which
+`readVetChainAnimalOnboardingReadiness(...)` returns `ready: true` may be
+activated and issued a Card. See
+[`docs/101-ANIMAL-INDIVIDUAL-ONBOARDING.md`](docs/101-ANIMAL-INDIVIDUAL-ONBOARDING.md).
+
 `vet-sdk-core-ts/place-service-directory` is the VetChain-only bundle boundary
 for claims-first Schema.org `Place` and `Service` resources. It builds GW VET
 batch/search envelopes and joins authorized directory search responses for the

package/dist/animal-onboarding.d.ts

@@ -1,3 +1,7 @@
+/** Canonical member relationship for the animal SELF subject. */
+export declare const VetChainAnimalMemberRoles: Readonly<{
+    readonly Self: "ONESELF";
+}>;
 export type VetChainAnimalOnboardingInput = Readonly<{
     subjectId: string;
     cardDidWeb: string;
@@ -7,10 +11,29 @@ export type VetChainAnimalOnboardingInput = Readonly<{
     birthYear?: number;
     gender?: 'female' | 'male' | 'other' | 'unknown';
     ncbiTaxonomyId: string;
+    breedLabel?: string;
     controllerEmail?: string;
     controllerTelephone?: string;
     sector?: string;
 }>;
+export type VetChainAnimalDraftInput = Readonly<{
+    subjectId: string;
+    cardDidWeb?: string;
+    alternateName?: string;
+    legalName?: string;
+    birthDate?: string;
+    birthYear?: number;
+    gender?: 'female' | 'male' | 'other' | 'unknown';
+    ncbiTaxonomyId?: string;
+    breedLabel?: string;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    sector?: string;
+}>;
+export type VetChainAnimalOnboardingReadiness = Readonly<{
+    ready: boolean;
+    missing: ReadonlyArray<'alternateName' | 'species' | 'card'>;
+}>;
 /** Canonical schema.org claim names for the VetChain animal registration. */
 export declare const VetChainAnimalOnboardingClaimNames: Readonly<{
     readonly identifierValue: "org.schema.Organization.identifier.value";
@@ -20,6 +43,7 @@ export declare const VetChainAnimalOnboardingClaimNames: Readonly<{
     readonly sameAs: "org.schema.Organization.sameAs";
     readonly memberName: "org.schema.Organization.member.name";
     readonly memberAdditionalType: "org.schema.Organization.member.additionalType";
+    readonly memberBreed: "org.schema.Organization.member.breed";
     readonly memberBirthDate: "org.schema.Organization.member.birthDate";
     readonly memberGender: "org.schema.Organization.member.gender";
     readonly memberRole: "org.schema.Organization.member.role";
@@ -27,9 +51,24 @@ export declare const VetChainAnimalOnboardingClaimNames: Readonly<{
     readonly ownerTelephone: "org.schema.Organization.owner.telephone";
     readonly serviceCategory: "org.schema.Service.category";
 }>;
+/**
+ * Creates the claims-first administrative draft for one animal.
+ *
+ * A draft always identifies its private subject and the creating controller,
+ * but name, NCBI species and public Card DID may remain absent. The animal is
+ * still its own `ONESELF` member; `Organization.owner` is the controller.
+ */
+export declare function buildVetChainAnimalDraftClaims(input: VetChainAnimalDraftInput): Readonly<Record<string, string>>;
+/** Reports whether an animal draft can be activated and issued a public Card. */
+export declare function readVetChainAnimalOnboardingReadiness(claims: Readonly<Record<string, unknown>>): VetChainAnimalOnboardingReadiness;
 /**
  * Projects one controller-authorized animal to the GW Organization envelope.
  *
+ * The animal is the envelope's first member and therefore has the HL7
+ * `ONESELF` relationship. The authenticated human that creates it is kept in
+ * `Organization.owner`; controller authority such as `RESPRSN` is never
+ * copied into `Organization.member.role`.
+ *
  * Species remains separate governed metadata. It validates the Damm digit with
  * jurisdiction and animalNumericId15 but is never decoded from cardNumber21.
  */

package/dist/animal-onboarding.js

@@ -1,6 +1,8 @@
 import { parseVetChainAnimalCardDid } from 'vet-data-utils-ts';
 import { buildAnimalIdentifier16, buildSpeciesId7 } from './animal-identity.js';
 import { normalizeVetChainNcbiTaxonomyId } from './card-issuance.js';
+/** Canonical member relationship for the animal SELF subject. */
+export const VetChainAnimalMemberRoles = Object.freeze({ Self: 'ONESELF' });
 /** Canonical schema.org claim names for the VetChain animal registration. */
 export const VetChainAnimalOnboardingClaimNames = Object.freeze({
     identifierValue: 'org.schema.Organization.identifier.value',
@@ -10,6 +12,7 @@ export const VetChainAnimalOnboardingClaimNames = Object.freeze({
     sameAs: 'org.schema.Organization.sameAs',
     memberName: 'org.schema.Organization.member.name',
     memberAdditionalType: 'org.schema.Organization.member.additionalType',
+    memberBreed: 'org.schema.Organization.member.breed',
     memberBirthDate: 'org.schema.Organization.member.birthDate',
     memberGender: 'org.schema.Organization.member.gender',
     memberRole: 'org.schema.Organization.member.role',
@@ -18,26 +21,26 @@ export const VetChainAnimalOnboardingClaimNames = Object.freeze({
     serviceCategory: 'org.schema.Service.category',
 });
 /**
- * Projects one controller-authorized animal to the GW Organization envelope.
+ * Creates the claims-first administrative draft for one animal.
  *
- * Species remains separate governed metadata. It validates the Damm digit with
- * jurisdiction and animalNumericId15 but is never decoded from cardNumber21.
+ * A draft always identifies its private subject and the creating controller,
+ * but name, NCBI species and public Card DID may remain absent. The animal is
+ * still its own `ONESELF` member; `Organization.owner` is the controller.
  */
-export function buildVetChainAnimalOnboardingClaims(input) {
+export function buildVetChainAnimalDraftClaims(input) {
     const subjectId = required(input.subjectId, 'vet_animal_subject_id_invalid');
-    const alternateName = required(input.alternateName, 'vet_animal_name_invalid');
-    const card = parseVetChainAnimalCardDid(input.cardDidWeb);
-    const ncbiTaxonomyId = normalizeVetChainNcbiTaxonomyId(input.ncbiTaxonomyId);
-    const expectedAnimalId16 = buildAnimalIdentifier16({
-        speciesId7: buildSpeciesId7(ncbiTaxonomyId),
-        jurisdictionCode5: card.jurisdictionCode5,
-        animalNumericId15: card.animalNumericId15,
-    });
-    if (expectedAnimalId16 !== card.animalId16) {
-        throw new TypeError('vet_animal_card_species_checksum_invalid');
-    }
-    const birthDate = String(input.birthDate || '').trim()
-        || (Number.isInteger(input.birthYear) ? String(input.birthYear) : '');
+    const alternateName = String(input.alternateName || '').trim();
+    const ncbiTaxonomyId = String(input.ncbiTaxonomyId || '').trim()
+        ? normalizeVetChainNcbiTaxonomyId(String(input.ncbiTaxonomyId))
+        : '';
+    const cardDidWeb = String(input.cardDidWeb || '').trim();
+    if (cardDidWeb && !ncbiTaxonomyId)
+        throw new TypeError('vet_animal_card_species_required');
+    if (cardDidWeb)
+        assertCardSpecies(cardDidWeb, ncbiTaxonomyId);
+    const birthDate = normalizePartialBirthDate(String(input.birthDate || '').trim()
+        || (Number.isInteger(input.birthYear) ? String(input.birthYear) : ''));
+    const breedLabel = String(input.breedLabel || '').trim();
     const legalName = String(input.legalName || '').trim();
     const gender = input.gender && input.gender !== 'unknown' ? input.gender : '';
     const claim = VetChainAnimalOnboardingClaimNames;
@@ -45,12 +48,17 @@ export function buildVetChainAnimalOnboardingClaims(input) {
         '@context': 'org.schema',
         [claim.identifierValue]: subjectId,
         [claim.additionalType]: 'animal',
-        [claim.alternateName]: alternateName,
+        ...(alternateName ? {
+            [claim.alternateName]: alternateName,
+            [claim.memberName]: alternateName,
+        } : {}),
         ...(legalName ? { [claim.legalName]: legalName } : {}),
-        [claim.sameAs]: card.did,
-        [claim.memberName]: alternateName,
-        [claim.memberAdditionalType]: `http://purl.obolibrary.org/obo/NCBITaxon_${ncbiTaxonomyId}`,
-        [claim.memberRole]: 'RESPRSN',
+        ...(cardDidWeb ? { [claim.sameAs]: cardDidWeb } : {}),
+        ...(ncbiTaxonomyId ? {
+            [claim.memberAdditionalType]: `http://purl.obolibrary.org/obo/NCBITaxon_${ncbiTaxonomyId}`,
+        } : {}),
+        ...(breedLabel ? { [claim.memberBreed]: breedLabel } : {}),
+        [claim.memberRole]: VetChainAnimalMemberRoles.Self,
         ...(birthDate ? { [claim.memberBirthDate]: birthDate } : {}),
         ...(gender ? { [claim.memberGender]: gender } : {}),
         [claim.ownerEmail]: String(input.controllerEmail || '').trim(),
@@ -58,6 +66,70 @@ export function buildVetChainAnimalOnboardingClaims(input) {
         [claim.serviceCategory]: String(input.sector || '').trim() || 'animal-care',
     });
 }
+/** Normalizes ISO 8601 reduced-precision animal birth dates (year, year-month or full date). */
+function normalizePartialBirthDate(value) {
+    if (!value)
+        return '';
+    const match = value.match(/^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/);
+    if (!match)
+        throw new TypeError('vet_animal_birth_date_invalid');
+    const year = Number(match[1]);
+    const month = match[2] ? Number(match[2]) : undefined;
+    const day = match[3] ? Number(match[3]) : undefined;
+    if (year < 1000 || year > 9999 || (month !== undefined && (month < 1 || month > 12))) {
+        throw new TypeError('vet_animal_birth_date_invalid');
+    }
+    if (day !== undefined) {
+        const lastDay = new Date(Date.UTC(year, month, 0)).getUTCDate();
+        if (day < 1 || day > lastDay)
+            throw new TypeError('vet_animal_birth_date_invalid');
+    }
+    return value;
+}
+/** Reports whether an animal draft can be activated and issued a public Card. */
+export function readVetChainAnimalOnboardingReadiness(claims) {
+    const claim = VetChainAnimalOnboardingClaimNames;
+    const missing = [];
+    if (!String(claims[claim.alternateName] || '').trim())
+        missing.push('alternateName');
+    if (!/^http:\/\/purl\.obolibrary\.org\/obo\/NCBITaxon_[1-9]\d*$/.test(String(claims[claim.memberAdditionalType] || '').trim())) {
+        missing.push('species');
+    }
+    if (!String(claims[claim.sameAs] || '').trim())
+        missing.push('card');
+    return Object.freeze({ ready: missing.length === 0, missing: Object.freeze(missing) });
+}
+/**
+ * Projects one controller-authorized animal to the GW Organization envelope.
+ *
+ * The animal is the envelope's first member and therefore has the HL7
+ * `ONESELF` relationship. The authenticated human that creates it is kept in
+ * `Organization.owner`; controller authority such as `RESPRSN` is never
+ * copied into `Organization.member.role`.
+ *
+ * Species remains separate governed metadata. It validates the Damm digit with
+ * jurisdiction and animalNumericId15 but is never decoded from cardNumber21.
+ */
+export function buildVetChainAnimalOnboardingClaims(input) {
+    const alternateName = required(input.alternateName, 'vet_animal_name_invalid');
+    const ncbiTaxonomyId = normalizeVetChainNcbiTaxonomyId(input.ncbiTaxonomyId);
+    const claims = buildVetChainAnimalDraftClaims({ ...input, alternateName, ncbiTaxonomyId });
+    const readiness = readVetChainAnimalOnboardingReadiness(claims);
+    if (!readiness.ready)
+        throw new TypeError(`vet_animal_onboarding_incomplete:${readiness.missing.join(',')}`);
+    return claims;
+}
+function assertCardSpecies(cardDidWeb, ncbiTaxonomyId) {
+    const card = parseVetChainAnimalCardDid(cardDidWeb);
+    const expectedAnimalId16 = buildAnimalIdentifier16({
+        speciesId7: buildSpeciesId7(ncbiTaxonomyId),
+        jurisdictionCode5: card.jurisdictionCode5,
+        animalNumericId15: card.animalNumericId15,
+    });
+    if (expectedAnimalId16 !== card.animalId16) {
+        throw new TypeError('vet_animal_card_species_checksum_invalid');
+    }
+}
 function required(value, error) {
     const normalized = String(value || '').trim();
     if (!normalized)

package/docs/101-ANIMAL-INDIVIDUAL-ONBOARDING.md

@@ -0,0 +1,54 @@
+# Animal Individual Organization onboarding 101
+
+The animal and the human controller are two different identities:
+
+- `Organization.member` is the indexed animal itself. Its relationship is
+  `ONESELF`.
+- `Organization.owner` is the authenticated human that creates and controls
+  the Individual Organization by default. Controller authority may be
+  represented as `RESPRSN`, but that value never becomes the animal's member
+  role.
+
+```ts
+import {
+  buildVetChainAnimalDraftClaims,
+  readVetChainAnimalOnboardingReadiness,
+} from 'vet-sdk-core-ts/animal-onboarding'
+
+// Step 1. The controller starts a private draft using a verified contact.
+const draft = buildVetChainAnimalDraftClaims({
+  subjectId: crypto.randomUUID(),
+  controllerTelephone: '+12365162385',
+})
+
+// Optional breed text stays separate from the governed NCBI species. The
+// birth date may safely retain reduced year-month precision.
+buildVetChainAnimalDraftClaims({
+  subjectId: crypto.randomUUID(),
+  controllerTelephone: '+12365162385',
+  ncbiTaxonomyId: '9615',
+  breedLabel: 'Beagle',
+  birthDate: '2022-01',
+})
+
+// Step 2. The draft has member=SELF/ONESELF and owner=controller.
+draft['org.schema.Organization.member.role'] // ONESELF
+draft['org.schema.Organization.owner.telephone'] // verified controller
+
+// Step 3. Do not issue or display a Card while required data is missing.
+readVetChainAnimalOnboardingReadiness(draft)
+// { ready: false, missing: ['alternateName', 'species', 'card'] }
+```
+
+The BFF later rebuilds the same subject draft with its name and exact NCBI
+taxonomy, issues the public Card, and resubmits it under the same private
+`subjectId`. GW VET alone performs the `pending -> active` transition. A draft
+does not need a clinical `Composition`; the active clinical index is a
+separate document lifecycle.
+
+The controller is the author of demographics supplied during this draft. A
+veterinarian later verifies them as attester. That verification locks the
+controller-facing edit path; a correction is a new version authored and
+attested by an authorized veterinarian, never a rewrite of the earlier author.
+Veterinary identity evidence publishes only protected proof and lifecycle
+metadata to the ledger, not raw identity documents or private demographics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",