gdc-common-utils-ts 1.14.13 → 1.14.14

package/README.md

@@ -1,5 +1,11 @@
 # gdc-common-utils-ts
 
+Employee shared examples live in `src/examples/employee.ts`.
+Employee pure helper functions live in `src/utils/employee.ts`.
+
+The canonical employee contract note lives in
+`gdc-sdk-core-ts/docs/EMPLOYEES_101.md`.
+
 Shared TypeScript utilities for GDC client and connector code. This package provides low-level primitives for cryptography, DID/DIDComm-related helpers, and the shared models and interfaces used across SDKs.
 
 It is intentionally not a full backend orchestration layer.

package/dist/examples/employee.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical employee directory fixture shared by docs and tests.
+ *
+ * Semantics:
+ * - `identifier` points to one technical employee profile
+ * - `email` can map to multiple active roles
+ * - a purged profile remains historically addressable by `identifier`
+ */
+export type ExampleEmployeeRecord = Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: 'active' | 'inactive' | 'purged';
+}>;
+export declare const ExampleEmployeeEmails: Readonly<{
+    readonly SharedProfessional: "shared.professional@example.org";
+}>;
+export declare const ExampleEmployeeRoles: Readonly<{
+    readonly Controller: "ISCO-08|1120";
+    readonly Doctor: "ISCO-08|2211";
+}>;
+export declare const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DIRECTORY_RECORDS: readonly [Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>, Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>, Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>];
+export declare function buildExampleEmployeeClaims(record: ExampleEmployeeRecord): Readonly<Record<string, string>>;

package/dist/examples/employee.js

@@ -0,0 +1,39 @@
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+export const ExampleEmployeeEmails = Object.freeze({
+    SharedProfessional: 'shared.professional@example.org',
+});
+export const ExampleEmployeeRoles = Object.freeze({
+    Controller: 'ISCO-08|1120',
+    Doctor: 'ISCO-08|2211',
+});
+export const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE = Object.freeze({
+    identifier: 'urn:uuid:employee-controller-active-001',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Controller,
+    status: 'active',
+});
+export const EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE = Object.freeze({
+    identifier: 'urn:uuid:employee-doctor-active-001',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Doctor,
+    status: 'active',
+});
+export const EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL = Object.freeze({
+    identifier: 'urn:uuid:employee-doctor-purged-000',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Doctor,
+    status: 'purged',
+});
+export const EXAMPLE_EMPLOYEE_DIRECTORY_RECORDS = Object.freeze([
+    EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE,
+    EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE,
+    EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL,
+]);
+export function buildExampleEmployeeClaims(record) {
+    return Object.freeze({
+        '@context': 'org.schema',
+        [ClaimsPersonSchemaorg.identifier]: record.identifier,
+        [ClaimsPersonSchemaorg.email]: record.email,
+        [ClaimsPersonSchemaorg.hasOccupationalRoleValue]: record.role,
+    });
+}

package/dist/examples/index.d.ts

@@ -4,6 +4,7 @@ export * from './dataspace-discovery';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';
+export * from './employee';
 export * from './related-person';
 export * from './consent-access';
 export * from './relationship-access';

package/dist/examples/index.js

@@ -4,6 +4,7 @@ export * from './dataspace-discovery.js';
 export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';
+export * from './employee.js';
 export * from './related-person.js';
 export * from './consent-access.js';
 export * from './relationship-access.js';

package/dist/utils/communication-bundle-document-request.d.ts

@@ -1,5 +1,6 @@
 import { HealthcareDocumentTypes } from '../constants/healthcare';
 import type { ParameterData } from '../models/params';
