gdc-common-utils-ts 1.0.1

package/src/models/clinical-sections.en.ts

@@ -0,0 +1,82 @@
+/**
+ * English display labels for supported clinical document section codes.
+ *
+ * Notes:
+ * - This file is intentionally separate from the section registry so apps can:
+ *   - use these labels as a default (e.g., server-side rendering), and/or
+ *   - override them via i18n resources keyed by `org.loinc.<CODE>`.
+ * - Sources: HL7 FHIR doc-section-codes + project-specific additions.
+ */
+export const clinicalSectionTitleEn = {
+  // ---------------------------------------------------------------------------
+  // HL7 FHIR doc-section-codes (LOINC) — subset used by the platform/docs
+  // ---------------------------------------------------------------------------
+  '10154-3': 'Chief complaint Narrative - Reported',
+  '10157-6': 'History of family member diseases Narrative',
+  '10160-0': 'History of Medication use Narrative',
+  '10164-2': 'History of Present illness Narrative',
+  '10183-2': 'Hospital discharge medications Narrative',
+  '10184-0': 'Hospital discharge physical findings Narrative',
+  '10187-3': 'Review of systems Narrative - Reported',
+  '10210-3': 'Physical findings of General status Narrative',
+  '10216-0': 'Surgical operation note fluids Narrative',
+  '10218-6': 'Surgical operation note postoperative diagnosis Narrative',
+  '10222-8': 'Surgical operation note surgical complications [Interpretation] Narrative',
+  '10223-6': 'Surgical operation note surgical procedure Narrative',
+  '11329-0': 'History general Narrative - Reported',
+  '11348-0': 'History of Past illness Narrative',
+  '11369-6': 'History of Immunization Narrative',
+  '11493-4': 'Hospital discharge studies summary Narrative',
+  '11535-2': 'Hospital discharge Dx Narrative',
+  '11537-8': 'Surgical drains Narrative',
+  '18776-5': 'Plan of care note',
+  '18841-7': 'Hospital consultations Document',
+  '29299-5': 'Reason for visit Narrative',
+  '29545-1': 'Physical findings Narrative',
+  '29549-3': 'Medication administered Narrative',
+  '29554-3': 'Procedure Narrative',
+  '29762-2': 'Social history Narrative',
+  '30954-2': 'Relevant diagnostic tests/laboratory data Narrative',
+  '42344-2': 'Discharge diet (narrative)',
+  '42346-7': 'Medications on admission (narrative)',
+  '42348-3': 'Advance directives',
+  '42349-1': 'Reason for referral (narrative)',
+  '46240-8': 'History of Hospitalizations+Outpatient visits Narrative',
+  '46241-6': 'Hospital admission diagnosis Narrative - Reported',
+  '46264-8': 'History of medical device use',
+  '47420-5': 'Functional status assessment note',
+  '47519-4': 'History of Procedures Document',
+  '48765-2': 'Allergies and adverse reactions Document',
+  '48768-6': 'Payment sources Document',
+  '51848-0': 'Evaluation note',
+  '55109-3': 'Complications Document',
+  '55122-6': 'Surgical operation note implants Narrative',
+  '57852-6': 'Problem list Narrative - Reported',
+  '59768-2': 'Procedure indications [Interpretation] Narrative',
+  '59769-0': 'Postprocedure diagnosis Narrative',
+  '59770-8': 'Procedure estimated blood loss Narrative',
+  '59771-6': 'Procedure implants Narrative',
+  '59772-4': 'Planned procedure Narrative',
+  '59773-2': 'Procedure specimens taken Narrative',
+  '59775-7': 'Procedure disposition Narrative',
+  '59776-5': 'Procedure findings Narrative',
+  '61149-1': 'Objective Narrative',
+  '61150-9': 'Subjective Narrative',
+  '69730-0': 'Instructions',
+  '8648-8': 'Hospital course Narrative',
+  '8653-8': 'Hospital Discharge instructions',
+  '8716-3': 'Vital signs',
+
+  // ---------------------------------------------------------------------------
+  // Project additions (not part of doc-section-codes, but used by clients)
+  // ---------------------------------------------------------------------------
+  '60591-5': 'Patient summary',
+  '11450-4': 'Problem list',
+  '61144-2': 'Diet',
+  '82810-3': 'History of pregnancy',
+  '87520-3': 'Health insurance coverage',
+  '10190-7': 'Mental status',
+  '18726-0': 'Radiology studies',
+  '11503-0': 'Medical records (generic)',
+  '56796-6': 'Healthcare (general)',
+} as const;

