gdc-common-utils-ts 2.0.2 → 2.0.5

package/dist/utils/legal-organization-verification-transaction.d.ts

@@ -0,0 +1,130 @@
+import type { BundleJsonApi } from '../models/bundle';
+import type { ClaimsRecord } from '../models/resource-document';
+/**
+ * Canonical business entry type for the first host-side onboarding step that
+ * asks GW CORE to forward a legal-organization verification request to ICA.
+ *
+ * Responsibilities of this transaction:
+ * - carry the signed PDF evidence or PDF URL attachment
+ * - carry the controller business binding key
+ * - optionally carry the organization VC-signing public key chosen by the host
+ * - carry the legal organization claims that GW CORE should keep through the
+ *   verification/onboarding pipeline
+ *
+ * Non-responsibilities:
+ * - it is not the same thing as host `_activate`
+ * - it does not model Fabric/CSR enrollment
+ */
+export declare const LegalOrganizationVerificationTransactionEntryTypes: Readonly<{
+    readonly Request: "Organization-verification-transaction-request-v1.0";
+    readonly Response: "Organization-verification-transaction-response-v1.0";
+}>;
+export type LegalOrganizationVerificationTransactionEntryType = typeof LegalOrganizationVerificationTransactionEntryTypes[keyof typeof LegalOrganizationVerificationTransactionEntryTypes];
+/**
+ * Explicit controller binding material that ICA should project into the legal
+ * representative VC.
+ */
+export type LegalOrganizationVerificationTransactionController = Readonly<{
+    did?: string;
+    sameAs?: string;
+    publicKeyJwk?: Record<string, unknown>;
+    jwks?: {
+        keys: Array<Record<string, unknown>>;
+    };
+}>;
+/**
+ * Optional organization-side public key material that the hosting operator may
+ * already know before the final activation/publication step.
+ */
+export type LegalOrganizationVerificationTransactionOrganization = Readonly<{
+    did?: string;
+    url?: string;
+    publicKeyJwk?: Record<string, unknown>;
+    jwks?: {
+        keys: Array<Record<string, unknown>>;
+    };
+}>;
+/**
+ * Additional legal-representative payload fields forwarded to ICA `_verify`.
+ *
+ * These values help ICA derive `sameAs` when the signed document itself does
+ * not expose that contact value in a directly reusable way.
+ */
+export type LegalOrganizationVerificationRepresentativePayload = Readonly<{
+    email?: string;
+    sameAs?: string;
+}>;
+/**
+ * Optional verification routing hints for ICA.
+ *
+ * `resourceType` defaults to `contract`, which matches the current
+ * legal-organization terms flow in ICA.
+ */
+export type LegalOrganizationVerificationRouting = Readonly<{
+    resourceType?: string;
+}>;
+/**
+ * Canonical input accepted by shared SDK/GW helpers when building the first
+ * host onboarding transaction that wraps an ICA `_verify` request.
+ */
+export type LegalOrganizationVerificationTransactionInput = Readonly<{
+    claims: ClaimsRecord;
+    controller: LegalOrganizationVerificationTransactionController;
+    organization?: LegalOrganizationVerificationTransactionOrganization;
+    legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
+    verification?: LegalOrganizationVerificationRouting;
+    attachments?: unknown[];
+}>;
+export type LegalOrganizationVerificationTransactionEntry = Readonly<{
+    type?: string;
+    meta?: {
+        claims?: ClaimsRecord;
+        [key: string]: unknown;
+    };
+    resource?: {
+        controller?: LegalOrganizationVerificationTransactionController;
+        organization?: LegalOrganizationVerificationTransactionOrganization;
+        legalRepresentativePayload?: LegalOrganizationVerificationRepresentativePayload;
+        legalRepresentative?: LegalOrganizationVerificationRepresentativePayload;
+        verification?: LegalOrganizationVerificationRouting;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}>;
+/**
+ * Builds the canonical Bundle payload for host-side legal organization
+ * verification transactions.
+ *
+ * Contract notes:
+ * - business claims remain in `meta.claims`
+ * - controller binding material remains in `resource.controller.*`
+ * - organization signing material remains in `resource.organization.*`
+ * - PDF evidence or URL attachments stay at the DIDComm-message level
+ * - `Service.category` is the canonical business-sector input later used by GW
+ *   to target the appropriate ICA verification route
+ */
+export declare function buildLegalOrganizationVerificationTransactionBundle(input: LegalOrganizationVerificationTransactionInput): BundleJsonApi;
+/**
+ * Returns the first bundle entry when the payload matches the canonical
+ * legal-organization verification transaction shape.
+ *
+ * This helper accepts either:
+ * - the raw bundle itself
+ * - or a DIDComm/API wrapper object whose `body` contains that bundle
+ */
+export declare function getFirstLegalOrganizationVerificationTransactionEntry(value: unknown): LegalOrganizationVerificationTransactionEntry | undefined;
+/**
+ * Returns the normalized controller binding payload from the first legal
+ * organization verification transaction entry when present.
+ */
+export declare function getLegalOrganizationVerificationController(value: unknown): LegalOrganizationVerificationTransactionController | undefined;
+/**
+ * Returns the normalized legal representative contact payload from the first
+ * legal-organization verification transaction entry when present.
+ *
+ * Compatibility note:
+ * - GW/SDK request builders use `resource.legalRepresentativePayload`
+ * - the ICA forwarding payload currently uses `resource.legalRepresentative`
+ * - this helper intentionally accepts both shapes
+ */
+export declare function getLegalOrganizationVerificationRepresentativePayload(value: unknown): LegalOrganizationVerificationRepresentativePayload | undefined;

package/dist/utils/legal-organization-verification-transaction.js

@@ -0,0 +1,118 @@
+import { ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
+/**
+ * Canonical business entry type for the first host-side onboarding step that
+ * asks GW CORE to forward a legal-organization verification request to ICA.
+ *
+ * Responsibilities of this transaction:
+ * - carry the signed PDF evidence or PDF URL attachment
+ * - carry the controller business binding key
+ * - optionally carry the organization VC-signing public key chosen by the host
+ * - carry the legal organization claims that GW CORE should keep through the
+ *   verification/onboarding pipeline
+ *
+ * Non-responsibilities:
+ * - it is not the same thing as host `_activate`
+ * - it does not model Fabric/CSR enrollment
+ */
+export const LegalOrganizationVerificationTransactionEntryTypes = Object.freeze({
+    Request: 'Organization-verification-transaction-request-v1.0',
+    Response: 'Organization-verification-transaction-response-v1.0',
+});
+function normalizeText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Builds the canonical Bundle payload for host-side legal organization
+ * verification transactions.
+ *
+ * Contract notes:
+ * - business claims remain in `meta.claims`
+ * - controller binding material remains in `resource.controller.*`
+ * - organization signing material remains in `resource.organization.*`
+ * - PDF evidence or URL attachments stay at the DIDComm-message level
+ * - `Service.category` is the canonical business-sector input later used by GW
+ *   to target the appropriate ICA verification route
+ */
+export function buildLegalOrganizationVerificationTransactionBundle(input) {
+    const businessSector = normalizeText(input.claims?.[ClaimsServiceSchemaorg.category]);
+    if (!businessSector) {
+        throw new Error(`buildLegalOrganizationVerificationTransactionBundle requires ${ClaimsServiceSchemaorg.category}.`);
+    }
+    return {
+        resourceType: 'Bundle',
+        type: 'collection',
+        total: 1,
+        data: [{
+                type: LegalOrganizationVerificationTransactionEntryTypes.Request,
+                meta: {
+                    claims: input.claims,
+                },
+                resource: {
+                    controller: input.controller,
+                    ...(input.organization ? { organization: input.organization } : {}),
+                    ...(input.legalRepresentativePayload
+                        ? { legalRepresentativePayload: input.legalRepresentativePayload }
+                        : {}),
+                    verification: {
+                        resourceType: normalizeText(input.verification?.resourceType) || 'contract',
+                    },
+                },
+            }],
+        ...(Array.isArray(input.attachments) && input.attachments.length > 0
+            ? { attachments: input.attachments }
+            : {}),
+    };
+}
+/**
+ * Returns the first bundle entry when the payload matches the canonical
+ * legal-organization verification transaction shape.
+ *
+ * This helper accepts either:
+ * - the raw bundle itself
+ * - or a DIDComm/API wrapper object whose `body` contains that bundle
+ */
+export function getFirstLegalOrganizationVerificationTransactionEntry(value) {
+    const root = asRecord(value);
+    const bundle = asRecord(root?.body) || root;
+    const data = Array.isArray(bundle?.data) ? bundle.data : [];
+    const first = data[0];
+    return asRecord(first);
+}
+/**
+ * Returns the normalized controller binding payload from the first legal
+ * organization verification transaction entry when present.
+ */
+export function getLegalOrganizationVerificationController(value) {
+    const entry = getFirstLegalOrganizationVerificationTransactionEntry(value);
+    const controller = asRecord(entry?.resource?.controller);
+    return controller
+        ? controller
+        : undefined;
+}
+/**
+ * Returns the normalized legal representative contact payload from the first
+ * legal-organization verification transaction entry when present.
+ *
+ * Compatibility note:
+ * - GW/SDK request builders use `resource.legalRepresentativePayload`
+ * - the ICA forwarding payload currently uses `resource.legalRepresentative`
+ * - this helper intentionally accepts both shapes
+ */
+export function getLegalOrganizationVerificationRepresentativePayload(value) {
+    const entry = getFirstLegalOrganizationVerificationTransactionEntry(value);
+    const candidate = asRecord(entry?.resource?.legalRepresentativePayload)
+        || asRecord(entry?.resource?.legalRepresentative);
+    if (!candidate)
+        return undefined;
+    const email = normalizeText(candidate.email);
+    const sameAs = normalizeText(candidate.sameAs);
+    return {
+        ...(email ? { email } : {}),
+        ...(sameAs ? { sameAs } : {}),
+    };
+}

package/dist/utils/organization-did-binding.d.ts

@@ -0,0 +1,60 @@
+import type { BundleJsonApi } from '../models/bundle';
+export declare const OrganizationDidBindingEntryTypes: Readonly<{
+    readonly Request: "Organization-did-binding-request-v1.0";
+    readonly Response: "Organization-did-binding-response-v1.0";
+}>;
+export type OrganizationDidBindingErrorCode = 'MISSING_ORGANIZATION_URL' | 'UNSUPPORTED_ORGANIZATION_LOCATOR';
+export type OrganizationDidBindingValidationError = Readonly<{
+    code: OrganizationDidBindingErrorCode;
+    message: string;
+    claimPaths: string[];
+}>;
+export type OrganizationDidBindingControllerInput = Readonly<{
+    sameAs?: string;
+}>;
+export type OrganizationDidBindingOrganizationInput = Readonly<{
+    url: string | string[];
+    taxID?: string;
+    taxId?: string;
+    identifier?: string;
+}>;
+export type OrganizationDidBindingInput = Readonly<{
+    organization: OrganizationDidBindingOrganizationInput;
+    controller?: OrganizationDidBindingControllerInput;
+}>;
+export type ValidateOrganizationDidBindingInputResult = Readonly<{
+    ok: boolean;
+    errors: OrganizationDidBindingValidationError[];
+    normalizedInput: Readonly<{
+        organization: {
+            url: string[];
+        };
+        controller?: OrganizationDidBindingControllerInput;
+    }>;
+}>;
+/**
+ * Validates the tenant-scoped organization DID binding request.
+ *
+ * Canonical contract:
+ * - the organization is already identified by the tenant path in GW CORE
+ * - callers send one or more public aliases in `organization.url`
+ * - `controller.sameAs` is optional additional evidence, not a new key-binding
+ *   bootstrap step
+ *
+ * Current version limits:
+ * - no `taxID` / `identifier` locator is required
+ * - sending those legacy locator fields is rejected so callers do not mix path
+ *   identity with payload identity
+ */
+export declare function validateOrganizationDidBindingInput(input: OrganizationDidBindingInput): ValidateOrganizationDidBindingInputResult;
+/**
+ * Builds the canonical bundle payload for one tenant-scoped DID binding
+ * request.
+ *
+ * Result contract:
+ * - `resource.organization.url` carries the public alias replacement list
+ * - `resource.controller.sameAs` is optional corroborating identity material
+ * - organization identity is resolved from the tenant path, not from payload
+ *   locators
+ */
+export declare function buildOrganizationDidBindingBundle(input: OrganizationDidBindingInput): BundleJsonApi;

package/dist/utils/organization-did-binding.js

@@ -0,0 +1,103 @@
+export const OrganizationDidBindingEntryTypes = Object.freeze({
+    Request: 'Organization-did-binding-request-v1.0',
+    Response: 'Organization-did-binding-response-v1.0',
+});
+function normalizeOptionalText(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+function normalizeOrganizationUrls(value) {
+    if (Array.isArray(value)) {
+        const urls = value
+            .map((item) => normalizeOptionalText(item))
+            .filter((item) => Boolean(item));
+        return urls.length ? urls : undefined;
+    }
+    const raw = normalizeOptionalText(value);
+    if (!raw)
+        return undefined;
+    const urls = raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return urls.length ? urls : undefined;
+}
+/**
+ * Validates the tenant-scoped organization DID binding request.
+ *
+ * Canonical contract:
+ * - the organization is already identified by the tenant path in GW CORE
+ * - callers send one or more public aliases in `organization.url`
+ * - `controller.sameAs` is optional additional evidence, not a new key-binding
+ *   bootstrap step
+ *
+ * Current version limits:
+ * - no `taxID` / `identifier` locator is required
+ * - sending those legacy locator fields is rejected so callers do not mix path
+ *   identity with payload identity
+ */
+export function validateOrganizationDidBindingInput(input) {
+    const errors = [];
+    const normalizedUrls = normalizeOrganizationUrls(input?.organization?.url);
+    const taxID = normalizeOptionalText(input?.organization?.taxID || input?.organization?.taxId);
+    const identifier = normalizeOptionalText(input?.organization?.identifier);
+    const controllerSameAs = normalizeOptionalText(input?.controller?.sameAs);
+    if (!normalizedUrls?.length) {
+        errors.push({
+            code: 'MISSING_ORGANIZATION_URL',
+            message: 'Organization DID binding requires at least one organization.url value.',
+            claimPaths: ['organization.url'],
+        });
+    }
+    if (taxID || identifier) {
+        errors.push({
+            code: 'UNSUPPORTED_ORGANIZATION_LOCATOR',
+            message: 'Organization DID binding in GW CORE uses the tenant path as locator and does not accept organization.taxID or organization.identifier in this version.',
+            claimPaths: ['organization.taxID', 'organization.identifier'],
+        });
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        normalizedInput: {
+            organization: {
+                url: normalizedUrls || [],
+            },
+            ...(controllerSameAs ? { controller: { sameAs: controllerSameAs } } : {}),
+        },
+    };
+}
+/**
+ * Builds the canonical bundle payload for one tenant-scoped DID binding
+ * request.
+ *
+ * Result contract:
+ * - `resource.organization.url` carries the public alias replacement list
+ * - `resource.controller.sameAs` is optional corroborating identity material
+ * - organization identity is resolved from the tenant path, not from payload
+ *   locators
+ */
+export function buildOrganizationDidBindingBundle(input) {
+    const validation = validateOrganizationDidBindingInput(input);
+    if (!validation.ok) {
+        throw new Error(validation.errors.map((item) => item.message).join(' '));
+    }
+    return {
+        resourceType: 'Bundle',
+        type: 'collection',
+        total: 1,
+        data: [{
+                type: OrganizationDidBindingEntryTypes.Request,
+                resource: {
+                    organization: {
+                        url: validation.normalizedInput.organization.url,
+                    },
+                    ...(validation.normalizedInput.controller
+                        ? { controller: validation.normalizedInput.controller }
+                        : {}),
+                },
+            }],
+    };
+}

package/dist/utils/professional-smart.d.ts

@@ -0,0 +1,21 @@
+export type ProfessionalEmployeeCredentialInput = Readonly<{
+    actorDid: string;
+    role: string;
+    additionalCredentialSubject?: Record<string, unknown>;
+    additionalCredential?: Record<string, unknown>;
+}>;
+export type ProfessionalSmartVpPayloadInput = Readonly<{
+    clientId: string;
+    actorDid: string;
+    role: string;
+    verifiableCredential?: string | Record<string, unknown> | ReadonlyArray<string | Record<string, unknown>>;
+    additionalVp?: Record<string, unknown>;
+    additionalPayload?: Record<string, unknown>;
+}>;
+export declare function buildProfessionalEmployeeCredential(input: ProfessionalEmployeeCredentialInput): Record<string, unknown>;
+export declare function buildProfessionalSmartVpPayload(input: ProfessionalSmartVpPayloadInput): Record<string, unknown>;
+export declare function buildUnsignedProfessionalSmartVpJwt(input: ProfessionalSmartVpPayloadInput, options?: Readonly<{
+    nowSeconds?: number;
+    ttlSeconds?: number;
+    nonce?: string;
+}>): string;

package/dist/utils/professional-smart.js

@@ -0,0 +1,37 @@
+import { ProfessionalCredentialTypes, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+import { buildUnsignedVpJwt } from './jwt.js';
+export function buildProfessionalEmployeeCredential(input) {
+    return {
+        type: [
+            W3cCredentialTypes.VerifiableCredential,
+            ProfessionalCredentialTypes.EmployeeCredential,
+        ],
+        credentialSubject: {
+            id: String(input.actorDid || '').trim(),
+            hasOccupation: String(input.role || '').trim(),
+            ...(input.additionalCredentialSubject || {}),
+        },
+        ...(input.additionalCredential || {}),
+    };
+}
+export function buildProfessionalSmartVpPayload(input) {
+    const credentials = Array.isArray(input.verifiableCredential)
+        ? [...input.verifiableCredential]
+        : input.verifiableCredential
+            ? [input.verifiableCredential]
+            : [buildProfessionalEmployeeCredential({
+                    actorDid: input.actorDid,
+                    role: input.role,
+                })];
+    return {
+        ...(input.additionalPayload || {}),
+        vp: {
+            holder: String(input.clientId || '').trim(),
+            verifiableCredential: credentials,
+            ...(input.additionalVp || {}),
+        },
+    };
+}
+export function buildUnsignedProfessionalSmartVpJwt(input, options = {}) {
+    return buildUnsignedVpJwt(buildProfessionalSmartVpPayload(input), options);
+}

package/dist/utils/related-person-list.d.ts

@@ -9,6 +9,14 @@ export type RelatedPersonListRecord = Readonly<{
     resourceId?: string;
     claims: Record<string, unknown>;
 }>;
+export type RelatedPersonListSelection = Readonly<{
+    index?: number;
+    identifier?: string;
+    name?: string;
+    telecom?: string;
+    patient?: string;
+    activeOnly?: boolean;
+}>;
 /**
  * Reads subject-side relationship records from one current GW-style result
  * body into one neutral list shape for frontend screens.
@@ -18,3 +26,9 @@ export declare function readRelatedPersonListRecords(body: unknown): RelatedPers
  * Returns one related-person record by canonical business identifier.
  */
 export declare function findRelatedPersonListRecord(body: unknown, identifier: string): RelatedPersonListRecord | undefined;
+/**
+ * Selects one related-person record from one neutralized list/body using the
+ * same high-level criteria that channel apps usually expose to users:
+ * list position, identifier, display name, contact value, or linked patient.
+ */
+export declare function selectRelatedPersonListRecord(body: unknown, selection: RelatedPersonListSelection): RelatedPersonListRecord | undefined;

package/dist/utils/related-person-list.js

@@ -52,3 +52,34 @@ export function findRelatedPersonListRecord(body, identifier) {
     return readRelatedPersonListRecords(body)
         .find((record) => record.identifier === normalizedIdentifier);
 }
+/**
+ * Selects one related-person record from one neutralized list/body using the
+ * same high-level criteria that channel apps usually expose to users:
+ * list position, identifier, display name, contact value, or linked patient.
+ */
+export function selectRelatedPersonListRecord(body, selection) {
+    const records = readRelatedPersonListRecords(body);
+    const candidates = selection.activeOnly
+        ? records.filter((record) => record.active === 'true')
+        : records;
+    if (typeof selection.index === 'number' && Number.isInteger(selection.index)) {
+        return candidates[selection.index];
+    }
+    const identifier = normalizeText(selection.identifier);
+    if (identifier) {
+        return candidates.find((record) => record.identifier === identifier);
+    }
+    const name = normalizeText(selection.name)?.toLowerCase();
+    if (name) {
+        return candidates.find((record) => normalizeText(record.name)?.toLowerCase() === name);
+    }
+    const telecom = normalizeText(selection.telecom)?.toLowerCase();
+    if (telecom) {
+        return candidates.find((record) => normalizeText(record.telecom)?.toLowerCase() === telecom);
+    }
+    const patient = normalizeText(selection.patient);
+    if (patient) {
+        return candidates.find((record) => record.patient === patient);
+    }
+    return undefined;
+}

package/package.json

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