+import { FhirParametersResource } from './fhir-search';
 export declare const BundleDocumentRequesterKinds: Readonly<{
     readonly Controller: "controller";
     readonly Employee: "employee";
@@ -140,6 +141,11 @@ export declare function createSummaryOperationRequestParameters(subjectIdOrInput
  * path currently stored in `Communication.content-reference`.
  */
 export declare function createSummaryOperationRequestReferencePath(parameters: ReadonlyArray<ParameterData>): string;
+/**
+ * Builds the preferred FHIR `Parameters` body for the same semantic summary
+ * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ */
+export declare function createSummaryOperationRequestParametersResource(parameters: ReadonlyArray<ParameterData>): FhirParametersResource;
 /**
  * Resolves the full runtime URL to call GW CORE from the provider sector DID
  * and the generated relative search path.

package/dist/utils/communication-bundle-document-request.js

@@ -3,6 +3,7 @@ import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { DocumentTypeLoincOntology, HealthcareDocumentTypes } from '../constants/healthcare.js';
 import { parseActorFromSub } from './actor.js';
 import { getBaseUrlFromDidWeb } from './did.js';
+import { buildFhirParametersResourceFromParameterData } from './fhir-search.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 import { transformCommunicationClaimsToResourceFhirR4 } from './communication-fhir-r4.js';
 export const BundleDocumentRequesterKinds = Object.freeze({
@@ -260,6 +261,13 @@ export function createSummaryOperationRequestReferencePath(parameters) {
     }
     return `individual/org.hl7.fhir.r4/Bundle/_search?${params.filter(Boolean).join('&')}`;
 }
+/**
+ * Builds the preferred FHIR `Parameters` body for the same semantic summary
+ * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ */
+export function createSummaryOperationRequestParametersResource(parameters) {
+    return buildFhirParametersResourceFromParameterData(parameters);
+}
 /**
  * Resolves the full runtime URL to call GW CORE from the provider sector DID
  * and the generated relative search path.

package/dist/utils/employee.d.ts

@@ -0,0 +1,75 @@
+import { SearchParameterPrimitive, SearchRequestEncoding } from './fhir-search';
+export type EmployeeClaims = Record<string, unknown>;
+export type EmployeeSearchValue = SearchParameterPrimitive;
+export type EmployeeDraftInput = Readonly<{
+    identifier?: string;
+    email?: string;
+    role?: string;
+    worksFor?: string;
+    memberOf?: string;
+    memberOfOrgTaxId?: string;
+    additionalClaims?: EmployeeClaims;
+}>;
+export type EmployeeBatchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type EmployeeBatchEntryInput = Readonly<{
+    method: EmployeeBatchMethod;
+    claims: EmployeeClaims;
+    resourceId?: string;
+    resourceType?: 'Employee';
+    type?: string;
+}>;
+export type EmployeeSearchBundleInput = Readonly<{
+    claims?: Record<string, EmployeeSearchValue | undefined>;
+    method?: 'GET' | 'POST';
+    encoding?: SearchRequestEncoding;
+    resourceType?: 'Employee';
+}>;
+/**
+ * Builds canonical `org.schema.Person.*` employee claims from semantic input.
+ */
+export declare function buildEmployeeClaims(input: EmployeeDraftInput): EmployeeClaims;
+/**
+ * Builds a claims-first employee batch entry from the minimum semantic input.
+ *
+ * Callers only provide the operation method, employee claims, and optional
+ * resource id. The helper places claims in the canonical `resource.meta.claims`
+ * location and infers the business `type` internally.
+ */
+export declare function buildEmployeeBatchEntry(input: EmployeeBatchEntryInput): {
+    type: string;
+    request: {
+        method: EmployeeBatchMethod;
+    };
+    resource: {
+        resourceType: 'Employee';
+        id?: string;
+        meta: {
+            claims: EmployeeClaims;
+        };
+    };
+};
+/**
+ * Builds the legacy query-string employee search target kept for compatibility
+ * with older `_search` wrappers.
+ */
+export declare function buildEmployeeSearchQuery(input?: EmployeeSearchBundleInput): string;
+/**
+ * Builds a canonical employee search bundle.
+ *
+ * Defaults to `POST + Parameters`. Set `method` or `encoding` to legacy GET
+ * only when talking to older search consumers.
+ */
+export declare function buildEmployeeSearchBundle(input?: EmployeeSearchBundleInput): {
+    resourceType: 'Bundle';
+    type: 'batch';
+    entry: Array<{
+        request: {
+            method: 'GET' | 'POST';
+            url: string;
+        };
+        resource?: {
+            resourceType: 'Parameters';
+            parameter: Array<Record<string, unknown>>;
+        };
+    }>;
+};

package/dist/utils/employee.js

@@ -0,0 +1,114 @@
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+import { buildFhirParametersResourceFromSearchParams, buildSearchQueryString, } from './fhir-search.js';
+function cloneClaims(claims) {
+    return { ...(claims || {}) };
+}
+function inferEmployeeEntryType(method) {
+    switch (method) {
+        case 'DELETE':
+            return 'Employee-delete-request-v1.0';
+        case 'PUT':
+        case 'PATCH':
+            return 'Employee-update-request-v1.0';
+        case 'GET':
+            return 'Employee-search-request-v1.0';
+        case 'POST':
+        default:
+            return 'Employee-create-request-v1.0';
+    }
+}
+/**
+ * Builds canonical `org.schema.Person.*` employee claims from semantic input.
+ */
+export function buildEmployeeClaims(input) {
+    const claims = {
+        '@context': 'org.schema',
+        ...cloneClaims(input.additionalClaims),
+    };
+    if (typeof input.identifier === 'string' && input.identifier.trim()) {
+        claims[ClaimsPersonSchemaorg.identifier] = input.identifier.trim();
+    }
+    if (typeof input.email === 'string' && input.email.trim()) {
+        claims[ClaimsPersonSchemaorg.email] = input.email.trim();
+    }
+    if (typeof input.role === 'string' && input.role.trim()) {
+        claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue] = input.role.trim();
+    }
+    if (typeof input.worksFor === 'string' && input.worksFor.trim()) {
+        claims[ClaimsPersonSchemaorg.worksFor] = input.worksFor.trim();
+    }
+    if (typeof input.memberOf === 'string' && input.memberOf.trim()) {
+        claims[ClaimsPersonSchemaorg.memberOf] = input.memberOf.trim();
+    }
+    if (typeof input.memberOfOrgTaxId === 'string' && input.memberOfOrgTaxId.trim()) {
+        claims[ClaimsPersonSchemaorg.memberOfOrgTaxId] = input.memberOfOrgTaxId.trim();
+    }
+    return claims;
+}
+/**
+ * Builds a claims-first employee batch entry from the minimum semantic input.
+ *
+ * Callers only provide the operation method, employee claims, and optional
+ * resource id. The helper places claims in the canonical `resource.meta.claims`
+ * location and infers the business `type` internally.
+ */
+export function buildEmployeeBatchEntry(input) {
+    const claims = cloneClaims(input.claims);
+    const resourceType = input.resourceType || 'Employee';
+    return {
+        type: input.type || inferEmployeeEntryType(input.method),
+        request: { method: input.method },
+        resource: {
+            resourceType,
+            ...(input.resourceId ? { id: input.resourceId } : {}),
+            meta: { claims },
+        },
+    };
+}
+/**
+ * Builds the legacy query-string employee search target kept for compatibility
+ * with older `_search` wrappers.
+ */
+export function buildEmployeeSearchQuery(input = {}) {
+    const resourceType = input.resourceType || 'Employee';
+    const query = buildSearchQueryString(input.claims || {});
+    return query ? `${resourceType}?${query}` : resourceType;
+}
+/**
+ * Builds a canonical employee search bundle.
+ *
+ * Defaults to `POST + Parameters`. Set `method` or `encoding` to legacy GET
+ * only when talking to older search consumers.
+ */
+export function buildEmployeeSearchBundle(input = {}) {
+    const resourceType = input.resourceType || 'Employee';
+    const claims = input.claims || {};
+    const method = input.method || (input.encoding === 'get-query' ? 'GET' : 'POST');
+    if (method === 'GET') {
+        return {
+            resourceType: 'Bundle',
+            type: 'batch',
+            entry: [
+                {
+                    request: {
+                        method: 'GET',
+                        url: buildEmployeeSearchQuery({ ...input, resourceType }),
+                    },
+                },
+            ],
+        };
+    }
+    return {
+        resourceType: 'Bundle',
+        type: 'batch',
+        entry: [
+            {
+                request: {
+                    method: 'POST',
+                    url: `${resourceType}/_search`,
+                },
+                resource: buildFhirParametersResourceFromSearchParams(claims),
+            },
+        ],
+    };
+}

package/dist/utils/fhir-search.d.ts

@@ -0,0 +1,26 @@
+import { ParameterData } from '../models/params';
+export type SearchParameterPrimitive = string | number | boolean | readonly (string | number | boolean)[];
+export type SearchRequestEncoding = 'get-query' | 'post-parameters';
+export type FhirParametersParameter = {
+    name: string;
+    valueString?: string;
+    valueCode?: string;
+    valueBoolean?: boolean;
+    valueInteger?: number;
+    valueDecimal?: number;
+    valueUri?: string;
+    valueReference?: {
+        reference: string;
+    };
+    valueCoding?: {
+        system?: string;
+        code: string;
+    };
+};
+export type FhirParametersResource = {
+    resourceType: 'Parameters';
+    parameter: FhirParametersParameter[];
+};
+export declare function buildSearchQueryString(searchParams: Readonly<Record<string, SearchParameterPrimitive | undefined>>): string;
+export declare function buildFhirParametersResourceFromSearchParams(searchParams: Readonly<Record<string, SearchParameterPrimitive | undefined>>): FhirParametersResource;
+export declare function buildFhirParametersResourceFromParameterData(parameters: ReadonlyArray<ParameterData>): FhirParametersResource;

package/dist/utils/fhir-search.js

@@ -0,0 +1,84 @@
+function normalizeSearchPrimitiveValues(value) {
+    const values = Array.isArray(value) ? [...value] : [value];
+    return values
+        .map((item) => typeof item === 'string' ? item.trim() : item)
+        .filter((item) => item !== '' && item !== undefined && item !== null);
+}
+function toPrimitiveString(value) {
+    return typeof value === 'string' ? value.trim() : String(value);
+}
+function toSearchParameter(name, value) {
+    if (typeof value === 'boolean') {
+        return { name, valueBoolean: value };
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value)
+            ? { name, valueInteger: value }
+            : { name, valueDecimal: value };
+    }
+    return { name, valueString: value.trim() };
+}
+function flattenParameterDataValue(parameter) {
+    const name = String(parameter?.name || '').trim();
+    if (!name) {
+        return undefined;
+    }
+    if (parameter.type === 'reference') {
+        const reference = String(parameter.reference || parameter.value || '').trim();
+        return reference ? { name, valueReference: { reference } } : undefined;
+    }
+    if (parameter.type === 'token') {
+        const code = String(parameter.value || '').trim();
+        if (!code) {
+            return undefined;
+        }
+        return parameter.system
+            ? { name, valueCoding: { system: String(parameter.system).trim(), code } }
+            : { name, valueCode: code };
+    }
+    if (parameter.type === 'uri') {
+        const value = String(parameter.value || '').trim();
+        return value ? { name, valueUri: value } : undefined;
+    }
+    if (typeof parameter.value === 'number') {
+        return Number.isInteger(parameter.value)
+            ? { name, valueInteger: parameter.value }
+            : { name, valueDecimal: parameter.value };
+    }
+    const value = String(parameter.value || '').trim();
+    return value ? { name, valueString: value } : undefined;
+}
+export function buildSearchQueryString(searchParams) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(searchParams)) {
+        if (value === undefined || value === null)
+            continue;
+        const normalized = normalizeSearchPrimitiveValues(value);
+        if (normalized.length === 0)
+            continue;
+        params.set(key, normalized.map(toPrimitiveString).join(','));
+    }
+    return params.toString();
+}
+export function buildFhirParametersResourceFromSearchParams(searchParams) {
+    const parameter = [];
+    for (const [name, value] of Object.entries(searchParams)) {
+        if (value === undefined || value === null)
+            continue;
+        for (const item of normalizeSearchPrimitiveValues(value)) {
+            parameter.push(toSearchParameter(name, item));
+        }
+    }
+    return {
+        resourceType: 'Parameters',
+        parameter,
+    };
+}
+export function buildFhirParametersResourceFromParameterData(parameters) {
+    return {
+        resourceType: 'Parameters',
+        parameter: parameters
+            .map((parameter) => flattenParameterDataValue(parameter))
+            .filter((parameter) => Boolean(parameter)),
+    };
+}