package/src/models/clinical-sections.ts

@@ -0,0 +1,64 @@
+/**
+ * Canonical registry of supported clinical document sections (e.g., IPS Composition sections).
+ *
+ * Design goals:
+ * - Use stable codes (LOINC) for interoperability.
+ * - Provide a reverse-DNS i18n key for consistent UI translations across apps.
+ * - Keep this in `gdc-common-utils-ts` so both backend and frontend can share it.
+ */
+
+import { clinicalSectionTitleEn } from './clinical-sections.en';
+
+export const LOINC_SYSTEM_URL = 'http://loinc.org' as const;
+export const LOINC_SYSTEM_REVERSE_DNS = 'org.loinc' as const;
+
+export type ClinicalSectionDescriptor = {
+  /** Canonical coding system URL (FHIR-style). */
+  system: string;
+  /** Code within the coding system (e.g., a LOINC code). */
+  code: string;
+  /**
+   * Reverse-DNS translation key, intended for i18n resources.
+   * Example: `org.loinc.48765-2`.
+   */
+  i18nKey: string;
+  /**
+   * English fallback label (documentation/UI fallback).
+   *
+   * Prefer rendering a UI label via `i18nKey` (e.g., `org.loinc.<CODE>`) rather than relying on this.
+   */
+  titleEn?: string;
+  /** True when this is an IPS-aligned section code. */
+  ips?: boolean;
+};
+
+export function loincI18nKey(code: string): string {
+  return `${LOINC_SYSTEM_REVERSE_DNS}.${code}`;
+}
+
+export type SupportedClinicalSectionCode = keyof typeof clinicalSectionTitleEn;
+
+export const supportedClinicalSectionCodes = Object.freeze(
+  Object.keys(clinicalSectionTitleEn) as SupportedClinicalSectionCode[]
+);
+
+export const clinicalSectionRegistry: Readonly<Record<string, ClinicalSectionDescriptor>> = (() => {
+  const entries = Object.entries(clinicalSectionTitleEn).map(([code, titleEn]) => {
+    const descriptor: ClinicalSectionDescriptor = {
+      system: LOINC_SYSTEM_URL,
+      code,
+      i18nKey: loincI18nKey(code),
+      titleEn,
+      ips: true,
+    };
+    return [code, descriptor] as const;
+  });
+
+  return Object.freeze(Object.fromEntries(entries));
+})();
+
+export { clinicalSectionTitleEn };
+
+export function getClinicalSectionByCode(code: string): ClinicalSectionDescriptor | undefined {
+  return clinicalSectionRegistry[code];
+}

package/src/models/comm.ts

