gdc-common-utils-ts 2.3.17 → 2.3.19

package/dist/constants/schemaorg.d.ts

@@ -38,6 +38,8 @@ export declare enum ClaimsSoftwareApplicationSchemaorg {
  * based on Schema.org vocabulary.
  */
 export declare enum ClaimsOrganizationSchemaorg {
+    /** Schema.org type discriminator for the indexed organization/member profile. */
+    additionalType = "org.schema.Organization.additionalType",
     /** Public aliases used for exact organization or individual resolution. */
     sameAs = "org.schema.Organization.sameAs",
     /** ISO 3166-1 alpha-2 (two-letter country code). The jurisdiction could be the country or the region (county, province or state) */
@@ -88,6 +90,16 @@ export declare enum ClaimsOrganizationSchemaorg {
     ownerIdentifierValue = "org.schema.Organization.owner.identifier.value",
     /** Individual/family indexed member friendly name used by onboarding draft helpers. */
     memberAlternateName = "org.schema.Organization.member.alternateName",
+    /** Public display name of the indexed member. */
+    memberName = "org.schema.Organization.member.name",
+    /**
+     * Semantic type of the indexed member.
+     *
+     * Animal onboarding uses the canonical NCBI Taxonomy OBO URI here. This
+     * distinguishes an animal without inferring species from a FHIR resource
+     * name or from an application-local flag.
+     */
+    memberAdditionalType = "org.schema.Organization.member.additionalType",
     memberGivenName = "org.schema.Organization.member.givenName",
     memberFamilyName = "org.schema.Organization.member.familyName",
     memberBirthDate = "org.schema.Organization.member.birthDate",

package/dist/constants/schemaorg.js

@@ -42,6 +42,8 @@ export var ClaimsSoftwareApplicationSchemaorg;
  */
 export var ClaimsOrganizationSchemaorg;
 (function (ClaimsOrganizationSchemaorg) {
+    /** Schema.org type discriminator for the indexed organization/member profile. */
+    ClaimsOrganizationSchemaorg["additionalType"] = "org.schema.Organization.additionalType";
     /** Public aliases used for exact organization or individual resolution. */
     ClaimsOrganizationSchemaorg["sameAs"] = "org.schema.Organization.sameAs";
     /** ISO 3166-1 alpha-2 (two-letter country code). The jurisdiction could be the country or the region (county, province or state) */
@@ -92,6 +94,16 @@ export var ClaimsOrganizationSchemaorg;
     ClaimsOrganizationSchemaorg["ownerIdentifierValue"] = "org.schema.Organization.owner.identifier.value";
     /** Individual/family indexed member friendly name used by onboarding draft helpers. */
     ClaimsOrganizationSchemaorg["memberAlternateName"] = "org.schema.Organization.member.alternateName";
+    /** Public display name of the indexed member. */
+    ClaimsOrganizationSchemaorg["memberName"] = "org.schema.Organization.member.name";
+    /**
+     * Semantic type of the indexed member.
+     *
+     * Animal onboarding uses the canonical NCBI Taxonomy OBO URI here. This
+     * distinguishes an animal without inferring species from a FHIR resource
+     * name or from an application-local flag.
+     */
+    ClaimsOrganizationSchemaorg["memberAdditionalType"] = "org.schema.Organization.member.additionalType";
     ClaimsOrganizationSchemaorg["memberGivenName"] = "org.schema.Organization.member.givenName";
     ClaimsOrganizationSchemaorg["memberFamilyName"] = "org.schema.Organization.member.familyName";
     ClaimsOrganizationSchemaorg["memberBirthDate"] = "org.schema.Organization.member.birthDate";

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

@@ -0,0 +1,42 @@
+export declare const AnimalSubjectKinds: Readonly<{
+    readonly Animal: "animal";
+}>;
+export declare const NcbiTaxonomy: Readonly<{
+    readonly Dog: "9615";
+    readonly Cat: "9685";
+    readonly Horse: "9796";
+}>;
+export type NcbiTaxonomyId = string;
+export type AnimalOnboardingInput = Readonly<{
+    subjectId: string;
+    cardDidWeb: string;
+    alternateName: string;
+    legalName?: string;
+    birthDate?: string;
+    birthYear?: number;
+    gender?: 'female' | 'male' | 'other' | 'unknown';
+    ncbiTaxonomyId: NcbiTaxonomyId;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    sector?: string;
+}>;
+export type AnimalOnboardingClaims = Readonly<Record<string, string>>;
+/**
+ * Builds the canonical OBO URI for one NCBI Taxonomy numeric identifier.
+ *
+ * The URI is public taxonomy metadata, not an animal identifier. Callers must
+ * keep microchip, registry and controller identifiers in their separately
+ * typed confidential/index contracts.
+ */
+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;
+ * 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.
+ */
+export declare function buildAnimalOnboardingClaims(input: AnimalOnboardingInput): AnimalOnboardingClaims;

package/dist/models/animal-onboarding.js

@@ -0,0 +1,65 @@
+import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
+import { DataspaceSectors } from '../constants/sectors.js';
+export const AnimalSubjectKinds = Object.freeze({
+    Animal: 'animal',
+});
+export const NcbiTaxonomy = Object.freeze({
+    Dog: '9615',
+    Cat: '9685',
+    Horse: '9796',
+});
+/**
+ * Builds the canonical OBO URI for one NCBI Taxonomy numeric identifier.
+ *
+ * The URI is public taxonomy metadata, not an animal identifier. Callers must
+ * keep microchip, registry and controller identifiers in their separately
+ * typed confidential/index contracts.
+ */
+export function buildNcbiTaxonomyUri(id) {
+    const normalized = id.trim();
+    if (!/^[1-9]\d*$/.test(normalized)) {
+        throw new TypeError('ncbiTaxonomyId must be a positive numeric NCBI Taxonomy identifier.');
+    }
+    if (normalized === '9606') {
+        throw new TypeError('Human NCBI Taxonomy 9606 is not valid for animal onboarding.');
+    }
+    return `http://purl.obolibrary.org/obo/NCBITaxon_${normalized}`;
+}
+/**
+ * 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;
+ * 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.
+ */
+export function buildAnimalOnboardingClaims(input) {
+    const subjectId = input.subjectId.trim();
+    const cardDidWeb = input.cardDidWeb.trim();
+    const alternateName = input.alternateName.trim();
+    if (!subjectId || !cardDidWeb || !alternateName) {
+        throw new TypeError('subjectId, cardDidWeb and alternateName are required.');
+    }
+    const birthDate = input.birthDate?.trim()
+        || (Number.isInteger(input.birthYear) ? String(input.birthYear) : '');
+    const legalName = input.legalName?.trim();
+    const gender = input.gender && input.gender !== 'unknown' ? input.gender : '';
+    return Object.freeze({
+        '@context': 'org.schema',
+        [ClaimsOrganizationSchemaorg.identifierValue]: subjectId,
+        [ClaimsOrganizationSchemaorg.additionalType]: AnimalSubjectKinds.Animal,
+        [ClaimsOrganizationSchemaorg.alternateName]: alternateName,
+        ...(legalName ? { [ClaimsOrganizationSchemaorg.legalName]: legalName } : {}),
+        [ClaimsOrganizationSchemaorg.sameAs]: cardDidWeb,
+        [ClaimsOrganizationSchemaorg.memberName]: alternateName,
+        [ClaimsOrganizationSchemaorg.memberAdditionalType]: buildNcbiTaxonomyUri(input.ncbiTaxonomyId),
+        [ClaimsOrganizationSchemaorg.memberRole]: 'RESPRSN',
+        ...(birthDate ? { [ClaimsOrganizationSchemaorg.memberBirthDate]: birthDate } : {}),
+        ...(gender ? { [ClaimsOrganizationSchemaorg.memberGender]: gender } : {}),
+        [ClaimsOrganizationSchemaorg.ownerEmail]: input.controllerEmail?.trim() || '',
+        [ClaimsOrganizationSchemaorg.ownerTelephone]: input.controllerTelephone?.trim() || '',
+        [ClaimsServiceSchemaorg.category]: input.sector?.trim() || DataspaceSectors.AnimalCare,
+    });
+}

package/dist/models/index.d.ts

@@ -26,6 +26,7 @@ export * from './interoperable-claims';
 export * from './indexing';
 export * from './identity-bootstrap';
 export * from './individual-onboarding';
+export * from './animal-onboarding';
 export * from './inter-tenant-access-contract';
 export * from './issue';
 export * from './jsonapi';
@@ -49,6 +50,7 @@ export * from './relationship-access';
 export * from './response';
 export * from './subject-identifier-ledger';
 export * from './subject-identity-binding';
+export * from './terminology';
 export * from './urlPath';
 export * from './verifiable-credential';
 export * from './wallet';

package/dist/models/index.js

@@ -26,6 +26,7 @@ export * from './interoperable-claims.js';
 export * from './indexing.js';
 export * from './identity-bootstrap.js';
 export * from './individual-onboarding.js';
+export * from './animal-onboarding.js';
 export * from './inter-tenant-access-contract.js';
 export * from './issue.js';
 export * from './jsonapi.js';
@@ -49,6 +50,7 @@ export * from './relationship-access.js';
 export * from './response.js';
 export * from './subject-identifier-ledger.js';
 export * from './subject-identity-binding.js';
+export * from './terminology.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';
 export * from './wallet.js';

package/dist/models/terminology.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One terminology block in the legacy JSON catalog format.
+ *
+ * `id` is normally the canonical coding-system URI. The compatibility alias
+ * `ips` is accepted for the SNOMED IPS catalog used by
+ * the predecessor FHIR utility package.
+ */
+export type TerminologyCatalogResource = Readonly<{
+    id: string;
+    language?: string;
+    attributes: Readonly<Record<string, string>>;
+    meta?: Readonly<Record<string, unknown>>;
+}>;
+/**
+ * Loadable local terminology document compatible with the historic
+ * `data[].attributes[code] = display` JSON shape.
+ */
+export type TerminologyCatalogDocument = Readonly<{
+    id?: string;
+    name?: string;
+    language?: string;
+    system?: string;
+    version?: string;
+    jurisdiction?: string;
+    data: readonly TerminologyCatalogResource[];
+    meta?: Readonly<Record<string, unknown>>;
+}>;
+/** Input for a synchronous local terminology label lookup. */
+export type TerminologyLookupInput = Readonly<{
+    system: string;
+    code: string;
+    language: string;
+    jurisdiction?: string;
+}>;
+/** Input for an offline/local terminology text search. */
+export type TerminologySearchInput = Readonly<{
+    text: string;
+    language: string;
+    jurisdiction?: string;
+    systems?: readonly string[];
+    limit?: number;
+}>;
+/** One terminology option suitable for a coded clinical form control. */
+export type TerminologySearchResult = Readonly<{
+    system: string;
+    code: string;
+    display: string;
+    language: string;
+}>;
+/**
+ * Synchronous terminology contract used by cached and offline applications.
+ *
+ * A future remote terminology client should populate a local implementation
+ * of this contract before synchronous clinical-card rendering.
+ */
+export interface TerminologyProvider {
+    lookup(input: TerminologyLookupInput): string | undefined;
+    search(input: TerminologySearchInput): readonly TerminologySearchResult[];
+}

package/dist/models/terminology.js

@@ -0,0 +1 @@
+export {};

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

@@ -45,6 +45,9 @@ export type ClinicalResourceDisplayOptions = Readonly<{
      *
      * Return `undefined` when the product has no translation so the shared
      * reader can fall back to the international `Coding.display`.
+     * `createClinicalCodeTranslator(new LocalTerminologyProvider(catalogs))`
+     * provides the synchronous MVP/offline implementation. Remote terminology
+     * results must be fetched and cached before this render callback runs.
      */
     translateCode?: (input: ClinicalTerminologyTranslationInput) => string | undefined;
 }>;

package/dist/utils/index.d.ts

@@ -81,6 +81,7 @@ export * from './jwt-signer';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
 export * from './legal-organization-verification-transaction';
+export * from './local-terminology-provider';
 export * from './license';
 export * from './license-commercial-search';
 export * from './license-list-search';

package/dist/utils/index.js

@@ -81,6 +81,7 @@ export * from './jwt-signer.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
 export * from './legal-organization-verification-transaction.js';
+export * from './local-terminology-provider.js';
 export * from './license.js';
 export * from './license-commercial-search.js';
 export * from './license-list-search.js';

package/dist/utils/local-terminology-provider.d.ts

@@ -0,0 +1,27 @@
+import type { TerminologyCatalogDocument, TerminologyLookupInput, TerminologyProvider, TerminologySearchInput, TerminologySearchResult } from '../models/terminology.js';
+import type { ClinicalTerminologyTranslationInput } from './clinical-resource-view.js';
+/**
+ * In-memory terminology provider compatible with the historic JSON
+ * catalogs. It performs no network requests and keeps catalog loading under
+ * application control.
+ */
+export declare class LocalTerminologyProvider implements TerminologyProvider {
+    private readonly terms;
+    private readonly byIdentity;
+    private readonly byScopedIdentity;
+    constructor(catalogs: readonly TerminologyCatalogDocument[]);
+    /** Returns the best local label for one canonical coding identity. */
+    lookup(input: TerminologyLookupInput): string | undefined;
+    /**
+     * Searches local labels and codes, optionally constrained to coding systems.
+     * Results are deterministic and contain at most 100 entries.
+     */
+    search(input: TerminologySearchInput): readonly TerminologySearchResult[];
+    private identityKey;
+    private scopedIdentityKey;
+}
+/**
+ * Adapts a synchronous local terminology provider to
+ * `ClinicalResourceDisplayOptions.translateCode`.
+ */
+export declare function createClinicalCodeTranslator(provider: Pick<TerminologyProvider, 'lookup'>): (input: ClinicalTerminologyTranslationInput) => string | undefined;

package/dist/utils/local-terminology-provider.js

@@ -0,0 +1,154 @@
+const SNOMED_SYSTEM = 'http://snomed.info/sct';
+const DEFAULT_LANGUAGE = 'en';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+function normalizedString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function normalizeSystem(value) {
+    const system = normalizedString(value);
+    return system.toLowerCase() === 'ips' ? SNOMED_SYSTEM : system;
+}
+function normalizeLanguage(value) {
+    return normalizedString(value).replace(/_/g, '-').toLowerCase();
+}
+function normalizeJurisdiction(value) {
+    return normalizedString(value).toUpperCase();
+}
+function languageCandidates(language) {
+    const normalized = normalizeLanguage(language);
+    const base = normalized.split('-')[0];
+    return [...new Set([normalized, base, DEFAULT_LANGUAGE].filter(Boolean))];
+}
+function searchableText(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLocaleLowerCase();
+}
+function normalizedLimit(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_LIMIT;
+    return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(value)));
+}
+/**
+ * In-memory terminology provider compatible with the historic JSON
+ * catalogs. It performs no network requests and keeps catalog loading under
+ * application control.
+ */
+export class LocalTerminologyProvider {
+    terms;
+    byIdentity;
+    byScopedIdentity;
+    constructor(catalogs) {
+        const terms = [];
+        const byIdentity = new Map();
+        const byScopedIdentity = new Map();
+        for (const catalog of catalogs) {
+            const catalogLanguage = normalizeLanguage(catalog.language) || DEFAULT_LANGUAGE;
+            const jurisdiction = normalizeJurisdiction(catalog.jurisdiction) || undefined;
+            for (const resource of catalog.data || []) {
+                const system = normalizeSystem(resource.id || catalog.system);
+                const language = normalizeLanguage(resource.language) || catalogLanguage;
+                if (!system || !language || !resource.attributes)
+                    continue;
+                for (const [rawCode, rawDisplay] of Object.entries(resource.attributes)) {
+                    const code = normalizedString(rawCode);
+                    const display = normalizedString(rawDisplay);
+                    if (!code || !display)
+                        continue;
+                    const term = { system, code, display, language, jurisdiction };
+                    terms.push(term);
+                    byIdentity.set(this.identityKey(language, system, code), display);
+                    byScopedIdentity.set(this.scopedIdentityKey(language, jurisdiction, system, code), display);
+                }
+            }
+        }
+        this.terms = terms;
+        this.byIdentity = byIdentity;
+        this.byScopedIdentity = byScopedIdentity;
+    }
+    /** Returns the best local label for one canonical coding identity. */
+    lookup(input) {
+        const system = normalizeSystem(input.system);
+        const code = normalizedString(input.code);
+        const jurisdiction = normalizeJurisdiction(input.jurisdiction) || undefined;
+        if (!system || !code)
+            return undefined;
+        for (const language of languageCandidates(input.language)) {
+            if (jurisdiction) {
+                const scopedDisplay = this.byScopedIdentity.get(this.scopedIdentityKey(language, jurisdiction, system, code)) || this.byScopedIdentity.get(this.scopedIdentityKey(language, undefined, system, code));
+                if (scopedDisplay)
+                    return scopedDisplay;
+                continue;
+            }
+            const display = this.byIdentity.get(this.identityKey(language, system, code));
+            if (display)
+                return display;
+        }
+        return undefined;
+    }
+    /**
+     * Searches local labels and codes, optionally constrained to coding systems.
+     * Results are deterministic and contain at most 100 entries.
+     */
+    search(input) {
+        const query = searchableText(normalizedString(input.text));
+        if (!query)
+            return [];
+        const allowedSystems = new Set((input.systems || []).map(normalizeSystem).filter(Boolean));
+        const jurisdiction = normalizeJurisdiction(input.jurisdiction);
+        const languages = languageCandidates(input.language);
+        const languageRank = new Map(languages.map((language, index) => [language, index]));
+        const selected = new Map();
+        for (const term of this.terms) {
+            if (allowedSystems.size > 0 && !allowedSystems.has(term.system))
+                continue;
+            if (jurisdiction && term.jurisdiction && term.jurisdiction !== jurisdiction)
+                continue;
+            const rank = languageRank.get(term.language);
+            if (rank === undefined)
+                continue;
+            if (!searchableText(term.code).includes(query)
+                && !searchableText(term.display).includes(query)) {
+                continue;
+            }
+            const identity = `${term.system}\u0000${term.code}`;
+            const current = selected.get(identity);
+            if (!current || rank < current.rank)
+                selected.set(identity, { term, rank });
+        }
+        return [...selected.values()]
+            .sort((left, right) => (left.rank - right.rank
+            || left.term.display.localeCompare(right.term.display)
+            || left.term.code.localeCompare(right.term.code)))
+            .slice(0, normalizedLimit(input.limit))
+            .map(({ term }) => ({
+            system: term.system,
+            code: term.code,
+            display: term.display,
+            language: term.language,
+        }));
+    }
+    identityKey(language, system, code) {
+        return `${language}\u0000${system}\u0000${code}`;
+    }
+    scopedIdentityKey(language, jurisdiction, system, code) {
+        return `${language}\u0000${jurisdiction || ''}\u0000${system}\u0000${code}`;
+    }
+}
+/**
+ * Adapts a synchronous local terminology provider to
+ * `ClinicalResourceDisplayOptions.translateCode`.
+ */
+export function createClinicalCodeTranslator(provider) {
+    return (input) => {
+        if (!input.system)
+            return undefined;
+        return provider.lookup({
+            system: input.system,
+            code: input.code,
+            language: input.locale,
+        });
+    };
+}

package/package.json

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