package/dist/utils/index.d.ts

@@ -14,12 +14,14 @@ export * from './did-resolution';
 export * from './dataspace-discovery';
 export * from './dataspace-discovery-defaults';
 export * from './dataspace-protocol';
+export * from './employee';
 export * from './didcomm';
 export * from './didcomm-submit';
 export * from './didcomm-submit-policy';
 export * from './discovery-normalization';
 export * from './format-converter';
 export * from './fhir-cid';
+export * from './fhir-search';
 export * from './communication-fhir-r4';
 export * from './communication-document-reference';
 export * from './communication-bundle-document-request';

package/dist/utils/index.js

@@ -14,12 +14,14 @@ export * from './did-resolution.js';
 export * from './dataspace-discovery.js';
 export * from './dataspace-discovery-defaults.js';
 export * from './dataspace-protocol.js';
+export * from './employee.js';
 export * from './didcomm.js';
 export * from './didcomm-submit.js';
 export * from './didcomm-submit-policy.js';
 export * from './discovery-normalization.js';
 export * from './format-converter.js';
 export * from './fhir-cid.js';
+export * from './fhir-search.js';
 export * from './communication-fhir-r4.js';
 export * from './communication-document-reference.js';
 export * from './communication-bundle-document-request.js';

package/package.json

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