@@ -0,0 +1,63 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: src/models/comm.ts
+// Description: Defines the core communication and data structures based on DIDComm and FHIR.
+
+/**
+ * Represents the standard payload of a DIDComm v2 message.
+ * @see https://identity.foundation/didcomm-messaging/spec/v2.0/#plaintext-message-structure
+ */
+export interface DidCommPayload {
+  id: string;   // Message ID, required.
+  type: string; // Message Type URI, required.
+  from?: string; // Sender DID
+  to?: string[]; // Recipient DIDs
+  thid?: string; // Thread ID
+  pthid?: string; // Parent Thread ID
+  created_time?: number;
+  expires_time?: number;
+  body: { [key: string]: any };
+}
+
+/**
+ * Represents a data entry in the `body` of a CommMsgExtended,
+ * following a hybrid JSON:API and FHIR structure.
+ */
+export interface DataEntry {
+  id: string;
+  type: 'Annotation' | 'Reference' | 'Attachment' | 'CodeableConcept' | string;
+  resource: { [key: string]: any };
+  meta?: {
+    claims: any;
+  }
+}
+
+/**
+ * The canonical, internal representation of a secure message, extending
+ * the standard DIDComm payload with FHIR-specific, flattened metadata.
+ */
+export interface CommMsgExtended extends DidCommPayload {
+  // Overriding body for a more specific structure
+  body: {
+    data: DataEntry[];
+  };
+
+  // FHIR Communication resource fields, flattened for use as metadata or search parameters.
+  // These are derived from the source FHIR resource during conversion.
+  
+  // 'status'?: string; // e.g., 'completed', 'in-progress'
+  // 'statusReason'?: string; // Flattened from CodeableConcept
+  // 'partOf'?: string; // Comma-separated list of URNs/URLs
+  // 'basedOn'?: string; // Comma-separated list of URNs/URLs
+  // 'inResponseTo'?: string; // Comma-separated list of URNs/URLs
+  // 'priority'?: string; // e.g., 'routine', 'urgent'
+  // 'topic'?: string; // Flattened from CodeableConcept
+  // 'medium'?: string; // Flattened from CodeableConcept
+  // 'about'?: string; // Comma-separated list of URNs/URLs
+  // 'encounter'?: string; // URN or URL
+}
+
+/**
+ * A type placeholder for a FHIR Communication resource.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type FhirCommunication = any;

package/src/models/confidential-job.ts

@@ -0,0 +1,100 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/confidential-job.ts
+
+/**
+ * @file This file contains the core data models for the job processing system.
+ * These models are platform-agnostic and are part of the core SDK.
+ * @sdk
+ */
+
+import { IDecodedDidcommPayload as DecodedDidcommPayload } from "./confidential-message";
+import { ConfidentialStorageDoc, IndexedData } from "./confidential-storage";
+import { ServiceEndpointSelector } from "./did";
+
+/** When the organization has its own domain for the connector do not appear in the path:
+ * - the tenantId and jurisdiction, and
+ * - the apiVersion and sector; 
+ */
+export interface JobRequestInfo extends ServiceEndpointSelector {
+  /** When the organization has its own domain for the connector the tenantId and jurisdiction do not appear in the path */
+  tenantId?: string;
+  jurisdiction?: string;
+  /** The Unix epoch timestamp (in milliseconds) of when the job record was created. */
+  createdAtTimestamp: number;
+  requestUrl?: string;
+  httpMethod?: string;
+  contentType?: string;
+  language?: string;  
+}
+
+/**
+ * Defines the possible statuses of a job throughout its lifecycle.
+ */
+export enum JobStatus {
+  /** The job has been created locally but not yet submitted. */
+  DRAFT = 'DRAFT',
+  /** The job is in the process of being submitted to the server. */
+  SUBMITTING = 'SUBMITTING',
+  /** The job was successfully submitted and is awaiting asynchronous processing. */
+  SENT = 'SENT',
+  /** The server has finished processing the job and returned a final result. This is a terminal state. */
+  COMPLETED = 'COMPLETED',
+  /** The job failed due to a transport-level error and will not be retried. This is a terminal state. */
+  FAILED = 'FAILED',
+  /** The job failed due to a transient error and may be retried. */
+  ERROR_RETRYABLE = 'ERROR_RETRYABLE',
+}
+
+/**
+ * Represents the entire data package for a single job ready for processing.
+ * It combines the HTTP request context with the unprotected message and its security context.
+ * The hosted URL has this structure: `https://<host-domain>/:tenantId/cds-:jurisdiction/v1/:sector/:section/:format/:resourceType/:action`
+ * The external URL has this structure: `https://<organization-domain>/:section/:format/:resourceType/:action`
+ */
+export interface JobRequest extends ConfidentialStorageDoc, JobRequestInfo {
+    // 'id' serves as the primary key in the vault.
+    id: string;
+    /**
+     * DIDComm thread ID for correlating async jobs.
+     * Stored outside encrypted `content` so UIs can query jobs by thread without decrypting.
+     */
+    thid?: string;
+    status: JobStatus;
+    versionId?: string;
+    vaultId?: string;
+    chunks?: number;
+
+    // From ConfidentialStorageDoc
+
+    /** A number that MUST be incremented each time the document is updated. */
+    sequence: number;
+    
+    /** Previous sequence being replaced by the update */
+    previousSequence?: number;
+
+    /** Contains an array of indexed attributes protected with HMAC for blind queries. */
+    indexed?: IndexedData;
+    
+    /** The decoded DIDComm message. Present when the job is unprotected. */
+    content?: DecodedDidcommPayload;
+
+    /** The JWE representation of the encrypted content. Present when the job is protected. */
+    jwe?: Record<string, any>;
+
+    // Additional information for job processing
+
+    /** Addtional information from HTTP header */
+    onBehalfOf?: string;
+
+    /** The URL provided by the server to poll for the job's status. */
+    locationUrl?: string;
+
+    /** A counter for the number of retry attempts. */
+    retryCount?: number;
+
+    /** The ID of the corresponding response message stored in the vault, once the job is COMPLETED. */
+    responseMessageId?: string;
+
+    /** CAUTION: Only for debugging purposes. It is the last error message, o*/
+    errorMessage?: string;
+}

package/src/models/confidential-message.ts

@@ -0,0 +1,137 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/confidential-message.ts
+// Description: Defines the core communication and data structures based on DIDComm and FHIR.
+
+import { ProtectedHeadersJWE } from "./jwe";
+import { JwsHeader } from "./jws";
+
+export type { DataEntry } from "./comm";
+
+/**
+ * Defines the structure of the cryptographic metadata associated with a job request.
+ */
+export interface DidCommDecodedMetadata {
+  jws?: {
+    protected?: JwsHeader;
+    /** Detached signature of the request JWS (when available). */
+    signature?: string;
+  };
+  jwe?: {
+    header?: ProtectedHeadersJWE;
+  };
+  bearer?: {
+    compact?: string,
+    jwt: {
+      header?: JwsHeader;
+      payload?: Record<string, any>;
+    };
+  };
+}
+
+/**
+ * Represents the standard payload of a DIDComm v2 message.
+ * @see https://identity.foundation/didcomm-messaging/spec/v2.0/#plaintext-message-structure
+ */
+/**
+ * Represents the plaintext of a decoded DIDComm message.
+ * This is the core business-level "input" for a job.
+ * For FAPI compliance, this entire object is typically the payload of a signed JWS.
+ */
+export interface IDecodedDidcommPayload {
+
+  /** Relevant information available through the decryption and verification process */
+  meta?: DidCommDecodedMetadata;
+
+  // --- FAPI & JWT Core Claims ---
+  
+  /**
+   * (Issuer) The DID of the entity that issued the message.
+   * REQUIRED for FAPI. MUST match the signer of the enclosing JWS.
+   */
+  iss: string;
+
+  /**
+   * (Audience) The URL of the backend endpoint that will process this message.
+   * REQUIRED for FAPI. The backend MUST validate that this value matches its own URL.
+   */
+  aud: string;
+
+  /** (Expiration Time) Timestamp after which the message is considered invalid. REQUIRED for FAPI (instead of expires_time). */
+  exp?: number;
+
+  /** (Not Before) Timestamp before which the message must not be processed. REQUIRED for FAPI (instead of created_time). */
+  nbf?: number;
+
+  /** (Issued At) Timestamp when the message was issued. REQUIRED for FAPI. */
+  iat?: number;
+  
+  /**
+   * (JWT ID) A unique identifier for this message/token. Can be used to prevent replay attacks.
+   * In our architecture, this can also serve as the version hash of the data content.
+   */
+  jti: string;
+
+  // --- DIDComm Core Fields ---
+
+  /** Optional. The `jti` identifies both the message and job for processing */
+  id?: string;
+  
+  /** The Transaction ID / Thread ID for message correlation across an interaction. */
+  thid: string;
+
+  /**  Parent Thread ID */
+  pthid?: string; 
+
+  /** The DID of the intended recipient. Used for P2P messaging, informational in client-server requests. */
+  to?: string[];
+  
+  /** The DID of the sender. Used for P2P messaging, but `iss` is the authoritative value for FAPI. */
+  from?: string;
+
+  /**
+   * The Message Type URI, identifying the type of data in the body or protocol used.
+   * (e.g. 'application/json') 
+  */
+  type: string;
+
+  /** The main business payload of the message. The structure is defined by the 'type' protocol. */
+  body: any;
+}
+
+/**
+ * Represents a data entry in the `body` of a CommMsgExtended,
+ * following a hybrid JSON:API and FHIR structure.
+ */
+export interface CommDataEntry {
+  id: string;
+  type: 'Annotation' | 'Reference' | 'Attachment' | 'CodeableConcept' | string;
+  resource: { [key: string]: any };
+  meta?: {
+    claims: any;
+  }
+}
+
+/**
+ * The canonical, internal representation of a secure message, extending
+ * the standard DIDComm payload with FHIR-specific, flattened metadata.
+ */
+export interface ICommPayloadExtended extends IDecodedDidcommPayload {
+  // Overriding body for a more specific structure
+  body: {
+    data: CommDataEntry[];
+  };
+
+  // FHIR Communication resource fields, flattened for use as metadata or search parameters.
+  // These are derived from the source FHIR resource during conversion.
+  
+  // 'status'?: string; // e.g., 'completed', 'in-progress'
+  // 'statusReason'?: string; // Flattened from CodeableConcept
+  // 'partOf'?: string; // Comma-separated list of URNs/URLs
+  // 'basedOn'?: string; // Comma-separated list of URNs/URLs
+  // 'inResponseTo'?: string; // Comma-separated list of URNs/URLs
+  // 'priority'?: string; // e.g., 'routine', 'urgent'
+  // 'topic'?: string; // Flattened from CodeableConcept
+  // 'medium'?: string; // Flattened from CodeableConcept
+  // 'about'?: string; // Comma-separated list of URNs/URLs
+  // 'encounter'?: string; // URN or URL
+}

package/src/models/confidential-storage.ts

@@ -0,0 +1,170 @@
+// Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: gdc-common-utils-ts/src/models/confidential-storage.ts
+
+import { ParameterType } from './params';
+
+/**
+ * FHIR `Coding`-like tag used for research/analytics metadata.
+ * Keep values coarse and coded; avoid free text in `display` unless explicitly policy-approved.
+ */
+export interface MetaTagCoding {
+  system?: string;
+  code?: string;
+  version?: string;
+  display?: string;
+  userSelected?: boolean;
+}
+
+/**
+ * Research/analytics metadata kept outside encrypted `content`.
+ * Policy-dependent: treat these fields as potentially sensitive.
+ */
+export interface ResearchInfo {
+  /** Coarse jurisdiction identifier (e.g., "cds-es" or "ES"). */
+  jurisdiction?: string;
+  /** Year of birth (YYYY). */
+  yearOfBirth?: string;
+  /** Gender identity (user-identified). Keep coded and coarse. */
+  gender?: string;
+  /** Sex assigned at birth (if collected). Keep coded and coarse. */
+  sexAtBirth?: string;
+}
+
+/**
+ * Audit metadata for traceability.
+ *
+ * Values are set by the software (off-ledger) and/or by an external attestation layer (on-ledger).
+ * This object is intentionally separate from:
+ * - `research` (analytics metadata)
+ * - any `meta` object inside encrypted `content` (e.g., entry `meta.claims`)
+ */
+export interface AuditInfo {
+  /** When the document was first created off-ledger (ISO 8601). */
+  created?: string;
+  /** When the document was last updated off-ledger (ISO 8601). */
+  updated?: string;
+  /** True if removed/deactivated (deactivation time is typically `updated`). */
+  deactivated?: boolean;
+  /** Name of the channel/network where the data is audited/anchored. */
+  channel?: string;
+  /** Base58/Base64Url transaction identifier, depending on the attestation layer. */
+  txId?: string;
+  /** Transaction timestamp (ISO 8601). */
+  txTime?: string;
+}
+
+/**
+ * Defines the structure of an attribute to be indexed for blind, searchable queries.
+ * @see https://identity.foundation/confidential-storage/#indexed-attributes
+ */
+export interface IndexedAttribute {
+  name: string;
+  value: string;
+  unique?: boolean;
+  /**
+   * The original data type of the `value` before it was converted to a string
+   * for HMAC protection. This is essential for performing type-aware queries
+   * (e.g., numerical range queries) on the indexed data.
+   * If not present, the type is assumed to be 'string'.
+   */
+  type?: ParameterType | string;
+}
+
+/**
+ * Defines an indexed portion of a confidential document, allowing specific attributes to be searchable.
+ */
+export interface IndexedData {
+    attributes: IndexedAttribute[];
+    hmac?: {
+        id: string;
+        type: string;
+    };
+    sequence?: number;
+}
+
+/**
+ * Represents a complete Structured Document as defined by the Confidential Storage specification.
+ * This is the canonical format for all documents persisted in a vault.
+ * @see https://identity.foundation/confidential-storage/#structureddocument
+ */
+export interface ConfidentialStorageDoc {
+    // 'id' is inherited from RecordBase
+    id: string;
+    status: string;
+    /**
+     * Optional content-derived version identifier.
+     *
+     * Recommended usage:
+     * - set to a deterministic content hash of the canonicalized artifact/claims (e.g., multihash over JCS bytes),
+     *   so each semantic update yields a new `versionId`.
+     * - do NOT use this for blockchain transaction identifiers (use `audit.txId` / `audit.txTime` instead).
+     */
+    versionId?: string;
+    vaultId?: string;
+    chunks?: number;
+
+    /** A number that MUST be incremented each time the document is updated. */
+    sequence: number;
+
+    /** Contains an array of indexed attributes protected with HMAC for blind queries. */
+    indexed?: IndexedData;
+    
+    /** The main, potentially encrypted, content of the document. */
+    content?: Record<string, any>;
+
+    /** The JWE representation of the encrypted content. It could be a URL in case of a bucket is used to store the JWE or chunks */
+    jwe?: Record<string, any>;
+
+    /**
+     * Document-level created timestamp (outside encrypted `content`).
+     * This is distinct from any `meta` objects inside `content` (e.g., entry meta.claims).
+     */
+    audit?: AuditInfo;
+
+    /**
+     * @deprecated Use `audit.created` instead.
+     */
+    created?: string;
+
+    /**
+     * Document-level content type label (outside encrypted `content`).
+     * This is distinct from any `contentType` claims inside `content`.
+     */
+    contentType?: string;
+
+    /**
+     * Optional research/routing tags kept outside encrypted `content`.
+     * These tags are intended for analytics/routing and may be mirrored back to API responses.
+     * Avoid free text in `display` unless explicitly policy-approved.
+     */
+    tag?: MetaTagCoding[];
+
+    /** Policy-dependent research/analytics metadata, kept outside encrypted `content`. */
+    research?: ResearchInfo;
+
+    /**
+     * @deprecated Use `created`, `contentType`, and `research` instead.
+     * This legacy field is kept for backwards compatibility with older stored documents.
+     */
+    meta?: {
+        created?: string;
+        contentType?: string;
+        chunks?: number;
+        jurisdiction?: string;
+        yearOfBirth?: string;
+        gender?: string;
+        sexAtBirth?: string;
+        /** @deprecated Use `tag` instead. */
+        tags?: string;
+    };
+}
+
+/**
+ * Represents a document whose sensitive content has been decrypted and is held
+ * in memory. The `jwe` property is removed, and the `content` is guaranteed to exist.
+ * This type should ONLY be used for in-memory processing and NEVER for persistence.
+ * @template T The expected type of the decrypted `content`.
+ */
+export type UnprotectedStorageDoc<T> = Omit<ConfidentialStorageDoc, 'jwe' | 'content'> & {
+    content: T;
+};